에이전트 자체 평가
복잡한 작업을 완료한 후, 에이전트는 구조화된 5축 평가 기준에 따라 자신의 출력을 평가합니다. 이는 합격/불합격 게이트가 아닙니다. 사용자가 개입하기 전에 누락된 부분을 발견하고, 과신을 지적하며, 개선 영역을 표면화하는 의도적인 성찰 단계입니다.
활성화 시점
- 3개 이상의 파일 또는 50줄 이상에 걸친 코드를 작성한 후
- 다단계 워크플로우(구현 → 테스트 → 검토)를 완료한 후
- 3회 이상의 시도가 있었던 디버깅 세션 후
- 설계 문서, 아키텍처 결정, 또는 서면 분석을 작성한 후
- 사용자가 "그 결과가 얼마나 좋은가?" 또는 "자기 평가를 해봐"라고 요청했을 때
- 모든 세션 종료 훅에서 (설정된 경우 —
references/hook-integration.md참조)
핵심 개념
5가지 평가 축
| 축 | 질문 | 발견 대상 |
|---|---|---|
| 정확성 | 사실, 주장, 출력이 올바른가? | 환각, 잘못된 API 이름, 잘못된 구문, 거짓 진술 |
| 완전성 | 사용자가 요청한 모든 것을 다루었는가? | 놓친 엣지 케이스, 처리되지 않은 오류 경로, 잊혀진 요구 사항, 건너뛴 하위 작업 |
| 명확성 | 설명이 이해하기 쉽고 구조화되어 있는가? | 혼란스러운 설명, 정의 없는 전문 용어, 누락된 맥락, 산만함 |
| 실행 가능성 | 사용자가 출력을 즉시 실행할 수 있는가? | 모호한 제안, 누락된 단계, 방법을 보여주지 않는 "X를 해야 함", 확인 경로 없음 |
| 간결성 | 필요한 최소한의 단어/토큰을 사용했는가? | 중복, 과도한 설명, 사용자 질문의 그대로 반복, 불필요한 내용 |
점수 척도
5 — 탁월함: 합리적인 개선 가능성이 없음
4 — 좋음: 사소한 것만 있음, 실질적인 결함 없음
3 — 적절함: 요청을 충족하지만 최소 하나의 축에서 눈에 띄는 약점이 있음
2 — 약함: 사용성이나 정확성에 영향을 미치는 명확한 결함이 있음
1 — 나쁨: 요청을 근본적으로 이해하지 못했거나 심각한 오류를 포함함
증거 규칙
5점 미만의 모든 점수는 특정 증거를 반드시 인용해야 합니다. 3점이 "더 나을 수 있다"라고만 말할 수 없습니다. 정확히 무엇이 누락되었거나 잘못되었는지 말해야 합니다. 핵심 원칙: "결함을 보여주되, 이름만 대지 마라."
워크플로우
1단계: 원자재 수집
평가할 항목을 수집합니다:
- 원래 사용자 요청 (대화에서 다시 읽기)
- 최종 응답/출력 (산출물)
- 정확성을 확인하는 도구 출력 (테스트 결과, 종료 코드, 린트 출력)
- 작업 중 받은 사용자 피드백 (수정 사항, "다시 시도", "그게 아니야")
2단계: 각 축을 독립적으로 평가
다섯 축을 하나씩 순서대로 처리합니다. 각 축에 대해:
- 축 질문을 읽습니다.
- 출력에서 증거(또는 증거 부족)를 찾습니다.
- 1-5점을 할당합니다.
- 점수가 5 미만이면 결함을 인용하는 한 문장의 개선 사항을 작성합니다.
먼저 머릿속에서 점수를 평균낸 다음 거꾸로 작업하지 마십시오. 각 축을 새롭게 평가하십시오.
3단계: 평가 보고서 작성
templates/evaluation-report.md의 템플릿을 사용합니다. 보고서에는 다음이 포함되어야 합니다:
- 한 줄 요약
- 5축 점수표 (축별 점수 + 증거)
- 전체 점수 (간단 평균, 소수점 첫째 자리까지 반올림)
- 영향도 순으로 정렬된 1-3개의 구체적인 개선 사항
- 자체 점검: "사용자가 이 평가에 동의할까?"
4단계: 개선 사항 적용
어떤 축이 3점 이하인 경우:
- 다르게 했을 행동을 설명합니다.
- 결함이 30초 이내에 수정 가능한 경우(누락된 링크, 불명확한 표현), 지금 수정합니다.
- 결함이 재작업을 필요로 하는 경우, 명시적으로 표시합니다: "이 축이 [이유]로 [점수]를 받았습니다. [특정 수정]으로 다시 실행하면 [점수]로 올라갈 가능성이 높습니다."
코드 예제
예제: 좋은 평가 (4점 이상)
작업: HTTP 클라이언트에 재시도 로직 추가
점수표:
정확성: 5 — 모든 API 호출이 올바름. 확인: 재시도가
지수 백오프를 사용함. 환각된 메서드 없음.
완전성: 4 — 정상 경로 + 3개의 오류 사례를 다룸. 누락:
끊긴 연결에 대한 타임아웃 처리.
명확성: 5 — 코드 주석이 백오프 공식을 설명함.
PR 설명이 이를 동기로 한 사고에 연결함.
실행 가능성:5 — 단일 병합. 후속 작업 없음. 테스트 통과.
간결성: 4 — 총 47줄. 재시도 루프를 헬퍼로 추출하면
약 8줄을 줄일 수 있음.
전체: 4.6 — 한 가지 결함(타임아웃 처리). 병합 전 수정.
예제: 약한 평가 (2-3점)
작업: HTTP 클라이언트에 재시도 로직 추가
점수표:
정확성: 2 — urllib3를 사용했는데, 이는 우리의
httpx 기반 코드베이스와 일치하지 않음. 잘못된 라이브러리.
완전성: 3 — GET에 대해 작동함. POST/PUT은 처리되지 않음(사용자가
"모든 HTTP 요청"이라고 말함).
명확성: 4 — 코드가 읽기 쉬움. 변수명이 좋음.
실행 가능성:2 — "테스트 추가"가 언급되었지만 테스트 파일이 생성되지 않음.
사용자가 병합 전에 테스트를 작성해야 함.
간결성: 3 — 120줄. 재시도 구성이 하나의 공유 RetryConfig 객체 대신
3곳에 중복됨.
전체: 2.8 — 잘못된 라이브러리 사용. httpx로 재작성 필요.
먼저 정확성 수정(httpx로 전환), 그런 다음 모든 HTTP 메서드로 확장,
그런 다음 구성 통합.
안티 패턴
"모든 것이 5점"
실패: 정확성: 5 — 모두 좋음.
완전성: 5 — 모든 것 다룸.
명확성: 5 — 명확함.
증거가 인용되지 않음. 이는 평가가 아니라 자기 칭찬입니다. 진정한 5점은 개선할 것이 없다는 것을 증명해야 합니다.
작업 범위 확장에 대한 과도한 페널티
실패: 완전성: 2 — WebSocket 연결이나 gRPC 스트리밍을 처리하지 않음(사용자가 요청하지 않음)
추가로 구축할 수 있었던 것이 아니라, 사용자가 실제로 요청한 것에 대해서만 평가하십시오.
평가를 재논쟁에 사용
실패: "앞서 말했듯이, 이 접근 방식은 잘못되었습니다. 점수: 1"
평가는 전달된 출력에 대한 것이지, 이미 결정된 설계 결정을 다시 논쟁하는 것이 아닙니다. 접근 방식이 잘못되었다면, 전달 전에 발견되었어야 합니다.
개인적 선호와 객관적 결함 혼합
실패: "점수: 3. 저는 Python 데코레이터를 좋아하지 않습니다."
"좋아하지 않는다"는 증거가 아닙니다. 구체적인 가독성, 테스트 용이성, 또는 정확성 문제를 인용하거나, 점수를 4+로 남겨두십시오.
모범 사례
- 과정이 아닌 출력을 평가하십시오. 사용자는 몇 번의 반복을 거쳤는지가 아니라, 무엇을 전달했는지에 관심이 있습니다.
- 약한 축당 하나의 개선 사항. 한 축에 대해 5가지를 나열하지 말고, 가장 영향력이 큰 결함을 선택하십시오.
- 개선 사항을 사용자 영향과 연결하십시오. "오류 처리가 누락되어 사용자의 API 호출이 조용히 충돌할 것이다"가 "오류 처리 추가"보다 낫습니다.
- '수정'이 어떻게 보일지 구체적으로 설명하십시오. "재시도를 위해 httpx 전송이 구성된 상태로 다시 실행"이 "라이브러리 문제 수정"보다 낫습니다.
- 도구 출력을 증거로 사용하십시오. 테스트가 통과했으면 인용하십시오. 린트가 깨끗하면 인용하십시오. 추측하지 말고 grep으로 증거를 찾으십시오.
- 결함을 찾을 수 없으면 더 열심히 찾으십시오. 모든 5개 축에서 완벽한 점수는 드뭅니다. 질문하십시오: "내가 사용자라면, 이 출력에서 무엇이 짜증날까?"
관련 스킬
agent-eval— 벤치마크 작업에서 서로 다른 코딩 에이전트의 1:1 비교verification-loop— 예상 결과에 대한 출력의 체계적 검증security-review— 보안 중심 코드 검토 체크리스트