Records

Design decisions, implementation plans, and feature specs that persist across sessions.

What Are Records?

Records are Markdown files in docs/records/ that document:

• Architecture decisions
• Feature specifications
• Design documents
• Implementation plans

They start as planning docs and turn into permanent documentation over time.

When to Create a Record

Rule of thumb: If you’d write more than 5 lines in CLAUDE.md → create a Record.

Tip: Use /design for complex features - it auto-generates Records with Problem, Options, Solution, and User Stories sections.

Record Format

docs/records/
├── 001-authentication-design.md
├── 002-api-refactoring.md
└── 003-caching-strategy.md

Each Record follows this structure:

# Record 001: Authentication Design
 
**Status:** Done
**Priority:** High
**Date:** 2026-01-15
 
## Problem
 
What problem does this solve?
 
## Solution
 
What approach did we take?
 
## Alternatives Considered
 
What else was considered and why rejected?
 
## Trade-offs
 
Pros and cons of the chosen approach.

Records vs Recent Decisions

Recent Decisions are for small project-level choices with a “why” worth remembering, but too small for a full Record. Implementation details of a specific feature belong in the Record, not in Recent Decisions.

How Records Are Used

1. During work: Create Records when making significant decisions
2. /wrapup: References active Records in Current Status table
3. /catchup: Loads Records referenced in active work
4. On disk: ls docs/records/ lists all Records — no separate table needed

Related

• /design - Creates Records with structured design workflow
• Architecture - All project Records