사람용 문서와 에이전트용 문서
사람용 문서와 에이전트용 문서
저장소에는 두 종류의 독자를 위한 문서가 공존합니다. 사람과 코드 보조 에이전트 (LLM 기반 IDE 보조 · AI 코더). 이 글은 두 종류의 표준 · 관습.
1. 사람용 문서의 표준
README — 1980 년대 전후의 Unix 소프트웨어 배포에서 굳어진 관습. 패키지의 최상위에 모든 대문자 이름의 텍스트 파일을 두어 사용자가 가장 먼저 읽도록 유도. GitHub 가 2008 년 출범 후 저장소 첫 화면에 README 를 자동 렌더링하면서 사실상 표준의 위치.
대표 구성:
- 프로젝트 소개 · 목적
- 설치 · 실행
- 사용법 · 예시
- 기여 방법 (또는
CONTRIBUTING.md로 분리) - 라이선스
CONTRIBUTING.md — GitHub 가 Issue / PR 작성 시 자동 안내 링크로 사용. 프로젝트 별 PR 절차 · 코드 스타일 · 테스트 실행법.
CODE_OF_CONDUCT.md — Contributor Covenant (Coraline Ada Ehmke, 2014) 가 가장 널리 쓰이는 템플릿. 커뮤니티 행동 규약.
RFC 프로세스 — 큰 변경 결정을 문서로 모아 토론하는 관습. 출처는 IETF 의 Request for Comments (1969~). 소프트웨어 회사 내부 RFC 는 같은 이름을 차용해 "이 변경은 왜 · 무엇을 · 어떻게" 를 명시적으로 기록. Rust 의 RFC 저장소가 OSS 표준 격으로 자주.
ADR — Architecture Decision Record — Michael Nygard 의 2011 년 글 "Documenting Architecture Decisions" 가 출처. 한 결정 당 한 짧은 문서 (컨텍스트 · 결정 · 결과). docs/adr/ 같은 폴더에 누적해 시간 순으로 결정 이유를 추적.
2. 에이전트용 문서의 관습
LLM 기반 코드 보조의 등장 이후, 도구마다 저장소에 두는 지시 파일의 관습이 자라남. 통일된 표준은 없으나 다음이 자주:
GitHub Copilot:
- 저장소 단위 지시 —
.github/copilot-instructions.md(저장소 루트에서 자동 적용). - 경로별 지시 —
.github/instructions/<NAME>.instructions.md. YAML 프론트매터의applyTo에 glob 으로 적용 범위 지정. - 에이전트 형 지시 —
AGENTS.md·CLAUDE.md·GEMINI.md등.
Cursor — .cursor/rules/*.mdc (현행) 또는 .cursorrules (구). 프로젝트 단위 지시.
Anthropic Claude Code:
CLAUDE.md(저장소 루트) — 작업 시 우선 읽힘.- 사용자 글로벌 지시 —
~/.claude/CLAUDE.md.
OpenAI — AGENTS.md 가 OpenAI 코드 에이전트가 참고하는 관습으로 정착.
공통 패턴:
- 빌드 / 실행 / 테스트 방법
- 폴더 구조 · SSOT 위치
- 코드 스타일 · 금지 사항
- 도메인 용어 정의
3. 두 종류 문서의 분담
같은 사실을 두 종류 문서가 모두 알아야 하는 경우가 많음. 이때 한쪽을 SSOT 로 두고 다른 쪽이 링크 또는 요약으로 참조하는 패턴이 안전.
| 사실 | 권장 SSOT |
|---|---|
| 빌드 명령 | README.md (사람) → 에이전트 지시 파일이 링크 |
| 도메인 용어 | docs/glossary.md |
| 폴더 구조 규칙 | docs/architecture.md 또는 에이전트 지시 |
| 보안 · 시크릿 정책 | SECURITY.md |
에이전트 지시 파일에 사람용 정보를 모두 다시 적으면 갱신 누락이 잦아짐. 에이전트 지시는 "에이전트가 이 저장소에서 어떻게 행동해야 하는지" 에 한정하고, 사실 자체는 사람용 문서를 가리키게 두는 분담이 흔히 권장됩니다.
4. 자주 쓰는 모양
저장소 루트의 파일 분담:
README.md # 프로젝트 소개 · 설치 · 사용
CONTRIBUTING.md # 기여 방법 · 코드 스타일
CODE_OF_CONDUCT.md # 커뮤니티 규약
SECURITY.md # 취약점 보고 채널
LICENSE # 라이선스 본문
docs/
adr/ # 결정 기록
architecture.md # 폴더 · 의존 규칙
CLAUDE.md # Claude Code 지시
AGENTS.md # OpenAI 에이전트 지시
.github/
copilot-instructions.md # Copilot 지시
instructions/
backend.instructions.md
ADR 한 장 (Nygard 형식):
# 0007. PostgreSQL 을 RDB 로 채택
## 컨텍스트
- 트랜잭션 ACID 가 필요
- 팀 운영 경험 — PostgreSQL > MySQL
## 결정
- PostgreSQL 16 채택. 매니지드 RDS 운영.
## 결과
- JSONB · CTE 같은 기능을 활용 가능
- MySQL 호환 도구는 사용 불가
5. 자주 걸리는 자리
README 가 너무 길어 사람이 끝까지 읽지 않는 경우 — 핵심을 위에 두고 상세는 docs/ 로 분리.
에이전트 지시 파일을 갱신하지 않아 도구가 옛 사실을 따르는 경우 — 본질이 코드인 사실은 코드 자체에서 추출하는 편이 안전 (package.json 의 명령).
회사 내부 RFC 가 결정 후 갱신되지 않아 "토론 중" 상태로 영원히 남는 경우 — 결정 시점에 상태 라벨 (Accepted / Rejected / Superseded by #N) 을 명시.
같은 사실이 README · 에이전트 지시 · ADR 세 곳에 적혀 갈라진 사고 — SSOT 하나를 정하고 나머지는 링크.
하고픈 말
사람과 에이전트가 같은 저장소를 함께 다루는 시대, 문서 분담은 미래로 갈수록 더 중요해질 자리. 같은 사실은 한 자리에 (SSOT) + 다른 곳은 링크. 에이전트 지시 파일에 모든 사실을 복제하면 갱신 누락이 누적. CLAUDE.md / AGENTS.md / Cursor rules / Copilot instructions 어느 도구를 쓰든 핵심은 같음 — 행동 방식만 적고 사실은 가리킴.
Next
- korean-first
- no-ai-credit
GitHub Adding repository custom instructions for Copilot · Anthropic Claude Code 공식 문서 · Cursor Rules 공식 문서 · Contributor Covenant · Michael Nygard Documenting Architecture Decisions · Rust RFCs 저장소 · Keep a Changelog · Make a README 를 참고합니다.