에이전트 친화 문서

AI에게 프로젝트를 알려주는 문서는 새 팀원에게 작업 맥락을 알려주는 문서와 같은 성질을 가집니다. 핵심은 많은 문서가 아니라 올바른 진입점, 소유권, 검증 기준입니다.

1. AGENTS.md — 최상위 진입점

# Example workspace

다중 앱·서비스 저장소. 웹·API·워커·PostgreSQL을 사용한다.

## 서비스 맵
| 역할 | 경로 | 스택 |
|---|---|---|
| web | apps/web | Next.js |
| console | apps/console | Next.js |
| api | services/api | Spring |
| worker | services/worker | Python |

## 문서 구조
- docs/RULES.md       — 전역 규칙
- docs/shared/*.md    — 기술 규칙 SSOT
- docs/agent/{role}/   — 역할별 작업 지시
- docs/service/{role}/ — 제품·운영 문서

첫 화면에서 무엇을 만들고 어디서 계약을 찾는지 보여야 합니다. 폴더 목록보다 역할과 읽기 순서를 먼저 적습니다.

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

## §1. 패키지 매니저
프론트엔드는 pnpm, Python은 uv를 사용한다.

## §2. 변경 경계
소유하지 않은 데이터와 비밀값을 임의로 수정하지 않는다.

## §3. SQL = SSOT
스키마 변경은 선언 파일과 마이그레이션을 함께 검증한다.

사람과 에이전트가 모두 지킬 규칙에 번호를 붙이면 리뷰와 자동화가 쉬워집니다. 서비스별 파일에는 전역 규칙을 복사하지 말고 예외만 적습니다.

3. 역할별 rules.md — 고유 규칙만

# console — absolute rules

전역 규칙은 ../../RULES.md를 따른다.

## 데이터 경계
관리 명령은 인증·감사 로그·advisory lock을 통과해야 한다.

## 공개 경계
내부 경로와 실제 운영 호스트를 학습용 예시에 복사하지 않는다.

규칙에는 “왜”보다 실행 가능한 판단 기준과 실패 시 증거를 적습니다.

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

docs/agent/console/features/
├── content.md       — 콘텐츠 목록·편집·검증
├── users.md         — 사용자 권한·감사
└── README.md        — 의존 매트릭스

“검색을 수정해 달라”는 요청에는 검색 기능 문서와 데이터 계약만 먼저 읽게 합니다. 기능 문서는 API, DB, 화면 상태, 검증 명령을 한 묶음으로 소유해야 합니다.

5. Skill·agent prompt — 도메인 표지판

---
name: workspace-console
description: 관리 콘솔과 콘텐츠 계약 작업에 사용.
  Next.js · PostgreSQL · 인증된 쓰기 경계 · 접근성 검증.
  TRIGGER — console, content, audit log.
---

# 진입 문서
1. docs/RULES.md
2. docs/agent/console/rules.md
3. docs/agent/console/features/{기능}.md

작업 범위, 읽을 문서, 좁은 검증 명령을 prompt에 명시하면 토큰과 실수를 함께 줄일 수 있습니다.

6. 좋은 문서의 특성

• 스캔 가능 — h2/h3와 짧은 표로 구조를 보임
• 예시 포함 — 추상 원칙과 안전한 placeholder를 함께 제공
• 링크 명시 — 상대 경로와 공개 경로를 자동 검증
• 최신 — 코드·DB·화면 변경과 같은 변경에서 갱신
• 짧음 — 한 문서가 길어지면 독자와 소유권으로 분할
• 실패 포함 — 오류 상태와 복구 방법을 성공 흐름과 함께 설명

7. 나쁜 문서의 특성

• 코드 전체를 복사해 원본과 drift 발생
• 모든 엔티티 필드를 덤프해 중요한 계약이 묻힘
• 실제 비밀·운영 호스트·프로젝트 고유명을 교육 예시에 노출
• 변경 가능한 화면을 스크린샷만으로 설명

8. docs 폴더 계약

docs/
├── RULES.md                  — 전역 규칙
├── shared/*.md               — 공통 기술 기준
├── agent/{role}/             — AI 작업 지시
│   ├── rules.md
│   └── features/
└── service/{role}/           — 제품·운영 맥락
    ├── prd.md
    ├── api.md
    └── improvements.md

문서의 독자, 소유자, 갱신 주기를 경로에 반영합니다. 공개 교육 콘텐츠는 이 내부 경로를 그대로 보여주지 않고 apps/web, services/api 같은 placeholder를 사용합니다.

9. 자동 검증

# 공개 경로가 실제 대상인지 검사하는 저장소 전용 명령의 예
pnpm content:check
pnpm links:check

링크, UTF-8, frontmatter, 번역 쌍, 고유명사 누출, 예시 비밀값을 CI에서 검사합니다. 문서 변경이 동작 계약을 바꾸면 해당 서비스 테스트도 함께 실행합니다.

10. CHANGELOG — 시간순 이력

# Changelog

## 2026-08-10 — 공개 콘텐츠 범용화
- 실제 서비스 이름과 운영 URL을 placeholder로 교체
- 검색 노트의 공개 slug를 역할 기반 이름으로 변경

각 항목에는 날짜, 배경, 영향 범위, 검증 증거와 롤백 단서를 남깁니다. “무엇을 바꿨나”뿐 아니라 “어떤 사용자가 달라졌나”를 적으세요.

자주 걸리는 자리

• 문서를 한 번 쓰고 갱신하지 않음
• 모든 내용을 README에 넣어 진입점이 길어짐
• 규칙과 실제 검증 명령이 다름
• 교육 문서에 내부 서비스명·호스트·경로를 복사함
• Mermaid를 과하게 써 모바일에서 읽기 어려움

하고픈 말

에이전트 친화 문서는 빨리 읽을 수 있는 사람 친화 문서입니다. 대상 독자, 변경 경계, 실패 기준을 명확히 하면 사람과 AI 모두 같은 근거로 작업합니다.

Next

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