Docs and adrs

Documentation and ADRs

Overview

Document decisions, not just code. The most valuable documentation captures the why: the context, constraints, and trade-offs that led to a decision. Code shows what was built; documentation explains why it was built this way and what alternatives were considered. This context is essential for future humans and agents working in the codebase.

When to Use

• Making a significant architectural decision
• Choosing between competing approaches
• Adding or changing a public API
• Shipping a feature that changes user-facing behavior
• Onboarding new team members (or agents) to the project
• When you find yourself explaining the same thing repeatedly

When NOT to use: Don't document obvious code. Don't add comments that restate what the code already says. Don't write docs for throwaway prototypes.

Architecture Decision Records (ADRs)

Read references/adrs.md when making a significant architectural decision (framework/library choice, data model, auth strategy, API architecture, or any expensive-to-reverse choice) — it has the "When to Write an ADR" checklist, the ADR template, and the lifecycle states.

Inline Documentation

Read references/inline-comments.md when writing or reviewing inline code comments — it has the why-not-what rule with before/after examples and the gotcha-documentation pattern.

API Documentation

Read references/api-documentation.md when adding or changing a public API — it has the TypeScript JSDoc pattern and the OpenAPI/Swagger REST pattern.

README Structure

Read references/readme-structure.md when a project lacks a README or its README is stale — it has the section skeleton (quick start, commands, architecture, contributing).

Changelog Maintenance

Read references/changelog.md when shipping a feature that changes user-facing behavior — it has the Keep-a-Changelog-style entry format.

Documentation for Agents

Special consideration for AI agent context:

• Agent rules files (CLAUDE, AGENTS): Document project conventions so agents follow them
• Spec files: Keep specs updated so agents build the right thing
• ADRs: Help agents understand why past decisions were made (prevents re-deciding)
• Inline gotchas: Prevent agents from falling into known traps

Common Rationalizations

Rationalization	Reality
"The code is self-documenting"	Code shows what. It doesn't show why, what alternatives were rejected, or what constraints apply.
"We'll write docs when the API stabilizes"	APIs stabilize faster when you document them. The doc is the first test of the design.
"Nobody reads docs"	Agents do. Future engineers do. Your 3-months-later self does.
"ADRs are overhead"	A 10-minute ADR prevents a 2-hour debate about the same decision six months later.
"Comments get outdated"	Comments on why are stable. Comments on what get outdated. That's why you only write the former.

Red Flags

• TODO comments that have been there for weeks

Verification

After documenting:

• ADRs exist for all significant architectural decisions
• README covers quick start, commands, and architecture overview
• API functions have parameter and return type documentation
• Known gotchas are documented inline where they matter
• No commented-out code remains
• Agent rules files (CLAUDE, AGENTS) are current and accurate