SOP: 관측 가능성 피드백 루프(Observability Feedback Loop)

디버깅이 느리거나, 에이전트(agent)가 증거 없이 성공을 주장하거나, 런타임 동작이 코드 자체보다 파악하기 어려울 때 이 표준 작업 절차(SOP)를 사용하십시오.

관측 가능성(observability)이란 로그, 메트릭, 트레이스와 같은 런타임 신호를 통해 시스템 내부 상태를 외부에서 추론할 수 있는 능력을 말합니다. 피드백 루프(feedback loop)는 이러한 신호를 에이전트가 코드 검사뿐 아니라 실행 결과로부터 추론할 수 있도록 반복 가능하게 구성한 것입니다.

목표

에이전트에게 로컬 피드백 루프를 제공하여 로그, 메트릭, 트레이스, 실행 가능한 워크로드를 통해 코드 검사만이 아닌 실행 결과로부터 추론할 수 있게 합니다.

최소 스택

• 애플리케이션이 구조화된 로그를 내보낸다
• 애플리케이션이 가능한 경우 메트릭과 트레이스를 내보낸다
• 로컬 팬아웃(fan-out) 또는 수집 계층
• 로그, 메트릭, 트레이스에 대한 쿼리 인터페이스
• 각 변경 후 재실행할 수 있는 반복 가능한 워크로드 또는 사용자 여정

실행 절차

1. 가장 중요한 황금 런타임 여정(golden runtime journey)을 정의한다.
2. 시작 및 핵심 경로에 구조화된 로그를 추가한다.
3. 유용한 경우 지연 시간, 실패 횟수, 큐 깊이에 대한 메트릭을 추가한다.
4. 느리거나 여러 단계로 구성된 흐름에 트레이스 또는 타이밍 마커를 추가한다.
5. 로컬 개발 환경에서 신호를 쿼리 가능하게 만든다.
6. 에이전트에게 재실행할 반복 가능한 워크로드 또는 시나리오를 하나 제공한다.
7. 루프를 강제한다: 쿼리 -> 상관 분석 -> 추론 -> 구현 -> 재시작 -> 재실행 -> 검증.

디버그 세션 체크리스트

• 무엇이 실패했는가?
• 어떤 신호가 실패를 증명하는가?
• 어떤 계층이 실패를 소유하는가?
• 수정 후 무엇이 변경되었는가?
• 앱이 깔끔하게 재시작되었는가?
• 재실행 후 동일한 워크로드가 통과했는가?

완료 정의

• 에이전트가 런타임 증거로부터 실패 모드를 설명할 수 있다.
• 각 변경 후 동일한 워크로드를 재실행할 수 있다.
• 재시작과 재실행이 일반적인 작업 루프의 일부이다.
• 신뢰성(reliability) 신호가 docs/RELIABILITY.md에 문서화되어 있다.