실전 패치 루프

AI가 “코드 다 고쳤습니다”라고 말할 때 그 말을 곧이곧대로 믿으면 안 됩니다. AI 코딩에서 가장 위험한 착각은 **“설명이 그럴싸하니 코드도 잘 돌아가겠지”**라고 넘겨짚는 것입니다.

Codex의 진짜 완료는 텍스트 설명이 아니라 **“고친 흔적(diff: 수정 내역서)“과 “합격 통지서(test evidence: 테스트 통과 증거)“**로 닫힙니다.

패치 루프란 거창한 소프트웨어 이론이 아닙니다. **1. 맡기기(범위) ➔ 2. 고치기(diff) ➔ 3. 영수증 검증하기(test) ➔ 4. 남기기(handoff)**로 이어지는 안전한 4단계 검증 한 바퀴를 뜻합니다.

flowchart LR
    A["1. 맡기기<br/>(Scope)"] --> B["2. 고치기<br/>(Patch)"]
    B --> C["3. 영수증 검증<br/>(Evidence)"]
    C --> D["4. 인수인계<br/>(Handoff)"]
    style A fill:#eaf1eb,stroke:#157048,stroke-width:2px
    style B fill:#eaf1eb,stroke:#157048,stroke-width:2px
    style C fill:#eaf1eb,stroke:#157048,stroke-width:2px
    style D fill:#157048,stroke:#0c3a25,stroke-width:2px,color:#ffffff

이 문서를 읽으면

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

오늘 바로 해볼 일

작은 버그 하나를 골라 “수정 전 실패 증거”와 “수정 후 통과 증거”를 둘 다 가져오게 하세요. 둘 중 하나가 없으면 아직 작업이 끝난 것이 아닙니다. 문서 수정처럼 테스트가 없는 작업이라도 최소한 바뀐 파일, 핵심 diff (수정 내역서), 확인하지 못한 것을 명확히 받아야 합니다.

첫 완료 보고로 확인할 것

첫 결과의 목표는 단번의 수정 완료보다는 다음 단계의 판단을 내릴 수 있는 근거 제공입니다. Codex가 작업을 마치면 아래 형식으로 다시 보고하게 하세요.

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

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

루프별 닫는 기준

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

TUI 세션 운영 팁:

작업 디렉토리 제어: TUI 세션을 재시작하지 않고도 /cd <경로>, /pwd, /cwd 명령으로 현재 작업 위치를 전환하거나 확인할 수 있습니다.

코드 블록 선택 복사 (/copy): 전체 응답 대신 필요한 특정 코드 블록이나 인용구만 인터랙티브 선택기로 골라 클립보드에 복사합니다.

세션 맥락 타이틀링 (/rename): 세션 대화 맥락을 분석해 제안된 제목으로 세션 이름을 정돈하여 추후 탐색 비용을 줄입니다.

세션 큐잉 (codex queue): 이미 실행 중인 백그라운드 세션이나 원격 호스트에 인터럽트 없이 추가 작업 메시지를 전달할 때 codex queue 명령을 사용합니다.

유스케이스별 완료 증거

공식 유스케이스가 넓어질수록 “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

공식 문서

📖 함께 읽으면 좋은 문서

안전선과 승인 기준: 패치 루프 안에서 패키지 설치, 네트워크, sandbox를 어디서 멈출지 정합니다.
작업 요청서: 패치 루프를 시작하기 전 목표, 범위, 금지선을 한 장으로 묶는 법을 봅니다.