Codex가 저장소마다 다르게 일하도록 하려면 AGENTS.md를 긴 매뉴얼로 만들기보다, 꼭 지켜야 할 지침을 작업 범위에 맞게 두는 편이 낫습니다. OpenAI가 2026년 9월 11일 공개한 안내의 요점도 짧고 관련성 높은 설명, 필요한 순간에만 여는 세부 자료, 모델이 이미 할 수 있는 일을 과하게 지시하지 않는 것입니다.
간단 요약
- 핵심 원칙: 지침은 짧고 작업에 맞게
- 첫 단계: 반복되는 중요한 규칙만 남김
- 둘째 단계: 하위 폴더 지침으로 적용 범위 좁힘
- 셋째 단계: 예외와 안전한 다음 행동을 씀
1. 왜 AGENTS.md가 길어지면 불편할까
AGENTS.md는 Codex가 저장소에서 일할 때 매번 참고하는 지침입니다. 중요도와 관계없이 모든 배경 문서를 늘어놓으면 간단한 수정에도 불필요한 맥락을 읽게 되고, 실제로 적용할 규칙이 긴 글 속에서 묻힙니다. OpenAI의 9월 안내는 모든 모델이 똑같은 도움을 필요로 하지 않는다는 점도 짚습니다.
2. 먼저 반복되는 판단을 고르기
규칙을 추가하기 전에 최근 코드 리뷰나 작업 기록에서 같은 설명을 두 번 이상 했는지 살펴보세요. 예를 들어 “사용자 데이터가 로그에 나오면 안 된다”처럼 중요한 경계는 남길 수 있지만, 이미 테스트나 포매터가 자동으로 검사하는 간격·따옴표 규칙은 그 도구에 맡기는 편이 낫습니다.
저장소 루트에는 여러 작업에서 계속 유효한 원칙을 두고, 특정 서비스의 스키마나 호환성 설명은 그 폴더에 가까운 문서에 둡니다. 모든 작업에 데이터베이스 설계서를 읽으라고 하는 대신, 데이터베이스를 바꿀 때 그 문서를 확인하라고 연결하면 지침이 더 정확해집니다.
3. 실행 가능한 안내를 쓰기
“조심해서 수정”처럼 추상적인 문구는 Codex가 무엇을 확인해야 하는지 알려주지 못합니다. “응답 필드를 바꾸기 전에 저장소의 소비자를 검색하고, 기존 이름을 유지하거나 호환 별칭을 추가한다”처럼 위험과 안전한 대안을 함께 쓰면 행동으로 옮기기 쉽습니다.
내 경우 판단 순서
- 반복되는 중요한 실수를 하나 고릅니다.
- 그 실수가 적용되는 폴더와 파일을 정합니다.
- Codex가 따를 안전한 대안을 한 문장으로 씁니다.
4. 예시로 보는 적용 범위
한 팀에서 루트 지침에 “외부 응답 필드 이름을 임의 변경하지 않는다”를 두고, 결제 폴더에는 “금액은 정수 센트로 저장한다”를 별도로 둘 수 있습니다. 결제 코드를 건드리지 않는 수정에 센트 단위 규칙을 끌어오지 않도록 적용 범위를 분리하는 방식입니다.
큰 문서가 필요하다면 AGENTS.md에는 어떤 질문에 어떤 자료를 참고할지만 적고, 상세 설명은 별도 문서로 둡니다. 이렇게 하면 작업이 그 주제와 관계 있을 때만 세부 내용을 읽을 수 있습니다. 지침 파일을 압축하는 목표는 글자 수 자체보다 매 작업에서 유효한 지시의 비율을 높이는 것입니다.
Codex 지침 설계를 실제로 시작할 때는 최근 리뷰 의견이나 수정 기록에서 같은 경고가 반복된 사례를 세 개만 골라 보세요. 그중 포매터가 잡아낼 수 있는 항목은 자동 도구로 옮기고, 맥락을 알아야 이해되는 위험만 지침에 남깁니다. 각 문장 옆에 적용 폴더와 안전한 행동을 적어 두면 새 팀원이 규칙을 다른 상황에 확대 해석할 가능성도 줄어듭니다. 지침을 바꾼 뒤에는 단순 문구 수정, 해당 서비스 변경, 예외 상황을 각각 요청해 불필요한 절차가 끼지 않는지도 살펴보세요.
Codex 지침 설계는 작성자의 의도를 저장소에서 실제로 반복하는 방법입니다. 따라서 프로젝트 구조가 바뀌거나 같은 규칙의 소유 팀이 달라지면 적용 범위와 담당 문서도 함께 확인해야 합니다. 오래된 파일 경로나 바뀐 명령이 남아 있으면 정확한 지침도 잘못된 행동으로 이어질 수 있습니다.
5. 변경 뒤 확인할 것
짧은 수정, 특정 하위 폴더 작업, 예외가 있는 변경을 각각 요청해 지침이 의도한 경우에만 적용되는지 확인합니다. 테스트가 아닌 단순 포매팅을 불필요하게 강제하거나, 매번 같은 문서를 전부 읽게 한다면 지침이 여전히 넓은 것입니다. 모델이 행동을 바꿀 핵심 규칙이 무엇인지 설명할 수 있는지도 좋은 점검 기준입니다.
✅ 결론
AGENTS.md는 저장소의 백과사전이 아니라, 매번 필요한 행동을 정하는 짧은 작업 안내에 가깝습니다. 반복되는 중요한 경계를 추리고, 해당 폴더에만 적용하고, 안전한 대안까지 적은 뒤 대표 작업으로 불필요한 지시가 나오지 않는지 확인해 보세요.
자료 출처 OpenAI Developers, 「Rethinking skills and prompts for GPT-6 Astra」(2026년 9월 11일) 확인 기준. 기능과 안내는 변경될 수 있습니다.
FAQ — 자주 묻는 질문
Q1. AGENTS.md에 모든 프로젝트 문서를 넣어도 되나요?
권장되지 않습니다. 항상 필요한 핵심 규칙만 파일에 두고, 특정 작업에서만 필요한 설명은 해당 자료를 참조하도록 연결하면 맥락 낭비를 줄일 수 있습니다.
Q2. 테스트와 AGENTS.md 규칙은 어떻게 나누나요?
포매팅이나 정해진 조건처럼 자동화할 수 있는 검사는 테스트·린터가 맡고, 호환성 원칙이나 데이터 경계처럼 맥락 판단이 필요한 내용은 지침에 둡니다.
Q3. 지침은 언제 다시 검토해야 하나요?
같은 안내가 반복되거나, 적용되지 않는 지시가 자주 나타나거나, 프로젝트 구조가 달라졌을 때 확인하세요. 오래된 세부 구현 이름보다 계속 유효한 결과와 경계를 중심으로 고칩니다.
※ 이 글은 2026년 9월 29일 기준 OpenAI 공식 안내를 바탕으로 작성한 정보성 해설입니다. 제품 기능과 운영 방식은 바뀔 수 있으며, 실제 저장소 적용과 코드 변경 결과는 프로젝트 환경에서 별도로 검토해야 합니다.
