Required Project Documentation
Every project must maintain AGENTS.md, README.md, DEVELOPMENT.md, and CONTRIBUTING.md. ARCHITECTURE.md becomes required once the project has meaningful architectural boundaries. Use the templates under templates/ as the starting point.
Documentation modes follow Diátaxis: the README introduces the project and directs readers to the relevant documents; DEVELOPMENT.md and CONTRIBUTING.md contain how-to guidance and reference material; ARCHITECTURE.md is explanation; AGENTS.md is reference for agents. Keep one mode per document — when a document needs another mode, link to the document that owns it instead of mixing it in.
AGENTS.md
Every project must include AGENTS.md at the repository root.
It is the agent-facing entry point: commands, engineering standards, repository layout, boundaries, the confirmed language policy, and project conventions.
See Authoring AGENTS.md for what belongs in AGENTS.md, section order, length limits, and nested files.
Template: project-agents.template.md
README.md
Every project must include README.md.
The README is the project's front door, written for readers who skim.
The first screen states what the project is, what problem it solves, and
how to run it. It points readers to the right detail documents instead of
teaching, listing internals, or writing long background essays. Agent-facing
rules — engineering standards, language policy, project conventions — belong in
AGENTS.md (see templates/project-agents.template.md), and the README gives a
copyable prompt that points agents there.
The body is organized around reader tasks, not around the repository directory structure. Do not write a separate Why section; follow this order:
- An identity block: the project name, a one-sentence tagline stating what the project is and for whom, and status badges — followed by one to three plain sentences on the need the project solves. Mention what the project intentionally is not, and its status, only when that saves the reader time.
- When the project has a visual surface — a UI, CLI output, generated artifacts — a screenshot or a short GIF immediately after the opening.
- One section for getting started: use
Quick Startfor projects that need a developer,Usagefor end-user products, andUsage / Quick Startwhen both apply. Start with a copyable instruction directing an AI coding agent toAGENTS.md. Then give the manual steps: prerequisites (toolchain, supported platforms, pinned versions), copy-paste commands, and the expected result. For end-user products, show the two or three most common uses with their expected output. - Between the getting-started section and the reading map, include only the sections the project needs. Order them by what the project must demonstrate first, using a standard title and emoji for each:
Concepts: the few ideas a reader needs to understand.Features: what the project does, why it matters, and how it differs from alternatives.Performance: a one-sentence claim, a supporting chart or table, the measurement environment, and a methodology link. Every performance claim needs numbers.Experiments: experimental content, if the project has any.
- A Goal → Read table linking the detail documents below.
- The license, stated explicitly.
Keep section titles standard, short, and instantly recognizable — Quick Start, Usage, Concepts, Features, Performance, Experiments, Learn More, License — and prefix each with one semantically stable emoji: 🚀 for the get-it-running section, 💡 for concepts, ✨ for features, ⚡ for performance, 🧪 for experiments, 📚 for further reading, 📄 for the license. Keep the emoji set small and consistent; the project title and body text carry no emoji.
Fold long auxiliary content — platform-specific setup, environment variable tables, extended examples, troubleshooting — into <details> blocks whose <summary> names the content in a few words. Keep one blank line after <summary> so Markdown renders, and never collapse the primary path: the opening, the get-it-running commands, and the license stay expanded.
Keep it scannable: paragraphs of one to three sentences, one idea per bullet, copyable commands in code blocks. Present enumerations as lists or tables, never as running prose. Route to the detail documents instead of duplicating their content — teaching, reference, and explanation are their modes, not the README's — but never shrink the README to a bare "see the docs" pointer: it must stand alone as the entry point. Add a table of contents once it grows beyond a few screens.
An outdated README is worse than none, because it actively misleads. Update it in the same change that alters setup, usage, or scope, and state at the top when development has slowed or stopped.
The confirmed product/UI language policy (see Language Policy) is agent-facing: record it in AGENTS.md, not in the README.
Template: README.template.md
DEVELOPMENT.md
Every project must include DEVELOPMENT.md.
Describe the development workflow step by step, then provide the command and configuration reference.
It should describe:
- Development workflow
- Toolchain
- Common mise tasks
- Coding standards
- Testing workflow
- Local setup
- Validation workflow
- Deployment workflow when relevant
Both humans and AI agents should be able to follow it to develop the project.
Template: DEVELOPMENT.template.md
CONTRIBUTING.md
Every project must include CONTRIBUTING.md.
It is a how-to guide: ordered steps for landing a change, not background essays.
It should document:
- Contribution expectations
- Issue workflow when relevant
- Pull request workflow
- Review expectations
- Required validation
- Commit conventions
Every pull request description should clearly include:
- Purpose of the change
- Impact of the change
- Relevant context or background
- Potential risks or concerns
- Testing or validation performed
The GitHub pull request template must stay synchronized with these requirements.
Template: CONTRIBUTING.template.md
ARCHITECTURE.md
Projects with meaningful architectural boundaries must maintain ARCHITECTURE.md.
Keep it short and practical: a brief overview, a high-level codebase map (name modules, do not link files), and the architectural invariants.
Its job is to explain why the boundaries exist and keep the architecture from drifting — not to be a theoretical essay or a complete file list.
Invariants and ADR rules are defined in Architecture Governance.
Template: ARCHITECTURE.template.md