-
Notifications
You must be signed in to change notification settings - Fork 0
06 Checkpoints
이현민 edited this page Jun 15, 2026
·
4 revisions
목적: Agent가 내 지시를 잘못 해석해서 — 비슷한 다른 걸 만들거나, 시키지 않은 걸 끼워 넣거나, 시킨 일을 임의로 줄이거나, "처리했다"고 거짓 보고하는 것 — 사람이 잡기 위한 가이드라인.
typecheck / lint / unit·component test / E2E smoke / 가로 스크롤 / 접근성 같은 기계가 잡을 수 있는 것은 CI·PR 템플릿으로 옮기고, 이 문서는 사람만 잡을 수 있는 해석 fidelity 만 남긴다.
각 PR을 merge 하기 전에 아래 7개를 위에서 아래로 자문한다. 하나라도 답이 흐릿하면 merge 금지.
- spec / 이슈 / 직전 프롬프트의 수용 기준 한 줄씩 손가락으로 짚어가며 PR에서 어디서 만족되는지 보인다.
- 수용 기준에 없던 동작이 추가됐다면 — 그게 아무리 합리적이어도 — 삭제하거나 spec을 먼저 갱신한다.
- Agent가 "비슷하지만 다른 문제" 를 풀었는지 확인. 예: "본인 행만 수정 가능하게 해줘" → 호스트 행만 수정 가능으로 구현하면 다른 문제를 푼 것.
- Diff에서 spec 범위 밖 파일을 모두 따로 본다.
- 자주 발생: 새
utils.ts/helpers.ts/ 새 폴더 / 새 추상화. 합의 없이 생긴 것은 되돌린다. - "어차피 곁다리로 리팩터링했다"는 변경은 별도 PR로 분리.
- 새 의존성 추가 — 정말 필요한가, 표준 라이브러리/이미 있는 패키지로 되지 않는가.
- 수용 기준 중 TODO·placeholder·"추후 구현"·stub 으로 처리된 게 있나? 그건 끝난 게 아니다.
- 에러 처리, 빈 상태, 권한 체크, 인증 — Agent가 "주된 흐름"만 만들고 곁가지를 빠뜨리는 경향이 있다.
- 입력 검증의 negative case: 권한 없는 사용자, 잘못된 입력, 동시 요청, 빈 값. 코드 안에서 막혔는지.
- "Server Action으로 하자"고 했는데 API Route를 깠는가
- "SQLite 유지"라고 했는데 raw SQL/별도 어댑터를 도입했는가
- "기존 X 패턴을 따라라"고 했는데 새 패턴을 도입했는가
- 합의된 라이브러리·디렉터리 구조·네이밍 규칙을 일관되게 따랐는가
- ※ 더 나은 접근이라고 Agent가 판단했더라도, 합의 변경 없이 갈아치우는 것은 fidelity 위반.
- Agent가 PR 본문에 "테스트 통과", "동작 확인" 이라고 쓴 항목은 내가 다시 한 번 실행했는가.
- "기존 패턴을 따랐다"고 적었으면 그 참조 파일을 직접 열어서 같은 구조인지 비교했는가.
- 스크린샷 / 로그 / 명령어 출력처럼 Agent가 위조할 수 없는 증거가 PR에 붙어 있는가.
- "동작은 같다"는 주장이 있는데 동작 동일성을 검증하는 테스트가 함께 추가되었는가.
- "한 줄 버그 수정"이 200줄 diff면 의심.
- Agent가 무의미한 rename / 무의미한 포맷 변경 / import 재정렬을 섞었는가 — 진짜 변경을 보이지 않게 만든다.
- 같은 함수를 두 군데 동일하게 수정했는가 (= 한쪽이 죽은 코드)
- spec과 무관한 파일 변경 = 즉시 빼라고 요구.
- Agent가 단위 동작을 확인했다는 것과, 내가 로그인 → 진입 → 조작 → 결과 확인을 직접 했다는 것은 다른 일이다.
- 로컬 또는 prod에서 진짜 시나리오를 1회 끝까지 흘려본 흔적이 있는가.
- 권한 변경이면 두 계정(예: ADMIN + 일반 멤버)으로 각각 진입해 봤는가.
- 모바일 변경이면 실제 모바일 또는 DevTools 모바일 모드에서 봤는가.
-
검증 위치: PR open 중엔 feature/fix 브랜치에서 자동 테스트, 머지된 변경은
main배포 후 prod smoke 1회. -
Happy path 만으로는 부족. 폼/입력이 있으면 다음 negative case 를 머릿속에서라도 흘려본다 (PR #28/#29 에서 누락한 항목):
- 빈 입력 (특히 "최소 한 가지" 조건의 폼)
- 잘못된 타입 / 음수 / 범위 밖 (예: 초 60 이상)
- 빠른 더블/연속 클릭으로 row 중복 생성
- 권한 없는 사용자로 동일 페이지 진입
- 인증 만료 / 쿠키 삭제 후 새로고침
- 파일 업로드면 framework limit 경계 도 같이: Next Server Actions 기본 1MB 를 넘는 파일이 들어왔을 때 우리 코드의 에러 메시지가 보이는가 (PR #44 사고 — 큰 사진이 generic 413 으로 죽는 동안 inline 에러는 안 떴음)
- Agent 가 "코드 측 검증 통과" 라고 보고하는 것 ≠ 사용자가 동작 확인. 빌드 그린은 시작점.
## Fidelity check (사람 직접 확인)
- [ ] 1. 수용 기준 항목을 하나씩 짚었을 때 PR에서 만족되는 위치가 명확
- [ ] 2. spec 범위 밖 파일/추상화/의존성 추가 없음 (있다면 별 PR로 분리)
- [ ] 3. TODO/placeholder/stub 으로 처리된 수용 기준 없음
- [ ] 4. 합의된 접근법(Server Action / SQLite / 기존 패턴)을 일관되게 따름
- [ ] 5. "테스트/동작 확인" 보고를 내가 다시 한 번 실행해서 확인
- [ ] 6. diff 크기가 변경 범위에 비례 (무의미한 rename/format 없음)
- [ ] 7. 로컬 또는 prod에서 end-to-end 시나리오 1회 직접 흘려봄기계가 잡는 것(typecheck / lint / build / 모바일 레이아웃 / a11y)은 CI와 Lighthouse가, 도메인 모델 결정은 spec이 책임진다. 이 문서는 그 사이 — 사람 판단만 가능한 영역 — 만 다룬다.