1. 과제: 왜 「코딩 규약(Coding Convention)만」으로는 부족한가

기존의 프로젝트 구성은 인간의 가독성과 유지보수성을 주요 기준으로 설계되어 왔습니다. AI 에이전트가 일상적으로 코드베이스를 읽고 쓰게 되면서, 새로운 제약 조건도 추가되었습니다.

| 관점 | 인간 중심의 설계 | AI 에이전트 중심으로 추가되는 제약 |
|---|---| |
| 정보 탐색 방법 | IDE의 검색·보완·경험을 통해 추적 | 디렉토리 이름·파일명·프론트매터(Frontmatter)로부터 기계적으로 추측 |
| ... |
AI 시대의 디렉토리 구성이란,

에이전트에 대한 컨텍스트 엔지니어링(Context Engineering)을 파일 시스템 레벨에서 설계하는 행위입니다. 무엇을 루트에 둘 것인지, 무엇을 깊숙이 숨길 것인지, 무엇을 별도의 리포지토리로 분리할 것인지. 이 판단이 정확도와 비용 모두에 직결됩니다.

2. 전체상: 2종류의 리포지토리를 구분하여 사용하기

| 프로덕트 리포지토리 | 에이전트 리포지토리 | |
|---|---| |
| 목적 | 프로덕트 자체를 구현함 | AI 에이전트의 운용을 담당함 |
| ... |

혼재되었을 때 발생하는 일 (안티 패턴)

• 프로덕트의 코드 리뷰에 무관한 프롬프트(Prompt) 변경 차분이 섞임
• 도메인 지식(Domain Knowledge)이 코드 리포지토리의 라이프사이클(브랜치 삭제, force push 등)에 휘말려 소실됨
• 여러 프로덕트를 가로지르는 팀이 프로덕트마다 에이전트 설정을 재구현함

따라서, 「에이전트를 움직이는 조작 코드」와 「에이전트가 참조하는 세계 지식」을 분리합니다.

Garry Tan의 gbrain은 이를 agent repo / brain repo로 정리하고 있습니다.

에이전트의 설정은 교체 가능하며, 세계 지식은 영구적인 자산이라는 경계 설정 방식입니다.

3. 프로덕트 리포지토리의 구성

your-product-repo/
├── README.md # 인간용: 개요·셋업
├── AGENTS.md # AI용: 정전(Canon). 빌드/테스트/규약/금지 사항
...

3.1 정전 파일은 AGENTS.md로 일원화한다

2025년 후반기 이후, AGENTS.md는 여러 AI 코딩 도구가 공통으로 읽어들이는 기계 판독 가능한 운용 컨텍스트 파일로서 업계 표준이 되어가고 있습니다.

README.md
—인간용. 프로젝트의 목적, 셋업 절차, 컨트리뷰션 가이드 -
AGENTS.md
—AI용. 빌드나 테스트 명령, 코딩 규약, 디렉토리의 의미, 금지 사항

CLAUDE.md와 같은 도구 특화 파일은 내용을 중복시키지 않고, 「상세 내용은 AGENTS.md를 참조」라는 얇은 포인터 역할만 수행합니다. 여러 도구를 병용하더라도 규칙의 분기나 중복이 발생하지 않습니다.

3.2 rules는 glob 스코프로 세분화한다

루트에 거대한 규칙 파일을 하나 두면, 무관한 태스크에서도 매번 컨텍스트에 포함됩니다. .mdc의 프론트매터(Frontmatter)에서 globs를 지정하여, 해당 경로를 다룰 때만 발화하도록 합니다.

---
description: 프론트엔드 코딩 규약
globs: "src/frontend/**/*.tsx"
...

• alwaysApply: true는 정말로 모든 태스크에 필요한 원칙(보안, 명명 규칙 등)으로 한정할 것
• 기능 영역별, 레이어별로 파일을 나누어 파일 하나를 작게 유지할 것
• 중첩된 rules/의 동작은 도구마다 차이가 있으므로, 우선은 1계층 플랫(Flat) + glob 스코프를 기본으로 할 것

3.3 모노레포는 「루트 개요 + 패키지 상세」의 계층 구조로 한다

monorepo/
├── AGENTS.md # 전체상 + 각 패키지로의 포인터
├── packages/
...

에이전트가 packages/web/에서 작업할 때는 packages/web/AGENTS.md만 읽으면 되며, 무관한 패키지의 정보를 읽어들이지 않습니다.

3.4 의사결정의 이유는 ADR에 남긴다

「왜 이 구성을 선택했는가」는 코드나 디렉터리 이름만으로는 파악할 수 없습니다. ADR (Architecture Decision Record)로서 docs/architecture/에 **배경·비교한 대안·트레이드오프 (Trade-off)**를 기록해 두면, 과거의 의사결정을 무시한 역행적인 제안을 에이전트가 내놓을 리스크를 줄일 수 있습니다.

3.5 생성물과 비밀 정보는 읽기 대상에서 제외한다

4. 에이전트 리포지토리의 구성

agent-ops-repo/ # 에이전트 본체 (조작 코드)
├── .cursor/
│ ├── skills/
...

4.1 「에이전트 본체」와 「지식 베이스 (Knowledge Base)」를 분리한다

동작 정의 (스킬, 워크플로우, MCP 설정)는 변경 빈도가 중간 정도이며, Git 관리를 세심하게 하고 싶은 대상입니다. 반면 도메인 지식 (화면 사양, 용어집, API 사양)은 최신성 유지가 중요하며, 업데이트 빈도와 담당자도 다릅니다. 분리의 장점은 다음과 같습니다.

• 지식 베이스의 업데이트가 워크플로우의 코드 리뷰 (Code Review)를 거치지 않고 빠르게 반영될 수 있음
• 여러 에이전트 리포지토리 (QA용, 개발용, PdM용)가 동일한 지식 베이스를 공유할 수 있음
• 지식 베이스를 개인의 로컬 환경에 의존하지 않는, 팀의 공식적인 공유 자산으로 둘 수 있음

4.2 스킬은 프론트매터 (Frontmatter)와 단계적 공개로 구성한다

skills/generate-test-cases/
├── SKILL.md # 프론트매터 (description 등) + 실행 절차 요약
├── references/ # 상세 사양·템플릿 (필요할 때만 읽음)
...

SKILL.md는 간결하게 유지하고, 상세 내용은 references/로 넘깁니다. 이렇게 하면 가시성 (어떤 스킬이 있는지 파악하기 쉬움)과 컨텍스트 효율 (Context Efficiency) (사용할 때만 상세 내용을 읽음)을 양립할 수 있습니다.

4.3 멀티 프로젝트 대응은 「규칙 + 로컬 상태 파일」로 해결한다

하나의 에이전트 리포지토리에서 여러 프로덕트를 다루는 경우, 「지금 어떤 프로덕트의 문맥인가」를 자동으로 판정하는 메커니즘이 필요합니다.

• 규칙 측 (project-detection.mdc)에 판정 로직과 지식 베이스의 경로 해결 규칙을 작성한다.
• 어떤 프로젝트가 활성화되어 있는지는 Git 관리 외의 로컬 상태 파일에 담는다.
• 상태 파일은 .example이 붙은 템플릿을 커밋하고, 각 멤버가 복사해서 사용한다.

{
"project": "product-a",
"knowledgeRoot": "/path/to/knowledge-repo/projects"
...
}

위의 current-project.json은 .gitignore 대상으로 지정하며, 각자가 로컬에서 유지합니다.

4.4 생성물과 출력은 명확하게 격리한다

에이전트의 생성물 (리포트, 테스트 케이스 CSV, 분석 결과)은 outputs/에 모으고, .gitignore 처리합니다.

• **소스 (지식·설정)**와 **생성물 (실행 결과)**이 혼재되지 않음 - diff가 「의도적인 설정 변경」만을 반영하여, 실행할 때마다 지저분해지지 않음
• 영구 저장하고 싶은 경우에는 명시적으로 별도의 스토리지 (Notion, Wiki, 외부 DB 등)로 내보내는 설계로 한다

4.5 MCP 설정은 스코프를 나누어 관리한다

API 키 등은 설정 파일에 직접 쓰지 않고 환경 변수 (Environment Variable)를 참조하게 하며, 설정 파일 자체는 안전하게 커밋할 수 있는 상태를 유지합니다.

5. 양측에 공통되는 6가지 원칙

6. 흔한 실패 패턴과 대책

7. 실천 체크리스트

7.1 프로덕트 측 점검 항목

• 루트에 AGENTS.md (진실 파일)가 있는가? - 도구별 파일은 진실 파일에 대한 참조만 포함하며, 내용을 중복시키지 않는가?
• .cursor/rules/*.mdc가 glob 스코프를 통해 기능 단위로 분할되어 있는가?
• alwaysApply: true는 모든 태스크 공통 원칙에만 한정되어 있는가?
• 모노레포(Monorepo)의 경우, 패키지마다 AGENTS.md가 있는가?
• 주요 설계 결정이 ADR로서 기록되어 있는가?
• .env나 비밀 정보가 읽기 대상에서 제외되어 있는가?

7.2 에이전트 측 점검 항목

• 에이전트 본체와 지식 베이스(Knowledge Base)가 분리되어 있는가?
• 스킬이 '1스킬 1디렉토리' 구조이며, SKILL.md와 references/로 나뉘어 있는가?
• 판정 로직(규칙)과 활성 상태(로컬 파일)가 분리되어 있는가?
• 생성물 전용 디렉토리가 .gitignore 처리되어 있는가?
• MCP 설정이 스코프별로 정리되어 있으며, 비밀 정보를 포함하지 않는가?
• 지식 베이스에 최종 업데이트 날짜와 정보 출처가 명시되어 있어 신선도(Freshness)를 추적할 수 있는가?

8. 요약

AI 시대의 디렉토리 구성 설계란, 인간의 가독성에 더해 AI 에이전트의 컨텍스트 효율(Context Efficiency)·신선도·스코프 제어를 동시에 최적화하는 파일 시스템 설계입니다.

• 프로덕트 리포지토리에서는 진실 파일의 단일화와 glob 스코프를 통한 규칙 분할이 핵심입니다.
• 에이전트 리포지토리에서는 '조작 코드'와 '세계 지식'의 분리, 스킬의 단계적 공개 구조가 핵심입니다.
• 두 경우 모두 공통적으로 생성물과 소스의 분리, 로컬 상태의 분리, 판단 이유의 기록이 장기적인 유지보수성을 결정합니다.

참고 링크

표준화·사양계

Discussion