OpenAI Codex와 AGENTS.md — 계층 로딩, 샌드박스 격리, 그리고 멀티 레포 위임

AI 코딩 에이전트가 팀 커밋 컨벤션을 무시하고, any 타입을 아무 데나 뿌리고, 로컬에서 무거운 E2E 테스트를 돌리려 하는 상황. 대개 규칙이 없어서가 아니라 규칙을 전달할 채널이 없어서 생기는 문제입니다. 매 세션마다 시스템 프롬프트에 규칙을 복붙하는 방식은 스케일하지 않고, 도구를 하나 바꾸면 처음부터 다시 해야 합니다.

AGENTS.md는 그 채널을 파일 하나로 정형화합니다. 프로젝트 디렉터리에 놓인 에이전트용 README로, 에이전트가 세션을 시작할 때 자동으로 읽어들여 팀 규칙을 컨텍스트에 포함시킵니다. OpenAI Codex에서 출발해 여러 코딩 에이전트 도구가 점차 채택하고 있는 포맷이지만, 도구마다 우선순위 처리와 기본 규칙 파일(예: Cursor는 .cursor/rules, Windsurf는 .windsurfrules)이 달라 동일 파일이 도구별로 정확히 같은 방식으로 해석되지는 않습니다. 이 글에서는 검증 가능한 범위에서 Codex의 동작을 기준으로 삼습니다.

다룰 주제는 세 가지입니다. 파일 로딩 계층이 실제로 어떻게 병합되는지, 클라우드 에이전트의 샌드박스 2단계 실행 모델이 왜 보안적으로 의미가 있는지, 그리고 모노레포·멀티 레포 환경에서 병렬 에이전트에 팀 규칙을 위임하는 패턴입니다.

파일 로딩 계층: 전역부터 서브디렉터리까지

Codex는 세 스코프의 AGENTS.md를 읽어 하나의 컨텍스트로 이어붙입니다. 스코프별로 커버 범위가 다릅니다.

• 전역: ~/.codex/AGENTS.md — 개인 머신 전체 기본값. 팀원마다 다를 수 있고, 팀 규칙은 여기에 넣지 않습니다.
• 저장소 루트: <git-root>/AGENTS.md — Git에 커밋되는 팀 공통 규칙.
• 서브디렉터리: 에이전트의 작업 경로를 따라 존재하는 모든 AGENTS.md. 파일이 CWD에 가까울수록 우선 해석됩니다.

세 스코프는 덮어쓰기가 아니라 이어붙이기입니다. 충돌하는 지시가 있으면 더 구체적인(현재 디렉터리에 가까운) 파일의 내용이 우선 해석됩니다. 병합된 컨텍스트에는 크기 상한이 있고(관행적으로 32 KiB 안팎), 상한을 넘기면 뒤로 밀린 내용이 잘려나갈 수 있으므로 각 파일은 짧고 밀도 있게 유지하는 편이 안전합니다.

샌드박스 2단계 실행 모델

클라우드 Codex 에이전트는 태스크마다 격리된 컨테이너를 받습니다. 그 컨테이너 안의 실행이 두 단계로 분리된다는 점이 보안적으로 핵심입니다.

Setup 단계에서는 네트워크가 열려 있어 pnpm install, pip install 등 준비 작업을 완료할 수 있습니다. Agent 단계로 넘어가면 네트워크가 차단되고, 환경 안에 CODEX_SANDBOX_NETWORK_DISABLED=1이 설정됩니다. 이 시점부터 에이전트는 오프라인 상태에서 코드 편집·테스트 실행·결과 반환만 수행합니다.

분리의 실질적 이점은 두 가지입니다. 첫째, 에이전트가 실행 중 외부 서버로 데이터를 유출하거나 추가 패키지를 임의로 내려받는 벡터를 원천 차단합니다. 둘째, Setup에서 캐시를 미리 만들어두면 Agent 단계 시간이 짧아져 반복 태스크 비용이 줄어듭니다. 기반 이미지인 codex-universal에는 Python, Node.js, Go, Rust 등 주요 런타임이 사전 탑재되어 있습니다.

승인 모드: 자율성과 안전의 조율

Codex CLI는 에이전트의 자율 범위를 세 단계로 나눕니다.

full-auto는 처음부터 켤 모드가 아닙니다. auto-edit으로 팀이 에이전트의 행동 패턴을 학습한 뒤 단계적으로 확장하는 편이 안정적입니다. 특히 외부 기여자 PR을 받는 저장소에서는 full-auto를 피하는 것이 좋습니다(뒤의 프롬프트 인젝션 항목 참고).

도입 전 검토: 장점과 트레이드오프

실전 적용에 들어가기 전에, 팀 관점에서 무엇을 얻고 무엇을 감수해야 하는지 정리합니다.

체크리스트로 판단해보면 됩니다. 팀이 규칙을 문서화할 만큼 코드베이스가 성숙했는가, 클라우드 실행에 소스를 올릴 수 있는가, PR 리뷰 파이프라인이 병렬 태스크를 소화할 여력이 있는가. 셋 다 예스면 도입 효용이 큽니다.

모노레포에서 계층 구성하기

큰 저장소에서는 루트에 공통 규칙만 두고, 서브디렉터리마다 팀별 규칙을 얹는 구성이 관리하기 편합니다.

<repo-root>/
├── AGENTS.md                   ← 공통: 커밋 컨벤션, 보안 규칙
├── packages/
│   └── web/
│       └── AGENTS.md           ← 프론트엔드: React 패턴, CSS 규칙
└── services/
    └── api/
        └── AGENTS.md           ← 백엔드: API 설계, DB 규칙

에이전트가 packages/web/ 내부에서 작업하면 루트 파일과 packages/web/AGENTS.md가 함께 로드됩니다. 프론트엔드 팀은 자기 규칙만 관리하면 되고, 공통 규칙은 루트가 자동으로 커버합니다.

루트 AGENTS.md의 실용적인 예시입니다. 다국적 기여자를 고려해 파일 자체는 영어로 두는 것을 기본으로 권장합니다.

# AGENTS.md
 
## Build & Test
- Before commit: `pnpm lint && pnpm test`
- E2E: `pnpm test:e2e` (CI only, do not run locally)
- Type check: `pnpm typecheck`
 
## Commit Convention
- Format: `feat:`, `fix:`, `chore:`, `docs:`
- Subject in imperative mood (e.g., "add user auth endpoint")
 
## Code Style
- Functional components only (no class components)
- No `any` types
- Remove `console.log` before committing
 
## Do Not
- Disable the sandbox network guard in test fixtures
  (do not stub or override `CODEX_SANDBOX_NETWORK_DISABLED`)
- Commit real secrets — use `.env.example` templates
- Edit files under `node_modules/` directly

핵심은 실행 가능한 명령과 명시적 금지 규칙입니다. 저장소를 훑으면 알 수 있는 내용(사용 언어, 디렉터리 구조)은 넣지 않습니다.

Setup 스크립트는 AGENTS.md에 경로만 명시하고 별도 파일로 분리하는 편이 관리가 쉽습니다.

## Setup
Environment bootstrap is performed by `./setup.sh`.
All network-dependent downloads must complete in this phase.

#!/bin/bash
# setup.sh — runs in the Setup phase (network allowed)
set -euo pipefail
 
pnpm install --frozen-lockfile
pnpm build:deps

Python·Node 혼합 스택이라면 setup.sh 안에 pip install을 함께 두면 되고, 그 경우 루트 AGENTS.md에도 파이썬 관련 명령(pytest, ruff 등)을 함께 표기해 스택 일관성을 맞춰야 에이전트가 혼동하지 않습니다.

멀티 레포 병렬 위임 패턴

Codex는 매니저 에이전트가 다수의 워커 에이전트를 조율하는 서브에이전트 구성을 지원합니다. 엔지니어링 리드가 티켓 하나를 던지면 매니저가 저장소별로 태스크를 분해하고, 각 워커가 독립 샌드박스에서 진행합니다.

각 저장소에는 그 팀의 AGENTS.md가 존재하므로, api 저장소에서 도는 워커는 자동으로 백엔드 팀의 규칙을 따르게 됩니다. Linear·Jira 같은 이슈 트래커의 티켓을 트리거로 삼아, 하나의 사양이 여러 저장소 PR로 비동기 확산되는 워크플로를 구성할 수 있습니다. 다만 병렬 PR의 상호 의존성과 리뷰 순서는 여전히 사람이 관리해야 합니다.

실무에서 자주 마주치는 함정

LLM에게 AGENTS.md를 대신 쓰게 하는 것. AGENTS.md의 가치는 코드베이스를 봐도 알 수 없는 비자명한 정보에 있습니다. LLM은 코드베이스를 훑고 자명한 사실을 그대로 요약해 넣는 경향이 있어, 컨텍스트 예산만 소모하고 신호 대 잡음비가 떨어집니다. 파일의 선별은 사람이 하는 편이 낫습니다.

시크릿을 파일에 포함시키는 것. AGENTS.md는 Git에 커밋됩니다. API 키·프로덕션 토큰은 환경변수나 시크릿 매니저로 Setup 단계에서 주입해야 합니다.

"규칙을 썼으니 에이전트가 반드시 따른다"는 가정. AGENTS.md는 모델 컨텍스트로 들어가는 텍스트일 뿐, 강제력이 없습니다. 위반 빈도를 줄여줄 뿐 없애지는 못하므로, 승인 모드와 코드 리뷰가 최종 방어선입니다.

프롬프트 인젝션의 저평가. 에이전트가 셸을 실행하는 이상, 저장소에 섞여 들어온 악성 스크립트(postinstall 훅, 타이포스쿼팅 패키지, README 안의 지시문 등)가 인젝션 벡터가 될 수 있습니다. full-auto는 외부 기여자 PR이 들어오지 않는 내부 신뢰 저장소에서만 검토를 거쳐 활성화하는 편이 안전합니다.

컨텍스트 예산 무시. 매우 큰 모노레포를 단일 태스크로 밀어 넣으면 컨텍스트가 포화되어 에이전트가 규칙을 놓칩니다. 서브디렉터리 단위로 태스크를 쪼개고 계층형 AGENTS.md로 스코프를 좁혀 주는 편이 결과가 안정적입니다.

정리

AGENTS.md의 실용적 가치는 한 문장으로 압축됩니다. 팀 규칙을 파일로 만들어두면, 도구와 저장소가 늘어나도 규칙은 자기 자리에 남는다. 도구가 Codex에서 다른 에이전트로 교체돼도 파일은 그대로 쓸 수 있고, 저장소가 여러 개여도 각자의 계층이 살아 있습니다.

기억해둘 지점만 다시 정리합니다.

• 세 스코프의 AGENTS.md는 이어붙여지며, 가까운 파일이 우선 해석됩니다.
• Setup 단계에서만 네트워크가 열립니다. 다운로드가 필요한 모든 작업은 여기서 끝내야 합니다.
• AGENTS.md는 강제가 아니라 안내입니다. 승인 모드와 코드 리뷰가 최종 방어선입니다.
• 파일 선별은 사람이 합니다. LLM에 위임하면 자명한 정보로 채워져 컨텍스트만 소모합니다.

가장 부담이 적은 시작 지점은, 팀에서 자주 어기는 규칙 두세 개와 커밋 컨벤션만 담은 루트 AGENTS.md 하나를 커밋하고, suggest 모드로 며칠 돌려보며 에이전트의 반응을 관찰하는 것입니다. 계층은 그다음에 필요한 곳에만 붙이면 됩니다.

참고 자료

• OpenAI Codex 공식 AGENTS.md (GitHub)
• Sandbox 개념 공식 문서 — OpenAI Developers
• Cloud Environments 공식 문서 — OpenAI Developers
• Agent Approvals & Security — OpenAI Developers
• Introducing Codex — OpenAI 공식 블로그
• Run Long Horizon Tasks with Codex — OpenAI Developers Blog
• Running Codex Safely at OpenAI — OpenAI 공식 블로그
• AGENTS.md 공식 포맷 사이트
• AGENTS.md Spec 2026: Recommended Sections — morphllm.com
• AGENTS.md for OpenAI Codex: Rules, Loading, and Templates — eastondev.com
• Codex CLI Guide 2026: Setup, Sandbox, AGENTS.md & MCP — blakecrosley.com
• Shipyard: Codex CLI Cheatsheet — shipyard.build
• OpenAI Codex Security Risks and Best Practices — cybedefend.com
• Codex Cloud Environments: Setup Scripts and Caching — codex.danielvaughan.com
• AGENTS.md Advanced Patterns: Nested Hierarchies — codex.danielvaughan.com