전역 파일은 개인 취향, 루트 파일은 팀 규칙, 하위 파일은 특정 영역 규칙이다. 여기서 전역은 운영체제 전체 설정이 아니라 Codex 홈 디렉토리의 공통 지침층을 뜻한다.
루트는 현재 프로젝트의 가장 바깥 폴더다. 팀에서 공유해야 하는 내용은 개인 전역 파일이 아니라 저장소 안의 AGENTS.md에 둔다.
Codex 지침 체인 (세션 시작 시 순서대로 로드)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
~/.codex/AGENTS.md ← 1단계: 전역 (개인 선호)
│
▼
{repo}/AGENTS.md ← 2단계: 저장소 루트 (팀 규칙)
(같은 위치에 AGENTS.override.md 있으면 대체)
│
▼
{subdir}/AGENTS.md ← 3단계: 하위 디렉토리 (모듈별)
(같은 위치에 AGENTS.override.md 있으면 대체)
─────────────────────────────────────────
config.toml ← 모델·승인·샌드박스 런타임 설정
.rules ← 셸 명령 허용/차단 정책
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
같은 위치에 AGENTS.override.md가 있으면 그 디렉토리의 AGENTS.md는 무시되고 override 파일만 지침으로 포함된다.
AGENTS.override.md는 팀 전체 AGENTS.md 규칙 중 특정 폴더에서만 일부를 덮어쓸 때 쓰는 로컬 예외 파일이라고 보면 된다. 디렉토리마다 최대 한 개의 지침 파일만 포함되므로, 임시로 강한 예외가 필요할 때는 AGENTS.override.md를 쓰고 끝나면 제거하는 방식이 안전하다. Codex는 세션이나 실행을 시작할 때 지침 체인을 만들기 때문에, 지침 파일을 바꾼 뒤 현재 세션에 바로 반영되지 않으면 Codex를 다시 시작하거나 새 명령으로 확인한다.
예를 들어 계약직 개발자에게 tests/integration/만 접근을 허용하고 나머지 테스트는 원래 규칙대로 막을 때 이렇게 쓴다.
# tests/AGENTS.override.md
# 원본 AGENTS.md: "tests/ 수정 금지"
# 이 파일이 있으면 tests/ 안에서는 아래 규칙만 적용된다
## 덮어쓰기 규칙 (feature/contractor-scope 브랜치용)
- tests/integration/ 하위 파일은 수정 가능하다.
- tests/unit/ 하위 파일은 원래 규칙대로 수정 금지.
- 작업 완료 후 이 파일을 삭제하고 PR을 올린다.
AGENTS.md는 길수록 Codex가 잘 따를까?
좋은 시스템 프롬프트는 자세할수록 좋다는 경험을 가진 개발자라면 AGENTS.md도 길수록 낫다고 느낀다.
실제로는 반대다.
날카로운 규칙 10줄 > 위키 dump 100줄. 파일이 길어질수록 중요한 규칙이 잡음에 묻히고, Codex가 읽어야 할 토큰도 늘어난다. 공식 AGENTS.md 가이드도 "중요한 지시사항만으로 시작하라"고 명시한다.
그래도 올려야 하는 것은 딱 세 가지다: ① 반복해서 리뷰에서 지적되는 패턴, ② 새 세션에서 Codex가 놓치는 프로젝트 구조, ③ 실수하면 되돌리기 어려운 금지 명령. 그 외는 프롬프트에서 그때그때 말하면 된다.
2.2 무엇을 적어야 효과적인가
공식 문서는 AGENTS.md에 빌드와 테스트 명령, 리뷰 기대사항, 저장소별 컨벤션, 디렉토리별 지시사항을 적는 것을 권장한다. 동시에 "중요한 지시사항만으로 시작하라"는 방향도 함께 제시한다(Customization 문서).
그래서 첫 버전부터 회사 위키 전체를 옮길 필요는 없다. Codex가 자주 틀리는 부분, 사람이 반복해서 리뷰하는 부분, 프로젝트 구조상 반드시 지켜야 하는 부분만 먼저 적으면 된다. 처음 AGENTS.md를 만들 때 어디서부터 시작해야 할지 막막하다면 /init 명령을 써볼 수 있다. Codex가 저장소 구조를 읽고 AGENTS.md 초안을 생성해준다.
# AGENTS.md
## 프로젝트 규칙
- 프론트엔드 명령은 `pnpm`을 사용한다. `npm install`은 사용하지 않는다.
- 작업을 완료했다고 말하기 전에 `pnpm lint`와 `pnpm test`를 실행한다.
- 변경 범위는 요청받은 기능이나 버그 수정에 한정한다.
- `generated/` 아래 파일은 직접 편집하지 않는다.
## 백엔드
- API 코드는 `apps/api`에 둔다.
- 백엔드 변경 후에는 `pytest tests/api`를 실행한다.
- 데이터베이스 마이그레이션은 커밋 전에 검토를 받아야 한다.
## 프론트엔드
- UI 컴포넌트는 `apps/web/components`에 둔다.
- 일회성 색상값보다 기존 디자인 토큰을 우선 사용한다.
- 아이콘만 있는 버튼에는 접근성 라벨을 추가한다.
이 예시는 일부러 짧다. 좋은 AGENTS.md는 긴 문서가 아니라 작업 중 판단이 갈리는 지점을 줄이는 문서다. 특히 "하지 말아야 할 일"과 "완료라고 말하기 전에 돌릴 명령"을 명확히 적으면 효과가 크다.
내용
어디에 둘까
이유
이번 요청에서만 필요한 제약
프롬프트
다음 작업까지 남길 필요가 없다
팀이 항상 지켜야 하는 빌드·테스트·리뷰 규칙
AGENTS.md
저장소와 함께 공유되고 반복 적용된다
개인 말투, 선호하는 설명 방식, 반복 작업 습관
전역 AGENTS.md 또는 메모리
팀 규칙과 개인 선호를 섞지 않는다
특정 명령을 허용·확인·차단하는 실행 정책
Rules
자연어 지침이 아니라 명령 실행 경계를 제어한다
비교 — 효과 있는 AGENTS.md 규칙 vs 무시되기 쉬운 규칙
❌ 이렇게 하면
## 규칙
- 좋은 코드를 작성한다.
- 문제를 만들지 않는다.
- migrations/는 중요하다.
✅ 이렇게 하면
## 빌드와 테스트
- 작업을 완료했다고 말하기 전에 `pytest`를 실행한다.
## 수정 금지
- `migrations/`는 커밋 전에 DBA 검토가 필요하다.
직접 수정하면 데이터 손실 위험이 있다.
이유 없는 금지("문제 만들지 않는다")는 다음 세션에서 무시되기 쉽다. 완료 조건과 금지 이유를 함께 적어야 Codex가 예외 상황에서도 의도를 지킨다.
2.3 언제 업데이트해야 하는가
처음 만든 AGENTS.md는 완성본이 아니라 출발점이다. 공식 문서는 세 가지 상황에서 내용을 추가하라고 안내한다(Customization 문서). Codex가 잘못된 가정을 반복할 때, 너무 많은 문서를 읽느라 헤맬 때, PR 리뷰에서 같은 피드백이 반복될 때다.
초심자 입장에서는 이렇게 기억하면 쉽다. "한 번만 말하면 되는 내용"은 프롬프트에 쓰고, "다음에도 또 지켜야 하는 내용"은 AGENTS.md에 올린다.
다만 문서가 커질수록 Codex가 읽어야 할 내용도 늘어난다. 공식 가이드는 합쳐진 지침 크기가 project_doc_max_bytes(Codex가 읽을 프로젝트 문서의 최대 바이트 한도) 한도에 닿으면 더 이상 추가하지 않는다고 설명하고, AGENTS.md 가이드의 기본 설명에서는 32 KiB를 기준값으로 안내한다. 그래서 규칙은 이유가 분명한 것만 넣고, 오래된 규칙은 주기적으로 걷어낸다.
AGENTS.md로 옮길지 판단하는 체크리스트
같은 피드백을 세 번 이상 반복해서 말하고 있는가?
새 세션에서도 반드시 지켜야 하는 팀 규칙인가?
규칙을 지키지 않으면 테스트 실패, 보안 위험, 배포 사고로 이어질 수 있는가?
반대로 오래된 도구명, 사라진 폴더, 더 이상 쓰지 않는 명령은 없는가?
또 하나 중요한 점은 AGENTS.md가 모든 문제를 혼자 해결하는 파일은 아니라는 점이다. Codex 문서에는 메모리, 스킬, MCP, 서브에이전트처럼 역할이 다른 확장 기능도 따로 설명되어 있다. 프로젝트 규칙은 AGENTS.md, 반복 워크플로는 스킬, 외부 시스템 연결은 MCP처럼 역할을 나눠 생각하면 된다.
2.4 모듈식으로 나누는 법
여기서 말하는 모듈식 구성은 AGENTS.md 안에서 다른 문서를 import한다는 뜻이 아니다. 공식 AGENTS.md 가이드가 설명하는 방식은 적용 범위에 맞게 지침 파일을 가까운 디렉토리에 두는 것이다. 저장소 전체 규칙은 루트 AGENTS.md에 두고, 특정 폴더에만 필요한 규칙은 그 폴더의 AGENTS.md 또는 AGENTS.override.md에 둔다.
상황
권장 위치
이유
공통 빌드·테스트 명령
{repo-root}/AGENTS.md
저장소 어디에서 작업하든 적용되는 규칙
프론트엔드만의 UI 규칙
web/frontend/AGENTS.md
해당 폴더 아래 작업에만 적용
특정 팀의 임시 우선 규칙
하위 폴더/AGENTS.override.md
같은 위치의 AGENTS.md 대신 override 파일만 포함
기본값 그대로 사용하면 된다. 파일명 커스텀이나 용량 한도 조정은 처음에는 필요하지 않다.
더 알아보기 — 파일명 커스텀과 한도 조정
이미 팀에서 TEAM_GUIDE.md 같은 파일을 쓰고 있다면, 아래처럼 fallback 이름으로 등록할 수 있다. 설정을 바꾼 뒤에는 Codex를 재시작해야 반영된다.
처음부터 한도를 키우는 방식은 좋은 기본값이 아니다. 한도 상향은 중요한 지침이 잘릴 때 검토하고, 그 전에는 오래된 규칙 삭제와 폴더별 분리를 먼저 시도한다.
또 하나 자주 헷갈리는 점이 있다. @rules/foo.md나 ./rules/foo.md를 AGENTS.md 안에 적는다고 해서 그 파일이 자동으로 합쳐지는 것은 아니다.
공식 문서가 설명하는 자동 발견 대상은 AGENTS.md, AGENTS.override.md, 그리고 설정에 등록한 fallback 파일명이다. 한 번만 참고할 파일은 프롬프트에 경로를 직접 쓰고, 반복해서 적용할 규칙은 가까운 AGENTS.md로 승격하는 편이 명확하다.
2.5 AGENTS.md 스타터 템플릿 4가지
빈 파일 앞에서 "뭘 써야 하지?"가 막히는 게 가장 흔하다.
바로 복붙해서 쓸 수 있는 템플릿 4가지를 준비해봤다.
예시 A는 개인 프로젝트, B는 작은 풀스택 팀, C는 모노레포, D는 Next.js App Router 팀 프로젝트 기준이다.
예시들이 반복해서 보여주는 섹션 패턴
빌드와 테스트: 완료라고 말하기 전에 반드시 돌릴 명령
코드 스타일 / 규칙: 리뷰에서 반복 지적된 것만 — 취향 수준은 넣지 않는다
수정 금지 또는 금지 규칙: 실수하면 되돌리기 어려운 파일과 이유
각 규칙에 이유: "하지 마" 한 줄보다 "하지 마 — 이유" 형식이 Codex가 예외 상황을 더 잘 판단한다
예시 A — 개인: Node.js 프로젝트 혼자 쓸 때
처음 AGENTS.md를 만들 때 가장 흔한 실수는 너무 많이 쓰는 것이다.
반복 지적된 것 3가지, 금지 파일 2가지로 시작한다.
나머지는 나중에 추가한다.
# AGENTS.md
## 빌드와 테스트
- 작업을 완료했다고 말하기 전에 `npm test`를 실행한다.
- `npm install`은 자동으로 실행하지 않는다. 새 패키지가 필요하면
패키지 이름과 이유를 먼저 설명하고 확인을 기다린다.
## 코드 스타일
- 새 비동기 코드는 `.then()` 체인보다 `async/await`로 작성한다.
- 커밋될 코드에 `console.log`를 남기지 않는다. `lib/log.ts`의 logger를 사용한다.
## 수정 금지
- `package-lock.json`은 직접 편집하지 않는다. `npm install`로만 갱신한다.
- `.env`, `.env.local`은 읽거나 수정하지 않는다.
직접 해보자
아래 내용을 그대로 복붙해서 프로젝트 루트에 AGENTS.md 파일을 만들어 보자.
Codex가 다음 작업부터 테스트를 자동으로 돌리고, 지정한 파일은 건드리지 않는다.
# AGENTS.md
## 빌드와 테스트
- 작업을 완료했다고 말하기 전에 `npm test`를 실행한다.
## 수정 금지
- `.env`, `.env.local`은 읽거나 수정하지 않는다.
줄별 해설
빌드와 테스트 — "완료 전에 실행": 이 문구가 없으면 Codex가 테스트를 돌리지 않고 완료라고 말한다. 완료 조건을 명시하는 게 핵심이다.
npm install 자동 실행 금지: 패키지가 추가되면 package-lock.json이 바뀌고 빌드 환경이 달라진다. 어떤 패키지인지 사람이 먼저 확인하게 강제하는 규칙이다.
수정 금지 — .env: 이 섹션이 없으면 Codex가 환경 파일을 읽거나 수정할 수 있다. API 키나 DB 주소가 담긴 파일은 반드시 명시한다.
규칙 자체는 10줄 안팎: 처음엔 한국어로 짧게 시작한다. 실제 리뷰에서 "또 이거야"가 나올 때만 규칙을 추가한다.
Python 프로젝트를 쓴다면 — pytest 기반 예시 보기
# AGENTS.md
## 빌드와 테스트
- 작업을 완료했다고 말하기 전에 `pytest`를 실행한다.
- 데이터베이스 마이그레이션은 자동 실행하지 않는다. 먼저 마이그레이션 파일을
보여주고 검토 확인을 기다린다.
## 코드 스타일
- 모든 함수 시그니처에 타입 힌트를 작성한다.
- `except:`만 단독으로 쓰지 않는다. 처리할 예외 타입을 명확히 적는다.
## 수정 금지
- `migrations/` 파일은 커밋 전에 수동 검토가 필요하므로 자동 수정하지 않는다.
- `.env`, `.env.local`은 읽거나 수정하지 않는다.
예시 B — 소팀: 프론트엔드(Node) + 백엔드(Python) 한 저장소
프론트엔드는 Node.js, 백엔드는 Python·FastAPI인 흔한 풀스택 구조다. 팀원마다 다른 명령을 쓰면 Codex도 흔들린다. 어느 폴더에서 어떤 명령을 써야 하는지 지도를 먼저 그려준다.
# AGENTS.md
## 프로젝트 구조
- 프론트엔드: `apps/web/` (Next.js, pnpm)
- 백엔드: `apps/api/` (FastAPI, pytest)
- 공유 타입: `packages/types/`
## 빌드와 테스트
- 프론트엔드 변경: `pnpm --filter web lint && pnpm --filter web test`
- 백엔드 변경: `pytest apps/api/tests/ -q`
- 공유 타입이나 양쪽에 걸친 변경을 건드렸다면 프론트엔드와 백엔드 검증을 모두 실행한다.
## 코드 스타일
- 프론트엔드: 기존 디자인 토큰을 사용한다. 컴포넌트 안에 일회성 hex 색상값을 넣지 않는다.
- 백엔드: 모든 API 요청/응답 스키마는 Pydantic 모델로 정의한다.
- 공통: TODO 주석을 남길 때는 연결된 이슈 번호를 함께 적는다.
## 수정 금지
- `apps/api/migrations/`는 DBA 검토가 필요하므로 자동 수정하지 않는다.
- `packages/types/`는 양쪽 팀 계약에 해당하므로 변경 전에 영향 범위를 설명한다.
줄별 해설
프로젝트 구조 섹션: Codex가 어느 폴더에서 어떤 명령을 써야 할지 아는 지도다. 없으면 웹 명령을 API에 적용하거나 반대가 된다.
테스트 명령에 "cross-cutting changes" 조건: "항상 둘 다 돌려라"고 적으면 백엔드만 건드려도 프론트 테스트가 불필요하게 돈다. 언제 둘 다 돌릴지 조건을 명시하는 게 낫다.
코드 스타일 영역 분리: 프론트엔드/백엔드/공통으로 나눠야 Codex가 잘못된 영역에 규칙을 적용하지 않는다.
packages/types/ 수정 주의: 팀 경계를 넘는 파일은 항상 명시해야 한다. 적지 않으면 Codex가 단독으로 수정할 수 있다.
예시 C — 모노레포: 루트 공통 + 모듈별 분리
팀 규모가 커진 다음에 보면 된다 — 처음 도입이라면 예시 A나 D부터 시작하자.
팀이 커지면 루트 하나에 모든 규칙을 다 넣으면 금방 커진다. "이 규칙이 저장소 전체에 적용되는가, 아니면 특정 앱에만 적용되는가"를 기준으로 나눠서 둔다.
# AGENTS.md ← 저장소 루트 (어디서 작업하든 적용)
## 공통 규칙
- 작업을 완료했다고 말하기 전에 `pnpm -r lint`를 실행한다.
- 패키지 버전은 직접 올리지 않는다. 버전 변경이 필요하면 `pnpm changeset`을 사용한다.
- `packages/ui/` 또는 `packages/types/`를 변경했다면, 변경 후 모든 `apps/` 소비자에서
타입 오류가 없는지 확인한다.
## 모노레포 구조
- apps/web: Next.js 앱 (`pnpm test`, `pnpm lint`)
- apps/api: Node.js Express API (`npm test`)
- packages/ui: 디자인 시스템. UI 컴포넌트의 원본이다.
- packages/types: 공유 TypeScript 타입. 모든 앱에 영향을 줄 수 있다.
# apps/web/AGENTS.md ← 프론트엔드 전용 (이 폴더 안 작업에만 적용)
## 테스트 명령
- 단위 테스트: `pnpm test`
- E2E 테스트: 인증 흐름이나 라우팅이 바뀐 경우에만 `pnpm test:e2e`를 실행한다.
## 수정 금지
- `src/components/ui/`는 `packages/ui`에서 동기화되는 폴더다. 원본 패키지를 수정한다.
- `public/assets/`의 정적 파일은 디자인팀 확인 없이 바꾸지 않는다.
줄별 해설
루트에는 공통 규칙만: "어디서 작업하든 적용되는 것"만 루트에 둔다. 특정 앱 규칙은 해당 폴더 AGENTS.md로 내린다. 루트가 길어지면 정작 중요한 규칙이 묻힌다.
pnpm changeset 명시: 버전 관리 도구를 적지 않으면 Codex가 package.json을 직접 수정한다. 도구 이름과 이유를 함께 적어야 한다.
apps/web E2E 조건: "항상 돌려라"보다 "언제 돌려라"가 더 실용적이다. 조건 없이 쓰면 매 변경마다 E2E가 돌 수 있다.
src/components/ui/ 수정 금지 이유: 소스 패키지가 따로 있는데 여기를 직접 고치면 다음 동기화에서 덮어씌워진다. 이유를 적어야 Codex가 왜 금지인지 이해한다.
예시 A~C에서 반복된 패턴
빌드와 테스트에 완료 조건을 명시했다 — "돌려라"보다 "완료라고 말하기 전에 돌려라"가 낫다
금지 규칙에 이유를 같이 적었다 — 이유 없는 금지는 다음 세션에서 무시될 수 있다
조건부 규칙을 명시했다 — "항상"보다 "언제"가 더 실용적이다
처음엔 짧게 시작했다 — 리뷰에서 반복된 것만 추가하면 문서가 자연스럽게 성숙한다
예시 D — Next.js App Router 팀 프로젝트: 컴포넌트·API·DB 규칙 한 파일에
Node.js / React 단일 스택을 쓴다면 예시 D가 가장 실전적이다. 예시 A 다음에 바로 읽어도 좋다.
A·B·C가 언어나 저장소 구조 중심이었다면, 예시 D는 프레임워크 특화 규칙이 필요한 상황이다. Next.js App Router 프로젝트에서 Codex가 새 파일을 만들 때 가장 자주 발생하는 실수는 세 가지다. Server Component와 Client Component를 구분 없이 쓰는 것, API 경로 밖에서 DB를 직접 호출하는 것, Tailwind 대신 인라인 스타일을 섞는 것. 이 규칙들을 AGENTS.md에 못 박으면 다음 세션에서 같은 실수를 반복하지 않는다.
# 프로젝트
Next.js 14 App Router (TypeScript). 주요 스택: React, Tailwind CSS, Prisma, PostgreSQL.
# 구조
- app/: 페이지와 레이아웃을 둔다. App Router 기준 폴더다.
- app/api/: API Route Handler를 둔다. 서버 API는 이 폴더 안에서 만든다.
- components/: 공유 UI 컴포넌트를 둔다.
- lib/: 유틸리티, Prisma client, 서버 전용 함수를 둔다.
- prisma/: 스키마와 마이그레이션을 둔다.
# 규칙
- "use client"는 필요한 컴포넌트에만 붙인다. 기본은 Server Component다.
- app/api/ 이외에서 DB를 직접 호출하지 않는다. DB 접근은 lib/db.ts를 통해서만 한다.
- Tailwind 클래스는 className에만 쓴다. style 속성으로 인라인 스타일을 넣지 않는다.
- .env, .env.local 파일을 읽거나 수정하지 않는다.
- prisma/migrations/ 아래 파일을 직접 수정하지 않는다.
# 빌드와 테스트 (완료 기준)
코드 수정 후 완료라고 말하기 전에 아래를 순서대로 실행한다:
1. npx tsc --noEmit # TypeScript 타입 에러 확인
2. npm run lint # ESLint 경고 확인
3. npm run build # 프로덕션 빌드 성공 여부 확인
줄별 해설
"use client"는 필요한 컴포넌트에만: App Router에서 Server Component가 기본이다. "use client"를 남발하면 서버 사이드 렌더링 이점이 사라진다. 이 한 줄이 Codex가 새 파일을 만들 때 기본값을 잡아준다.
lib/db.ts를 통해서만: DB 접근 경로를 단일화하면 컴포넌트 안에서 Prisma를 직접 import하는 실수를 막는다. "하지 마라"보다 "어디서 해라"가 더 잘 지켜진다.
prisma/migrations/ 직접 수정 금지: 마이그레이션 파일은 자동 생성 파일이다. Codex가 선의로 고치면 DB 스키마가 코드와 어긋난다. 이 줄이 없으면 Codex가 임의로 수정할 수 있다.
빌드와 테스트에 순서 명시: 타입 에러 → 린트 → 빌드 순으로 가장 빨리 발견할 수 있는 문제부터 확인하게 한다. "빌드를 돌려라" 한 줄보다 세 단계를 순서대로 적는 편이 놓치는 오류가 적다.
3. AGENTS.md와 로컬 메모리의 차이
핵심: AGENTS.md는 팀 전체가 공유하는 규칙, 로컬 메모리는 나만 쓰는 개인 맥락이다. 팀 기준은 반드시 AGENTS.md에 넣는다.
Codex에는 로컬 메모리 기능도 있다. 이름만 보면 AGENTS.md와 비슷해 보이지만, 이번 편의 핵심은 "팀 공유 규칙"이다.
Memories 공식 문서는 필수 팀 지침을 AGENTS.md나 저장소에 포함된 문서에 보관하고, 메모리는 항상 적용되어야 하는 규칙의 유일한 출처로 보지 말라고 안내한다.
구분
AGENTS.md
로컬 메모리
목적
팀과 프로젝트 규칙을 Codex에 전달
이전 작업 맥락과 개인 선호를 이어받음
공유 방식
Git에 포함해 팀에 공유 가능
기본적으로 개인 Codex 홈 아래에 저장
적합한 내용
테스트 명령, 코드 규칙, 디렉토리별 주의사항
자주 쓰는 워크플로, 개인 선호, 최근 작업 맥락
위험
너무 길면 읽기 비용 증가
팀 규칙을 개인 메모리에만 두면 다른 사람에게 전파되지 않음
AGENTS.md는 팀 일관성을 위한 파일이고, 로컬 메모리는 개인 작업 연속성을 위한 보조층이다. "이 규칙은 누구에게나 항상 적용되어야 한다"면 메모리가 아니라 저장소 문서로 올려야 한다.
4. Rules 파일로 명령어 제어하기
핵심: .rules 파일로 위험한 명령은 막고, 안전한 명령은 자동 허용해 불필요한 승인 확인을 줄인다.
4.1 Rules가 다루는 문제
AGENTS.md가 팀 위키의 “작업 방식” 페이지라면, Rules는 그 방식 중 셸 명령 부분을 실제로 강제하는 CI 게이트다. 위키에 “테스트 먼저 돌려라”고 적어 두어도 CI가 없으면 선언에 그친다. Rules는 Codex가 셸 명령을 실행할 때마다 “자동 통과 / 사람 확인 / 차단” 중 하나를 자동으로 결정해 그 선언을 집행한다.
AGENTS.md가 “무엇을 해야 하는가”를 설명한다면 .rules 파일은 “샌드박스 밖으로 나가려는 명령을 허용할지, 물어볼지, 막을지”를 정한다. Rules 공식 문서는 Rules를 샌드박스 밖에서 Codex가 실행할 수 있는 명령을 제어하는 기능으로 설명하며, 2026년 5월 기준 실험적 기능이라고 안내한다. 즉 아직 바뀔 수 있는 기능이므로, 팀에 적용하기 전에 최신 문서를 반드시 한 번 더 확인한다.
이 차이를 놓치면 Rules를 샌드박스 자체로 오해하기 쉽다. 샌드박스는 Codex가 기술적으로 어디까지 접근할 수 있는지 정하는 울타리이고, Rules는 그 울타리 밖 실행 요청에 붙는 승인/차단 정책이다. 둘은 서로 대체 관계가 아니라 함께 쓰는 안전장치다.
.rules 파일은 현재 설정이 놓인 위치 옆의 rules/ 폴더 아래에 둔다.
예를 들어 개인 설정에는 ~/.codex/rules/default.rules를 둘 수 있고, 프로젝트별 규칙은 신뢰된 프로젝트 안의 .codex/rules/ 폴더에서 읽힌다(Rules 문서).
규칙 파일을 새로 만들거나 바꾼 뒤에는 Codex를 재시작해야 시작 시점에 다시 스캔된다.
다음 절에서는 규칙 파일의 가장 단순한 형태인 두 필드짜리 규칙부터 시작한다.
4.2 가장 단순한 prefix_rule 한 개
prefix_rule은 “명령어의 앞부분(prefix)이 패턴과 일치하면, 그 명령을 허용할지·물어볼지·막을지 정한다”는 뜻이다. 이름만 보면 낯설지만, 동작 자체는 단순하다.
이 규칙이 하는 일은 단순하다. git status로 시작하는 명령은 자동 허용한다. pattern은 명령의 앞부분, decision은 결정값이다. 이 두 필드만 있어도 규칙은 동작한다.
pattern이 배열인 이유는 명령어를 단어(토큰) 단위로 끊어서 비교하기 때문이다. ["git",
"status"]는 “git”으로 시작하고 두 번째 토큰이 “status”인 명령을 잡는다. 뒤에 --short 같은 플래그가 붙어도 앞부분만 맞으면 이 규칙에 걸린다.
더 알아보기 — Starlark란? (초보자는 건너뛰어도 됩니다)
Rules 파일은 Starlark(스타라크)라는 언어로 작성한다. Python과 생김새가 거의 같지만 파일시스템 접근이나 네트워크 호출 같은 부작용이 없다. 쉽게 말해 "읽기 전용 Python"이라고 보면 된다. 규칙 파일 안에서 실행 코드를 넣는 방식이 아니라 명령 패턴과 결정을 선언하는 방식이라고 이해하면 된다.
4.3 결정값(decision) 3가지와 우선순위
한 줄 요약 — allow = 자동 통과, prompt = 실행 전 물어봄, forbidden = 막힘. 이 셋만 알면 된다.
decision에는 세 가지 값만 있다.
값
동작
언제 쓰나
allow
자동 허용 (사람 확인 없음)
읽기 전용·안전한 명령 (git
status, npm
test)
prompt
실행 전 사람 확인 요청
되돌릴 수 있지만 검토가 필요한 명령 (npm
install, git
push)
forbidden
실행 금지
되돌리기 어려운 명령 (rm
-rf, terraform
apply -var-file=prod)
여러 규칙이 같은 명령에 걸릴 때는 더 제한적인 결정이 이긴다. forbidden
> prompt > allow 순서다.
decision 값을 따로 쓰지 않으면 기본값은 allow다.
4.4 옵션 필드와 응용 예시
pattern과 decision 외에 세 가지 선택 필드를 더 쓸 수 있다.
justification은 이 규칙을 왜 만들었는지 설명하는 메모다. Codex가 사람에게 확인을 요청할 때 이 텍스트를 함께 보여 주므로, 팀원이 규칙의 의도를 바로 알 수 있다.
match에는 이 규칙에 걸려야 하는 명령 예시를, not_match에는 걸리면 안 되는 예시를 적는다. 일종의 인라인 단위 테스트처럼 활용할 수 있어서, 규칙이 많아질수록 이 예시를 빠뜨리지 않는 게 낫다.
네 가지 필드를 모두 활용한 실전 예시다.
# .codex/rules/team.rules
# 프로덕션 terraform apply 차단 — CI/CD 파이프라인을 통해서만 허용
prefix_rule(
pattern = ["terraform", "apply"],
decision = "forbidden",
justification = "프로덕션 배포는 CI/CD 파이프라인을 통해서만. Codex가 직접 apply하면 변경 이력이 남지 않는다",
match = [
"terraform apply -var-file=prod.tfvars",
"terraform apply -var-file=production.tfvars",
],
not_match = [
"terraform apply -var-file=dev.tfvars",
],
)
# Git 읽기 전용 명령은 자동 허용
prefix_rule(
pattern = ["git", ["status", "diff", "log"]],
decision = "allow",
justification = "Read-only git inspection is safe for routine work",
match = [
"git status",
"git diff",
"git log --oneline",
],
not_match = [
"git reset --hard",
],
)
# 파괴적 Git 명령 차단
prefix_rule(
pattern = ["git", "reset", "--hard"],
decision = "forbidden",
justification = "Use a reviewed revert plan instead of destructive reset",
match = [
"git reset --hard",
],
)
# 의존성 변경은 사람이 확인
prefix_rule(
pattern = ["npm", "install"],
decision = "prompt",
justification = "Dependency changes require human review",
match = [
"npm install react",
],
)
심화 예시 — kubectl 읽기/쓰기 분리 (Kubernetes를 쓰지 않는다면 건너뛰어도 됩니다)
not_match로 kubectl 쓰기 명령을 막고 읽기 명령만 허용하는 예시다. 클러스터를 직접 건드리는 명령은 사람이 수동으로 실행해야 하는 환경에서 쓴다.
# kubectl 읽기 전용만 허용 — 쓰기 명령은 수동 실행 금지
prefix_rule(
pattern = ["kubectl"],
decision = "forbidden",
justification = "kubectl 쓰기 명령은 클러스터에 즉시 반영되므로 수동 실행 필요",
not_match = [
"kubectl get",
"kubectl describe",
"kubectl logs",
"kubectl top",
],
)
# 읽기 명령은 자동 허용
prefix_rule(
pattern = ["kubectl", ["get", "describe", "logs", "top"]],
decision = "allow",
justification = "클러스터 조회·로그 확인은 안전한 읽기 작업",
match = [
"kubectl get pods",
"kubectl describe deployment api",
"kubectl logs -f api-pod",
],
)
핵심 패턴: 넓은 forbidden으로 전체를 먼저 막고, 허용할 읽기 명령을 not_match 또는 별도 allow로 예외를 낸다.
4.5 규칙 검증 명령
규칙 파일을 작성한 뒤에는 실제로 원하는 대로 동작하는지 반드시 확인한다. 공식 문서는 codex execpolicy check로 규칙을 검증하는 예시를 제공한다. --rules로 파일을 지정하고, -- 뒤에 검사할 명령을 둔다(Rules 문서).
기본 출력은 JSON 형태이고, --pretty를 붙이면 사람이 읽기 좋은 형태로 확인할 수 있다.
팀에 적용하기 전에는 “허용해야 하는 명령이 막히는가”보다 “막아야 하는 명령이 통과하는가”를 먼저 본다. 예를 들어 파일을 지우거나 Git 기록을 되돌리는 명령은 특히 먼저 확인해야 한다. 여러 명령을 한 번에 감싸서 실행하는 방식은 실제 실행 형태가 단일 명령과 달라질 수 있으므로, 팀이 실제로 쓰는 명령 그대로 검사하는 것이 좋다.
4.6 셸 래퍼: 정의·함정·체크리스트
Rules를 처음 팀에 적용할 때 가장 자주 뚫리는 구멍이 셸 래퍼다. 셸 래퍼는 bash -lc "...", zsh -c "..."처럼 문자열 안에 여러 명령을 담아 실행하는 방식이다.
예를 들어 bash -lc "git add . && rm -rf /"처럼 보이면 겉으로는 하나의 명령이지만, 실제로는 여러 행동이 숨어 있다.
변수 확장, 리다이렉션, 제어문 같은 복잡한 문법 없이 단순한 명령들이 &&, ||, ;, |로 이어진 형태라면 Codex가 이를 개별 명령으로 나누어 규칙을 적용할 수 있다. 하지만 복잡한 셸 문법이 들어가면 사람이 의도한 대로 나뉘지 않을 수 있으므로, 위험한 명령은 실제 실행 형태로 반드시 검사해야 한다.
허용 목록만 있으면 Codex는 목록에 없는 명령도 기본 승인 정책을 따른다. 위험한 명령은 별도로 명시해야 확실히 막힌다.
Rules 적용 전 preflight — preflight는 비행기 이륙 전 조종사가 체크리스트를 점검하듯, 실제 작업 전에 규칙이 의도대로 동작하는지 미리 검사하는 사전 점검이다.
허용하려는 wrapper가 아니라 실제 하위 명령을 기준으로 검사했는가?
삭제, reset, 배포, secret 출력처럼 되돌리기 어려운 명령은 좁은 forbidden 규칙을 먼저 두었는가?
codex execpolicy check로 허용·확인·차단 결과를 실제 명령 문자열로 확인했는가?
새 규칙을 넣은 뒤 Codex를 재시작해 스캔 시점을 맞췄는가?
TUI에서 어떤 명령을 허용 목록에 추가하면 Codex는 사용자 레이어의 ~/.codex/rules/default.rules에 기록해 다음 실행에서 같은 확인을 줄일 수 있다.
Smart approvals란? — 신뢰도 높은 작업은 매번 사람이 승인하지 않아도 자동으로 통과시키는 Codex의 승인 정책 기능이다. SSH의 authorized_keys처럼, 한 번 신뢰 등록된 명령은 매번 승인 없이 자동으로 통과하는 방식이다.
Smart approvals가 켜져 있으면 Codex가 승인 요청 중에 prefix_rule을 제안할 수도 있다. 편하긴 하지만, 제안된 prefix가 너무 넓으면 의도보다 많은 명령을 허용할 수 있으므로 적용 전에 좁게 잡혔는지 확인해야 한다.
Smart approvals가 켜져 있으면 Codex가 승인 요청 중에 prefix_rule을 제안할 수도 있다. 편하긴 하지만, 제안된 prefix가 너무 넓으면 의도보다 많은 명령을 허용할 수 있으므로 적용 전에 꼭 좁게 잡혔는지 확인해야 한다.
Rules 작성 순서: 금지 → 확인 → 허용
파일시스템 삭제, Git 기록 변경, 시크릿 출력처럼 되돌리기 어려운 명령을 forbidden으로 먼저 나열하고, 그 다음에 prompt와 allow를 추가한다.
허용 규칙이 많아지면 패턴이 넓어지기 쉽다. codex execpolicy check로 실제 명령 문자열을 넣어 검사하는 습관이 이 문제를 막는 가장 간단한 방법이다.
5. config.toml 핵심 설정
핵심: config.toml은 모델·승인 정책·샌드박스 수준을 팀 전체에 통일하는 설정 파일이다. 처음에는 기본값 그대로 써도 된다.
프로젝트 헌법(AGENTS.md)과 시행령(Rules)이 준비됐다면, config.toml은 이 모든 규칙이 실제로 집행되는 환경 자체를 설정한다. 어떤 모델에서 실행할지, 승인 없이 진행할 수 있는 범위는 어디까지인지, 파일 시스템 접근 울타리는 어떻게 치는지를 정한다.
config.toml은 Codex의 기본 실행 환경을 정하는 파일이다. 어떤 모델을 쓸지, 명령 실행 전에 승인을 받을지, 파일을 어디까지 수정할 수 있게 할지 같은 값을 여기서 정한다.
Config basics 문서에 따르면 사용자 전역 설정은 ~/.codex/config.toml에 두고, 프로젝트별 설정은 저장소 안의 .codex/config.toml에 둔다.
프로젝트 안의 .codex/ 설정은 신뢰된 프로젝트에서만 로드된다. 프로젝트를 신뢰하지 않음으로 표시하면 프로젝트 로컬 config, hooks, rules는 건너뛰고 사용자/시스템 설정만 로드된다.
# .codex/config.toml — 팀 공유 기본 설정 예시
# model 값은 공식 문서(developers.openai.com/codex/config-reference) 기준으로 확인한다.
# 아래는 구조 예시이므로 실제 모델명은 최신 문서를 참고한다.
approval_policy = "on-request"
sandbox_mode = "workspace-write"
default_permissions = "workspace"
줄별 해설 — 빠뜨리거나 잘못 설정하면 생기는 일
model: 생략하면 Codex 기본 모델로 실행된다. 팀 전체가 같은 모델을 쓰려면 명시하는 것이 낫다. 모델에 따라 컨텍스트 길이와 비용이 다르므로, 긴 코드베이스 작업이라면 미리 확인해야 한다.
approval_policy: "never"로 두면 모든 명령이 승인 없이 실행된다. CI 환경처럼 외부 격리가 확실한 곳이 아니라면 "on-request"가 팀 기본값으로 적합하다.
sandbox_mode: "danger-full-access"는 이름 그대로 샌드박스를 끈다. approval_policy = "never"와 함께 쓰면 완전 자동 전체 접근이 된다. 처음 설정할 때는 "workspace-write"에서 시작한다.
default_permissions: 생략하면 Codex가 기본 권한 프로필로 실행된다. 프로젝트마다 다른 접근 범위가 필요하다면 .codex/config.toml에 별도로 두고 저장소에 커밋한다.
자주 조정하는 값은 세 가지다.
approval_policy로 자동 승인 범위를 정한다. Codex가 명령 실행 전에 언제 멈춰서 사람 확인을 받을지 결정하는 값이다. 팀 기본값으로는 "on-request"가 무난하다.
sandbox_mode는 파일 시스템 접근 허용 범위를 조정한다. "workspace-write"는 작업 디렉토리 안 쓰기를 허용하고, "danger-full-access"는 샌드박스를 끈다.
처음 설정이라면 "workspace-write"에서 시작한다.
default_permissions는 팀 기본 권한 프로필을 덮어쓸 때 쓴다. 프로젝트마다 접근 범위가 다르다면 .codex/config.toml에 별도로 두고 저장소에 커밋하면 팀 전체에 공유된다.
공식 보안 문서는 기본적으로 네트워크 접근이 꺼져 있고, 로컬 Codex는 OS 수준 샌드박스와 승인 정책을 함께 사용한다고 설명한다.
default_permissions는 샌드박스 모드 자체라기보다 재사용 가능한 권한 프로필을 고르는 값이다.
현재 공식 문서 기준으로는 sandbox_mode = "read-only", workspace-write, danger-full-access 같은 sandbox mode와 default_permissions = "workspace" 같은 permission profile을 구분해서 읽는 것이 안전하다.
설정
의미
실전 기준
approval_policy = "untrusted"
더 제한적인 승인 흐름
낯선 저장소, 위험한 자동화
approval_policy = "on-request"
필요할 때 승인 요청
일반적인 팀 개발 기본값
approval_policy = "never"
승인 없이 진행
격리된 환경에서만 신중히 사용
sandbox_mode = "read-only"
읽기 중심 작업
리뷰, 조사, 구조 파악
sandbox_mode = "workspace-write"
작업공간 쓰기 허용
일반적인 기능 수정
sandbox_mode = "danger-full-access"
샌드박스 비활성화
외부 격리가 이미 있는 특수 환경
주의할 점도 있다. workspace-write라고 해서 작업공간 안의 모든 경로가 항상 쓰기 가능한 것은 아니다.
공식 보안 문서는 기본 정책에서 .git, .codex, .agents 같은 보호 경로가 읽기 전용으로 남을 수 있다고 설명한다. 그래서 Git 커밋이나 Codex 설정 파일 변경은 별도 승인이 필요할 수 있다.
특히 sandbox_mode = "danger-full-access"와 approval_policy = "never"를 함께 쓰면 사실상 전체 접근 + 승인 없음 조합이 된다. 공식 문서는 파일 수정과 명령 실행을 자동화하려는 중간 지점으로 workspace-write와 on-request 조합을 예로 든다. 초심자나 일반 팀 개발 환경이라면 이 조합부터 시작하는 게 낫다.
처음 팀 규칙을 도입할 때는 단순한 문자열 정책으로 시작한다. 실제로 막히는 지점이 보이면 그때 조금씩 세분화해도 늦지 않다.
고급 옵션 — granular 승인 정책 (처음 도입할 때는 건너뛰어도 됩니다)
승인 정책을 더 잘게 나누는 방식도 가능하다. 샌드박스 밖으로 나가는 명령은 확인을 받고, Rules 검사는 켜 두고, 별도 권한 요청은 막는 식으로 나눌 수 있다. granular는 이렇게 잘게 나눈다는 뜻이다. (Advanced Configuration 문서 참조 — 실제 팀 설정 전에 최신 필드 목록을 확인한다.)
핵심: 구체적인 규칙이 일반적인 규칙을 이긴다. 하위 디렉토리 설정이 루트보다, AGENTS.override.md가 AGENTS.md보다 먼저 적용된다.
AGENTS.md, .rules, config.toml은 각각 다른 층위에서 동작한다. 어떤 설정이 어떤 설정을 덮어쓰는지 한눈에 보면 이렇다.
설정 우선순위 (높음 → 낮음)
CLI 플래그 / --config 직접 지정 ← 실행 시점에 가장 강하게 적용
──────────────────────────────────
config.toml (프로젝트 .codex/) ← 권한·샌드박스 정책, 팀 기본 실행 환경
AGENTS.override.md ← 특정 폴더에서만 AGENTS.md를 덮어쓰는 로컬 예외
AGENTS.md (저장소 루트) ← 프로젝트 전체 팀 규칙 (자연어 지침)
.rules ← 셸 명령 허용·확인·차단 (실행 정책)
~/.codex/config.toml ← 사용자 전역 기본값 (개인 설정)
규칙이 충돌하면 더 제한적인 결정이 적용된다. Rules에서 forbidden > prompt > allow 순서가 대표적인 예다.
6.1 AGENTS.md 우선순위
여러 AGENTS.md가 동시에 존재하면 작업 디렉토리에 가까운 파일이 우선한다.
즉 하위 디렉토리 AGENTS.md가 저장소 루트보다 우선하고, 저장소 루트가 전역 ~/.codex/AGENTS.md보다 팀 규칙에 더 가깝다(Customization 문서).
이 규칙은 모노레포(monorepo, 프론트엔드·백엔드·공통 라이브러리처럼 여러 프로젝트가 한 저장소 안에 함께 들어 있는 구조)에서 특히 유용하다. 루트에는 공통 규칙을 두고, apps/web/AGENTS.md에는 프론트엔드 규칙을, apps/api/AGENTS.md에는 백엔드 규칙을 둘 수 있다. 서로 다른 영역의 테스트 명령과 금지 파일이 달라도 가까운 파일이 판단 기준이 된다.
6.2 config.toml 우선순위
config.toml에도 별도의 우선순위가 있다. 공식 문서 기준으로는 실행할 때 직접 넘긴 CLI 플래그와 --config 값이 가장 강하다.
그다음은 프로필 값, 프로젝트 config, 사용자 config, 시스템 config, 기본값 순이다(Config basics 문서). CLI 플래그는 터미널에서 명령을 실행할 때 붙이는 옵션이라고 생각하면 된다. 프로젝트 config는 프로젝트 루트에서 현재 작업 디렉토리까지 내려오며 적용되고, 가까운 .codex/config.toml이 더 우선한다.
규칙 충돌을 디버깅할 때는 "AGENTS.md 우선순위"와 "config.toml 우선순위"를 섞지 않아야 한다. 전자는 작업 지침의 가까운 파일 우선이고, 후자는 실행할 때 더 직접 지정한 설정을 우선하는 방식이다.
6.3 Rules 충돌 처리
Rules에서는 여러 규칙이 같은 명령에 매칭될 수 있다. 이때 Codex는 더 제한적인 결정을 적용한다. 공식 문서가 제시한 순서는 forbidden > prompt > allow다(Rules 문서).
따라서 넓은 allow 규칙과 좁은 forbidden 규칙을 함께 둘 수 있다.
예를 들어 git status와 git diff처럼 내용을 확인하는 명령은 허용하되, git reset --hard처럼 작업 내용을 되돌릴 수 있는 명령은 금지하는 식이다.
팀 규칙에서는 넓은 허용보다 좁은 금지 규칙을 명확히 쓰는 편이 리뷰 비용을 줄인다.
7. 팀에 적용하는 방법
핵심: AGENTS.md 한 파일을 저장소에 커밋하면 팀 전체가 같은 Codex 기준을 자동으로 공유한다.
첫 적용은 작게 시작하는 것이 좋다. 루트 AGENTS.md 하나, .codex/config.toml 하나, .codex/rules/team.rules 하나면 충분하다.
팀 공통 규칙으로 확정한 AGENTS.md와 .codex/rules/team.rules는 저장소에 체크인해 같은 기준을 공유한다. 체크인은 Git에 파일을 포함해 팀원이 같은 내용을 받을 수 있게 만드는 과정이다. 그리고 실제 리뷰에서 반복된 피드백만 조금씩 반영한다.
다만 저장소에 넣었다고 해서 항상 강제로 적용되는 것은 아니다. 프로젝트 .codex/ 설정은 신뢰된 프로젝트에서만 로드되고, 사용자 config나 CLI 플래그, 프로필, 기업 관리 설정과 우선순위가 함께 작동한다. 따라서 저장소 체크인은 "팀의 공유 기본값"이고, 반드시 강제해야 하는 보안 정책은 CI, 브랜치 보호, 사전 커밋 훅, 기업용 requirements.toml 같은 관리형 설정과 함께 설계해야 한다.
추천 순서는 다음과 같다.
루트 AGENTS.md에 빌드/테스트 명령과 금지 디렉토리를 적는다.
하위 디렉토리별로 규칙이 다를 때만 추가 AGENTS.md를 만든다.
.codex/rules/에는 자동 허용할 읽기 명령과 금지할 파괴적 명령을 먼저 적는다.
codex execpolicy check로 실제 팀 명령을 검증한다.
PR 리뷰에서 같은 피드백이 반복되면 규칙으로 승격한다.
처음부터 완성된 규칙집을 만들려고 하면 금방 낡는다. 실제 실패 사례를 하나씩 규칙으로 바꾸면 문서는 작게 시작해도 오래 유지된다.
솔직히 말하면, 처음 Rules를 도입할 때 너무 넓은 패턴으로 bash를 허용했다가 의도하지 않은 명령이 통과한 적이 있다. 그 이후로 "허용 규칙은 좁게, 금지 규칙은 먼저"라는 순서를 항상 지키게 됐다. 팀에 적용하기 전에 codex execpolicy check로 실제 명령을 한 줄씩 검사하는 것이 가장 빠른 확인 방법이다.
8. 정리와 Part 5 예고
핵심: AGENTS.md·.rules·config.toml 세 파일이 각각 '무엇을·어떻게 실행할지·어느 수준까지 허용할지'를 담당한다.
AGENTS.md는 Codex에게 "이 프로젝트에서는 이렇게 일한다"를 알려주는 팀 규칙 파일이다. 로컬 메모리가 개인 작업 흐름을 이어주는 보조층이라면, AGENTS.md는 저장소와 함께 이동하는 공유 기준이다.
.rules는 그 기준을 명령 실행 정책으로 한 단계 더 좁힌다. 어떤 명령은 자동 허용하고, 어떤 명령은 매번 확인하고, 어떤 명령은 막을지 파일로 관리할 수 있다. config.toml은 이 규칙들이 동작하는 기본 실행 환경을 정한다.
파일
역할
저장소 공유
AGENTS.md
팀 전체 행동 규칙 (자연어)
Git에 포함 — 팀 공유
.rules
명령 실행 허용·확인·차단 정책
Git에 포함 — 팀 공유
.codex/config.toml
모델·샌드박스·승인 정책 기본값
신뢰된 프로젝트에서 로드
~/.codex/config.toml
개인 전역 기본값
개인 로컬 — 공유 안 함
실전 판단 기준 — 어디에 두면 되는가
팀 전체가 따라야 할 코딩 컨벤션, 테스트 명령, 금지 디렉토리라면 AGENTS.md에 둔다. Git에 함께 커밋하면 팀원 모두에게 같은 기준이 자동으로 전달된다.
"rm -rf 차단"처럼 특정 명령을 막거나, 읽기 전용 Git 명령은 자동 허용하고 싶을 때는 .rules에 둔다. 실행 경계를 선언하는 곳이다.
나만 반복해서 쓰는 워크플로 스타일이나 개인 취향은 내 ~/.codex/config.toml 또는 로컬 메모리에 둔다. 팀 저장소에 올리지 않아도 된다.
