agent-introspection-debugging

name	agent-introspection-debugging
description	캡처, 진단, 제한된 복구, 자기 점검 보고서를 통해 AI 에이전트 실패를 구조적으로 디버깅하는 워크플로.
origin	ECC

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” 같은 말만 남기고 끝내지 않는다.

항상 다음을 제공한다.

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