Documentation And Adrs

Documentation and ADRs

Purpose

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 / when to skip

• 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.

Inputs

This skill is a referenced cross-cutting standard, not a chain workhorse — it has no upstream artifact gate. Invoke it whenever a decision, API, or shipped feature needs a durable record. It reads:

• The decision / API / feature being recorded — the named architectural choice, the public

signature, or the user-facing behavior change. Refuse to run if nothing concrete is named to document — a vague "write some docs" is not an input; ask which decision or surface needs recording.

• docs/adr/ (repo-wide design substrate) — the existing ADR set, used to (a) pick the next

sequential ADR- number and (b) find any ADR this decision supersedes. Created by project-setup; written by spec-grilling, codebase-design, and api-design using this skill's standard.

• CONTEXT.md (repo-root glossary — terms live under its canonical ## Glossary heading) — to reuse ubiquitous-language terms verbatim in the record.

When another skill (spec-grilling, codebase-design, api-design, the Ship skills) references this skill, that skill supplies the decision; this skill supplies only the form.

Process

Documentation captures the why. The sections below are the method, ordered by leverage: ADRs (highest), then inline // why comments, typed API docs, the README, the changelog, and agent-facing context. Reach for the instrument that fits the decision or surface you're recording — you rarely touch all of them at once.

Architecture Decision Records (ADRs)

ADRs capture the reasoning behind significant technical decisions. They're the highest-value documentation you can write.

When to Write an ADR

Write an ADR SPARINGLY — only when all three hold: hard-to-reverse ∧ surprising ∧ a real trade-off. A reversible or obvious choice does not earn an ADR. ADRs live in docs/adr/ repo-wide (cross-feature); they are NOT per-feature and NEVER go into prd.md (which references them by id).

• Choosing a framework, library, or major dependency
• Designing a data model or database schema
• Selecting an authentication strategy
• Deciding on an API architecture (REST vs. GraphQL vs. tRPC)
• Choosing between build tools, hosting platforms, or infrastructure
• Any decision that would be expensive to reverse

ADR Template

Store ADRs in docs/adr/ as ADR--.md, sequential repo-wide numbering (not per-feature; `` lowercase-hyphenated):

# ADR-: Use PostgreSQL for primary database

## Status
Accepted | Superseded by ADR-XXX | Deprecated

## Date
2025-01-15

## Context
We need a primary database for the task management application. Key requirements:
- Relational data model (users, tasks, teams with relationships)
- ACID transactions for task state changes
- Support for full-text search on task content
- Managed hosting available (for small team, limited ops capacity)

## Decision
Use PostgreSQL with Prisma ORM.

## Alternatives Considered

### MongoDB
- Pros: Flexible schema, easy to start with
- Cons: Our data is inherently relational; would need to manage relationships manually
- Rejected: Relational data in a document store leads to complex joins or data duplication

### SQLite
- Pros: Zero configuration, embedded, fast for reads
- Cons: Limited concurrent write support, no managed hosting for production
- Rejected: Not suitable for multi-user web application in production

### MySQL
- Pros: Mature, widely supported
- Cons: PostgreSQL has better JSON support, full-text search, and ecosystem tooling
- Rejected: PostgreSQL is the better fit for our feature requirements

## Consequences
- Prisma provides type-safe database access and migration management
- We can use PostgreSQL's full-text search instead of adding Elasticsearch
- Team needs PostgreSQL knowledge (standard skill, low risk)
- Hosting on managed service (Supabase, Neon, or RDS)

ADR Lifecycle

PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)

• Don't delete old ADRs. They capture historical context.
• When a decision changes, write a new ADR that references and supersedes the old one.
• ADRs are append-only / immutable once accepted: never edit or delete a decision body. A changed

decision is a NEW ADR; set the old one's ## Status to Superseded by ADR- and link both ways.

• Renaming or superseding an ADR → update every referrer (prd.md, other ADRs, PR bodies) in the

same commit — "change the shape → update the consumer" extends to ADR cross-refs.

Inline Documentation

When to Comment

Comment the why, not the what:

// BAD: Restates the code
// Increment counter by 1
counter += 1;

// GOOD: Explains non-obvious intent
// Rate limit uses a sliding window — reset counter at window boundary,
// not on a fixed schedule, to prevent burst attacks at window edges
if (now - windowStart > WINDOW_SIZE_MS) {
  counter = 0;
  windowStart = now;
}

When NOT to Comment

// Don't comment self-explanatory code
function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

// Don't leave TODO comments for things you should just do now
// TODO: add error handling  ← Just add it

// Don't leave commented-out code
// const oldImplementation = () => { ... }  ← Delete it, git has history

Document Known Gotchas

/**
 * IMPORTANT: This function must be called before the first render.
 * If called after hydration, it causes a flash of unstyled content
 * because the theme context isn't available during SSR.
 *
 * See ADR-003 for the full design rationale.
 */
export function initializeTheme(theme: Theme): void {
  // ...
}

API Documentation

For public APIs (REST, GraphQL, library interfaces):

Inline with Types (Preferred for TypeScript)

/**
 * Creates a new task.
 *
 * @param input - Task creation data (title required, description optional)
 * @returns The created task with server-generated ID and timestamps
 * @throws {ValidationError} If title is empty or exceeds 200 characters
 * @throws {AuthenticationError} If the user is not authenticated
 *
 * @example
 * const task = await createTask({ title: 'Buy groceries' });
 * console.log(task.id); // "task_abc123"
 */
export async function createTask(input: CreateTaskInput): Promise {
  // ...
}

OpenAPI / Swagger for REST APIs

paths:
  /api/tasks:
    post:
      summary: Create a task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskInput'
      responses:
        '201':
          description: Task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '422':
          description: Validation error

README Structure

Every project should have a README that covers:

# Project Name

One-paragraph description of what this project does.

## Quick Start
1. Clone the repo
2. Install dependencies: `npm install`
3. Set up environment: `cp .env.example .env`
4. Run the dev server: `npm run dev`

## Commands
| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server |
| `npm test` | Run tests |
| `npm run build` | Production build |
| `npm run lint` | Run linter |

## Architecture
Brief overview of the project structure and key design decisions.
Link to ADRs for details.

## Contributing
How to contribute, coding standards, PR process.

Changelog Maintenance

For shipped features:

# Changelog

## [1.2.0] - 2025-01-20
### Added
- Task sharing: users can share tasks with team members (#123)
- Email notifications for task assignments (#124)

### Fixed
- Duplicate tasks appearing when rapidly clicking create button (#125)

### Changed
- Task list now loads 50 items per page (was 20) for better UX (#126)

Documentation for Agents

Special consideration for AI agent context:

• CLAUDE.md / rules files — 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

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

• Architectural decisions with no written rationale
• Public APIs with no documentation or types
• README that doesn't explain how to run the project
• Commented-out code instead of deletion
• TODO comments that have been there for weeks
• No ADRs in a project with significant architectural choices
• Documentation that restates the code instead of explaining intent

Verification (ending criteria)

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
• [ ] Rules files (CLAUDE.md etc.) are current and accurate

Outputs & handoff contract

Emits (referenced cross-cutting — no chain link of its own):

• docs/adr/ADR--.md — one ADR per significant decision, with stable sections

# ADR-: · ## Status · ## Date · ## Context · ## Decision · ## Alternatives Considered · ## Consequences. Sequential `; lowercase-hyphenated `.

• Inline // why comments, typed/JSDoc API docs, README, CHANGELOG at the touched files.
• Appends to CONTEXT.md under its canonical ## Glossary heading only when a decision introduces a

new ubiquitous-language term (glossary-only, devoid of implementation detail).

Stable sections other skills depend on (do not rename): the seven ADR headings above. to-prd references ADRs by id ("see ADR-007") and never restates their rationale; spec-review and the Spec gate open every referenced ADR so design isn't rubber-stamped unseen; pull-request anchors its summary to the prd + these ADR ids.

Append-only / immutable: never edit or delete an accepted ADR's decision body. A changed decision is a NEW ADR that flips the old one's ## Status to Superseded by ADR- and links both ways. Renaming/superseding → update every referrer in the same commit.

STATE.md: this skill moves no slice/feature state; an ADR id MAY appear in a slice's Artifacts column when that slice's decision was ADR-worthy.

Stage tag: cross-cutting — referenced in Spec by spec-grilling, in Plan by codebase-design / api-design, in Ship for API / inline / release docs. Lands EARLY: a hard dependency of spec-grilling.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: celestialdust
• Source: celestialdust/achilles-skills
• License: MIT

Install and usage instructions live in the source repository linked above.