문서

문서에는 두 독자가 있다. 과정을 되짚는 사람과, 필요할 때 근거를 찾는 에이전트다. 사람이 읽을 문서를 썼다면 에이전트는 매번 처음부터 설명을 다시 읽어야 하고, 그렇지 않으면 사람은 결정의 이유를 알 수 없다.

기준일: 2026-09-30

문서의 네 가지 갈래

문서 하나에 모든 내용을 넣으면 나중에 아무도 찾지 못한다. 이 저장소에서는 목적에 따라 네 종류로 나눈다.

문서	적는 내용	주로 읽는 시점
PRD	무엇을 만들지, 무엇을 만들지 않는지	작업을 시작할 때
SRS	어떤 기술과 방식으로 구현할지	설계를 정할 때
DESIGN.md	화면 구성과 디자인 규칙	화면을 고칠 때
ADR	어떤 결정을 왜 내렸는지	결정을 되짚을 때

요구사항은 웹에서 동작하는 대화 도구에서 초안을 만들면 빠르다. 대화 도구마다 장단이 있고 결과를 문서로 옮기는 데 시간이 걸리므로, 익숙한 도구 하나를 정해 두면 된다. 요구사항과 재작성 지침이 필요한 저장소에서는 각각 별도 파일로 모아 둔다.

DESIGN.md에는 프레임워크 선택만 적지 않는다. 실제로 배포된 화면에는 파비콘, 링크 미리보기 이미지, 글꼴처럼 값이 정해진 부분이 있다. 이런 결정은 나중에 "왜 이 글꼴인가"를 되짚을 때 필요하므로 같은 파일에 모은다.

문서와 에이전트 연결

문서를 만들어 두어도 읽히지 않으면 의미가 없다. 룰과 스킬에서 참조로 연결해 작업 직전에 확인하게 만든다.

아키텍처 경계를 넓히기 전에 docs/adr/의 관련 결정을 먼저 읽어 줘.
화면 요소를 추가하기 전에 DESIGN.md의 규칙을 먼저 읽어 줘.
중요한 결정을 내릴 때는 새 ADR을 쓸지, 기존 결정을 고칠지 판단해 줘.

지시문은 판단 순서를 적는 것이지, 내용을 복사해 넣는 자리가 아니다. 문서에 이미 있는 설명을 룰에 다시 쓰면 두 곳이 서로 다른 말을 하게 된다. 한쪽이 갱신되지 않으면 에이전트는 오래된 쪽을 읽는다.

긴 자료는 본문에서 잘라 별도 파일로 옮기고 거기만 가리킨다. 스킬은 필요할 때 불러 쓰는 곳이라 참고 자료를 references/처럼 한 곳에 모아 둘 수 있다. 자료가 많아지면 링크만 나열한 문서가 되므로, 무엇을 언제 읽어야 하는지도 같이 적는다.

결정의 이력 관리

결정을 문서에 적을 때 무엇을 골랐는지만 남기면 이유를 잃는다. ADR은 무엇을 하지 않았는지를 함께 남기는 자리다. 형식과 예시는 ADR 모음 사이트에서 확인할 수 있다.

# ADR-0001: 문서 사이트 배포 방식

- 상태: 승인
- 작성: 2026-09-30

## 맥락

문서 사이트를 어디에 올릴지 정해야 한다.

## 결정

VitePress로 만들고 정적 자산으로 배포한다. Pages는 쓰지 않는다.
작업 문서는 빌드에서 제외한다.

## 대안

Pages를 쓰면 저장소만으로 배포가 끝나지만, 요청을 처리하는 계층을
나중에 넣기 어렵다.

## 결과

제외 목록을 실수로 늘리면 작업 문서가 공개된다. 빌드 결과물을 확인한다.

이 저장소의 결정 기록은 docs/adr/에 모은다. 채택하지 않은 안과 단서도 남기면 나중에 같은 선택을 다시 검토하지 않아도 된다. 결정이 바뀌면 새 기록을 추가하고 이전 기록에 연결한다. 이전 결정을 지우면 왜 바꿨는지 알 수 없다.

기록의 상태는 세 가지면 충분하다. 제안, 승인, 대체됨이다. 아직 내리지 않은 결정을 승인된 것처럼 적지 않는다.

중간 과정의 문서화

작업 과정 자체를 남기는 것도 문서다. 요구사항 문서는 최종 모습만 설명하지만, 결정이 어떻게 바뀌었는지는 이슈와 PR에서 드러난다. 이슈·PR을 쓰면 GitHub 저장소에서 확인과 되돌리기가 한곳에 모인다. 목록을 읽고 리뷰를 남기는 명령은 GitHub 저장소 리뷰 자동화 페이지에서 다룬다.

과정 문서는 에이전트가 쓰게 해도 된다. 다만 사람이 읽을 형태로 정리한다. Mermaid 다이어그램으로 관계를 그리고, 표로 선택지를 나란히 두고, 긴 설명은 각주 대신 짧은 문장으로 줄인다. 사람이 읽지 않는 형식으로 남은 기록은 나중에 아무도 확인하지 않는다.

과정 문서의 마지막에는 무엇을 남겼는지를 적는다. 검증 명령, 확인하지 못한 항목, 다음에 할 일이 세 줄이면 충분하다. 이 세 줄이 나중에 다음 작업의 입력이 된다.

문서의 지속 갱신

문서는 만들어 놓고 방치하면 가장 빨리 낡아진다. 갱신 시점을 정해 둔다.

시점	확인할 것
결정을 바꿀 때	관련 기록의 상태와 대안
명령이나 경로가 바뀔 때	절차 문서의 예시
화면 규칙이 바뀔 때	DESIGN.md의 규칙과 예시
한 학기·한 분기가 지날 때	필요 없는 문서와 중복 내용

같은 내용을 두 곳에 두지 않는다. 둘이 필요해 보이면 기준 문서 하나를 정하고 다른 곳에서는 가리킨다. 중복이 생기는 가장 흔한 이유는 메모리와 문서의 역할을 나누지 않아서다.

보충: 런타임별 문서 참조 방식

Claude Code 모범 사례 안내는 상세 API 문서를 복사해 넣기보다 참조로 연결하고 필요할 때 읽으라고 권장한다. @경로 형태의 import는 세션 시작 시 내용을 불러오므로 단순 링크와 동작이 다르다. 긴 자료는 스킬 안의 별도 파일로 분리할 수 있다.

Codex 메모리 안내는 팀에 필요한 지침을 AGENTS.md나 버전 관리 문서에 두라고 한다. Codex 스킬 안내는 필요할 때 읽을 참고 자료를 스킬에 연결하는 구조를 설명한다. PRD·SRS·DESIGN·ADR라는 문서 묶음을 필수로 쓰라는 권장은 두 문서에서 확인되지 않았다. 이 네 가지 구분은 저장소를 운영하기 위해 정한 자체 구성이다. 기준일: 2026-09-30.