사람용 문서와 에이전트용 문서

저장소에는 두 종류의 독자를 위한 문서가 공존합니다. 사람과 코드 보조 에이전트 (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 를 참고합니다.