AI 에이전트 레포 구조Repository Context for Coding Agents
📅
들어가기 전에 🔗
AI 에이전트에게 기능 하나를 맡겼는데, 첫 행동이
이 글에서는 루트 지침, 작업별 문서, 하위 디렉터리 규칙을 연결하는 구조를 만들어 보겠습니다.
docs/ 전체를 읽는 일이라면 레포 구조부터 점검할 때입니다.
문서가 많아서가 아니라, 어떤 작업에 어떤 문서가 필요한지
경로가 없어서 에이전트가 넓게 탐색하는 것입니다.
작은 수정에도 맥락을 과하게 읽으면 비용과 대기 시간이 늘고, 오래된 문서를 근거로 잘못된 결정을 내릴 가능성도 커집니다.
👨💻
본인이 신입사원인데 README 파일 등 문서가 전혀 없는 프로젝트를 넘겨받았다고 생각해 보세요. 화가 많이 나겠죠...
루트 지침에서 작업별 문서와 하위 디렉터리 규칙으로 연결되는 AI 에이전트 레포 구조
컨텍스트 경로 🔗
레포 구조의 목적은 문서를 많이 정리하는 일이 아니라, 작업마다 읽을 문서의 범위를 좁히는 일입니다.
Codex는 저장소 루트부터 현재 작업 경로까지의
AGENTS.md를 순서대로 수집하고, 더 깊은 경로의 지침을 나중에 적용합니다.
OpenAI Docs의 AGENTS.md 로딩 방식↗
따라서 루트의 AGENTS.md에는 어느 작업에도 적용되는 짧은 계약만 두는 것이 좋습니다.
테스트 명령, 패키지 관리자, 변경 시 지켜야 할 호환성 경계처럼 추측하면 위험한 사실
이 여기에 해당합니다. # 프로젝트 공통 규칙
- 패키지 명령은 pnpm을 사용합니다.
- 변경 후 관련 테스트와 pnpm lint를 실행합니다.
- 공개 API와 데이터베이스 스키마 변경은 호환성 영향을 설명합니다.
# 작업별 문서
- 인증 변경은 docs/auth.md를 읽습니다.
- 배포 변경은 docs/deploy.md를 읽습니다.
- 결제 변경은 docs/billing.md와 apps/api/AGENTS.md를 읽습니다.이 파일에 전체 아키텍처나 과거 장애 기록까지 넣으면, 사소한 수정에도 쓸모없는 컨텍스트를 항상 지불하게 됩니다.
OpenAI도 모든 작업 전에 문서 묶음을 강제로 읽히기보다, 작업 조건에 따라 관련 문서를 가리키는 방식을 권장합니다.
OpenAI Developers의 컨텍스트 지침 설계↗
문서 분리 🔗
문서는 읽는 사람보다
읽는 조건
을 기준으로 나눕니다.
아래 구조는 Next.js 서비스와 API를 함께 운영하는 팀에서 바로 쓸 수 있는 예시입니다..
├── AGENTS.md # 모든 작업에 적용되는 최소 규칙
├── README.md # 사람이 빠르게 이해할 프로젝트 소개
├── docs/
│ ├── architecture.md # 서비스 경계가 필요한 변경
│ ├── auth.md # 인증·권한 변경
│ ├── deploy.md # 배포와 운영 변경
│ └── decisions/ # 중요한 설계 결정 기록
├── apps/
│ ├── web/
│ │ └── AGENTS.md # 프런트엔드 지역 규칙
│ └── api/
│ └── AGENTS.md # API와 데이터 접근 지역 규칙
└── packages/
└── ui/
└── AGENTS.md # 디자인 시스템 변경 규칙README.md는 처음 보는 사람이 프로젝트를 이해하는 문서이고, AGENTS.md는 에이전트가 작업을 안전하게 시작하는 지침입니다.
둘을 같은 문서로 만들면 사람에게 필요한 배경 설명과 에이전트가 즉시 실행해야 할 규칙이 섞입니다.👍
문서 위치만 나누고 루트 지침에서 연결하지 않으면, 에이전트는 docs/auth.md가 있는지 알지 못합니다. 특정 작업에 필요한 문서는 파일 이름과 적용 조건을 함께 적어 둡니다.하위 규칙 🔗
하위
AGENTS.md는 루트의 내용을 복사하는 공간이 아닙니다.
해당 폴더에서만 필요한 명령, 테스트 범위, 금지된 의존성처럼 지역성 있는 차이
만 적습니다. # API 변경 규칙
- API 계약 변경 전 docs/architecture.md를 확인합니다.
- 데이터 모델 변경은 prisma migration을 함께 만듭니다.
- apps/api/의 테스트는 pnpm --filter api test로 실행합니다.루트에서 공통 원칙을 지키고, API 디렉터리에서만 API 규칙을 추가하므로 두 문서가 서로 다른 역할을 갖게 됩니다.
이 구조는 모노레포에서 특히 유용합니다.
프런트엔드 작업자가 결제 백엔드 절차를 읽지 않아도 되고, API 수정에만 데이터 모델 지침이 추가되기 때문입니다.
모노레포의 루트 공통 규칙과 웹 API UI 패키지별 지역 규칙이 계층적으로 분리된 모습
탐색 비용 🔗
에이전트가 레포에서 문서를 찾는 방식도 설계 대상입니다.
목표는 문서 탐색을 금지하는 것이 아니라,
기본으로 읽는 범위
와 필요할 때 읽는 범위
를 나누는 것입니다.| 정보 | 기본 로드 | 필요할 때 로드 |
|---|---|---|
| 실행·검증 명령 | AGENTS.md | - |
| 서비스 경계 | 짧은 링크 | docs/architecture.md |
| 인증 정책 | 짧은 링크 | docs/auth.md |
| 변경 이력 | - | docs/decisions/ |
| 특정 앱 규칙 | - | 해당 경로의 AGENTS.md |
작업 요청에도 경로를 함께 주면 더욱 안정적입니다.
예를 들어 “로그인 화면 수정”보다 “
apps/web의 로그인 화면을 수정하고 docs/auth.md의 세션 규칙을 확인해 주세요”가 탐색 범위를 명확히 만듭니다.점검 루프 🔗
구조를 바꾼 뒤에는 실제 에이전트가 필요한 경로만 읽는지 확인해야 합니다.
아래처럼 작은 작업으로 점검하면 문서의 누락과 중복을 빠르게 찾을 수 있습니다.
1. 웹 화면 수정, API 수정, 배포 변경 작업을 각각 하나씩 고릅니다.
2. 각 작업에서 필요한 문서와 AGENTS.md를 목록으로 적습니다.
3. 공통 규칙이 중복되지 않았는지 확인합니다.
4. 작업과 무관한 문서가 기본 지침에 강제되지 않았는지 확인합니다.
5. 문서가 가리키는 테스트 명령을 실제로 실행합니다.git ls-files '*AGENTS.md' 'docs/*.md'로 추적 중인 지침과 주요 문서의 목록을 빠르게 확인할 수 있습니다.
새 팀원이 문서 하나를 고쳤을 때도 이 점검을 반복하면, 시간이 지나며 지침이 비대해지는 것을 막을 수 있습니다.
작업별 문서 확인과 테스트 실행으로 AI 에이전트 레포 구조를 검증하는 반복 흐름
팀 체크리스트 🔗
✓ 루트
AGENTS.md에는 공통 명령과 안전 경계만 둡니다.
✓ 작업별 상세 정보는 docs/로 분리하고 적용 조건을 링크합니다.
✓ 하위 AGENTS.md에는 해당 경로의 지역 규칙만 추가합니다.
✓ README.md와 에이전트 지침의 독자를 분리합니다.
✓ 대표 작업으로 실제 로딩 경로와 테스트 명령을 점검합니다.결론 🔗
AI 에이전트에게 좋은 레포 구조는 “문서가 많은 레포”가 아닙니다.
공통 규칙은 짧게 유지하고, 상세 문서는 작업 조건에 따라 찾아가게 만드는 것이 핵심입니다.
이 경로가 분명해지면 에이전트는 덜 읽고도 더 정확하게 작업하며, 팀은 문서 중복과 컨텍스트 낭비를 함께 줄일 수 있습니다.