에이전트 출력 eval 체크리스트
에이전트가 PR·패치·커밋 메시지까지 빠르게 채워도, 머지 직전 eval은 사람(또는 CODEOWNERS) 게이트입니다. diff를 “읽기 순서”로만 훑으면 기능 회귀·시크릿 근접·빈약한 문서/커밋 한 줄이 빠져나가기 쉽습니다. 그래서 출력 품질 축별 체크리스트가 필요합니다.
이 글은 **기능·회귀는? · 보안·시크릿은? · 문서·커밋 메시지는?**만 다룹니다. agent-diff-review는 stat→의도→위험 경로→테스트 짝 같은 diff 읽기 순서 축입니다. 여기서는 머지 전에 통과/실패를 찍는 eval 문항에 초점을 둡니다. 요금·플랜·토큰·제휴 링크는 없습니다.
기능·회귀는?
한 줄 답: 티켓의 성공 기준(Done) 과 비범위를 기준으로, 새/변경 동작이 재현 가능한가와 기존 핵심 경로가 깨지지 않았는가를 각각 통과해야 합니다. “에이전트가 통과했다고 함”은 eval 결과가 아닙니다.
머지 전 기능·회귀 eval:
| 문항 | 통과 조건 | 실패 시 |
|---|---|---|
| Done 매핑 | PR/브리프 Done 항목마다 증거(명령·화면·로그 경로)가 있음 | 빈 Done·주장만 → 머지 보류 |
| 비범위 | Out-of-scope에 적힌 것이 diff에 안 들어옴 | 범위 밖 리팩터·의존성 갱신 → 되돌리거나 분리 PR |
| 신규 경로 | 해피 패스 + 최소 1개 실패/경계 시나리오 | 해피만 → 조건부 보류 또는 후속 티켓 필수 |
| 회귀 | 팀이 합의한 스모크/관련 스위트 green | 빨강·스킵으로 초록 위장 → 머지 금지 |
| 계약 | 공개 API·스키마·권한 플래그 변경이 Done에 명시 | 암묵적 브레이킹 → 보류 |
복붙용:
[ ] Done 각 항목에 증거 경로(명령/CI/수동)가 있는가?
[ ] Out-of-scope가 diff에 섞이지 않았는가?
[ ] 신규 동작: 해피 + 실패/경계 최소 1?
[ ] 관련 회귀 스위트/스모크 green? skip·assertion 완화 없음?
[ ] API/스키마/권한 변경이 Done에 명시됐는가?에이전트 출력에서 자주 빠지는 것: 재현 명령 없이 “수정됨”만 적기, flaky만 타임아웃 상향, “동작 동일” 주장에 스위트 없음. agent-tdd-loop는 작성 중 red→green이고, 이 절은 머지 직전 기능·회귀 합격 여부입니다.
보안·시크릿은?
한 줄 답: diff·커밋·로그·이슈 본문에 시크릿·자격 증명·내부 URL·개인식별이 없는지 확인하고, 권한 확대·인증 우회·기본값 완화가 있으면 명시적 리뷰어 + 롤백 단위 없이는 머지하지 않습니다.
보안·시크릿 eval 표:
| 표면 | 볼 것 | 통과 |
|---|---|---|
| 시크릿 혼입 | .env*, 키·토큰·PEM, 하드코드 패스워드, 에이전트 채팅 붙여넣기 | 없음. 있으면 커밋 이력까지 제거·회전 계획 |
| 로그·스크린샷 | 예제 출력, capture, CI 로그에 토큰·쿠키 | 마스킹 또는 삭제 |
| 권한 | authz 체크 삭제, * allow, CORS/공개 ACL 확대 | Done에 명시 + 소유자 승인 |
| 공급망 | 잠금파일·새 의존성·postinstall 스크립트 | 설치·빌드·핵심 테스트 + 출처 확인 |
| 데이터 | 프로덕션 덤프·실사용자 PII 픽스처 | 합성/익명화만 |
복붙용:
[ ] diff/커밋/PR 본문에 시크릿·키·토큰 없음?
[ ] 예제·로그·스크린샷 마스킹?
[ ] 권한·인증·공개 ACL 변경이 Done에 있고 소유자 승인?
[ ] 새 의존성·잠금파일 변경 사유와 검증 명령?
[ ] 실데이터/PII 픽스처 없음?
[ ] 유출 의심 시: 머지 금지 + 키 회전 런북주의: agent-diff-review의 “위험 경로를 읽기 순서에 넣는다”와 겹쳐 보이지만, 여기는 합격/불합격 문항과 시크릿 사고 시 조치입니다. “리뷰에서 봤다”만으로는 eval 통과가 아닙니다.
문서·커밋 메시지는?
한 줄 답: 사람이 6개월 뒤에도 의도·비범위·검증 방법을 복원할 수 있어야 합니다. 제목은 무엇/왜, 본문은 검증·리스크·후속, 문서(README·ADR·런북)는 동작 변경과 짝이 있어야 합니다.
문서·커밋 eval:
| 항목 | 통과 기준 | 흔한 실패 |
|---|---|---|
| 커밋/PR 제목 | 범위가 한 문장으로 읽힘 (모듈·동작) | fix, update, agent changes |
| 본문 | Done / Out-of-scope / 검증 명령·결과 | “테스트 통과함”만, 증거 경로 없음 |
| 리스크 한 줄 | 시크릿·마이그레이션·플래그·롤백 단위 | 공란인데 위험 경로 변경 |
| 문서 짝 | 사용자/운영이 바뀌면 README·런북·API 노트 갱신 | 코드만 변경, 문서 방치 |
| 이슈 링크 | 티켓·후속 ID | “나중에”만 있고 ID 없음 |
복붙용:
[ ] 제목이 모듈·동작을 가리키는가? (fix/update만 아닌가?)
[ ] 본문에 Done / Out-of-scope / 검증 증거?
[ ] 위험 변경이면 리스크·롤백 한 줄?
[ ] 동작·운영 변경에 문서 짝?
[ ] 후속 작업에 티켓 ID?
[ ] 에이전트 생성 “셀프 리뷰 장문”만으로 본문을 대체하지 않음경계: agent-diff-review는 파일을 어떤 순서로 볼지, 이 절은 머지 기록·온보딩 문서가 eval을 통과하는지입니다. 둘 다 통과해야 머지합니다.
FAQ
agent-diff-review 글과 무엇이 다른가요?
그 글은 diff를 사람처럼 읽는 순서(stat·의도·위험·테스트 짝·스타일). 이 글은 머지 전 출력 eval 문항—기능·회귀 합격, 보안·시크릿 합격, 문서·커밋 합격—입니다. 읽기 순서만 끝내고 eval 표를 건너뛰면 안 됩니다.
eval을 에이전트에게 스스로 채우게 해도 되나요?
초안은 가능합니다. 최종 체크·Approve는 사람이 합니다. 셀프 eval만으로 초록 처리하면 본문과 코드 불일치가 반복됩니다.
문서만 바꾸는 PR도 같은 표를 쓰나요?
기능·회귀 열은 런타임 영향 없음으로 짧게 통과시키고, 링크·오타·프리뷰와 커밋 메시지 축은 그대로 적용합니다. 시크릿이 예제에 들어가지 않았는지도 봅니다.
체크리스트가 길어서 매번 못 돕니다.
팀 최소 5문항(Done 증거, 회귀 green, 시크릿 없음, 제목/본문, 문서 짝)만 고정하고, 위험 경로 PR에만 보안 표를 전부 엽니다.
출처 (Sources)
- 팀 관행: 머지 전 기능·회귀 / 보안·시크릿 / 문서·커밋 eval — 본문 체크리스트
- 인접 축: agent-diff-review(diff 읽기 순서), agent-tdd-loop(작성 중 red→green), multi-agent-pr-workflow(브랜치·게이트)