Codex AGENTS 파일로 프로젝트 지침을 정리하는 방법 | DAKER 커뮤니티
같은 저장소에서 Codex를 반복해서 쓰다 보면, 작업 설명보다 운영 규칙을 더 자주 적게 되는 순간이 옵니다. 빌드 명령, 테스트 기준, 건드리면 안 되는 디렉터리, 완료 보고 방식까지 매번 프롬프트에 다시 쓰고 있다면 작업 요청이 점점 흐려지기 쉽습니다.
이럴 때 도움이 되는 것이 AGENTS 파일입니다. 한 번 잘 정리한 규칙을 파일로 남겨 두면, 다음 작업부터는 오늘의 목표와 변경 범위에 더 집중할 수 있습니다.
Codex AGENTS 파일은 언제 유용할까요?
Codex AGENTS 파일은 같은 저장소에서 반복되는 규칙을 Codex가 먼저 읽게 만들고 싶을 때 유용합니다. 공식 문서 확인 기준으로 Codex는 프로젝트 지침, 메모리, 스킬, 외부 도구, 서브에이전트를 서로 보완되는 설정 층으로 다룹니다. 이 글은 2026-07-19 KST에 공식 문서를 확인한 뒤, DAKER Codex 독자가 바로 적용할 수 있는 최소 예시로 정리한 내용입니다.
한 번 통했던 프롬프트 규칙은 다음 작업부터 파일 지침으로 옮기는 것이 좋습니다.
왜 같은 지시를 매번 다시 쓰게 될까요?
Codex에게 테스트를 먼저 돌리라고 하거나, 특정 디렉터리는 건드리지 말라고 하거나, 완료 보고에 검증 결과를 포함하라고 매번 말하고 있다면 프롬프트가 작업 설명과 운영 규칙을 동시에 떠안고 있는 상태입니다. 이렇게 되면 새 작업자가 들어오거나 자동화를 돌릴 때 같은 실수가 반복되기 쉽습니다.
DAKER Codex 디렉터리의 최근 글도 비슷한 흐름을 다룹니다. 프롬프트 자체를 정리하려면 Codex 프롬프트 작성법을, 구현 전 계획을 고정하려면 Codex Plan mode 사용법을 함께 보면 맥락을 잡는 데 도움이 됩니다.
파일에 남길 것과 프롬프트에 남길 것은 무엇일까요?
파일에는 매번 반복되는 팀 규칙을 남기고, 프롬프트에는 오늘의 목표와 변경 범위를 남기는 구성이 잘 맞습니다. 공식 문서 기준으로 프로젝트 지침에는 저장소 구조, 실행 명령, 테스트와 린트 명령, 코드 관례, 하지 말아야 할 일, 완료 기준을 담을 수 있습니다.
반대로 오늘만 필요한 임시 요구, 비밀값, 아직 합의되지 않은 아이디어는 파일에 고정하지 않는 편이 안전합니다.
| 상황 | 파일에 적을 내용 | 피해야 할 내용 |
|---|---|---|
| 매번 같은 리뷰 피드백이 나온다 | 리뷰 기대치와 금지 패턴 | 개인 취향 수준의 문장 |
| 코덱스가 엉뚱한 파일부터 읽는다 | 우선 탐색 디렉터리와 참고 문서 | 모든 문서를 읽으라는 지시 |
| 검증 누락이 반복된다 | 테스트, 타입체크, 빌드 명령과 완료 기준 | 실행할 수 없는 추상적 기준 |
지침은 선언문보다 실행 가능한 체크포인트에 가까워야 합니다.
오늘 저장소에 적용하려면 어떻게 정리하면 될까요?
이 방식은 새 저장소를 처음 세팅할 때보다, 이미 Codex를 몇 번 써 보면서 반복 실수를 확인한 팀에 더 잘 맞습니다. 목표는 길고 거대한 규칙집이 아니라, Codex가 실제로 지킬 수 있는 짧고 정확한 안내문입니다.
- 최근 작업에서 반복해서 말한 지시를 5개만 적습니다.
- 빌드, 테스트, 린트, 리뷰 기준처럼 매번 변하지 않는 항목만 남깁니다.
- 저장소 전체 규칙은 루트에, 특정 폴더 규칙은 해당 폴더 가까이에 둡니다.
- 오늘만 필요한 요구는 프롬프트에 남기고 파일 지침에는 넣지 않습니다.
- Codex가 같은 실수를 두 번 하면 회고를 요청한 뒤 지침을 한 줄 보강합니다.
팀 규칙은 어떤 문장으로 쓰면 좋을까요?
좋은 지침 문장은 행동과 검증이 함께 보입니다. 예를 들면 검색은 먼저 빠른 파일 검색 도구를 사용한다, 수정 후 관련 테스트를 실행하고 실패하면 원인을 보고한다, 사용자 변경을 되돌리지 않는다, 공개 문서에는 비밀값과 로컬 경로를 쓰지 않는다 같은 문장이 여기에 해당합니다.
반대로 항상 최고 품질로 작성한다, 깔끔하게 만든다, 알아서 잘한다 같은 문장은 Codex가 무엇을 해야 하는지 판별하기 어렵습니다.
좋은 지침은 멋진 문장보다 실제 행동을 분명하게 만드는 문장입니다.
공개 저장소에서는 무엇을 특히 조심해야 할까요?
- API 키, 토큰, 고객 정보, 내부 계정명은 파일 지침에 넣지 않는 것이 좋습니다.
- 너무 긴 규칙은 Codex가 핵심을 놓치기 쉬우므로 실제 반복 실수 중심으로 줄이면 됩니다.
- 서로 충돌하는 지시는 삭제하거나 우선순위를 명확히 적는 편이 좋습니다.
- 실행 명령은 현재 저장소에서 실제로 동작하는 명령만 적어야 합니다.
- 완료 기준에는 테스트 통과, 빌드 성공, 변경 파일 요약처럼 확인 가능한 증거를 넣는 것이 좋습니다.
참고할 자료는 어디에 있을까요?
작성 기준일에는 OpenAI Codex 공식 문서의 프로젝트 지침, 커스터마이징 개요, 베스트 프랙티스 문서를 확인했습니다. 이어서 볼 수 있는 DAKER 내부 글은 코덱스 디렉터리, Codex 프롬프트 작성법, Codex Plan mode 사용법, Codex 플러그인 디렉터리 사용법입니다.
자주 묻는 질문
Codex AGENTS 파일은 프롬프트를 완전히 대체하나요?
아닙니다. 파일은 반복 규칙을 맡고, 프롬프트는 오늘의 목표와 범위를 맡는 구조가 좋습니다.
처음부터 긴 지침 파일을 만드는 편이 좋나요?
처음에는 짧게 시작하는 편이 좋습니다. 반복 실수가 확인될 때마다 한 줄씩 보강하는 방식이 더 오래 갑니다.
개인 규칙과 팀 규칙은 어디에 나누면 좋을까요?
개인 말투나 기본 선호는 개인 설정에 두고, 팀이 함께 지킬 빌드와 리뷰 규칙은 저장소 지침에 두는 편이 안전합니다.
이미 프롬프트 구조를 잘 쓰고 있어도 필요할까요?
반복되는 문장이 많아졌다면 필요합니다. 좋은 프롬프트에서 반복 규칙을 덜어 내면 작업 요청이 더 선명해집니다.
여러분은 최근 프롬프트에서 어떤 문장을 가장 자주 반복하고 있었나요?