참고자료 · Debugging
에이전트 디버깅 플레이북
에이전트가 낸 이상한 결과를 “모델이 원래 그렇다”고 넘기면 하네스는 성장하지 않습니다. 좋은 하네스는 디버깅 자체도 playbook 화합니다. 즉, 실패를 분류하고, 재현하고, 증거를 모으고, root cause를 찾고, 최소 수정과 회귀 방지까지 한 흐름으로 다룹니다.
1. 표준 디버깅 순서
debugging workflowtext
1. 실패를 분류한다
2. 재현 가능한지 확인한다
3. 에러 메시지 / stack trace / failing assertion 을 모은다
4. 실패 지점을 특정한다
5. 실행 경로를 추적한다
6. root cause 를 정리한다
7. 가장 작은 수정으로 고친다
8. 관련 테스트를 돌린다
9. 회귀 가능성을 확인한다2. 에이전트 디버깅에서 특별히 중요한 것
- 문제는 모델 출력이 아니라 harness 설정일 수 있습니다.
- 권한, sandbox, hooks, MCP 연결 실패가 실제 원인인 경우가 많습니다.
- “틀린 답변”도 trace 와 tool call history가 있으면 분석 가능한 실패가 됩니다.
3. 최소 수정 원칙
root cause가 잡혔다면, 해결은 가능한 한 작아야 합니다. 큰 리팩터는 디버깅의 승리가 아니라 새로운 실패의 시작일 수 있습니다.
4. 하네스 관점의 실패 분류 예시
Context 실패
AGENTS.md, docs, state 문서가 부족하거나 우선순위가 꼬여서 잘못된 판단을 하는 경우.
Tool 실패
MCP 연결, bash command, filesystem scope, browser automation 자체가 깨진 경우.
Policy 실패
rules, sandbox, approval 때문에 실제 필요한 행동을 못 하거나 반대로 열어 두어 위험이 생긴 경우.
Reasoning 실패
모델이 문제를 이해했지만 잘못 추론하거나, 충분히 계획하지 못한 경우.
5. 회귀 방지
디버깅이 끝났다면, 그 실패를 다시 못 밟게 해야 합니다. hook, rule, verify script, handoff 문서, 테스트 중 어디에 남길지 결정해야 합니다.