Software Project Documentation in the AI Era

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.

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.

# Project name

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

Until Claude Code 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 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.

Purpose

Principles

Practice

See also