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