Records decisions and documentation. Use when making architectural decisions, changing public APIs, shipping features, or when you need to record context that future engineers and agents will need to understand the codebase.
Download SKILL.md or inspect the source before installing.
Step 1
Copy the install command
Copy the command or download SKILL.md, then add it to your AI coding environment.
Step 2
Check source and behavior
Open the source repo and confirm the skill behavior, scope, and fit for the task.
Step 3
Overview
# 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)
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
Validate with a real task
Run one small real task before keeping it in your long-term workflow.
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.
Inline Documentation
When to Comment
Comment the *why*, not the *what*:
```typescript
// 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
```typescript
// 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
```typescript
/**
* 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):
