에이전트 친화 문서

"AI 에게 이 프로젝트를 알려주는" 문서가 결국 "새 팀원에게 알려주는" 문서와 똑같은 특성을 가집니다. 두 독자가 같은 문서를 읽어 이득.

1. CLAUDE.md (또는 AGENT.md) — 최상위 진입점

# Warragon

다중 서비스 모노레포. Next.js · Spring · FastAPI · Tauri · PostgreSQL.

## 서비스 맵
| 서비스 | 경로 | 스택 |
|---|---|---|
| pryzeet | frontend/pryzeet | Next 16 · TypeORM |
| admin   | frontend/admin   | Next 16 · 5 PG 풀 |
...

## 문서 구조
- docs/RULES.md      — 전역 규칙 (pnpm · AI 크레딧 · SQL=SSOT)
- docs/shared/*.md   — 기술 규칙 SSOT
- docs/agent/{svc}/  — 서비스별 Claude 지시
- docs/service/{svc}/— 제품 · 운영 문서

첫 10 줄만 읽어도 "무슨 프로젝트인지 · 어디서 뭘 찾는지" 가 보여야 합니다.

2. RULES.md — 전역 절대 규칙

## §1. 패키지 매니저
프론트엔드 pnpm · python uv. npm·yarn·pip·poetry 금지.

## §2. Git 커밋 — AI 크레딧 금지
❌ "Co-Authored-By: Claude"
❌ "🤖 Generated with Claude Code"
✅ "[type] 한 줄 요약"

## §4. SQL = SSOT
CREATE IF NOT EXISTS 만, DROP 금지, ALTER 파일 영구 보관 금지

AI 도 사람도 지킬 규칙. 번호 매겨 참조 쉽게.

3. 서비스별 rules.md — 고유 규칙만

# codingstairs — 절대 규칙

전역 규칙은 [RULES.md](...) 참조. 이 파일은 codingstairs 고유만.

## §1 SQL 물리 위치
스키마 SSOT: `frontend/admin/sql/codingstairs/*.sql`

## §8 i18n
next-intl 4.11 · ko 기본 + /en/*

중복 전사 금지. 상위 문서 참조 + 이 서비스만의 규칙.

4. features/ 폴더 — 기능별 컨텍스트

docs/agent/codingstairs/features/
├── notes.md       — /notes 페이지 로직
├── edu.md         — series · lessons CRUD
├── contact.md     — /contact 폼 · inquiries
└── README.md      — 의존 매트릭스

AI 에게 "블로그 수정" 요청 시 features/notes.md 만 로드하면 토큰 절약.

5. skill · agent prompt — 도메인 전문가 표지판

---
name: warragon-codingstairs
description: codingstairs (블로그/노트 + EDU 강좌) 작업 시 사용.
  Next 16 + next-intl · pg 직접 · 7 테이블 · 시드 2단.
  TRIGGER — codingstairs, frontend/codingstairs, 노트, 블로그.
---

# 진입 docs
1. docs/agent/codingstairs/rules.md
2. docs/agent/codingstairs/shared.md
...

AI 가 작업 시작 시 자동 로드. 사람이 읽어도 "이 서비스 전문 체크리스트".

6. 좋은 문서의 특성 (사람 + AI 공용)

• 스캔 가능 — h2/h3 로 구조 · TOC 역할
• 예시 포함 — 추상 설명 + 구체 코드 한 블록
• 링크 명시 — 상대 경로 · 유효성 자동 검증
• 최신 — 변경 시 같은 PR 에 문서도
• 짧음 — 한 문서 2000 단어 이하. 더 길면 분할

7. 나쁜 문서의 특성

• 코드 전문 복사 — src/x.ts:10-25 전체 인용 은 grep 이면 됨
• 엔티티 전 필드 덤프 — SQL 파일 열면 됨
• 설명 장황 — "우리는 ... 도구를 ... 위해 ..." 3 문장이면 충분
• 스크린샷 많음 — 1 년 뒤 UI 변경 시 전부 갱신 필요

8. docs 의 폴더 계약

docs/
├── RULES.md                  — 전역 (~30분 변경)
├── shared/*.md               — 기술 공통 (~분기)
├── agent/                    — AI 작업 지시 (~월)
│   └── {service}/
│       ├── rules.md
│       ├── features/
│       └── shared.md
└── service/                  — 제품 · 운영 (~주 · 일)
    └── {service}/
        ├── prd.md
        ├── api.md
        └── improvements.md

수정 빈도 · 독자 · 목적으로 분리.

9. 자동 검증

# 깨진 마크다운 링크 검출
grep -rn '\[.*\](.*\.md)' docs/ | while read line; do
  path=$(echo "$line" | sed 's/.*(\(.*\.md\)).*/\1/')
  if [ ! -f "$path" ] && [ ! -f "docs/$path" ]; then
    echo "BROKEN: $line"
  fi
done

CI 에 포함. 문서 PR 에서 깨진 링크 자동 block.

10. CHANGELOG — 시간순 이력

# Changelog

## 2026-05-06 (56) — notes · courses 확장
- notes 5 주제 신규 (backend/13 · frontend/15 · data/12 · security/07 · quality/06)
- courses admin-platform 시리즈 시드 (8 step)

## 2026-05-06 (55) — dmddksl UX race 4건 fix
- ...

각 entry: 날짜 (번호) — 제목 + 배경 + 변경 목록. AI 가 "지난 주 무슨 변경?" 질문에 바로 답.

11. 자주 걸리는 자리

• docs 를 한 번 쓰고 잊음 — 3 개월 후 stale. 리뷰에서 "문서도 같이?" 체크
• README 안에 모든 걸 — 스크롤 불가. 파일 분리
• 공식처럼 쓰려 함 — 작업 노트 · 추측도 TODO: 로 남기면 OK
• Mermaid 다이어그램 남용 — 텍스트 표가 대부분 충분

12. 실전 — warragon docs 규모

• 200+ 마크다운 파일
• 15 Claude skill
• 10 서비스 · 각 agent/ + service/

관리 부담 있지만 AI 가 스스로 작업 맥락을 찾음 이라는 가치가 압도적.

하고픈 말

에이전트 친화 문서 = "빠르게 읽을 수 있는 사람 친화 문서". AI 를 위해 과잉 문서화할 필요 없습니다. 사람을 위한 좋은 문서가 AI 에게도 좋음.

Next

• philosophy/06-docs-for-agent-and-human
• agent-tooling/09-claude-md-pattern