Codex 모범 사례: 같은 지적을 두 번 받았다면 AGENTS.md에 기록하도록 시키기

지난주에는 '테스트 명령어는 npm test이고 npm run test가 아니다'라고 지적했는데, 오늘 또다시 npm run test를 작성하여 테스트가 실패했다는 경험을 해보신 적이 없으신가요? 원인은 프롬프트의 실력이 아니라, 수정 사항이 프롬프트 안에만 존재하기 때문입니다. 공식 Codex 모범 사례 가이드(2026년 10월 2일 기준 확인)는 이를 '반복적인 지시'에서 '자산으로서의 축적'으로 바꾸는 문제로 다룹니다.

아래 명령어들은 공식 문서를 기반으로 하지만, 본 글에서는 개별적으로 실행하지 않았습니다. 실행하기 전에 현재의 공식 문서를 확인해 주세요.

설치 불필요. 어떤 채팅에서도 작동합니다.

실험 1: 모호한 지시를 4가지 요소로 재작성하기. '로그인 페이지 오류를 고쳐줘'라는 한 줄로는 모델이 대상 파일, 실행 명령어, 완료 판정을 추측하게 만듭니다. 공식 템플릿으로 보완합니다:

목표: 로그인 페이지 전송 시 500 에러가 발생한다. 복구시킨다.
문맥: 스택 트레이스는 error.log이다. 로그인 처리는 src/login/에 있다. 테스트는 npm test를 사용한다.
제약: 결제 모듈은 건드리지 않는다. 기존 코드 스타일에 따른다. 의존성을 늘리지 않는다.
...

한 줄의 지시에서는 범위와 끝점이 모델에게 맡겨지지만, 4가지 요소에서는 경계와 목표가 명확하게 제시됩니다. 공식 설명에 따르면, 가정이 줄어들고 검토하기 쉬운 출력이 됩니다. 기억해야 할 것은 한 마디입니다: 맡기기 전에 '완료의 정의'를 말로 꺼내는 것.

실험 2: AI에게 인터뷰 시키기. 요구사항이 모호하고 설명하기 어려울 때는, 오히려 질문하게 만듭니다:

팀을 위한 주간 보고서 정리 도구를 만들고 싶은데, 요구사항이 정해져 있지 않다.
아직 착수하지 않는다. 5가지 질문으로 가정을 테스트하고,
답변을 구체적인 요구사항 목록으로 정리해줘.

질문과 답변의 주고받음만으로도 자신이 언어화하지 못했던 요구사항 목록을 얻을 수 있습니다.

Plan mode: /plan

또는 Shift+Tab. 문맥 수집, 질문, 계획을 먼저 진행하고, 구현은 승인 후에 합니다. -
AGENTS.md: /init

으로 템플릿을 생성합니다. 실행 방법, 테스트, 금지 사항, 완료 정의를 실제 상황에 맞게 편집합니다. 핵심 원칙은 같은 실수를 두 번 당했다면 되돌아보기(레트로스펙티브) 시켜 AGENTS.md에 반영시키는 것입니다. 3단계 구조(개인 ~/.codex, 리포지토리 직하, 서브 디렉토리)는 가까운 파일이 우선합니다. -
설정의 계층: 개인 기본값은 ~/.codex/config.toml이고, 리포지토리는 .codex/config.toml이며, CLI 플래그는 일회성입니다. approval mode(언제 확인을 요청할지)와 sandbox mode(무엇을 읽고 쓸 수 있을지)는 처음에는 엄격하게 설정하고, 신뢰가 쌓인 후에 완화합니다. 공식에서 지적하듯이, 'AI의 품질 문제'의 상당수는 설정 문제입니다—작업 디렉토리, 쓰기 권한, 기본 모델 등입니다. -
검증 루프: 테스트 생성/실행/lint/diff 검토를 에이전트에게 시키고, 사람이 육안으로 확인한 후에 수용합니다. /review는 PR 형식, 미커밋 변경 사항, 특정 커밋에 대응합니다. 공식 문서의 한 구절:

• MCP에 한 번에 대량 연결하지 않기(먼저 1개부터).
• 불안정한 워크플로우를 수동으로 예약화하기.
• 기본 사일로(sandbox) 상태에서 신뢰를 쌓지 않고 모든 권한을 해제하지 않기.
• 병렬 작업에서 동일 파일 그룹을 공유하지 않기(병렬화는 Git worktree로 분리).
• 프로젝트 전체를 하나의 채팅으로 운영하지 않기(1작업당 1채팅, 길어지면 /compact)