diff --git a/CLAUDE.md b/CLAUDE.md
index 16532f5..94b1acc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -46,6 +46,16 @@ straight from `in_progress`.
    (`user_review → done`); the user may instead bounce it back
    (`user_review → in_progress`).
 
+## Recording decisions
+
+When a non-trivial decision is made — about scope, design, tradeoffs,
+dependencies, what to defer — call `record_decision(made_by, text,
+rationale?, project?, task_ref?)`. Use `made_by="claire"` for decisions
+you make, `made_by="user"` for ones the user makes. Keep `text` to one
+clear sentence; put context in `rationale`. Link a project or task when
+relevant. The Decisions log surfaces in the web app so the user can review
+what was decided and by whom.
+
 ## Style
 
 Concise, direct. Don't restate what the tools returned — synthesize.