에이전트 자기 평가은(는) 무엇을 하나요?
복잡한 작업을 완료한 후, 에이전트는 구조화된 5축 평가 기준에 따라 자신의 출력을 평가하기 위해 잠시 멈춥니다. 이는 합격/불합격 게이트가 아닙니다. 사용자가 지적하기 전에 누락을 포착하고, 과신에 플래그를 지정하며, 개선 영역을 표면화하는 의도적인 성찰 단계입니다.
활성화 시점
- 3개 이상의 파일 또는 50줄이 넘는 코드를 작성한 후
- 다단계 워크플로우(구현 → 테스트 → 검토)를 완료한 후
- 3회 이상의 시도가 포함된 디버깅 세션 후
- 설계 문서, 아키텍처 결정 또는 서면 분석을 생성한 후
- 사용자가 "그거 얼마나 잘했어?" 또는 "자기 평가해 봐"라고 물을 때
- 모든 세션 Stop 후크가 종료될 때(구성된 경우 —
references/hook-integration.md참조)
핵심 개념
5가지 평가 축
| 축 | 질문 | 파악하는 내용 |
|---|---|---|
| 정확성 | 사실, 주장 및 출력이 올바른가? | 환각, 잘못된 API 이름, 잘못된 구문, 거짓 진술 |
| 완전성 | 사용자가 요청한 모든 것을 다루었는가? | 누락된 에지 케이스, 처리되지 않은 오류 경로, 잊혀진 요구 사항, 건너뛴 하위 작업 |
| 명확성 | 설명이 이해하기 쉽고 잘 구조화되었는가? | 혼란스러운 설명, 정의 없는 전문 용어, 누락된 컨텍스트, 두서없는 설명 |
| 실행 가능성 | 사용자가 출력을 즉시 실행할 수 있는가? | 모호한 제안, 누락된 단계, 방법을 보여주지 않는 "X를 해야 함", 검증 경로 없음 |
| 간결성 | 필요한 최소한의 단어/토큰을 사용했는가? | 중복, 과잉 설명, 사용자 질문을 그대로 반복, 채우기 내용 |
점수 척도
5 — 탁월함: 합리적인 개선 가능성이 없음
4 — 좋음: 사소한 결점만 있으며, 실질적인 격차는 없음
3 — 적절함: 요청을 충족하지만 적어도 한 축에서 눈에 띄는 약점이 있음
2 — 약함: 사용성 또는 정확성에 영향을 미치는 명확한 격차가 있음
1 — 나쁨: 요청을 근본적으로 놓치거나 심각한 오류가 포함됨
증거 규칙
5 미만의 모든 점수는 특정 증거를 인용해야 합니다. 3점이 "더 나을 수 있음"이라고 말할 수 없습니다. 정확히 무엇이 누락되었거나 잘못되었는지 말해야 합니다. 핵심은 다음과 같습니다: "격차를 보여주고, 이름만 지정하지 마십시오."
워크플로우
1단계: 원자재 수집
평가할 항목을 수집합니다:
- 원래 사용자 요청(대화에서 다시 읽기)
- 최종 응답/출력(인도물)
- 정확성을 확인하는 모든 도구 출력(테스트 결과, 종료 코드, 린트 출력)
- 작업 중에 받은 모든 사용자 피드백(수정, "다시 시도", "맞지 않음")
2단계: 각 축을 독립적으로 점수 매기기
5가지 축을 한 번에 하나씩 작업합니다. 각각에 대해:
- 축 질문 읽기
- 출력에서 증거(또는 증거 부족) 찾기
- 점수 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 — httpx 기반 코드베이스와 일치하지 않는
urllib3을 사용했습니다. 잘못된 라이브러리입니다.
완전성: 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— 벤치마크 작업에서 서로 다른 코딩 에이전트의 일대일 비교verification-loop— 예상 결과에 대한 출력의 체계적인 검증security-review— 보안 중심 코드 검토 체크리스트