Teach-Me & Review Prompts

The Teach-Me prompt

Use it liberally — especially right after Claude builds something you don't fully follow:

Teach-Me prompt — after anything you don't fully understand 
Teacher mode — no code changes. Explain [this file @path / this concept / the change you just made]:

1. What it does, plain English, as to a beginner.

2. WHY it's built this way — what breaks with the naive alternative?

3. The 2-3 concepts here I should genuinely understand (name them so I can study more).

4. One question to test whether I understood.

Why each line is there:

  • "No code changes" makes it perfectly safe to run anytime — it's a conversation, not a task.
  • "What breaks with the naive alternative?" is the question that turns trivia into understanding. Knowing why the simple version fails is what you'll reuse in every future project.
  • Named concepts give you search terms for deeper study — the difference between "I saw this once" and "I can learn more tonight".
  • The test question catches the illusion of understanding while the topic is still open.

This habit is the difference between owning your codebase and being a passenger in it. It's also, not incidentally, interview gold: "explain a technical choice in your project and its trade-offs" is a question you'll now have practiced dozens of times.

The Review & Refactor prompt — every ~10 features

Codebases built fast accumulate rough edges — AI-built ones included. Every ten features or so, run a deliberate cleanup pass:

Review & Refactor prompt — run every ~10 features 
Read CLAUDE.md. Review session — [whole project / directory @src/components] — MODE: report first, change nothing yet.

Look for: duplicated logic worth extracting; files >300 lines doing multiple jobs; inconsistencies with our conventions; dead code; missing error handling; anything a senior dev would flag.

Output: a prioritized list (max 10), each with location, issue, why it matters, effort (S/M/L). I'll pick which to fix.
  • "Report first, change nothing yet" is the safety catch. A review that immediately starts refactoring produces a giant unreviewable diff of mixed concerns — exactly what the one-task-per-session habit exists to prevent.
  • The prioritized list with effort sizes turns vague guilt ("the code is getting messy") into a menu of decisions. You pick two or three items; each becomes its own task, its own session, its own commit.
  • Max 10 keeps the report honest — an unranked list of forty nitpicks helps nobody.

A cadence that works: Teach-Me whenever curiosity or confusion strikes (it's free of risk), the Review prompt on a rhythm — every ten features, or before anything you'd call a "release". Rhythm beats willpower.

Up next: the Power-Ups — plugins and skills that teach Claude specialized workflows, then MCP servers that give it real capabilities like browsing GitHub or driving a browser.

FAQ

Frequently Asked Questions

When should I use the Teach-Me prompt?
Right after Claude builds something you don't fully follow, or any time a file or concept confuses you. It starts with "no code changes", so it's always safe — pure explanation in beginner terms, the why behind the design, and named concepts to study further.
Does the Teach-Me prompt change my code?
No — its first words are "Teacher mode — no code changes". It explains what something does, why it's built that way, and gives you one question to test your understanding.
How often should I run the Review prompt?
Every ten features or so, or before anything you'd call a release. It reports (max 10 items, each with location, issue, why it matters, and S/M/L effort) and changes nothing — you pick which items become their own tasks.
Why "report first, change nothing yet"?
A review that starts refactoring immediately produces a giant unreviewable diff of mixed concerns. Report → you choose → each fix is its own session and commit. Same one-task discipline as everywhere else.