# Software project documentation in AI era

> 소프트웨어 프로젝트 문서화를 어떻게 해야할까에 대한 고민.

소프트웨어 프로젝트 문서화를 어떻게 해야할까에 대한 고민.

## 목적

에이전트와 인간 모두 읽기 좋은 문서를 만들어서 누구나 시스템을 빠르게 이해하고 일관된 규칙을 따르도록 돕는다.

## 원칙

문서를 코드처럼 관리한다.

- 중복을 제거하고 의도가 간결하고 명확하게 드러나게 한다.
- 응집력이 높은 단위의 문서로 나누고 좋은 이름을 지어준다.
- 문서 간 링크를 걸어서 연결하되 순환참조를 줄이고 엔트리로부터의 내비게이션 경로가 너무 걸어지지 않도록 한다.
- 죽은 문서(엔트리로부터 도달 불가능한 문서)는 삭제한다.
- 자동으로 생성할 수 있는 문서는 버전 관리를 하지 않는다.

보편 디자인을 지향한다.

- 에이전트용 문서와 인간용 문서를 되도록 하나로 관리한다.
- 에이전트 전용 또는 인간 전용 문서는 필요한 경우에만 예외적으로 나눈다.

독자(에이전트+인간)가 똑똑할 것이라고 가정한다.

- 필요한 정보가 주어지면 올바른 판단을 할 것이라고 가정한다. 예: "X를 하려면 Y를 읽으세요"라는 지시 보다는 Y에 어떤 내용이 담겨 있는지를 설명해서 X를 할때 Y를 읽어야 하는지 여부는 독자가 판단하도록 한다.

(좀 더 고민+구체화 필요) 의사결정에 필요한 정보를 충분히 제공한다.

- 기획 및 비즈니스 관련 문서도 점진적으로 버전 관리를 한다.
- 깃헙, 노션, 구글 드라이브, 슬랙 등을 목적에 맞게 사용한다?
- 흩어진 정보를 쉽게 참고할 수 있게 한다?
- 사용하는 도구를 줄인다?
- 흩어진 정보를 점진적으로 통합한다?

## 실천

`README.md`는 최대한 짧게 줄인다.

```markdown
# Project name

This project uses [AGENTS.md](./AGENTS.md) as the entry document.
```

[Claude Code](https://wiki.g15e.com/pages/Claude%20Code.txt)가 `AGENTS.md` 표준을 지원하기 전까지 한시적으로 `AGENTS.md`에 대한 심볼릭 링크 `CLAUDE.md`를 만들어 둔다.

`AGENTS.md`에는 반드시 LLM 컨텍스트에 담겨야 할 최소한의 내용만 담고 나머지는 모두 [Dynamic context discovery](https://wiki.g15e.com/pages/Dynamic%20context%20discovery.txt) 패턴을 쓴다. 다음은 예시:

```
# Project name

Short description of the project

## Essentials

To run dev server:

> pnpm dev

...Other essential information that must always be included in the context...

## Documents

-  System architecture and project structure: [docs/architecture.md](docs/architecture.md)
- General coding standard: [docs/coding.md](docs/coding.md)
- Additional coding standard for test cases: [docs/testing.md](docs/testing.md)
- Additional coding standard for SQL: [docs/sql.md](docs/sql.md)
- Documentation standard: [docs/documentation.md](docs/documentation.md)
- ...
```

각 스킬 내의 문서들도 마찬가지로 해당 스킬에 특화된 내용만 남기고 중복된 내용은 공통 문서를 링크한다.