decisions

Decisions

Projects may have a decisions.md file for recording significant decisions.

When to Record Decisions

Record a decision when:

• A significant choice was made after considering alternatives
• The decision affects future work (even if no code was written)
• You'd want to remember "why did we decide this?" later

Do NOT record:

• Exploration or experiments that didn't pan out
• Routine implementation choices
• Decisions still being discussed

Recording Format

Append to the project's decisions.md:

## YYYY-MM-DD: Brief Title
Context: [What prompted this decision]
Decision: [What we decided]
Rationale: [Why we chose this]

Example

# Decisions

## 2026-01-31: Use plugin architecture
Context: Wanted easier installation and portability for other users
Decision: Convert from install script to Claude Code plugin
Rationale: Plugins have one-line install, discoverable commands, and built-in distribution

## 2026-01-31: Save context on project switch
Context: Switching projects mid-session loses context about what was done
Decision: Write summary to CLAUDE.local.md when switching away from a project
Rationale: Captures context at the right moment, survives crashes, complements SessionEnd hook

On Resume

When resuming a project:

• Read decisions.md if it exists
• Reference relevant past decisions when they affect current work

Timing

Only record after the decision is confirmed and being acted on, not during exploration.