documentation-and-adrs

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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. To *consolidate* ephemeral `*_REPORT.md` / `*_ANALYSIS.md` artifacts into canonical docs (rather than author new ones), use `doc-consolidation`.

## 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

- 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/decisions/` with sequential numbering:

```markdown
# ADR-001: 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.

### Retroactive Backfill (existing codebases)

An established codebase full of unrecorded decisions doesn't need a historian — it needs the
handful of decisions that **still bind today**. Time-box the whole exercise to a few hours:

1. **Mine the history for decision points:**

   ```bash
   git log --all --oneline --grep="decide\|choose\|instead\|switch\|migrate\|refactor"
   git log --reverse --format="%ad %s" --date=short | head    # project timeline, oldest first
   ```

2. **Sketch the eras.** Group the history into 3–6 phases around major milestones (rewrites,
   version releases, architecture pivots). Phase boundaries are where decisions cluster.
3. **Write only the decisions that still constrain the code** — aim for 5–10 ADRs, not fifty.
   Mark each `Accepted`, and keep the "Reconstructed from `<source>`" provenance line from the
   ADR template so readers know it was back-filled, not contemporaneous.
4. **Stop.** Don't document every commit, and don't invent rationale you can't evidence from
   commits, code, or people — a back-filled ADR that guesses at *why* is worse than no ADR.
   From here forward, record decisions as they're made.

(Backfill process adapted, in this kit's terms, from the MIT-licensed
[`pborenstein/handoff`](https://github.com/pborenstein/handoff) `project-tracking` skill,
© 2026 Philip Borenstein.)

## Inline Documentation

### When to Comment

Comment the *why*, not the *what*:

```typescript
// BAD: Restates the code

From ajyadav013/claude-kit, MIT.

More from ajyadav013/claude-kit