agent-introspection-debugging

Agent Introspection Debugging

에이전트 실행이 반복적으로 실패하거나, 진전 없이 토큰만 소모하거나, 같은 도구를 반복 호출하거나, 원래 작업에서 점점 벗어날 때 이 스킬을 사용한다.

이 스킬은 숨겨진 런타임이 아니라 워크플로 스킬이다. 사람에게 에스컬레이션하기 전에 에이전트가 스스로를 체계적으로 디버깅하도록 가르친다.

언제 활성화할지

• 최대 tool call / loop-limit 실패
• 전진 없이 반복되는 재시도
• 컨텍스트 증가나 프롬프트 드리프트로 출력 품질이 떨어지기 시작할 때
• 기대와 실제 사이에 파일시스템 또는 환경 상태 불일치가 있을 때
• 진단과 더 작은 수정 조치로 회복 가능해 보이는 도구 실패

적용 범위

다음 목적에 이 스킬을 활성화한다.

• 무작정 재시도하기 전에 실패 상태를 캡처
• 흔한 에이전트 전용 실패 패턴 진단
• 범위를 제한한 복구 조치 적용
• 사람이 읽을 수 있는 구조화된 디버그 보고서 작성

다음의 주된 수단으로는 사용하지 않는다.

• 코드 변경 후 기능 검증: verification-loop 사용
• 더 좁고 적합한 ECC 스킬이 이미 있는 프레임워크 전용 디버깅
• 현재 하니스가 자동으로 강제할 수 없는 런타임 약속

4단계 루프

1단계: 실패 캡처

복구를 시도하기 전에 실패를 정확히 기록한다.

캡처할 것:

• 가능하면 오류 유형, 메시지, 스택 트레이스
• 마지막으로 의미 있었던 tool call 시퀀스
• 에이전트가 하려던 일
• 현재 컨텍스트 압력: 반복 프롬프트, 과도한 로그 붙여넣기, 중복 계획, 폭주하는 메모
• 현재 환경 가정: cwd, 브랜치, 관련 서비스 상태, 기대한 파일

최소 캡처 템플릿:

## Failure Capture
- Session / task:
- Goal in progress:
- Error:
- Last successful step:
- Last failed tool / command:
- Repeated pattern seen:
- Environment assumptions to verify:

2단계: 근본 원인 진단

무엇을 바꾸기 전에 실패를 알려진 패턴에 먼저 매칭한다.

패턴	가능한 원인	점검
최대 tool call / 같은 명령 반복	루프 또는 종료 없는 observer 경로	마지막 N개 tool call의 반복 여부 확인
컨텍스트 오버플로 / 추론 품질 저하	끝없이 늘어난 메모, 반복 계획, 과도한 로그	최근 컨텍스트의 중복과 저신호 대량 텍스트 확인
ECONNREFUSED / timeout	서비스 미가동 또는 잘못된 포트	서비스 상태, URL, 포트 가정 검증
429 / quota exhaustion	재시도 폭주 또는 backoff 누락	반복 호출 수와 retry 간격 점검
write 후 파일 누락 / stale diff	race, 잘못된 cwd, 브랜치 드리프트	경로, cwd, git status, 실제 파일 존재 재확인
“수정” 후에도 테스트 실패	잘못된 가설	정확히 실패하는 테스트를 분리하고 버그를 다시 도출

진단 질문:

• 이것은 로직 실패인가, 상태 실패인가, 환경 실패인가, 정책 실패인가?
• 에이전트가 진짜 목표를 놓치고 잘못된 하위 작업을 최적화하고 있는가?
• 이 실패는 결정적인가, 일시적인가?
• 진단을 검증할 수 있는 가장 작은 되돌릴 수 있는 조치는 무엇인가?

3단계: 제한된 복구

진단 표면만 바꾸는 가장 작은 조치로 복구한다.

안전한 복구 조치:

• 반복 재시도를 멈추고 가설을 다시 명시
• 저신호 컨텍스트를 잘라내고 활성 목표, blocker, 증거만 남기기
• 실제 파일시스템 / 브랜치 / 프로세스 상태 재확인
• 작업 범위를 하나의 실패 명령, 하나의 파일, 하나의 테스트로 축소
• 추측성 추론 대신 직접 관측으로 전환
• 고위험이거나 외부 blocker가 있으면 사람에게 에스컬레이션

현재 환경의 실제 도구로 실행하지 않는 한 “에이전트 상태 리셋”이나 “하니스 설정 업데이트” 같은 자동 치유 조치를 주장하지 않는다.

제한된 복구 체크리스트:

## Recovery Action
- Diagnosis chosen:
- Smallest action taken:
- Why this is safe:
- What evidence would prove the fix worked:

4단계: 자기 점검 보고서

다음 에이전트나 사람이 이해할 수 있도록 마지막에 보고서를 남긴다.

## Agent Self-Debug Report
- Session / task:
- Failure:
- Root cause:
- Recovery action:
- Result: success | partial | blocked
- Token / time burn risk:
- Follow-up needed:
- Preventive change to encode later:

복구 휴리스틱

다음 개입 순서를 선호한다.

1. 진짜 목표를 한 문장으로 다시 쓴다.
2. 기억을 믿지 말고 실제 세계 상태를 검증한다.
3. 실패 범위를 줄인다.
4. 하나의 판별력 있는 점검을 실행한다.
5. 그 다음에만 재시도한다.

나쁜 패턴:

• 문구만 조금 바꿔 같은 행동을 세 번 재시도

좋은 패턴:

• 실패 캡처
• 패턴 분류
• 직접 점검 한 번 실행
• 점검 결과가 가설을 지지할 때만 계획 변경

ECC와의 연계

• 코드가 바뀌었다면 복구 후 verification-loop를 사용한다.
• 실패 패턴을 instinct 또는 후속 스킬로 남길 가치가 있다면 continuous-learning-v2를 사용한다.
• 문제가 기술적 실패가 아니라 의사결정 모호성이라면 council을 사용한다.
• 실패 원인이 충돌하는 로컬 상태나 저장소 드리프트라면 workspace-surface-audit를 사용한다.

출력 기준

이 스킬이 활성화된 상태에서는 “I fixed it” 같은 말만 남기고 끝내지 않는다.

항상 다음을 제공한다.

• 실패 패턴
• 근본 원인 가설
• 복구 조치
• 지금 상황이 나아졌는지, 여전히 막혀 있는지에 대한 증거