# 문서

에이전트의 맥락 유지와 인간 검토를 돕는 PRD, ADR 등 문서 체계를 정리합니다.

원본 URL: https://abc.noco.kr/harness-basics/docs

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

기준일: 2026-09-30

## 문서의 네 가지 갈래

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

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

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

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

## 문서와 에이전트 연결

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

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

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

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

## 결정의 이력 관리

결정을 문서에 적을 때 무엇을 골랐는지만 남기면 이유를 잃는다. [ADR](/glossary#adr)은 무엇을 하지 않았는지를 함께 남기는 자리다. 형식과 예시는 [ADR 모음 사이트](https://adr.github.io/)에서 확인할 수 있다.

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

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

## 맥락

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

## 결정

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

## 대안

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

## 결과

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

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

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

## 중간 과정의 문서화

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

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

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

## 문서의 지속 갱신

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

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

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

::: details 보충: 런타임별 문서 참조 방식
[Claude Code 모범 사례 안내](https://code.claude.com/docs/en/best-practices)는 상세 API 문서를 복사해 넣기보다 참조로 연결하고 필요할 때 읽으라고 권장한다. `@경로` 형태의 import는 세션 시작 시 내용을 불러오므로 단순 링크와 동작이 다르다. 긴 자료는 [스킬](https://code.claude.com/docs/en/skills) 안의 별도 파일로 분리할 수 있다.

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