최근 Simon Willison이 OpenAI Codex의 base_instructions 내용을 조명하면서, 많은 개발자가 "에이전트를 어떻게 시켜야 하나"를 다시 보게 됐습니다.1 이게 중요한 이유는 간단합니다. 실제 프로젝트에서 Codex가 이상하게 똑똑한 실수를 하는 원인은, 개별 프롬프트가 약해서가 아니라 상시 지침이 빈약해서인 경우가 많기 때문입니다.
Codex는 단순한 채팅 모델이 아니라 로컬 저장소를 읽고, 파일을 고치고, 명령을 실행하는 에이전트입니다.2 이때 AGENTS.md나 config의 developer instructions 같은 지속 지침은 "한 번의 요청"이 아니라 에이전트의 기본 행동 규칙이 됩니다.3 모델 선택보다 이 층위가 더 중요한 순간이 많습니다.
왜 Codex는 자꾸 '똑똑하게 틀릴까'
확인 가능한 사실부터 보죠. Codex CLI는 프로젝트 시작 시 AGENTS.md를 불러 프로젝트 규칙을 따르도록 설계되어 있고, /init으로 그 초안을 만들 수도 있습니다.3 또 Git 작업 트리, 샌드박스, 승인 정책, 테스트 실행 같은 운영 규칙이 별도로 존재합니다.2
이 말은 곧, 실패의 원인을 모델 성능 탓으로만 돌리기 어렵다는 뜻입니다. 예를 들어 Codex가 과하게 많은 파일을 건드린다면 "수정 범위" 규칙이 없는 문제일 수 있습니다. 테스트를 빼먹는다면 "검증 규칙"이 빠졌을 가능성이 큽니다. 팀 스타일을 어긴다면 "저장소 관례"가 모델에 전달되지 않은 겁니다.
실무적으로는 이렇게 진단하는 편이 맞습니다.
"모델이 못했다"보다 먼저 "에이전트가 기본적으로 무엇을 하도록 배치돼 있었나"를 봐야 합니다.
실전에서 버티는 base_instructions는 네 가지로 나뉜다
좋은 base_instructions는 길다고 좋은 게 아닙니다. 오히려 Codex 쪽 가이드와 실제 사용 사례를 보면, 과도한 절차 지시는 에이전트를 둔하게 만들 수 있다는 해석이 가능합니다.14 상시 지침에는 반복적으로 지켜야 할 것만 남겨야 합니다.
제가 권하는 골격은 네 가지입니다.
첫째, 범위 경계입니다.
예: "요청과 무관한 파일은 수정하지 말 것", "대규모 리팩터링은 먼저 계획 제시 후 진행".
둘째, 저장소 관례입니다.
예: "새 파일은 TypeScript strict", "React 컴포넌트는 함수형", "Conventional Commits 준수". 이런 정보는 AGENTS.md에 가장 잘 맞습니다.35
셋째, 검증 규칙입니다.
예: "코드 변경 시 관련 테스트/린트 실행", "실행 못 했으면 이유를 명시". Codex는 명령 실행이 가능한 에이전트라, 이 항목이 특히 중요합니다.2
넷째, 에스컬레이션 조건입니다.
예: "파괴적 명령, 네트워크 사용, 기존 변경사항 충돌 시 사용자 확인". Codex는 승인 정책과 샌드박스를 지원하므로, 이 규칙은 도구 설정과 함께 맞물려야 합니다.2
핵심은 상시 규칙과 작업별 지시를 분리하는 것입니다. "항상 지킬 것"만 base_instructions에 넣고, 기능 요구사항은 그때그때 프롬프트로 줘야 덜 뻣뻣해집니다.
너무 엄격한 base_instructions는 오히려 생산성을 깎는다
반론도 분명합니다. 규칙을 많이 넣으면 더 안전할 것 같지만, 실제로는 과잉 확인, 불필요한 설명, 작은 수정에도 과도한 테스트 같은 부작용이 생깁니다. Codex는 이미 승인 정책, 샌드박스, 실행 규칙 같은 별도 안전장치가 있습니다.2 그런데 지침에서까지 모든 걸 중복 통제하면 에이전트가 "항상 멈추는 동료"가 됩니다.
그래서 구분이 필요합니다.
상시 지침에는 팀의 비가역적 원칙을 넣고, 작업 프롬프트에는 이번 일의 목적과 우선순위를 넣어야 합니다.
예를 들어 "모든 작업 전에 상세 계획을 먼저 써라"는 상시 규칙으로는 과합니다. 반면 "3개 이상 파일 수정이 예상되면 계획을 먼저 제시"는 현실적입니다. 제어와 유연성의 균형이 여기서 갈립니다.
프롬프트가 아니라 에이전트를 A/B 테스트해야 한다
base_instructions를 감으로 고르면 팀마다 Codex 평가가 엇갈립니다. 그래서 소프트웨어처럼 비교해야 합니다.
방법은 단순합니다. 같은 저장소, 같은 작업 5~10개를 준비하고, 지침 버전 A와 B를 각각 돌립니다. 그리고 네 가지만 봅니다.
정답률: 요구사항과 버그 수정이 실제로 맞았는가
편집 크기: 불필요한 파일/라인 변경이 줄었는가
검증 행동: 테스트·린트를 적절히 실행했는가
유지보수성: 팀 스타일과 설명 수준이 맞는가
Codex는 프로필, 프로젝트 설정, AGENTS.md, 승인/샌드박스 정책이 함께 동작합니다.23 즉 "모델 바꿔보자"보다 먼저 "운영 정책을 바꿔보자"가 더 생산적인 경우가 많습니다.
결국 base_instructions는 프롬프트 꾸미기가 아니라 코딩 에이전트의 운영 정책입니다. 개인이 장난감처럼 쓸 때는 체감이 약할 수 있습니다. 하지만 팀 저장소, 테스트 규율, PR 관례, 위험 명령 통제가 중요한 환경이라면 여기서 품질 차이가 크게 벌어집니다. 지금 Codex가 똑똑한데도 자꾸 어긋난다면, 다음에 손볼 것은 모델보다 기본 지침일 가능성이 높습니다.
참고
1Quoting OpenAI Codex base_instructions
2GitHub - openai/codex: Lightweight coding agent that runs in your terminal · GitHub
3OpenAI Codex CLI Cheat Sheet - Commands, Shortcuts, Tips
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.