Agent Introspection Debugging

1단계: 실패 캡처 (Failure Capture)

복구를 시도하기 전에 실패 상태를 정확하게 기록하세요.

캡처 항목:

• 에러 유형, 메시지 및 가능한 경우 스택 트레이스
• 마지막으로 의미 있었던 도구 호출 시퀀스
• 에이전트가 시도하려 했던 작업
• 현재 컨텍스트 압박: 반복되는 프롬프트, 너무 큰 로그 붙여넣기, 중복된 계획 또는 폭주하는 노트
• 현재 환경 가정: cwd, 브랜치, 관련 서비스 상태, 예상되는 파일

최소 캡처 템플릿:

## 실패 캡처
- 세션 / 작업:
- 진행 중인 목표:
- 에러:
- 마지막으로 성공한 단계:
- 마지막으로 실패한 도구 / 명령어:
- 관찰된 반복 패턴:
- 검증할 환경 가정:

2단계: 근본 원인 진단 (Root-Cause Diagnosis)

무언가를 변경하기 전에 실패를 알려진 패턴과 매칭하세요.

진단 질문:

• 이것은 로직 실패, 상태 실패, 환경 실패, 또는 정책 실패인가?
• 에이전트가 진짜 목표를 잃고 잘못된 하위 작업을 최적화하기 시작했는가?
• 실패가 결정론적인가 아니면 일시적인가?
• 진단을 검증할 수 있는 가장 작은 가역적 작업은 무엇인가?

3단계: 억제된 복구 (Contained Recovery)

진단 표면을 변화시키는 가장 작은 작업으로 복구하세요.

안전한 복구 작업:

• 반복적인 재시도를 멈추고 가설을 다시 명시함
• 저신호 컨텍스트를 잘라내고 활성 목표, 차단 요인, 증거만 유지함
• 실제 파일 시스템 / 브랜치 / 프로세스 상태를 다시 확인함
• 작업을 실패하는 하나의 명령어, 하나의 파일 또는 하나의 테스트로 좁힘
• 추측성 추론에서 직접 관찰로 전환함
• 실패가 고위험이거나 외부적으로 차단된 경우 인간에게 보고함

현재 환경의 실제 도구를 통해 수행하는 것이 아니라면 "에이전트 상태 리셋"이나 "하네스 구성 업데이트"와 같이 지원되지 않는 자동 복구 작업을 주장하지 마세요.

억제된 복구 체크리스트:

## 복구 작업
- 선택된 진단:
- 수행된 가장 작은 작업:
- 이것이 안전한 이유:
- 수정이 작동했음을 증명할 증거:

4단계: 인트로스펙션 보고서 (Introspection Report)

다음 에이전트나 인간이 복구 과정을 이해할 수 있도록 보고서로 마무리하세요.

## 에이전트 셀프 디버그 보고서
- 세션 / 작업:
- 실패 내용:
- 근본 원인:
- 복구 작업:
- 결과: 성공 | 부분적 | 차단됨
- 토큰 / 시간 소모 리스크:
- 필요한 후속 조치:
- 나중에 인코딩할 예방적 변경 사항:

복구 휴리스틱 (Recovery Heuristics)

다음 순서대로 개입을 선호하세요:

1. 진짜 목표를 한 문장으로 다시 명시합니다.
2. 기억을 믿는 대신 세상의 상태를 검증합니다.
3. 실패하는 범위를 좁힙니다.
4. 하나의 판별용 체크를 실행합니다.
5. 그런 다음에만 재시도합니다.

나쁜 패턴:

• 약간 다른 표현으로 동일한 작업을 세 번 재시도함

좋은 패턴:

• 실패 캡처
• 패턴 분류
• 하나의 직접적인 체크 실행
• 체크 결과가 뒷받침될 때만 계획 변경

ECC와의 통합

• 코드가 변경된 경우 복구 후 verification-loop를 사용하세요.
• 실패 패턴이 본능이나 나중의 기술로 만들 가치가 있을 때 continuous-learning-v2를 사용하세요.
• 문제가 기술적 실패가 아니라 의사 결정의 모호함인 경우 council을 사용하세요.
• 실패가 충돌하는 로컬 상태나 저장소 이탈에서 온 경우 workspace-surface-audit을 사용하세요.

출력 표준

이 기술이 활성화되어 있을 때 단순히 "수정했습니다"라고만 끝내지 마세요.

항상 다음을 제공하세요:

• 실패 패턴
• 근본 원인 가설
• 복구 작업
• 상황이 나아졌거나 여전히 차단되어 있다는 증거