Claude Code Mentoring Flow

A structured setup for using Claude Code as an active learning mentor — not just a code generator.

The core idea: instead of asking Claude to write everything for you, you define rules that force Claude to teach, review, and guide while you do the actual thinking and coding.

---

How It Works

CLAUDE.md — sets the rules for every session:

• Tone and communication style
• Two modes: explain-first (learning) vs. boilerplate-assist (execution)
• Hard constraints on what Claude must never do

memory/ — persists context across sessions:

• mentoring_rules.md — detailed mentoring protocol (how to review, how to teach)
• user_profile.md — your background, current stack, known weak points
• MEMORY.md — index file, loaded automatically each session

Claude reads these files at the start of each session, so it always knows who you are and how to interact with you — no re-explaining every time.

---

Setup

1. Clone this repo or copy the files into your project root
2. Fill in memory/user_profile.md with your actual background and weak points
3. Customize CLAUDE.md → ## Project-Specific Rules with your domain rules
4. Open Claude Code in your project directory — it loads CLAUDE.md automatically
5. Run /init-mentoring once (see below) so ./memory/ keeps growing without you having to remember to ask for it

Add this to the top of CLAUDE.md to make Claude load memory on session start:

> **Session start:** Read `./memory/mentoring_rules.md` and `./memory/user_profile.md` first.
> **Memory path:** All memory read/write uses `./memory/` (project root).

---

Memory That Grows Without You Asking

A memory file you never update is just a stale snapshot from the day you cloned this repo. The setup above works — but it only works if someone actually follows the SESSION UPDATE PROTOCOL in memory/MEMORY.md at the end of every session, by hand, every time. In practice that gets skipped, and the mentoring quality quietly degrades back to a plain chatbot with no memory of yesterday.

/init-mentoring closes that gap. It installs two hooks: Stop fires after every response and immediately forks a background worker, so it never adds latency to your turn. The worker ships the last turn to a cheap, fast model (Haiku) with a short rubric — "is this a decision, a correction/confirmation, a progress update, or a pattern insight?" A NO costs nothing and never touches the main conversation. A YES gets written to a small pending file, which UserPromptSubmit picks up on your next message and surfaces as a one-line reminder — at which point Claude decides what to actually write and where, following the same protocol as before. The filter never writes memory itself, it just makes sure the question gets asked, without ever making you wait for the answer.

Run once per project:

/init-mentoring

It copies the three hook scripts into .claude/hooks/, merges both the Stop and UserPromptSubmit registrations into .claude/settings.json (never overwrites existing settings), and confirms once it's live. Remove it any time by deleting both hook entries from .claude/settings.json.

Prerequisites: jq and the claude CLI must be on PATH. If either is missing, /init-mentoring will tell you which — and even if you skip that check, the hooks fail open (a missing dependency just means no reminders, never a broken session).

---

The Two Modes

Mode A (Default — learning something new): Claude explains the concept and reasoning first → you code → Claude reviews by asking guiding questions, never rewriting your code.

Mode B (Execution — you already know the pattern): Trigger: "I know this already, write the boilerplate" Claude writes: JPA entities, mappers, repos, migration SQL, DTOs, exception classes, unit/integration tests. You always write: domain layer (models, value objects, events, business logic), configs, stubs.

---

Key Constraints

These are non-negotiable in the default setup:

• Claude never implements business logic, state machine transitions, or saga/event handler bodies
• Claude never rewrites your code — only points out problems, you fix
• Code review follows: read all → correctness → edge cases → design → guiding questions → you find the bug

---

Context Compact (Token Saving)

When a session gets long, type /compress to get a handoff block:

{
  "t": "[timestamp]",
  "doing": "[service.class.method]",
  "approach": "[current reasoning]",
  "decided": ["..."],
  "done": ["..."],
  "todo": ["..."],
  "bug": "[error + hypothesis + tried]",
  "next": "[specific next action]"
}
---WIP---
[raw code snippet if mid-implementation]
---END---

Then /clear and paste the block — Claude picks up exactly where you left off without re-reading the whole conversation.

---

Customization

The memory/user_profile.md template has sections for:

• Your background and current learning goals
• Tech stack you know vs. stack you're learning
• Known weak points (so Claude targets them)
• Habits to fix (e.g., "remind me to commit at natural milestones")

The more specific your profile, the better the mentoring.