Codex 사용법 3편 - 문맥 엔지니어링, 최소 타격 버그 수정 및 TDD

OpenAI Codex 실전 가이드 3편에서는 문맥 엔지니어링 (Context Engineering), 최소 타격 버그 수정, 테스트 주도 개발 (TDD), 안전한 리팩터링 & 마이그레이션, 거대 코드베이스 길찾기, 그리고 반복 자가 치유 디버깅 루프를 다룹니다.

1. 많이 붙이는 문맥과 줄여야 할 문맥 (Context Pruning & Trimming)

에이전트에게 관련 없는 커다란 파일이나 로그 10,000줄을 통째로 넘기면 토큰 소비가 폭발할 뿐만 아니라 모델의 추론 지능이 급격히 저하됩니다.

문맥 조절 3대 수칙

필요 문맥 (Must Context): 현재 변경하려는 함수가 포함된 파일, 해당 함수의 타입 정의, 연관된 테스트 파일 1개
절삭 대상 (Trim Targets): 바이너리 파일, 대용량 build/dist 출력물, 무관한 서브모듈의 구현체
컨텍스트 프루닝 (Pruning): 에이전트 요청 시 AGENTS.md의 관련 가이드라인과 핑거프린팅된 관련 라우트 파일 2~3개만 제한적 핀포인팅 주입

문맥 프루닝 실전 팁

대용량 로그는 전체를 붙여넣지 말고 핵심 Error Traceback 상위 15줄만 추출하여 주입합니다.
복잡한 모듈 관계는 파일 전체 대신 interface나 type 선언부만 주입하는 것이 80% 이상의 토큰을 절약합니다.

2. 버그를 크게 건드리지 않고 바로잡는 법 (Minimal Impact Bug Fixing)

버그 하나를 고치려다 프로젝트 전체를 건드려 다른 10개의 새로운 버그를 만들어내는 현상(Regression Crash)을 예방하는 3단계 규칙입니다.

   ┌────────────────────────────────────────────────────────┐
   │             Minimal Impact Bug Fix Loop                │
   └───────────────────────────┬────────────────────────────┘
                               │
         ┌─────────────────────┼─────────────────────┐
         ▼                     ▼                     ▼
   1. Reproduce Test     2. Localized Fix      3. Regression Verification
  - 버그 재현 테스트 작성 - 최소 범위 라인 수정   - 전체 테스트 패스 검증

최소 타격 버그 수정 3단계

버그 재현 테스트(Failing Test) 선제 작성: 수정하기 전 버그가 발생하는 입력값을 넣어 반드시 실패하는 테스트 코드를 먼저 만듭니다.
최소 범위 국소 수정 (Localized Fix): 에이전트의 수정 범위를 단 하나의 함수나 지정된 파일 영역으로 엄격히 제한합니다.
기존 테스트 검증 (Regression Suite): 수정 후 전체 테스트 스위트를 돌려 기존 정상 기능들의 깨짐이 0건임을 확인합니다.

3. 테스트가 먼저 서야 수정이 흔들리지 않는다 (AI-Driven TDD)

AI 에이전트는 명확한 테스트 코드가 존재할 때 코드 작성 및 디버깅 정확도가 10배 이상 급상승합니다.

TDD 릴레이 루프 (Red-Green-Refactor)

Red (실패하는 테스트): 에이전트에게 원하는 성공/실패 조건이 적힌 테스트 코드 작성을 먼저 지시합니다.
Green (최소 구현): 해당 테스트를 통과시키는 가장 단순하고 명확한 구현 코드 작성을 지시합니다.
Refactor (구조 개선): 테스트 통과 상태를 유지하며 코드의 가독성과 성능을 다듬습니다.

4. 리팩터링과 마이그레이션을 안전하게 여는 법

대규모 리팩터링 및 마이그레이션(예: JavaScript ➔ TypeScript, Express ➔ Cloudflare Workers)을 수행할 때는 안전한 격리 지대를 만들어야 합니다.

인터페이스 마스킹 (Interface Masking): 외부 API 계약을 유지한 상태에서 내부 구현만 단계적 교체
Git Worktree 활용: 현재 작업 브랜치와 독립된 별도의 Git Worktree에서 마이그레이션 진행 후 검증 통과 시 PR 병합
점진적 마이그레이션 (Strangler Fig Pattern): 거대한 레거시를 한 번에 바꾸지 않고 라우트 단위로 하나씩 신규 시스템으로 이관

5. 거대 코드베이스에서 길을 잃지 않는 질문 기법

수만 줄에 달하는 프로젝트에서 에이전트에게 엉뚱한 수정을 방지하는 정밀 질문 패턴입니다.

"이 수정이 영향을 미치는 상위 호출자(Caller) 목록 3개만 나열해 줘."
"현재 데이터베이스 스키마와 이 라우트의 DTO 정의 사이의 불일치가 있는지 파악해 줘."

6. 어려운 문제를 반복 루프로 푸는 법 (Iterative Loop)

단번에 풀리지 않는 복잡한 결제 및 동시성 문제는 한 번의 대화로 해결하려 하지 말고, Max 3-Step Iterative Loop를 돌려 단계별로 좁혀나가는 것이 성공 열쇠입니다.

Codex 사용법 [3편: 문맥 엔지니어링, 자가 디버깅 & TDD]