Explanatory Coding Mode
Get educational insights about implementation choices and codebase patterns as Claude works — formatted, codebase-specific commentary woven into the session, not a generic tutorial.
Claude just refactored your auth middleware and you have no idea why it made the choices it did. You could ask, but that's another round trip — and by the time you think to ask, you've already moved on and lost the moment where the explanation would have stuck.
Who it's for: developers learning an unfamiliar codebase, engineers onboarding onto a new team's project, anyone maintaining a repo they inherited, developers who want to understand the 'why' behind AI-generated changes, not just the 'what'
Example
"Add rate limiting to the API" → Before implementing, a boxed insight explaining why the existing middleware order matters and which existing pattern to match; after implementing, a second insight explaining why a sliding window was chosen over a fixed one, tied to how the codebase already handles session TTLs
CLAUDE.md Template
New here? 3-minute setup guide → | Already set up? Copy the template below.
npx ccplaybooks add explanatory-coding-mode# Explanatory Coding Mode
## Your Role
You are in **explanatory mode**. As you help with my task, you also teach me about the codebase you're working in. You are clear and educational, providing helpful explanations while staying focused on the task.
Balance educational content with task completion. When providing insights, you may exceed typical length constraints — but stay focused and relevant. Explanation is a supplement to the work, not a replacement for it.
---
## Insights
Get new playbooks like this one
One email a week with new Claude Code workflows. Free, like everything here.
No spam. Unsubscribe anytime.
What This Does
Recreates the deprecated "Explanatory" output style as a CLAUDE.md instruction set. Claude provides brief, formatted educational insights before and after writing code — focused specifically on this codebase's patterns and trade-offs, not general programming theory. Insights appear in conversation, never as comments injected into your source files.
Quick Start
Step 1: Navigate to Your Project
cd ~/your-project
Step 2: Download the Template
Click Download above, then:
mv ~/Downloads/CLAUDE.md ./
Step 3: Start Working
claude
Work normally — the insights appear automatically as Claude writes code.
What "Codebase-Specific" Means
The whole value of this mode is specificity. A generic insight teaches nothing you couldn't get from a textbook; a codebase-specific one teaches you this project.
| Generic (low value) | Codebase-specific (the actual goal) |
|---|---|
| "Dependency injection makes code testable" | "This repo injects the DB client through the constructor rather than importing it — that's why UserService takes a db param instead of reaching for the singleton" |
| "Error handling is important" | "This codebase swallows errors at the route boundary and re-throws typed errors from the service layer — following that split rather than catching here" |
Tips & Best Practices
- Insights arrive as you go, not saved for a summary at the end — the value is catching the reasoning while it's still attached to the decision
- Nothing gets written into your source files — insights live in conversation only
- Costs extra tokens — both the added instructions and the longer responses. Worth it when understanding matters as much as shipping; skip it for repetitive work in a codebase you already know
When to Use This
Best for unfamiliar codebases, onboarding, and inherited repos. Less useful for time-critical fixes or bulk mechanical work.
If you want to go further and actually write some of the code yourself at key decision points rather than just reading explanations, pair this with the Learning Mode Coding Coach playbook — it includes everything here plus interactive contribution requests.