Code Review Trainer

A Claude Code skill that trains you to critically evaluate LLM-generated code through Socratic questioning. Instead of reviewing code for you, it makes you do the reviewing and gives feedback on what you caught, what you missed, and how to sharpen your eye.

Why

LLMs produce fluent, plausible-looking code. Most people accept it after a quick skim because it "looks right." This skill breaks that habit by making you practice code review with immediate feedback — the same way you'd build any other skill.

How it works

1. You provide code (paste it, point to a file, or let the trainer pick something from your codebase)
2. The trainer gives a neutral 2-3 sentence summary of what the code does
3. You get 3-5 questions, one at a time, each with the relevant code snippet
4. After each answer, you get feedback: what you caught, what you missed, and a reusable heuristic
5. At the end, you get a score, your strengths, blind spots, and what to practice next
6. Progress is tracked across sessions so difficulty adjusts over time

What it teaches you to spot

• Extra layers and wrappers that add indirection without value
• Single-implementation abstractions (interfaces with one implementor)
• Speculative extensibility built for requirements that don't exist
• Framework-heavy structure where wiring exceeds business logic
• Premature optimization without profiling evidence
• Shared references and mutation bugs
• Dead defensive code guarding against unreachable scenarios

Installation

Claude Code (recommended)

Copy SKILL.md to your Claude Code skills directory:

mkdir -p ~/.claude/skills/code-review-trainer
cp SKILL.md ~/.claude/skills/code-review-trainer/SKILL.md

The skill triggers automatically when you say things like:

• "teach me to review"
• "quiz me on this code"
• "help me get better at code review"
• "train me"

Or invoke it directly: /code-review-trainer

Other Claude environments

The skill is a single markdown file (SKILL.md). Adapt it to your tool's skill/prompt system as needed.

Progress tracking

The trainer saves your progress to ~/.claude/skills/code-review-trainer/progress.json between sessions. This tracks:

• Current difficulty level (beginner / intermediate / advanced)
• Your strengths and blind spots
• Heuristics you've already learned (so they aren't repeated)
• Score history across sessions

Delete this file to reset your progress.

Example session

See examples/garmin-py-workout-builder-session.md for a full transcript of a training session on a real Python module. It covers:

• 4 questions about a workout payload builder
• Detailed feedback on each answer
• Heuristics taught during the session
• Issues found and subsequently fixed
• Automated Codex review that caught a regression in the fixes

Heuristic examples

Each question teaches a reusable code review heuristic:

• "Technically correct" is not the same as "good design." Always ask: is there a simpler way to achieve the same guarantee?
• Before debating how to optimize code, ask whether the code needs to run at all. Dead logic is worse than slow logic.
• When the same dict appears in two places in a data structure, ask: are these aliases or independent copies?
• Reusing a function by feeding it dummy inputs and discarding half the output means the abstraction boundary is in the wrong place.
• Count the implementations. An interface with one implementor is indirection, not abstraction.
• If deleting a layer does not break anything, that layer is not doing work.

License

MIT