agent-introspection-debugging

Files (1)

• SKILL.md

SKILL.md (first lines)

# 에이전트 인트로스펙션 디버깅 (Agent Introspection Debugging)

에이전트 실행이 반복적으로 실패하거나, 진전 없이 토큰만 소비하거나, 동일한 도구에서 루프를 돌거나, 의도한 작업에서 벗어날 때 이 기술을 사용하세요.

이것은 워크플로우 기술이지 숨겨진 런타임이 아닙니다. 에이전트가 인간에게 보고하기 전에 체계적으로 스스로를 디버깅하도록 가르칩니다.

## 활성화 시점

- 최대 도구 호출 / 루프 제한 실패 시
- 진전 없는 반복적인 재시도 시
- 컨텍스트 증가 또는 프롬프트 이탈로 인해 출력 품질이 저하되기 시작할 때
- 파일 시스템 또는 환경 상태가 기대와 현실 사이에서 불일치할 때
- 진단과 작은 교정 조치로 복구 가능한 도구 실패 시

## 범위 경계

다음을 위해 이 기술을 활성화하세요:
- 맹목적으로 재시도하기 전에 실패 상태 캡처
- 흔한 에이전트 전용 실패 패턴 진단
- 억제된 복구 조치 적용
- 구조화된 사람이 읽을 수 있는 디버그 보고서 생성

다음을 위한 기본 소스로 이 기술을 사용하지 마세요:
- 코드 변경 후 기능 검증 (`verification-loop` 사용)
- 더 좁은 범위의 ECC 기술이 이미 존재하는 프레임워크 전용 디버깅
- 현재 하네스가 자동으로 강제할 수 없는 런타임 약속

## 4단계 루프 (Four-Phase Loop)

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

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

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

최소 캡처 템플릿:

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

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

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

| 패턴 | 가능성 높은 원인 | 확인 사항 |
| --- | --- | --- |
| 최대 도구 호출 / 동일 명령어 반복 | 루프 또는 종료 조건 없는 관찰자 경로 | 반복 여부를 위해 마지막 N개 도구 호출 검사 |
| 컨텍스트 오버플로우 / 추론 능력 저하 | 무제한의 노트, 반복된 계획, 너무 큰 로그 | 중복 및 저신호 대량 데이터에 대한 최근 컨텍스트 검사 |
| `ECONNREFUSED` / 타임아웃 | 서비스 사용 불가 또는 잘못된 포트 | 서비스 상태, URL 및 포트 가정 확인 |
| `429` / 쿼터 소진 | 재시도 폭풍 또는 백오프(backoff) 누락 | 반복 호출 횟수 및 재시도 간격 검사 |
| 쓰기 후 파일 누락 / 오래된 diff | 레이스 컨디션, 잘못된 cwd 또는 브랜치 이탈 | 경로, cwd, git 상태 및 실제 파일 존재 여부 재확인 |
| "수정" 후에도 여전히 실패하는 테스트 | 잘못된 가설 | 정확한 실패 테스트를 격리하고 버그 다시 도출 |

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

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

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

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

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

억제된 복구 체크리스트:

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

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

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

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

## 복구 휴리스틱 (Recovery Heuristics)

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

1. 진짜 목표를 한 문장으로 다시 명시합니다.
2. 기억을 믿는 대신 세상의 상태를 검증합니다.
3. 실패하는 범위를 좁힙니다.

From kypo42/everything-claude-code-kr, MIT.

More from kypo42/everything-claude-code-kr