Agentic Coding 시대의 Repo 부트스트래핑 가이드 Part 1: AGENTS.md 와 spec 문서 지형도

이 글은 Claude Opus 4.7 을 이용해 초안이 작성되었으며, 이후 퇴고를 거쳤습니다.

들어가며: README 한 장으로 안 되는 시대#

신규 서비스를 위한 git repo 를 막 만들었다고 합시다. 2년 전이라면 README.md 한 장에 빌드 명령과 디렉터리 구조를 적고, 나머지는 코드와 머릿속에서 합의된 관행으로 굴러갔습니다. 새 팀원이 들어오면 옆 자리 동료가 30분쯤 설명해 주고, 그걸로 충분했습니다.

지금은 그 “옆 자리 동료” 역할의 절반 이상을 Claude Code, Codex CLI, Gemini CLI, Cursor 같은 에이전트가 맡고 있습니다. 그런데 에이전트는 옆 자리에 앉지 않습니다. 매 세션마다 처음 합류한 신입처럼 repo 에 들어와서, 우리가 적어 둔 텍스트만 읽고 일을 시작합니다. 에이전트에게 “이 프로젝트는 이런 곳이고, 이런 규칙으로 일한다” 를 전달하는 문서가 부실하면, 에이전트가 만드는 결과물의 품질은 운에 좌우됩니다.

그 결과, 2025년 한 해 동안 git repo 의 최상위 디렉터리에 다음과 같은 파일들이 우후죽순으로 등장했습니다.

AGENTS.md
CLAUDE.md
GEMINI.md
.cursorrules
.cursor/rules/*.mdc
.windsurfrules
.aider.conf.yml
DESIGN.md
ARCHITECTURE.md
DEVELOPMENT.md
CONTRIBUTING.md
SPEC.md
docs/adr/*.md
docs/specs/*.md

이 글은 신규 서비스 git repo 를 부트스트래핑할 때, 2026년 5월 기준 de-facto 가 된 문서 셋과 그 역할 범위 를 정리합니다. 다음 편에서는 가상의 Go + Templ + HTMX 기반 To-Do 앱을 만든다고 가정하고, 위 문서들을 실제로 어떻게 채우는지 발췌 형태로 보여 드립니다.

2026-05 현재, spec 문서 지형도#

먼저 한눈에 보는 지도부터 그려 보겠습니다. 카테고리는 다음 다섯 가지입니다.

카테고리	대표 파일	주된 독자	역할
Agent 지시문	`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `.cursor/rules/*.mdc`, `.windsurfrules`	코딩 에이전트	매 세션마다 자동 주입되는 “이 repo 의 규칙”
아키텍처/설계	`ARCHITECTURE.md`, `DESIGN.md`, `docs/adr/*.md`	사람 + 에이전트	시스템 구조(ARCHITECTURE), 시각 디자인 시스템(DESIGN), 설계 의사결정의 “왜”(ADR)
개발 규약	`DEVELOPMENT.md`, `CONTRIBUTING.md`	사람 + 에이전트	빌드/테스트/포맷, 커밋 컨벤션, PR 흐름
명세	`SPEC.md`, `docs/specs/NNN-*.md`	사람 + 에이전트	feature 단위의 요구사항과 수용 기준
진입점	`README.md`	사람(우선) + 에이전트	무엇이고, 어떻게 5분 안에 굴려 볼 수 있는지

각 카테고리를 차례로 살펴봅니다.

1) Agent 지시문#

매 세션마다 에이전트의 컨텍스트에 자동으로 주입되는 문서입니다. 도구별로 파일명이 갈렸는데, 이게 2025년 한 해 동안 가장 혼란이 컸던 지점입니다.

AGENTS.md — 도구 중립적인 통합 표준. Codex CLI, Cursor, Aider, Continue, Sourcegraph Amp 등이 1차적으로 이 파일을 읽습니다.
CLAUDE.md — Claude Code 의 네이티브 파일. 전역(~/.claude/CLAUDE.md), 프로젝트(./CLAUDE.md), 하위 디렉터리 단위로 계층적으로 누적됩니다.
GEMINI.md — Gemini CLI 의 네이티브 파일.
.cursor/rules/*.mdc — Cursor 의 새 형식. 과거 .cursorrules 단일 파일에서 모듈화된 .mdc(Markdown + frontmatter) 다중 파일로 이전됐습니다.
.windsurfrules — Codeium Windsurf 용.

좋은 소식은, 2025년 후반부터 AGENTS.md 가 사실상 통합 표준 으로 자리 잡으면서 도구별 파일은 “이 파일도 같이 본다” 정도의 보조 역할로 정리되고 있다는 점입니다. 이 부분은 잠시 뒤 별도 섹션에서 다룹니다.

2) 아키텍처/설계 문서#

ARCHITECTURE.md 와 DESIGN.md 의 경계는 팀마다 다른데, 가장 흔한 구분은 이렇습니다.

ARCHITECTURE.md — 시스템 관점. 컴포넌트, 의존성, 데이터 흐름, 도메인 모델, 배포 토폴로지, 외부 시스템 연동. “어떻게 조립되어 있는가” 를 답합니다.
DESIGN.md — 시각 디자인 시스템. 컬러 팔레트, 타이포그래피, 컴포넌트 스타일, 레이아웃 원칙, Do’s & Don’ts. “어떤 모양인가” 를 답합니다.

DESIGN.md 는 2025년 후반 Google Stitch 가 제안한 비교적 새 컨벤션입니다(Stitch DESIGN.md format). 정의가 비교적 명확하다는 게 장점입니다 — AGENTS.md 가 “어떻게 빌드하는가” 라면 DESIGN.md 는 “어떤 모양인가” 입니다. VoltAgent 의 awesome-design-md 는 Linear/Vercel/Stripe 같은 실제 사이트 73개의 DESIGN.md 를 모아 둔 좋은 레퍼런스입니다.

표준 9개 섹션은 다음과 같습니다.

Visual Theme & Atmosphere — 무드, 밀도, 디자인 철학
Color Palette & Roles — 의미적 이름 + hex + 역할
Typography Rules — 폰트 패밀리, 위계 표
Component Stylings — 버튼/카드/입력 + 상태
Layout Principles — 간격 스케일, 그리드
Depth & Elevation — shadow 시스템
Do’s and Don’ts — 가드레일, 안티패턴
Responsive Behavior — breakpoint, 터치 타깃
Agent Prompt Guide — 에이전트에게 던질 짧은 프롬프트

도메인 모델/사용자 흐름은 (이름이 헷갈리지만) DESIGN.md 가 아니라 ARCHITECTURE.md 또는 feature spec 의 영역입니다. 작은 프로젝트라면 DESIGN.md 를 생략해도 되지만, UI 가 있는 서비스라면 새 화면을 만들 때마다 에이전트가 “이번 색은 뭘 쓸까” 를 매번 새로 결정하지 않도록 한 번 적어 두는 편이 큽니다.

docs/adr/ 는 ADR(Architecture Decision Records). 큰 의사결정을 시간 순서대로 누적합니다. Michael Nygard 의 고전 포맷이 여전히 표준입니다.

# ADR-0001: HTMX 채택

## Status
Accepted (2026-05-28)

## Context
브라우저에서 SPA 빌드 파이프라인을 운영할 인력이 없고,
SSR 기반의 단순한 인터랙션만 필요함.

## Decision
HTMX 를 채택한다. 클라이언트 사이드 JS 는 최소화한다.

## Consequences
- 빌드 파이프라인이 단순해진다 (esbuild/vite 불필요).
- 복잡한 client state 가 필요한 화면이 생기면 재검토 필요.

ADR 의 핵심 가치는 “왜 그렇게 결정했는가” 가 git log 에 묻히지 않는다 는 점입니다. 에이전트가 “이 부분 React 로 바꿔도 될까요?” 같은 질문을 받았을 때, ADR-0001 을 근거로 “이미 의도적으로 거부된 옵션” 임을 답할 수 있습니다.

3) 개발 규약 문서#

DEVELOPMENT.md — 개발자(사람/에이전트)가 매일 쓰는 명령어와 워크플로우. 빌드, 테스트, 포맷, 로컬 실행, 환경변수, 디버깅 팁.
CONTRIBUTING.md — 외부 기여자(또는 새 팀원)를 위한 절차. 브랜치 전략, PR 템플릿, 코드 리뷰 흐름, 행동 강령.

이 둘은 자주 혼동되는데, 구분 기준은 단순합니다. “매일 본다 → DEVELOPMENT.md, 처음 한 번 본다 → CONTRIBUTING.md”. 1인 프로젝트라면 DEVELOPMENT.md 만 두고 CONTRIBUTING.md 는 생략해도 됩니다.

4) 명세 문서#

SPEC.md 또는 docs/specs/NNN-*.md 형태로 feature 단위의 요구사항과 수용 기준을 적습니다. 2025년에 GitHub 의 Spec Kit 이 보급되면서 “feature 하나당 spec 하나” 패턴이 자리 잡았습니다.

docs/specs/
├── 001-task-crud.md
├── 002-due-date-reminder.md
└── 003-multi-user-sharing.md

각 spec 파일은 보통 다음 섹션을 가집니다. Background / Goals / Non-goals / Acceptance criteria / Open questions. 에이전트가 코드를 쓰기 전에 이 파일을 먼저 읽도록 하면, 작업 도중 “이게 요구사항이 맞나요?” 를 묻는 빈도가 눈에 띄게 줄어듭니다.

5) 진입점: `README.md`#

여전히 가장 먼저 읽히는 파일입니다. 다만 agent-friendly 한 README 의 형태는 과거와 다릅니다.

3줄 quick start 를 가장 위에 둡니다. git clone 부터 make dev 까지.
What it is / What it isn’t 를 짧게 둡니다. 에이전트가 잘못된 가정을 하지 않게.
세부 규칙은 다른 문서로 위임 합니다. README 가 모든 걸 담으려 들면 1500줄짜리 괴물이 됩니다.

# gotodo

A minimal SSR-based To-Do app. Go + Templ + HTMX + SQLite.

## Quick start
git clone ...
make dev          # http://localhost:8080

## Where to go next
- `AGENTS.md`        — 에이전트가 따라야 할 규칙
- `ARCHITECTURE.md`  — 시스템 구조와 도메인 모델
- `DEVELOPMENT.md`   — 매일 쓰는 명령어
- `docs/specs/`      — 진행 중인 feature spec

왜 AGENTS.md 가 통합 표준이 되었나#

2025년 초까지만 해도 repo 최상위는 CLAUDE.md, .cursorrules, GEMINI.md, .windsurfrules 가 동시에 존재하고 내용도 70% 가량 중복되는 카오스였습니다. 같은 내용을 4번 적고, 4번 동기화하는 건 사람도 에이전트도 손해입니다.

이 문제를 정리하기 위해 2025년 중반에 도구 벤더들이 AGENTS.md 라는 도구 중립적 단일 파일 을 합의했습니다. OpenAI 의 Codex CLI 가 가장 먼저 1차 시민으로 채택했고, 이어 Cursor, Aider, Continue, Sourcegraph Amp 등이 합류했습니다. Anthropic 의 Claude Code 도 CLAUDE.md 와 AGENTS.md 를 함께 인식하는 방향으로 정리됐습니다. Google 의 Gemini CLI 는 여전히 GEMINI.md 를 우선하지만, AGENTS.md 도 함께 읽을 수 있습니다.

실무에서 권장되는 패턴은 “AGENTS.md 를 단일 진실 원본(Single Source of Truth)으로 두고, 도구별 파일은 symlink 또는 짧은 보강 파일로 둔다” 입니다.

# AGENTS.md 를 원본으로 두고
echo "..." > AGENTS.md

# Claude Code 와 Gemini CLI 가 같은 내용을 보도록 symlink
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md GEMINI.md

이 방식의 장점은 명확합니다. 한 곳만 고치면 모든 에이전트가 같은 규칙을 따른다. Git 도 symlink 를 그대로 추적하므로 다른 개발자도 동일한 상태를 받습니다.

다만 도구별로 진짜로 갈리는 영역은 따로 보강해야 합니다. 예를 들어 Claude Code 의 hooks/skills/slash command 같은 기능은 다른 도구에 없으므로 CLAUDE.md 를 symlink 대신 짧은 보강 파일로 두고, 본문은 AGENTS.md 를 include 하는 식으로 갈 수도 있습니다.

# CLAUDE.md
@AGENTS.md

## Claude Code 전용 보강

이 repo 의 `~/.claude/commands/` 에 `/release` 가 정의되어 있습니다.
릴리스 직전에는 항상 `/release dry-run` 을 먼저 실행해 주세요.

Claude Code 는 @파일경로 형태로 다른 markdown 을 끌어와 합치는 include 문법을 지원합니다. 다른 도구에서는 작동하지 않을 수 있으므로, 가장 안전한 방식은 여전히 symlink 입니다.

.cursor/rules/*.mdc 의 경우 파일별로 적용 범위(glob, alwaysApply 여부)를 frontmatter 로 제어할 수 있어서 symlink 보다는 AGENTS.md 의 일부 섹션을 발췌해서 .mdc 로 옮기는 방식이 더 어울립니다.

“어디에 무엇을 적을 것인가” 매트릭스#

같은 정보를 여러 문서에 중복으로 적으면 동기화 비용이 폭증합니다. 다음은 정보 유형별로 1차 거주지를 정하는 매트릭스입니다.

정보 유형	1차 거주지	비고
이 프로젝트가 무엇인지 (1~2줄)	`README.md`	`AGENTS.md` 최상단에도 같은 문장 한 번 더
빌드/테스트/실행 명령어	`DEVELOPMENT.md`	`AGENTS.md` 에서는 “자주 쓰는 명령 표” 만 짧게
디렉터리 구조	`ARCHITECTURE.md`	`AGENTS.md` 에서는 “이 폴더는 이런 역할” 만 1줄씩
도메인 모델 / 핵심 엔티티	`ARCHITECTURE.md`	다이어그램(Mermaid) 권장
컬러/타이포/컴포넌트 스타일	`DESIGN.md`	Stitch 표준 9개 섹션. UI 가 없는 프로젝트라면 생략 가능
큰 의사결정의 “왜”	`docs/adr/NNN-*.md`	`AGENTS.md` 에서는 “이 결정은 ADR-NNN 참조” 1줄
feature 요구사항/수용 기준	`docs/specs/NNN-*.md`	진행 중인 feature 만 활성, 완료된 건 archived
코딩 스타일/네이밍	`AGENTS.md` 또는 `DEVELOPMENT.md`	linter 로 강제 가능한 것은 linter 설정이 우선
커밋 메시지/PR 컨벤션	`CONTRIBUTING.md` 또는 `DEVELOPMENT.md`	commitlint/danger 등으로 자동 강제하면 더 좋음
보안/시크릿 처리 규칙	`AGENTS.md` 의 별도 섹션	“절대 `.env` 를 커밋하지 말 것” 같은 핵심 금지사항

핵심 원칙은 “1차 거주지 1곳 + 나머지는 1줄 포인터” 입니다. 같은 문장을 두 문서에 적지 마세요. 한쪽이 낡으면 다른 쪽은 거짓말이 됩니다.

공통 best practices 5가지#

1. 짧게, 그리고 우선순위대로#

에이전트의 컨텍스트 윈도우는 유한합니다. 1000줄짜리 AGENTS.md 는 그 자체로 안티패턴입니다. 실무에서 권장되는 길이는 AGENTS.md 200~400줄 이내, 각 보조 문서는 그보다 짧게 입니다. 그 이상 필요하면 카테고리를 쪼개세요.

또 글의 위쪽일수록 더 중요한 규칙을 둡니다. 에이전트는 사람보다도 “맨 위에 적힌 것” 을 더 잘 따르는 경향이 있습니다.

2. “왜” 위주로 적을 것#

코드가 답해 줄 수 있는 정보(파일이 어디 있는지, 함수 이름이 뭔지)는 적지 마세요. 코드를 봐도 안 보이는 정보, 즉 제약, 결정의 이유, 과거에 시도했다가 폐기한 접근, 외부 시스템과의 암묵적 약속 위주로 적습니다.

Bad: “user_service.go 에는 UserService 가 정의되어 있습니다.”

Good: “User 의 email 은 unique 하지 않습니다. 동일 email 로 여러 계정이 존재할 수 있으며, 이는 2025-08 의 결정입니다 (ADR-0007 참조).”

3. 검증 가능한 명령어를 포함할 것#

“테스트는 잘 통과해야 합니다” 같은 모호한 문장 대신, 실행 가능한 명령어 를 함께 적습니다. 에이전트는 실행해서 결과를 보는 쪽으로 자연스럽게 흐릅니다.

## 작업 완료 전 체크리스트
- [ ] `make test` 가 통과한다.
- [ ] `make lint` 가 0 exit code 로 끝난다.
- [ ] `make build` 가 성공한다.

4. 살아 있는 문서로 유지할 것#

AGENTS.md 와 README.md 의 명령어 블록이 실제로 동작하는지 CI 에서 검증하는 팀이 늘고 있습니다. 가장 단순한 형태는 다음과 같습니다.

# .github/workflows/docs.yml
- name: Verify quick start commands
  run: |
    grep -A1 'Quick start' README.md | tail -1 | sh

작은 장치이지만, 문서가 거짓말을 못 하게 막아 줍니다.

5. 도구별 보강은 격리된 섹션으로#

AGENTS.md 본문은 도구 중립이어야 합니다. Claude Code 의 hooks, Cursor 의 .mdc glob 같은 도구별 디테일은 별도 섹션이나 별도 파일로 분리하세요.

## 도구별 보강 (Tool-specific)

### Claude Code
- `/release` slash command 는 `~/.claude/commands/release.md` 에 정의되어 있습니다.
- pre-commit hook 으로 `gofmt` 를 강제합니다.

### Cursor
- `.cursor/rules/templ.mdc` 가 `*.templ` 파일에 자동 적용됩니다.

이렇게 두면, 새 도구가 추가됐을 때 해당 섹션만 추가하면 됩니다.

흔한 안티패턴 3가지#

안티패턴 1: 1500줄짜리 `CLAUDE.md`#

가장 자주 보는 실패 모드입니다. “혹시 빠뜨릴까 봐” 모든 규칙, 모든 명령어, 모든 코딩 컨벤션을 한 파일에 욱여넣고, 결과적으로 에이전트의 컨텍스트 윈도우를 매 턴마다 잡아먹습니다. 문서가 길어지면 에이전트의 주의력은 떨어집니다. 200줄을 넘기 시작하면 분리할 시점입니다.

안티패턴 2: 같은 정보 3곳 중복#

README.md 에 빌드 명령, DEVELOPMENT.md 에 빌드 명령, AGENTS.md 에도 빌드 명령. 처음엔 친절해 보이지만, 한 곳을 고치면 나머지가 곧바로 거짓말이 됩니다. 1차 거주지 1곳, 나머지는 포인터.

안티패턴 3: README 는 사람이 읽고 `AGENTS.md` 는 에이전트가 읽는다는 분리#

가장 위험한 분리입니다. 에이전트는 매 세션마다 AGENTS.md 를 읽지만, 사람도 그걸 읽어야 합니다. 사람과 에이전트가 같은 규칙으로 일해야 결과가 일관됩니다. AGENTS.md 는 “에이전트 전용” 이 아니라 “이 repo 에서 일하는 모든 주체가 따르는 규칙” 으로 두십시오.

다음 편 예고#

다음 편에서는 가상의 Go + Templ + HTMX 기반 To-Do 앱 gotodo 를 부트스트래핑한다고 가정하고, 위에서 다룬 문서들을 실제로 어떻게 채우는지 발췌 형태로 보여 드립니다. git init 직후의 빈 repo 에서 시작해서, 첫 feature spec 으로 에이전트에게 작업을 시키기까지의 흐름을 따라갑니다.

Step 0: git init 직후 1차 골격
Step 1: agent-friendly README.md
Step 2: AGENTS.md + symlink 설정
Step 3: ARCHITECTURE.md (도메인 모델, Templ 컴포넌트 구조)
Step 4: DESIGN.md (Stitch 포맷의 시각 디자인 시스템)
Step 5: 첫 ADR
Step 6: DEVELOPMENT.md
Step 7: 첫 feature spec
검증: Claude Code 에 작업을 시켜 보기
부트스트래핑 체크리스트

이어서 보겠습니다.