# Software Project Documentation in the AI Era

> Some thoughts on documenting software projects.

Some thoughts on documenting software projects.

## Purpose

Create documents that both agents and humans can read easily, helping everyone understand the system quickly and follow consistent rules.

## Principles

Manage documentation like code.

- Remove duplication and express intent clearly and concisely.
- Divide documents into cohesive units and give them good names.
- Connect documents with links, while reducing circular references and keeping navigation paths from the entry point reasonably short.
- Delete dead documents: those unreachable from the entry point.
- Do not version-control documents that can be generated automatically.

Aim for [universal design](https://wiki.g15e.com/pages/Universal%20design.txt).

- Maintain shared documents for agents and humans wherever possible.
- Make separate agent-only or human-only documents only when necessary.

Assume readers—agents and humans—are sufficiently intelligent.

- Assume they can make sound judgments given the information they need. For example, rather than instructing "Read Y to do X," describe what Y contains and let readers judge whether to read it when doing X.

DOs and DON'Ts:

- ❌ Do not state the obvious, such as "write clean code."
- ✅ State decisions that are not obvious, such as not using Tailwind or mock objects.
- ❌ Do not use documentation to paper over problems in the current system.
- ✅ Create documentation about documentation. (This follows naturally from "manage documentation like code.")

Provide enough information for decision-making. (This needs more thought and detail.)

- Gradually bring planning and business documents under version control too.
- Use GitHub, Notion, Google Drive, Slack, and so on according to their purposes?
- Make scattered information easy to consult?
- Reduce the number of tools in use?
- Gradually integrate scattered information?

## Practice

Keep `README.md` as short as possible.

```markdown
# Project name

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

Until [Claude Code](https://wiki.g15e.com/pages/Claude%20Code.txt) supports the `AGENTS.md` standard, temporarily create `CLAUDE.md` as a symbolic link to `AGENTS.md`.

Put only the minimum information that must always be in the LLM's context in `AGENTS.md`, and use [dynamic context discovery](https://wiki.g15e.com/pages/Dynamic%20context%20discovery.txt) for everything else. For example:

```
# Project name

Short description of the project

## Essentials

...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/metadoc.md](docs/metadoc.md)
- ...
```

Likewise, documents within each skill should retain only information specific to that skill and link to shared documents for common material.

## See also

- 2026-01-17 - [An argument against using the same AGENTS.md](https://x.com/mitsuhiko/status/2012485329165443140?s=46) by <Armin Ronacher>
- [specdown](https://wiki.g15e.com/pages/specdown.txt) - Executable specifications: a way to reduce discrepancies between code and documentation.