테마 전환

Codex 실패 사례 검증: AI가 코드를 망가뜨리는 이유와 검수 절차

Easton editorial illustration: one raised charcoal terminal console with a small exec prompt, three compact output artifacts: changelog sheet, issue-tag stack, documentation checklist, one small lock gate leading to a separate patch or pull-request card

"OpenAI Codex best practices는 coding task에서 명확한 goal, context, constraints, done criteria, testing, checks, review를 강조합니다."

git diff --stat에 갑자기 18개 파일이 나타납니다. Codex에 준 작업은 “버튼 상태 하나 수정”이었을 뿐입니다. CI는 모두 초록색입니다. 그런데 diff를 열어 보면 coverageThreshold가 낮아졌고, flaky test 하나가 skip으로 바뀌었으며, 이미 저장소에 emailSchema가 있는데도 validateEmail() helper가 새로 생겼습니다.

Codex가 일부러 코드를 망가뜨린 것은 아닙니다. 작업 경계가 너무 넓었고, 검수 흐름이 너무 느슨했습니다. 이 글은 “AI를 믿어도 되는가”라는 추상 논쟁이 아닙니다. 실패 패턴 표, 검수 게이트, rollback 흐름, review checklist를 통해 실패를 우연이 아니라 프로세스의 빈틈으로 다루는 방법입니다.

실패 패턴 표: AI가 코드를 망가뜨릴 때의 전형

GitHub의 33k개 agent-authored PR을 분석한 arXiv 연구는, merge되지 않은 PR이 더 크고 더 많은 파일을 건드리며 프로젝트 CI/CD 검증에 실패하는 비율도 높다는 점을 관찰했습니다. 이는 AI agent의 지능만의 문제가 아닙니다. 작업 분해, 수락 기준, reviewer engagement가 함께 작용합니다.

자주 나오는 9가지 실패 패턴과 신호, 첫 대응은 다음과 같습니다.

패턴모습판단 신호첫 대응
diff가 너무 큼변경 범위가 요청을 크게 벗어남git diff --stat에서 “버튼 수정”인데도 10+ 파일처럼 작업 설명보다 훨씬 많은 파일이 바뀜먼저 file list를 보고 예상 변경과 scope 밖 변경을 나눕니다. scope 밖 변경은 작업을 나누거나 revert합니다
가짜 초록 테스트테스트는 통과하지만 로직이 틀림diff에서 coverageThreshold가 낮아지거나 flaky test가 skip이 되거나 assertion이 약해짐테스트 설정이 바뀌었는지 확인합니다. 변경 전에는 실패하는 regression test를 요구합니다
잘못된 디렉터리CI 설정이나 무관한 파일이 바뀜작업과 무관한데 .github/workflows/, Makefile, package.json scripts가 바뀜AGENTS.md가 CI/config 변경을 금지하는지 확인합니다. revert 후 규칙을 남깁니다
중복 코드이미 있는 helper/util을 생성함새 helper가 생겼지만 저장소에 같은 기능의 함수나 schema가 있음기존 구현을 검색합니다. 중복이면 revert하고 기존 구현을 쓰라고 Codex에 지시합니다
PR이 너무 큼plan 없는 큰 PRPR body가 “fix issue”뿐이고 implementation plan, 검증 명령, rollback 설명이 없음독립적으로 review, 검증, rollback 가능한 작은 PR로 나누라고 요구합니다
CI 약화체크를 통과시키려고 CI 설정을 바꿈CI가 실패했는데 비즈니스 코드 대신 test/CI 설정만 바뀜blocker로 봅니다. CI 변경을 revert하고 비즈니스 코드 수정을 요구합니다
숨은 비즈니스 오류로직은 맞아 보이지만 업무 제약을 어김권한 검사나 데이터 validation이 삭제됐지만 테스트가 해당 경로를 보지 않음critical path를 하나 추적하고 부작용을 확인합니다. reviewer의 명시적 approve를 요구합니다
Untrusted input외부 입력을 검증 없이 사용함Codex가 사용자 제공 데이터나 path를 sanitization 또는 validation 없이 직접 사용함input validation을 확인합니다. 없다면 validation test를 요구합니다
plan 없는 큰 변경plan 전에 구현을 시작함수정할 파일, 건드리지 않을 파일, 검증 명령을 나열하기 전에 Codex가 코드를 편집함먼저 /plan 또는 명확한 goal/context/constraints/done criteria를 요구합니다

이 패턴들은 고립되어 나타나지 않습니다. “diff가 너무 큰” PR은 “잘못된 디렉터리”, “중복 코드”, “가짜 초록 테스트”를 동시에 포함할 수 있습니다. GitHub의 agent PR review checklist도 CI gaming, 코드 재사용 누락, 숨은 correctness 문제, plan 없는 큰 PR을 agent-generated PR의 주요 경고 신호로 봅니다.

첫 원칙은 간단합니다. CI가 초록색인지부터 보지 마세요. diff scope와 rollback 가능한 단위를 먼저 봐야 합니다.

작업 분해 흐름: 큰 작업도 Codex에 맡길 수 있습니다

OpenAI best practices는 복잡하거나 모호한 작업에서 구현 전에 plan을 세우라고 권합니다. Codex는 검증 가능한 상태에서 더 좋은 결과를 내기 쉽고, 작고 집중된 작업은 테스트와 review가 쉽습니다.

하지만 “작게 나누기”는 막연한 구호가 아닙니다. 각 단계를 독립적으로 검증하고 rollback할 수 있을 때가 적절한 크기입니다.

7단계 폐루프: scope에서 update rules까지

Codex 변경에는 다음 검수 루프를 사용합니다.

scope -> plan -> patch -> verify -> review -> merge/rollback -> update rules

각 단계에는 질문과 되돌아갈 조건이 있습니다.

1. scope

질문:

  • 작업을 goal + context + constraints + done criteria로 구체적으로 쓸 수 있나요?
  • auth, payment, notification처럼 여러 하위 시스템을 넘나드나요?
  • CI 설정, database schema, 외부 의존성에 영향을 줄 수 있나요?

되돌아갈 조건: 여러 하위 시스템을 넘거나 CI/config에 영향이 있으면 먼저 별도 작업으로 나눕니다.

2. plan

질문:

  • Codex가 예상 변경 파일, 건드리지 않을 파일/디렉터리, 검증 명령을 먼저 나열했나요?
  • plan에 위험과 종료 조건이 있나요?
  • plan에 rollback 경로가 있나요?

되돌아갈 조건: plan이 없거나 위 항목이 빠졌다면 다시 /plan을 요구합니다.

3. patch

질문:

  • git diff --stat이 plan의 파일 scope와 맞나요?
  • CI/config나 무관한 파일처럼 scope 밖 변경이 있나요?
  • 이미 존재하는 helper 같은 중복 코드를 만들었나요?

되돌아갈 조건: diff가 plan과 맞지 않거나 경고 신호가 있으면 step 2로 돌아갑니다.

4. verify

질문:

  • core path를 덮는 테스트가 추가됐나요?
  • 그 테스트는 변경 전에는 실패하나요?
  • CI status checks가 required이고 skipped가 아닌가요?
  • lint/pre-commit이 통과했나요?

되돌아갈 조건: 관련 테스트가 없거나 테스트 설정을 약하게 만들어 통과시켰다면 step 3으로 돌아갑니다.

5. review

질문:

  • diff scope가 작업과 맞나요?
  • critical path 하나를 추적했나요?
  • AI의 완료 보고가 아니라 사람 reviewer가 명시적으로 approve했나요?
  • branch protection이 required reviews/status checks/conversation resolution을 요구하나요?

되돌아갈 조건: reviewer가 request changes를 하거나 경고 신호가 있으면 step 3으로 돌아갑니다.

6. merge/rollback

질문:

  • 다음 장의 검증 증거 checklist를 만족하나요?
  • hunk/file 단위로 독립적으로 되돌릴 수 있나요?
  • 실패한 작업은 버리고 성공한 작업만 PR로 보낼 수 있도록 worktree로 격리했나요?

되돌아갈 조건: 증거가 부족하거나 독립적으로 되돌릴 수 없다면 rollback하고 step 1로 돌아갑니다.

7. update rules

질문:

  • 실패가 AGENTS.md 규칙 부족에서 왔나요? 예를 들어 “CI 설정 변경 금지”, “5개 파일 초과 변경은 작업 분리” 같은 규칙입니다.
  • 금지 영역, 수락 기준, rollback 경로를 AGENTS.md에 써야 하나요?

행동: 규칙 부족이 원인이면 AGENTS.md에 씁니다.

큰 작업도 Codex에 맡길 수 있습니다

큰 리팩터링을 Codex에 맡기면 안 되는 것은 아닙니다. 다만 각 단계를 단독으로 rollback할 수 있을 때까지 나누어야 합니다. AI로 10,000줄을 리팩터링한 경험도 작은 단계와 테스트 안전망이 중요하다는 점을 보여줍니다.

충분히 작게 나누었는지는 다음으로 판단합니다.

  • 각 patch를 hunk/file 단위로 독립적으로 revert할 수 있나요?
  • 각 verify가 pre-change에서 실패한다는 것을 증명할 수 있나요?
  • 각 merge에 명확한 reviewer approve와 status checks가 있나요?

대답이 “아니요”라면 작업은 아직 큽니다.

Codex review pane 실전: 검수는 테스트만 보는 일이 아닙니다

Codex 변경을 검수할 때 첫 번째로 볼 것은 테스트 결과가 아닙니다. diff scope와 rollback 단위입니다. Codex app의 review pane은 세 가지 view와 hunk/file 단위 조작을 제공합니다.

세 가지 diff view

review pane은 Codex 변경만 보여주는 것이 아니라 Git 저장소 상태를 반영합니다. Codex 변경, 사용자 변경, 다른 uncommitted changes가 함께 보일 수 있습니다.

View표시 내용사용 상황
uncommitted changes모든 uncommitted changes, 기본값현재 Codex 작업의 변경 범위를 검수
all branch changes현재 branch와 base branch의 전체 차이여러 task나 turn의 누적 변경을 검수
last turn changes직전 Codex turn의 변경방금 Codex가 한 일을 분리해 scope 밖 변경을 빠르게 확인

먼저 uncommitted changes로 scope가 넓어지지 않았는지 확인합니다. 다음으로 all branch changes에서 이전 작업의 잔여 변경을 확인합니다. 마지막으로 last turn changes에서 Codex가 plan대로 움직였는지 봅니다.

inline comments와 hunk/file 단위 조작

review pane은 diff의 특정 줄에 inline comments를 달 수 있습니다. 이 comment는 이후 Codex 수정의 컨텍스트가 될 수 있습니다.

조작 단위:

  • entire diff: 전체 diff를 stage/unstage/revert
  • file: 단일 파일을 stage/unstage/revert
  • hunk: 단일 코드 블록을 stage/unstage/revert, 가장 작은 유용한 단위

CI 설정 삭제 같은 scope 밖 변경을 발견하면 전체 diff를 버리기 전에 해당 hunk/file만 먼저 revert할 수 있습니다.

PR context 로딩

PR branch에 있고 GitHub access 또는 gh auth login이 가능하면 review pane은 PR context, review comments, changed files를 불러올 수 있습니다. 그러면 검수는 “로컬 diff 보기”에서 “PR diff와 reviewer comments 함께 보기”로 넘어갑니다.

변동 가능 사실 알림: UI와 slash command 세부 동작은 바뀔 수 있습니다. 정확한 동작이 중요하면 공개 전에 공식 페이지를 다시 확인하세요.

검수의 핵심 원칙

검수는 테스트만 보는 일이 아닙니다.

  1. 먼저 diff scope가 plan과 맞는지 봅니다
  2. 다음으로 rollback 단위가 hunk/file처럼 충분히 작은지 봅니다
  3. 마지막으로 테스트가 추가됐고 critical path를 덮는지 봅니다

앞의 두 가지가 만족되지 않으면 테스트가 통과해도 코드가 맞다는 뜻은 아닙니다.

검증 증거 checklist: 테스트 통과만으로는 부족합니다

GitHub Docs는 protected branch에 merge하려면 required status checks가 successful, skipped, neutral 상태여야 한다고 설명합니다. GitHub Actions에서는 skipped check가 success처럼 처리되어 merge를 막지 못할 수 있습니다.

따라서 “CI가 초록색”은 “코드가 좋다”와 같지 않습니다. 필요한 것은 하나의 신호가 아니라 여러 증거입니다.

다음 checklist를 사용합니다.

코드 레벨 증거

  • diff scope가 작업과 맞고 scope 밖 변경이 없음
  • 중복 코드가 추가되지 않았고 기존 구현을 검색했음
  • 작업이 명시적으로 허용하지 않은 한 CI/config를 변경하지 않음

테스트 레벨 증거

  • core path를 위한 테스트가 추가됨
  • 테스트가 변경 후에만 통과하는 것이 아니라 변경 전에는 실패함
  • coverageThreshold 낮춤, skip, 약해진 assertion처럼 테스트 설정이 약해지지 않음

CI 레벨 증거

  • lint/pre-commit이 통과함
  • CI status checks가 required이고 skipped가 아님
  • check를 통과시키기 위해 CI 설정을 바꾸지 않음

PR 레벨 증거

  • PR body에 implementation plan, 검증 명령, rollback 설명이 있음
  • AI의 완료 보고가 아니라 사람 reviewer가 명시적으로 approve함
  • branch protection이 required reviews/status checks/conversation resolution을 포함함

rollback 레벨 증거

  • 각 patch가 hunk/file 단위로 독립적으로 revert 가능함
  • 실패한 시도는 버리고 성공한 것만 PR로 보낼 수 있도록 worktree로 작업을 격리함

branch protection과 status checks

GitHub protected branches는 다음을 요구할 수 있습니다.

  • required reviews: 지정된 수의 reviewer approve 이후 merge
  • required status checks: protected branch에 들어가기 전 checks가 pass, skipped, neutral이어야 함
  • conversation resolution: 모든 대화가 resolved된 뒤 merge

이는 AI 바깥의 merge gate입니다. AI가 완료했다고 말하는 것으로 대체되지 않습니다.

review 순서

다음 순서를 사용합니다.

  1. 먼저 file list와 diff size를 포함해 diff scope를 봅니다
  2. 다음으로 CI/test config가 바뀌었는지 봅니다
  3. 다음으로 테스트가 추가됐고 core path를 덮는지 봅니다
  4. 마지막으로 reviewer가 명시적으로 approve했는지 봅니다

순서를 뒤집지 마세요. 테스트부터 보면 scope 밖 변경과 약해진 CI를 놓치기 쉽습니다.

rollback과 회고: 나쁜 변경 뒤에 무엇을 할 것인가

review에서 scope 밖 변경이나 가짜 초록 테스트가 발견되면 첫 대응은 rollback입니다. 같은 혼란스러운 diff 위에서 Codex에게 계속 고치게 하는 것이 아닙니다.

rollback 단위: hunk에서 branch까지

변경 범위와 실패 원인에 따라 rollback 단위를 고릅니다.

단위사용 상황조작
hunk 레벨 revertCI 설정 삭제처럼 단일 코드 블록에 scope 밖 변경이 있음review pane에서 해당 hunk 선택 -> revert
file 레벨 revert파일 전체가 중복 코드나 scope 밖 변경을 포함함review pane에서 해당 file 선택 -> revert
branch 폐기작업 방향 전체가 틀렸고 여러 파일을 버려야 함git checkout main -> branch 삭제

쓸 수 있는 가장 작은 단위를 우선합니다. 여러 hunk/file이 모두 문제일 때만 branch 폐기를 고려합니다.

worktree 격리: 실패한 시도는 버릴 수 있습니다

이 시리즈의 Codex Worktree 글은 worktree로 병렬 작업을 격리합니다. 실패한 시도는 버리고, 성공한 시도만 PR로 보낼 수 있습니다.

worktree 안의 작업이 코드를 망가뜨렸다면 그 worktree를 삭제하면 됩니다. main workspace에 영향을 주지 않습니다. 같은 branch에서 반복적으로 revert하는 것보다 안전합니다.

rollback 후 행동: AGENTS.md에 쓰기

rollback 뒤에는 실패가 규칙 부족에서 왔는지 판단합니다. 그렇다면 AGENTS.md에 씁니다.

다음 질문을 봅니다.

  • “CI 설정 변경 금지”, “5개 파일 초과 시 작업 분리” 같은 프로젝트 규칙이 부족했나요?
  • “테스트는 변경 전 실패를 증명해야 한다” 같은 수락 기준이 부족했나요?
  • “각 patch는 독립적으로 revert 가능해야 한다” 같은 rollback 규칙이 부족했나요?

그렇다면 다음 장의 기준에 따라 알맞은 AGENTS.md에 씁니다.

회고 후 행동: 반복되는 흐름은 skill로 만들기

실패를 skill로 만들지 판단할 때는 다음을 봅니다.

  • 실패가 비즈니스 제약을 이해하지 못하는 등 Codex의 능력 경계에서 왔나요?
  • 여러 agent 협업처럼 복잡한 다단계 흐름에서 왔나요?
  • diff scope, CI config, 테스트 추가를 매번 확인하는 반복 검수 흐름에서 왔나요?

그렇다면 이 시리즈의 Codex Skills/plugins 글처럼 skill화를 고려합니다.

AGENTS.md에 규칙을 어디에 둘 것인가

Codex는 run/session 시작 전 instruction chain을 만들고 global 및 project AGENTS.md를 읽습니다. project 레벨에서는 Git root에서 현재 디렉터리까지 순서대로 읽고, 더 가까운 파일을 더 구체적인 규칙으로 봅니다.

즉 AGENTS.md는 repository root, submodule 디렉터리, 기능 디렉터리에 둘 수 있습니다. Codex는 겹치는 경로에서 더 구체적인 규칙을 우선해야 합니다.

AGENTS.md의 일반적인 위치와 내용

이 시리즈의 Codex 입문 가이드는 일반적인 AGENTS.md 템플릿을 다룹니다.

위치일반적인 내용예시
repo rootrepo layout, build/test/lint commands, engineering conventionsProject structure: src/frontend, src/backend, src/shared; build: npm run build; test: npm test; lint: npm run lint
src/frontendfrontend-specific conventions, PR expectationsfrontend는 React hooks만 쓰고 class components는 쓰지 않음. PR에는 Storybook stories 포함
src/backendbackend-specific conventions, do-not rulesbackend는 database에 직접 접근하지 않음. ORM 사용. controller에 SQL 작성 금지
src/sharedshared utility conventionsshared에는 pure functions만 두고 side effects를 두지 않음

실패 경험을 어디에 쓸 것인가

실패 후에는 원인에 따라 규칙 위치를 정합니다.

실패 원인쓸 위치예시
CI 설정을 실수로 삭제repo root -> PR expectations -> do-not rules명시적 승인 없이 .github/workflows/, Makefile, package.json scripts를 변경하지 않음
5개 파일 초과 변경repo root -> PR expectations -> do-not rules5개 파일을 넘는 변경은 분리함. 각 작업은 최대 3개 파일로 제한
가짜 초록 테스트repo root -> what done means테스트는 core path를 덮고 변경 전 실패를 증명해야 함. 변경 후만 테스트하지 않음
중복 코드repo root -> engineering conventionssrc/lib 아래 helper를 추가하기 전 기존 동등 구현을 검색함. 있으면 기존 구현 사용
plan 없는 큰 변경repo root -> PR expectations3개 파일을 넘는 변경은 먼저 /plan을 내고 수정 파일, 금지 파일, 검증 명령을 나열함
Untrusted inputsrc/backend -> engineering conventions모든 사용자 입력은 validation해야 함. 사용자 제공 데이터나 path를 직접 사용하지 않음
숨은 비즈니스 오류src/backend -> engineering conventionspermission checks나 validation 변경 후 critical path 하나를 추적하고 부작용을 확인함

규칙 발견: 더 가까운 파일이 우선입니다

OpenAI의 AGENTS.md 문서는 project instruction을 Git root에서 현재 디렉터리까지 이어지는 chain으로 설명하며, 더 가까운 파일이 더 구체적입니다.

실무에서는 다음처럼 나눕니다.

  • repo root의 AGENTS.md: build/test/lint commands, “CI 변경 금지” 같은 공통 규칙
  • submodule의 AGENTS.md: frontend는 hooks만, backend는 SQL 금지 같은 구체 규칙
  • 기능 디렉터리의 AGENTS.md: 특정 API의 비즈니스 제약 같은 가장 구체적인 규칙

교훈을 쓸 때는 다음처럼 판단합니다.

  • “CI 변경 금지” 같은 전역 규칙은 repo root
  • frontend 규칙 같은 submodule 규칙은 src/frontend
  • 특정 API 비즈니스 제약은 src/backend/api/xxx

AGENTS.md의 한계

AGENTS.md는 scope 밖 변경과 실수를 줄이지만 코드의 correctness를 증명하지 않습니다. Codex가 AGENTS.md를 따르더라도 로직이 틀릴 수 있습니다.

마지막 gate는 여전히 사람 reviewer의 명시적 approve입니다. 규칙 파일이 있다는 사실만으로 품질이 보장되지는 않습니다.

AI PR을 사람이 review할 때의 경고 신호

GitHub의 agent-generated PR review 조언은 file list와 diff size에서 시작합니다. 그다음 CI/test config 변경 여부를 보고, 중복 helper를 검색하고, critical path를 추적하며, 변경 전 실패를 증명하는 테스트를 요구합니다.

다음 경고 checklist를 사용합니다.

코드 레벨 경고

  • file list와 diff size가 작업 설명보다 훨씬 큼
  • .github/workflows/, Makefile, package.json scripts 같은 CI/test config가 바뀜
  • 새 helper가 기존 helper와 중복됨
  • PR body가 “fix issue”뿐이고 implementation plan, 검증 명령, rollback 설명이 없음
  • 10개 파일을 넘는 큰 PR

테스트 레벨 경고

  • 새 테스트가 없음
  • 테스트가 post-change만 보고 이전 동작의 실패를 증명하지 못함
  • coverageThreshold 낮춤, flaky test skip, 약해진 assertion처럼 테스트 설정이 약해짐

CI 레벨 경고

  • CI가 실패했는데 business code 대신 tests 또는 CI config만 바뀜
  • CI status checks가 passing이 아니라 skipped 또는 neutral
  • check를 통과시키려고 CI 설정이 바뀜

PR 레벨 경고

  • PR body가 비어 있음
  • implementation plan 없음
  • reviewer approval 없이 AI 완료 보고만 있음
  • conversation이 unresolved 상태임

blocker 신호와 분리 신호

유형경고 신호대응
blockerCI가 실패했는데 test/CI config만 바뀜request changes, CI 변경 revert, business code 수정 요구
blockercoverageThreshold 낮춤이나 skip 같은 가짜 초록 테스트request changes, test config 변경 revert, 새 테스트 요구
blockervalidation 없는 untrusted inputrequest changes 및 validation tests 요구
분리 신호10개 파일을 넘는 큰 PRrequest changes, 더 작은 PR로 분리
분리 신호implementation plan 없는 빈 PR bodyrequest changes, plan, 검증 명령, rollback 설명 추가

reviewer의 핵심 원칙

reviewer는 “AI가 믿을 만한가”라는 추상 질문을 판단하지 않습니다. 확인하는 것은 다음입니다.

  1. diff scope가 작업 설명과 맞는가
  2. CI/test config가 바뀌었는가
  3. 테스트가 추가됐고 core path를 덮는가
  4. critical path를 따라 숨은 부작용을 확인했는가

순서를 뒤집지 마세요. 테스트부터 보면 약해진 CI와 scope 밖 변경을 놓치기 쉽습니다.

결론

Codex가 코드를 망가뜨리는 원인은 추상적으로 “신뢰할 수 없어서”가 아닙니다. 작업 경계가 너무 넓고 수락 프로세스가 너무 느슨한 경우가 많습니다. 실무 checklist는 다음과 같습니다.

  • 실패 패턴 표: Codex 변경이 잘못되는 흔한 방식을 인식합니다
  • 7단계 폐루프: scope에서 update rules까지의 전체 수락 흐름
  • review pane 실전: 테스트에서 멈추지 말고 diff scope와 rollback 단위를 먼저 봅니다
  • 검증 증거 checklist: 테스트 통과만으로 부족하며 diff scope, 추가 테스트, CI status, 사람 review, branch protection도 봅니다
  • rollback과 회고: hunk/file 레벨 revert, worktree 격리, AGENTS.md 또는 skill에 쓰기
  • AGENTS.md 위치: scope에 따라 repo root, submodule, 기능 디렉터리에 규칙 배치
  • 사람 review 경고 신호: file list와 diff size에서 시작해 CI/test config, 추가 테스트, reviewer approval 순서로 봅니다

이 checklist를 실제 review 도구로 쓰세요. Codex 변경을 검수할 때마다 항목을 따라갑니다. 같은 review 흐름이 반복된다면 Codex Skills/plugins 글처럼 skill로 만드는 것을 고려합니다.

실패는 우연이 아닙니다. 프로세스의 빈틈입니다.

다음 단계와 함께 읽을 글

게시된 글

같은 시리즈: Codex 실전 가이드

  • Codex 완전 입문 가이드 — CLI, IDE, Cloud, desktop 진입점
  • Codex 보안과 권한 — sandbox/approval로 위험 낮추기
  • Codex 코드 리뷰 — review를 수락 gate 중 하나로 사용하기
  • Codex 자동화 작업 — exec가 만든 patch도 사람 review가 필요함
  • Codex Worktree 실전 — 병렬 작업 격리
  • Codex Skills/plugins — 검수 흐름을 skill로 만들기
  • Codex 테스트 주도 개발 — TDD + Codex
  • Codex 비용 최적화
  • Codex 엔터프라이즈 도입

Codex 변경 검수 흐름 설계하기

Codex 작업을 검증 가능하고 되돌릴 수 있는 단위로 나누고, diff review, 테스트, CI, 사람의 review, 규칙 업데이트까지 닫는 절차입니다.

⏱️ Estimated time: 45 min

  1. 1

    Step 1: 작업 경계를 정의합니다

    prompt나 AGENTS.md에 goal, context, constraints, done criteria를 적습니다. 특히 수정 가능한 파일, 건드리면 안 되는 디렉터리, 검증 명령을 명확히 합니다.
  2. 2

    Step 2: Codex가 먼저 plan을 만들게 합니다

    예상 파일 범위, 건드리지 않을 영역, 검증 명령, 위험, rollback 경로를 Codex가 먼저 나열하게 합니다. plan이 부족하면 구현으로 넘어가지 않습니다.
  3. 3

    Step 3: 되돌릴 수 있을 때까지 나눕니다

    큰 작업은 동작, 모듈, 테스트, 마이그레이션 단계별로 나눕니다. 각 단계는 독립적으로 revert할 수 있어야 합니다.
  4. 4

    Step 4: diff scope를 검토합니다

    git diff --stat, file list, last turn changes, all branch changes를 먼저 봅니다. 합의한 범위를 벗어난 변경이 없는지 확인합니다.
  5. 5

    Step 5: 관련 검증을 실행합니다

    관련 단위 테스트, build, lint, 수동 critical path를 실행하고, 실행하지 않은 예상 명령이 있다면 이유를 남깁니다.
  6. 6

    Step 6: CI가 약해졌는지 확인합니다

    skip, 낮아진 coverage threshold, 약해진 workflow trigger, || true 등 초록색 CI의 의미를 약하게 만드는 신호가 있는지 확인합니다.
  7. 7

    Step 7: 사람의 review를 거칩니다

    AI review는 추가 신호로만 봅니다. merge 결정은 여전히 사람 reviewer, required status checks, branch protection, conversation resolution에 달려 있습니다.
  8. 8

    Step 8: rollback하고 규칙을 남깁니다

    문제 범위에 따라 hunk, file, branch 단위 rollback을 선택하고, 규칙을 AGENTS.md, checklist, skill에 남깁니다.

FAQ

Codex가 코드를 망가뜨리는 가장 흔한 이유는 무엇인가요?
흔한 원인은 너무 넓은 작업 scope, 부정확한 컨텍스트, 빠진 검증 명령, 약한 테스트 커버리지, review 부재입니다. 단순히 “AI는 신뢰할 수 없다”로 정리하기에는 부족합니다.
Codex 작업의 검수 흐름은 어떻게 설계해야 하나요?
scope, plan, patch, verify, review, merge 또는 rollback, update rules의 7단계로 진행합니다. 각 단계에는 확인 가능한 증거와 되돌아갈 조건이 있어야 합니다.
Codex는 큰 리팩터링에 적합한가요?
Codex는 큰 리팩터링에도 도움을 줄 수 있지만, 되돌릴 수 없는 큰 작업 묶음을 한 번에 맡기면 안 됩니다. 검증하고 rollback할 수 있는 작은 단계로 나누어야 합니다.
Codex가 테스트가 통과했다고 하면 merge해도 되나요?
아닙니다. 테스트 통과는 증거 중 하나일 뿐입니다. diff scope, CI 설정, 비즈니스 critical path, PR review, branch protection도 함께 봐야 합니다.
AI가 코드를 망가뜨렸을 때 어떻게 rollback하나요?
먼저 적절한 단위를 고릅니다. 작은 문제는 hunk나 file을 revert하고, 작업 방향이 틀렸다면 현재 diff를 버리거나 새 branch에서 다시 시작합니다. 혼란스러운 diff 위에 계속 fix를 쌓지 않는 것이 중요합니다.
실패 경험을 AGENTS.md에 어떻게 적나요?
실패 원인을 실행 가능한 규칙으로 바꿉니다. 예를 들어 CI를 수정하지 않기, 파일 수가 일정 기준을 넘으면 작업을 나누기, 테스트는 변경 전 실패를 증명하기 같은 규칙입니다. 적용 범위에 가장 가까운 AGENTS.md에 둡니다.
어떤 실패는 AGENTS.md에 쓰고, 어떤 실패는 skill로 만드나요?
프로젝트 규칙, 금지 영역, 수락 기준은 AGENTS.md에 적합합니다. 반복되는 다단계 review 흐름, 고정 명령, 보고서 형식은 skill 후보입니다.

5분 읽기 · 게시일: 2026년 7월 27일 · 수정일: 2026년 7월 27일

댓글

GitHub로 로그인하여 댓글을 남기세요

Easton BlogEaston Blog