실전 패치 루프

Codex의 기본 산출물은 설명이 아니라 리뷰 가능한 patch입니다. 이 문서에서 “패치 루프”는 고치고, 확인하고, 넘기는 한 바퀴를 뜻합니다. 좋은 작업 루프는 범위 정하기 → diff (변경점) 만들기 → 검증하기 → review note (리뷰 메모) → handoff (인수인계) 순서로 닫힙니다.

이 문서를 읽으면

버그 수정, 기능 수정, UI 검증, CI 복구를 같은 방식으로 닫습니다.
Codex 결과를 “잘 됐다”는 말이 아니라 증거로 확인합니다.
리뷰어와 다음 작업자가 바로 판단할 수 있게 남깁니다.

오늘 바로 해볼 일

작은 버그 하나를 골라 “수정 전 재현 증거”와 “수정 후 통과 증거”를 모두 남기게 하세요. 둘 중 하나가 없으면 아직 완료가 아닙니다. 문서 수정처럼 테스트가 애매한 작업이라면 최소한 바뀐 파일, 핵심 diff (변경점), 확인하지 못한 것을 받아야 합니다.

첫 완료 보고로 확인할 것

좋은 첫 결과는 완벽한 수정이 아니라 사람이 다음 판단을 할 수 있는 증거입니다. Codex가 작업을 마치면 아래 형식으로 다시 보고하게 하세요.

완료한 목표:
바뀐 파일:
핵심 diff (변경점):
검증 명령과 결과:
확인하지 못한 것:
남은 위험:

10분 실습의 성공 기준은 간단합니다. 바뀐 파일을 열어볼 수 있고, 어떤 확인을 했는지 알 수 있고, 못 확인한 것이 숨겨지지 않으면 다음 루프로 넘어갈 수 있습니다.

루프별 닫는 기준

루프	목적	닫히는 증거
저장소 탐색	처음 보는 저장소의 진입점과 위험 파악	저장소 지도, 실행 후보 명령
버그 수정	재현 가능한 실패를 작게 수정	test evidence (테스트 증거)
기능 수정	새 기능을 좁은 diff로 구현	diff (변경점), 수락 기준 확인
UI 검증	화면 구현과 브라우저/스크린샷 확인	screenshot note (스크린샷 메모), 반응형 확인
CI 재실행	실패 job을 로컬/CI 차이로 분리	실패 분류, rerun (재실행) 결과
PR 리뷰	사람이 볼 위험을 먼저 드러냄	review note (리뷰 메모), requested changes (요청된 수정)

유스케이스별 완료 증거

공식 유스케이스가 넓어질수록 “Codex가 했다”보다 “사람이 무엇으로 믿을 수 있는가”가 더 중요합니다. 작업 흐름별로 닫는 증거를 먼저 정하면 과한 자동화와 애매한 완료 보고를 줄일 수 있습니다.

유스케이스	확인할 증거
프론트엔드 UI 구현	브라우저 스크린샷, 반응형 폭, 접근성 또는 overflow 확인
대형 코드베이스 이해	요청 흐름 지도, 핵심 파일, 아직 추정인 부분
여러 파일 리팩터링	동작 유지 기준, 작은 diff 묶음, 관련 테스트
문서화	공식 근거 링크, 내부 링크 검사, 변경 기록
MCP/앱 자동화	어떤 앱에서 무엇을 읽고 썼는지, 승인 기록, 실패 시 요약
goal 기반 장기 작업	남은 체크리스트, 완료 기준, 다음 세션이 이어받을 상태

패치 품질 기준

실전 워크숍에서 패치를 볼 때는 “돌아가는가”만 보지 않습니다. 리뷰 비용을 줄이는 패치인지도 함께 봅니다.

기준	좋은 상태	다시 돌릴 신호
범위	요청 범위 안의 파일만 바뀌었습니다.	관련 없는 리팩터링, 포맷 대량 변경, lockfile 변화가 섞임
원인	왜 고쳤는지 재현 증거 또는 판단 근거가 있습니다.	설명은 길지만 실패 조건이 없음
검증	최소 검증과 필요한 확장 검증이 분리되어 있습니다.	“아마 될 것” 또는 테스트 삭제로 통과
리뷰성	리뷰어가 봐야 할 파일과 위험을 먼저 말합니다.	변경 요약만 있고 위험이 없음
회수 가능성	문제가 생기면 되돌릴 수 있는 작은 diff (변경점)입니다.	여러 기능이 한 patch에 묶임
인수인계	확인하지 못한 환경과 다음 작업이 남아 있습니다.	남은 위험이 비어 있거나 지나치게 낙관적임

이 표에서 두 개 이상이 “다시 돌릴 신호”라면 merge 판단보다 패치 루프를 한 번 더 도는 것이 낫습니다.

자가 개선 루프

어려운 작업은 한 번에 끝내려고 하지 말고, 점수를 매기고 다시 돌릴 수 있는 루프로 만듭니다. 이때 “더 해봐”가 아니라 다음 반복에서 무엇을 더 좋아지게 할지 한 가지 기준을 정합니다.

반복 기준	다음 요청 예시
실패 재현	“아직 재현 증거가 약합니다. 실패 조건을 하나 더 좁히고 로그를 남겨주세요.”
테스트 범위	“수정 파일 주변의 가장 작은 테스트만 추가하고, 전체 테스트는 마지막에 돌려주세요.”
UI 품질	“모바일 스크린샷에서 겹침과 넘침만 다시 확인하고 필요한 CSS만 고쳐주세요.”
리뷰 품질	“요약을 줄이고 리뷰어가 봐야 할 위험 3개와 파일 위치를 먼저 적어주세요.”

반복이 끝나는 기준은 “설명이 그럴듯함”이 아니라 같은 검증 명령, 같은 화면, 같은 PR 기준에서 더 이상 새 문제가 나오지 않는 상태입니다.

완료 보고 예시

작업이 끝났다는 말은 짧아도 됩니다. 대신 리뷰어가 바로 확인할 수 있는 증거가 있어야 합니다.

약한 보고	좋은 보고
수정했습니다	`packets.md`에 예시 섹션을 추가했고, `npm.cmd run build`가 통과했습니다. 남은 위험은 예시가 실제 팀 도메인과 다를 수 있다는 점입니다.
테스트는 못 했지만 될 것 같습니다	빌드는 통과했습니다. 브라우저 확인은 하지 못했고, 모바일 긴 문장 overflow는 남은 확인 항목입니다.
CI 고쳤습니다	실패 job은 lockfile 불일치였고, 패키지 버전 고정 후 로컬 build와 redirect 검사가 통과했습니다. CI 재실행은 아직 필요합니다.

완료 보고는 성과 자랑이 아니라 다음 사람이 시간을 덜 쓰게 하는 압축된 handoff (인수인계)입니다.

통제 지점

수정 전에 저장소 탐색 또는 짧은 계획을 요구합니다.
버그 수정은 재현 실패를 먼저 남깁니다.
기능 수정은 수락 기준과 건드리지 않을 범위를 같이 줍니다.
CI 재실행은 설정 완화와 테스트 삭제를 금지합니다.
PR 리뷰는 요약보다 리뷰어가 봐야 할 위험을 먼저 남깁니다.

실패 양상

기능 구현 중 관계없는 리팩터링이 섞입니다.
테스트 없이 “동작할 것”이라고 설명만 합니다.
CI 실패를 로컬에서 재현하지 못했는데 수정 완료로 보고합니다.
UI 작업에서 실제 브라우저 확인 없이 코드만 만듭니다.

남길 증거

diff (변경점) 범위
실행한 테스트, 빌드, 린트 명령
실패한 명령과 이유
리뷰어 집중 포인트
handoff (인수인계): 남은 위험과 다음 작업
확인하지 못한 화면, 환경, CI job