First, welcome to all new subscribers. We have finally made it to 39,000+. I am very grateful to each of you and am still overwhelmed by the support, pledges, and encouragement you have sent — Thank you once again.

This issue brings you the first article in the Claude Code Deep Dive series — Claude Code Ralph Loop Deep Dive

Every Claude Code session has the same hidden flaw; Claude stops when it thinks the job is done.

• Tests broken

• API half-implemented,

• Edge cases untouched

But it declares complete and exits. And the longer and more complex the task, the worse it gets.

There is a technique designed to fix this problem. You have probably heard the word “Ralph” thrown around.

It’s a simple idea that forces Claude to keep iterating until the work is genuinely completed.

Surprisingly, this technique has been used to ship entire projects overnight at a fraction of the actual cost.

In this newsletter, I’ll take you from understanding why Claude fails on complex tasks to building the full Ralph Loop system and running it on real projects.

We’ll cover the Ralph core mechanism, the PRD and memory architecture, and everything you need to put Ralph Loop to work.

Let’s start with the basics.

What is Ralph Loop?

Let me start with something that might surprise you.

Ralph Loop isn’t a framework, and it is not a sophisticated AI orchestration system. At the core, it’s a Bash while loop.

while true; do
  cat prompt.md | claude
done

The technique was created by Jeffrey Huntley

This childlike persistence is the philosophy behind the technique.

With Ralph Loop, Claude is no longer allowed to exit when it thinks it’s done. It’s forced to keep working until the task is truly finished.

The key insight is that Ralph Loop treats failure as expected, not exceptional.

Each iteration builds on the last. The AI sees what it did before, recognizes what’s still broken, and improves.

Why Claude Code Needs Ralph

Claude Code has a limitation that most developers don’t recognize until they’ve hit it repeatedly.

It operates in single-pass mode.

Even though Claude reasons extremely well, it stops as soon as it believes the output is “good enough.”

The model has what you might call an implicit execution budget. Once it feels like it’s done reasonable work, it wraps up and exits.

The problem is that “ good enough”, according to Claude, often isn’t good enough.

I’ve seen this pattern dozens of times:

• Claude builds a feature, declares it complete, but the edge cases are broken

• Claude writes tests, says they pass, but they don’t actually run

• Claude implements an API, marks it done, but forgot error handling

It believes it’s finished, but it’s making that judgment based on what the code looks like, not whether it works.

Another problem that makes this worse is the context rot.

As the conversation with Claude gets longer, the context window fills up. The model’s reasoning quality degrades as it has to juggle more information.

This is why the single-pass approach fails for complex tasks.

By the time Claude reaches the end of a big feature, its context is bloated with attempts, errors, and fixes. The quality of its reasoning has degraded.

Ralph Loop solves both problems:

1. Forces verification — Claude can’t exit until it proves the work is done

2. Fresh context — Each iteration starts clean, avoiding context rot

Core Mechanism

Let me break down how Ralph Loop works.

The Anthropic plugin uses the stop hook. This is a feature in Claude Code that runs whenever Claude finishes responding and tries to end the session.

Here’s the flow:

1. You give Ralph your prompt and a completion promise (like “DONE” or “COMPLETE”)

2. Claude works on the task

3. Claude tries to exit

4. The stop hook intercepts the exit

5. It scans the output for the completion promise

6. If no promise is found, it feeds the same prompt back to Claude

7. Claude sees its previous work in the files and improves it

8. Repeat until the completion promise appears

The magic happens in those state files at the bottom.

• prd.json — Contains your task list with passes: true/false flags. Claude reads this to know what’s done and what’s left.

• progress.txt — Short-term memory. Claude appends learnings after each iteration. The next iteration reads this to avoid repeating mistakes.

• agents.md — Long-term memory. Patterns and knowledge that persist beyond the current sprint.

When Claude starts a new iteration, it reads these files and sees the code it wrote. It sees what passed and what failed, and it sees notes from previous iterations.

This is what makes Ralph Loop more than just “run it again.” Each iteration is informed by all previous iterations.

Completion Promise

The completion promise is how Ralph knows when to stop.

You define a specific word or phrase — typically “DONE” or “COMPLETE”. Claude must output this wrapped in a specific format:

<promise>COMPLETE</promise>

The stop hook scans for this pattern. If it finds it, the loop exits. If not, the loop continues.

This creates a contract between you and Claude:

• You define what “done” means (clear criteria in your prompt)

• Claude works until those criteria are met

• Claude signals completion with the promise

• Ralph verifies and exits

The promise should represent actual completion. Your prompt needs to define what must be true before Claude outputs the promise.

Bad prompt:

Build a todo API. Output COMPLETE when done.

Good prompt:

Build a REST API for todos.

Requirements:
- CRUD endpoints for todos
- Input validation
- Error handling
- Tests with 80% coverage

Run tests after implementation. 
Only output <promise>COMPLETE</promise> when ALL tests pass.

The second prompt gives Claude binary criteria that can be verified.

What Ralph Loop Is NOT

Before we go deeper, let me clear up some misconceptions.

1. Ralph is not the Anthropic plugin.

The plugin is convenient, but it’s a simplified implementation. It doesn’t fully reset context between iterations the way the original bash loop approach does. For simple tasks, the plugin works fine. For complex projects, you’ll want the full approach.

2. Ralph is not magic.

It amplifies whatever you feed it. Good planning and clear criteria produce great results. Vague prompts produce expensive loops that go nowhere.

3. Ralph is not a replacement for thinking.

You still need to design your tasks, write clear criteria, and review the output. Ralph automates the iteration cycle, not the engineering judgment.

4. Ralph is not always the right tool.

Some tasks need human judgment at every step. Some tasks are one-shot and simple. Ralph is ideal for complex, multi-step work that has verifiable completion criteria.

Ralph Architecture

1) PRD (Product Requirements Document)

Everything starts with the PRD.

Before you run a single iteration, you need a clear definition of what you’re building. The PRD is the definition that guides every Ralph Loop iteration.

Most developers get it wrong: they try to write the PRD themselves.

I don’t do that.

Generate it through a conversation with Claude.

Here's a PRD generator prompt you can use:

I want to build [DESCRIBE YOUR FEATURE/PROJECT].

Interview me about this. Ask 3-5 clarifying questions about:
- Target users
- Core functionality
- Technical requirements
- Success criteria

After I answer, generate a PRD with:
- Project overview
- User stories (who does what, why)
- Feature requirements
- Success criteria (binary, testable)
- Technical stack
- Out of scope (what we're NOT building)

Key principle: Every success criterion must be binary and testable.

Not “the UI should look good” — that’s subjective. Instead: “the dashboard loads in under 2 seconds,” or “all buttons have hover states,” or “accessibility score is 90+.”

2) Task List (prd.json)

The PRD describes what you’re building. The task list breaks it into atomic pieces.

This is where Ralph Loop gets its power.

Instead of asking Claude to build an entire feature in one shot, you give it a sequence of small, focused tasks. Each task completes in one iteration with a fresh context.

The format follows Anthropic’s recommendation from their long-running agents documentation:

{
  "projectName": "Todo API",
  "tasks": [
    {
      "id": "US-001",
      "title": "Set up project structure",
      "acceptanceCriteria": [
        "package.json exists with dependencies",
        "TypeScript configured",
        "npm run build succeeds"
      ],
      "passes": false
    },
    {
      "id": "US-002", 
      "title": "Create todo database schema",
      "acceptanceCriteria": [
        "todos table with id, title, completed, created_at",
        "Migration runs successfully",
        "Schema matches specification"
      ],
      "passes": false
    },
    {
      "id": "US-003",
      "title": "Implement GET /todos endpoint",
      "acceptanceCriteria": [
        "Returns array of todos",
        "Supports pagination",
        "Tests pass for endpoint"
      ],
      "passes": false
    }
  ]
}

The passes: false flag is crucial. As Ralph completes each task, it sets this to true. The loop continues until all tasks pass.

Task sizing is critical. Each task must:

• Complete in ONE iteration

• Fit comfortably in the context window

• Have verifiable acceptance criteria

• Result in a working, committable change

If a task feels big, split it. “Build authentication” is too big. Split into: “Add users table” → “Create signup endpoint” → “Create login endpoint” → “Implement JWT tokens” → “Write auth tests.”

3) Memory System

Ralph Loop has memory, both short-term and long-term.

Short-term memory: progress.txt

This file tracks what happened during the current sprint.

After each iteration, Claude appends:

• What was implemented

• What files were changed

• Any learnings or patterns discovered

• Blockers encountered

The next iteration reads this file. It knows what the previous iteration did, what worked, and what didn’t.

## Iteration 3 - 2024-01-15 14:32

**Task:** US-003 - Implement GET /todos endpoint

**Implemented:**
- Created routes/todos.ts
- Added GET /todos with pagination
- Added tests for endpoint

**Files Changed:**
- src/routes/todos.ts (new)
- src/routes/index.ts (updated)
- tests/todos.test.ts (new)

**Learnings:**
- Pagination requires offset and limit params
- Need to handle empty results case

**Next:** US-004 - POST endpoint

Long-term memory: agents.md

This is permanent knowledge. Things that should persist beyond the current sprint.

You can have agents.md files in any folder. Claude reads them when working in that folder. They’re like sticky notes for future iterations (and future sprints)

# Project Patterns

## API Routes
- All routes use Express Router
- Validation middleware goes before handler
- Error responses follow { error: string, code: number } format

## Testing
- Use vitest, not jest
- Mock database with in-memory SQLite
- Each test file needs afterEach cleanup

## Gotchas
- Don't use `any` type - breaks type checking
- Always await database operations
- Rate limiting middleware must be first

The memory system is why Ralph gets smarter over iterations instead of repeating mistakes. Each iteration learns from the last.

4) Feedback Loop System

Without feedback loops, Ralph Loop is just expensive guessing.

Claude needs automated ways to verify its own work.

It can’t just look at code and decide it’s correct — it needs to run tests, check types, and execute builds, which is the real verification.

Build verification into every prompt:

After implementing:
1. Run `npm run typecheck` — fix any errors
2. Run `npm run lint` — fix any warnings  
3. Run `npm test` — all tests must pass
4. Run `npm run build` — must compile

Only mark task complete when ALL checks pass.
If any fail, debug and fix before continuing.

Feedback types and what they catch:

For backend work, types + tests + build are usually sufficient.

For frontend work, add browser automation. Claude can’t “see” a UI by reading code. It needs to render pages and interact with elements to verify they work.

The feedback loop creates self-correction. Claude writes code, runs checks, sees failures, fixes them, runs checks again.

Ralph Execution

There’s a right way and a wrong way to start using Ralph Loop.

The wrong way: install the plugin, fire off a complex prompt, go to sleep, wake up to chaos.

The right way: progress through levels, building understanding at each stage.

Jeffrey Huntley, the creator of Ralph, puts it simply: “Don’t start with the jackhammer. Learn the screwdriver first.”

The screwdriver is a manual single runs while the jackhammer is an overnight autonomous operation.

You need to master each level before moving to the next.

Each level teaches you something you can't learn at the next level.

Level 1: Manual Single Runs (The Screwdriver)

Start here with every new project.

At Level 1, you run one iteration at a time and watch everything.
You see what Claude does, what it gets right, what it gets wrong.

Run Level 1:

# Option 1: Direct command
cat prompt.md | claude

# Option 2: Using the plugin with max-iterations 1
/ralph-loop "your task" --completion-promise "DONE" --max-iterations 1

After each iteration:

• Read the code Claude wrote

• Check if it was committed properly

• Verify the prd.json was updated

• Look at progress.txt entries

• Run the tests yourself

Then run the next iteration.

What you’re learning at Level 1:

• How Claude interprets your prompts

• What patterns does your codebase trigger?

• Where Claude gets confused

• How long does each iteration take?

• What the token cost looks like

• Whether your criteria are clear enough

When to move to Level 2:

• You’ve run 10+ manual iterations

• You understand the flow completely

• You can predict what Claude will do

• You know what success looks like

• You know what failure looks like

Level 2: Attended Loops (Power Drill)

At Level 2, you let Ralph run multiple iterations

/ralph-loop "your task" --completion-promise "DONE" --max-iterations 10

Every few iterations, you look at:

• Is it picking tasks in the right order?

• Are commits happening after each task?

• Is progress.txt being updated?

• Are the tests actually passing?

• Any strange patterns emerging?

The key at Level 2 is catching problems early.

What you’re learning at Level 2:

• How the loop handles your specific codebase over time

• What failure patterns look like in your setup

• How quickly issues compound if not caught

• What is your actual token cost per task

• Whether your max-iterations is set appropriately

When to move to Level 3:

• You’ve run 3-5 attended loops (50+ total iterations)

• No surprises in the last 2-3 runs

• You trust the setup

• You know exactly what to check in the morning

• You have a recovery plan if things go wrong

Level 3: Unattended Overnight (Jackhammer)

The goal is to set it running before bed, wake up to completed work.

But you only get here after mastering Levels 1 and 2.

The overnight checklist:

Before starting an unattended run:

• PRD is complete and reviewed

• All tasks are atomic with clear criteria

• Feedback loops built into prompt (tests, types, lint)

• Max iterations set (30-50 for overnight)

• Git branch is clean and ready

• Notification system configured (optional but helpful)

• You know what “success” looks like in the morning

Morning review process:

1. Check prd.json — how many tasks passed?

2. Read progress.txt — any errors or blockers?

3. Review git log — are commits sensible?

4. Run tests manually — do they pass?

5. Test the feature yourself — does it work?

Expect 80-95% completion on a good run. Some edge cases always need human attention.

The goal isn’t perfect code but 8 hours of work done while you slept, with 1-2 hours of cleanup in the morning.

Setting up notifications:

You can add a notification when Ralph completes:

# Simple approach: notify after loop exits
/ralph-loop "task" --max-iterations 30 --completion-promise "DONE" && \
  notify-send "Ralph complete" || notify-send "Ralph failed"

Some developers set up WhatsApp or Slack notifications using simple scripts. Useful if you want to check progress before morning.

Ralph Practical Examples

Different projects need different approaches. Here are four patterns that work for specific use cases.

Pattern 1: The Feature Builder

Building new features from a PRD

This is the classic Ralph Loop use case. You have a feature to build, you break it into tasks, and Ralph builds it piece by piece.

Prompt template:

You are an autonomous coding agent working on this project.

Your task:
1. Read prd.json to find the highest priority task where passes is false
2. Implement that single task
3. Run tests to verify: npm run typecheck && npm test && npm run build
4. If tests pass, update prd.json to set passes: true
5. Append progress to progress.txt
6. Commit your changes with a descriptive message

Only work on ONE task per iteration.

When ALL tasks in prd.json have passes: true, output <promise>COMPLETE</promise>

Example project: REST API with 15 endpoints

• Task 1-3: Project setup, database, basic structure

• Task 4-10: Individual endpoints (one per task)

• Task 11-13: Validation, error handling, edge cases

• Task 14-15: Documentation, final tests

Expected: 15-20 iterations, 2-4 hours unattended

Pattern 2: Test-Until-Green

Improving test coverage on existing code

You have code that works but lacks tests. Ralph writes tests until coverage hits your target.

Prompt template:

Your task: Improve test coverage for this codebase.

Current coverage: Check with `npm run coverage`
Target coverage: 80%

Process:
1. Run coverage report to identify untested code
2. Write tests for the most critical untested function
3. Run tests to verify they pass
4. Check new coverage percentage
5. Append progress to progress.txt

Only write tests for ONE function per iteration.

Output <promise>COMPLETE</promise> when coverage reaches 80% or higher.

What makes this pattern work:

• Clear binary goal (coverage >= 80%)

• Claude can verify progress with each iteration

• Natural small units (one function = one iteration)

• Built-in feedback loop (coverage report)

Expected: Varies by codebase. 10-30 iterations typically.

Pattern 3: Multi-Persona Review

Best for: Code quality and production readiness

Instead of just building, Claude rotates through different reviewer personas. Each persona catches different issues.

Prompt template:

You are reviewing and improving this codebase by rotating through personas.

Personas:
1. Code Reviewer: Check for bugs, edge cases, code quality
2. Solution Architect: Check structure, dependencies, patterns  
3. QA Engineer: Check test coverage, error handling
4. Security Reviewer: Check for vulnerabilities, input validation
5. Front End Dev: Check UI/UX, accessibility, responsiveness

For each iteration:
1. Select the next persona in rotation
2. Review the codebase from that persona's perspective
3. Identify ONE issue to fix
4. Fix the issue
5. Commit with message: "[Persona] - description of fix"
6. Log the review in progress.txt

Continue until ALL personas complete 2 full cycles finding no issues.

When that condition is met, output <promise>COMPLETE</promise>

Why this works:

Different personas catch different problems.

• Code reviewer sees bugs.

• Security reviewer sees vulnerabilities.

• QA engineer sees missing tests.

Rotating through all of them creates comprehensive coverage that single-pass reviews miss.

Expected: 15-30 iterations for thorough review

Pattern 4: Proof of Concept Validator

Best for: Quickly validating ideas, testing tech stacks

You want to see if an idea works before committing to full implementation. Ralph builds a rough version fast.

Prompt template:

Build a proof of concept for: [IDEA]

Tech stack: [YOUR CHOICES]

This is a POC, not production code. Priorities:
1. Core functionality works
2. Happy path is complete  
3. Basic error handling
4. Demonstrates the concept

NOT priorities (skip for now):
- Comprehensive tests
- Edge case handling
- Production security
- Perfect code quality

Tasks:
1. Set up project structure
2. Implement core feature
3. Add basic UI (if applicable)
4. Verify it works end-to-end

Output <promise>COMPLETE</promise> when the POC demonstrates the core concept working.

When to use this pattern:

• Validating a new architecture

• Testing if a tech stack works for your use case

• Building a demo for stakeholders

• Exploring a new API or service

Key difference: Lower quality bar. You’re not building production code. You’re answering the question “Does this approach work?”

Expected: 5-10 iterations for basic POC

Choosing the Right Pattern

You can also combine patterns. Build with Feature Builder, then polish with Multi-Persona Review.

Final Thoughts

Ralph Loop is simple at its core - a while loop, a stop hook, and a completion promise.

But mastery requires:

• Understanding the fundamentals

• Building the right architecture

• Progressing through the levels

• Choosing the right pattern

Resources

PS: I launched the Claude Code Masterclass Git repo, where I will be adding all these code snippets and templates for quick and easy access.

Claude Code Masterclass

Let’s Build It Together

— Joe Njenga

Hello, thank you for being part of our Claude Code Masterclass community.

We are now 28k+ members (and I’m honestly blown away by your support, your pledges, and the incredible energy you’ve brought) — I’m grateful for every single one of you!

I am working day and night to deliver the best practical Claude Code education material.

Last week brought some useful Claude Code updates: a command to chat while Claude works, voice mode now rolled out to everyone (I built a full app with it), a 1 million context window for Opus and Sonnet, and a diagrams feature that might replace Canva for technical visuals.

What Happened Last Week In Claude Code?

#1) /btw Command — Chat While Claude Works

Claude Code /btw lets you ask side questions while Claude is working on a task.

If you’ve been mid-task, watching Claude work through a complex operation, and suddenly have a question, you either wait or interrupt.

The /btw command fixes this.

How It Works

/btw <question>

For example:

/btw what does retry logic do?

Claude opens an overlay with the answer. Your main task continues running in the background.

Press Space, Enter, or Escape to dismiss it and return to your session.

Key Features

• Runs in parallel — Your main task doesn’t pause or wait

• Overlay response — Answer appears in a pop-up, not inline

• No history pollution — The side question doesn’t get added to your main conversation context

• Single-turn only — You get one response, no back-and-forth

• No tool access — The response comes from Claude’s knowledge and current session context

Requirements

Available in Claude Code version 2.1.72 and later.

claude --version
claude update

I tested /btw with real examples and documented the setup and use cases.

You can learn more here — I Tried (New) Claude Code /btw Command (Now You Can Chat As You Code)

#2) /voice Full Test — I Built a Complete App With Voice

Anthropic rolled out Claude Code /voice to all users. I put it through a real build.

Last week I introduced /voice, but didn’t have access. Now I do — and I built a food ordering system entirely with voice.

The Build

• Backend: FastAPI with menu and order endpoints

• Frontend: Vanilla JavaScript to display the menu and place orders

This forced me to dictate real code, handle multiple files, and see how fast voice coding is.

How It Works

Type /voice to toggle it on.

• Push-to-Talk: Hold Space, speak, release. Your words stream in real-time at your cursor.

• Hybrid Prompts: Type half a prompt, hold Space to voice the messy middle, keep typing.

Fix the auth middleware in [hold Space] — the token validation 
is failing silently when the expiry timestamp is malformed, 
it should throw a proper 401 [release] — and add a test for it.

What I Found

The transcription picked up “manual endpoint” instead of “menu endpoint” — but Claude understood the intent and generated the correct code.

25 lines of clean backend code with proper type hints. The frontend came together just as fast.

What You Get

• No extra cost — Voice transcription doesn’t count against rate limits

• Cross-platform — Works on macOS, Linux, and Windows

• No cloud dependency — Runs locally inside your Claude Code session

Voice mode is now available to everyone. Check your Claude Code welcome screen.

You can learn more here — I Finally Tested Claude Code /voice — It’s Faster than Typing (Don’t Waste Time)

#3) 1 Million Context Window — Opus 4.6 & Sonnet 4.6

Anthropic added a 1-million-context window to Opus 4.6 and Sonnet 4.6.

This is now available by default for Max, Team, and Enterprise plans.

What Changed

• Opus 4.6 — 1M context window by default (previously required extra usage)

• Sonnet 4.6 — Also gets 1M context

• Output tokens — Opus 4.6 now outputs 64k tokens by default, up to 128k max

1 million tokens is roughly 700,000 words or about 2,500 pages of text.

You can now:

• Load entire codebases into a single session

• Work with massive documentation without truncation

• Maintain longer conversation history without compaction

Who Gets It

• Max plan — Yes

• Team plan — Yes

• Enterprise plan — Yes

• Pro plan — Check your settings

Version

Available in Claude Code 2.1.75 and later.

You can learn more here — Anthropic Adds 1 Million Context Window to Opus 4.6 & Sonnet 4.6

#4) Diagrams & Charts — I Tested 21 Prompts (Goodbye Canva)

Claude can now create complex diagrams and charts. I tested 21 prompts, from simple to complex.

The results were impressive.

One Line Prompt

Show me how a JWT authentication flow works from login to protected API access

Claude generated a complete visual diagram. This will change how I approach technical content.

What I Tested

Flowcharts & System Architecture

• CI/CD pipeline from commit to production

• Microservices order flow for e-commerce

• AWS serverless architecture for real-time chat

• Three-tier web architecture with caching and CDN

• Kubernetes container orchestration

Data Visualizations

• Performance benchmark bar charts (Python, Go, Rust, Node.js)

• Cloud costs pie chart by service category

• JavaScript framework popularity line chart

Database & Data Flow

• Event sourcing and CQRS for banking systems

• Social media ERD (users, posts, comments, followers)

• Real-time analytics pipeline with Kafka and Spark

Algorithm & Concept Explainers

• Binary search tree balancing

• OAuth 2.0 authorization flow

• DNS resolution step by step

Interactive Explainers

• JavaScript garbage collection

• Neural network backpropagation

• Hash map collision handling

• SQL vs NoSQL decision tree

For developers, technical writers, and content creators — this is what you need.

No more switching to Canva or Figma for technical diagrams. One prompt, instant visual.

You can learn more here — Claude Can Now Create Complex Diagrams — I Tested 21 Prompts (Goodbye Canva!

Finally, this newsletter belongs to all of us. If there’s something that can make it better or something you don’t like, please let me know.

Claude Code Masterclass

Let’s Build It Together

— Joe Njenga

Hello, thank you for being part of our Claude Code Masterclass community.

We are now 21k+ members (still overwhelmed by your support, your pledges, and good vibes) — it’s unbelievable, and I’m grateful for every one of you!

I am working day and night to deliver the best practical Claude Code education material.

Last week brought some major Claude Code updates: a framework to test if your agent skills work, Ultrathink made a comeback, native voice input, and a way to run subagents without burning tokens.

What Happened Last Week In Claude Code?

#1) Skill-Creator Plugin — Finally Test If Your Agent Skills Work

Agent skills are notorious for fooling you into believing they work — but sometimes they fail, and the next day they work fine.

Anthropic released the Skill-Creator plugin — a testing framework to measure and refine your agent skills.

What It Does

• Evals — Define test prompts and expectations, then check if outputs match

• Benchmarks — Track pass rate, elapsed time, and token usage

• A/B Comparisons — Blind testing between skill versions

• Description Optimizer — Improves skill triggering accuracy

Two Types of Skills

• Capability Uplift Skills — Help Claude do something the base model can’t do consistently (PDF, DOCX, PPTX creation)

• Encoded Preference Skills — Document your team’s workflows so Claude follows your process every time

Real Results

Anthropic tested the PDF skill on non-fillable forms:

• Test With Skill Without Skill Pass Rate 5/5 (100%) 2/5 (40%)

• The skill clearly adds value where the base model fails.

Installing the Plugin

# Add the marketplace
/plugin marketplace add anthropics/skills

# Install skill-creator
/plugin install skill-creator@anthropic-agent-skills

I tested the PDF skill on a job application form and documented the entire process — what worked, what broke, and how the plugin measures it.

You can learn more here — Claude Code Skill-Creator Measures If Your Agent Skills Work

#2) Ultrathink Is Back — Version 2.1.68

A fresh Claude Code update reintroduced Ultrathink, changing how you manage thinking effort.

What Changed in 2.1.68

• Opus 4.6 now defaults to medium effort for Max and Team subscribers

• Opus 4 and 4.1 are gone from the first-party API — users are moved to Opus 4.6

• Ultrathink is back after being removed in an earlier release

High effort on every prompt was overkill. Renaming a variable doesn’t need deep thinking.

Medium effort handles 90% of daily tasks. But that other 10% — architecture decisions, complex debugging, security-critical code — needs more.

That’s where Ultrathink makes sense.

Effort Levels

Method Effort Level Duration Default (2.1.68) Medium Permanent /model → High High Permanent ultrathink High One turn only

How Ultrathink Works

Type ultrathink before your prompt. Claude switches to high effort for that one turn, then returns to your default.

It only works if your current effort is medium or low. If you’re already on high, it does nothing.

My Test

I gave Claude Code the same debugging task: Node.js API with a race condition.

• Medium effort: Identified the cause, suggested a fix.

• Ultrathink: Walked through the entire request lifecycle, found two separate issues (the race condition + a token expiry edge case), and outlined a testing strategy.

From my findings, Medium gives you the answer. Ultrathink gives you the answer, plus things you didn’t ask about.

You can learn more here — Claude Code Ultrathink Is Back In New Update (I Just Tested It)

#3) Native /voice Mode — Stop Typing, Start Talking

Claude Code introduced voice mode last week. You can now use the /voice command.

How It Works

Type /voice to toggle it on.

• Push-to-Talk: Hold Space, speak, release. Your words stream in real-time at your cursor.

• Hybrid Prompts: Type half a prompt, hold Space to voice the messy middle, keep typing.

Fix the auth middleware in [hold Space] — the token validation 
is failing silently when the expiry timestamp is malformed, 
it should throw a proper 401 [release] — and add a test for it.

What You Get

• No extra cost — Voice transcription doesn’t count against rate limits

• Cross-platform — Works on macOS, Linux, and Windows

• No cloud dependency — Runs locally inside your Claude Code session

Roll Out

It’s rolling out to ~5% of users first.

Check your Claude Code welcome screen — if you’re in the rollout, you’ll see a note confirming voice mode is available.

If not, as in my case above, the rollout is expanding over the coming weeks. I’ll run a full build test to show you how it works.

You can learn more here — Claude Code Voice Is Here /voice (You Can Now Talk & Stop Typing)

#4) Ollama Subagents & Web Search — Run Parallel Agents at No Cost

You can now run Claude Code subagents and web search using Ollama cloud models — without burning your Anthropic tokens.

One Command to Launch

ollama launch claude --model minimax-m2.5:cloud

Works with any model on Ollama’s cloud.

Subagents in Action

I built an expense tracker using three parallel subagents:

• frontend-ui-expert — HTML, CSS, vanilla JS (11.4k tokens)

• Backend agent — FastAPI routes and models (11.0k tokens)

• Project structure agent — Files and README (10.8k tokens)

All three ran simultaneously. Project completed in minutes.

Then I spun up three more subagents to audit the code. They found real issues:

• CORS vulnerability (allow_credentials=True with wildcard origins)

• Deprecated datetime. utcnow

• Float for monetary values instead of Decimal

Web Search Works Too

Subagents can research topics in parallel:

spawn research agents to find the latest FastAPI 0.115 release features,
research best practices for expense tracker API design, and summarize
Python REST API security guidelines

Three research agents returned structured tables with actionable recommendations.

Recommended Models

Not all Ollama models support subagents and web search. These three work:

• minimax-m2.5:cloud

• glm-5:cloud

• kimi-k2.5:cloud

This setup works best for prototypes and learning. For production work or sensitive codebases, stick with the paid API.

But for experimenting without watching your bill — or when Anthropic has an outage — this is the move.

You can learn more here — How I’m Running Claude Code Subagents & Web Search (At No Cost)

Finally, this newsletter belongs to all of us. If there’s something that can make it better or something you don’t like, please let me know.

See you in the next issue of Last Week In Claude Code.

Claude Code Masterclass

Let’s Build It Together

— Joe Njenga

Hello, thanks for being part of our Claude Code Masterclass community. We are now headed to 20k members — I am eternally grateful for every one of you!

I have updated the quick updates to be Last Week in Claude Code so that I can write a summary of updates once a week.

This conforms to our original content structure, as I shared in the Claude Code Masterclass Introduction.

In this series, I will be sharing the Claude Code updates from the previous week in a quick summary after I have tested and documented them.

The goal is to save your time and help you learn new Claude Code updates faster.

Quick Note: I apologize for taking longer to release the Hooks Masterclass. As you may already know, testing and creating comprehensive content takes a lot of time, especially for hooks.

I’m also slightly behind the publishing calendar, but I am doing my best to keep up with the pace at which things are changing.

What Happened Last Week In Claude Code?

#1) /simplify & /batch — Code Reviews Just Got 10x Faster

Version: 2.1.63

Claude Code introduced two commands to simplify code reviews - /simplify and /batch

/simplify — Automated Code Quality Pass

Spins up parallel agents that review your code against your CLAUDE.md standards and fix issues automatically.

What it catches:

• Dead code and commented-out blocks

• Inefficient patterns and code smells

• CLAUDE.md rule violations

• Duplicate logic across files

My test: 69 lines of messy code → 33 clean lines in 1 minute 29 seconds

/batch — Parallel Migration Engine

Plans and executes large-scale migrations using isolated agents in git worktrees.

/batch migrate src/ from Jest to Vitest
/batch migrate src/ from CommonJS to ES modules

How it works:

1. Scans your directory and creates a migration plan

2. Shows you exactly what will change before touching code

3. Spins up isolated agents per folder

4. Each agent tests its work before opening a PR

I tested both commands on a real project and documented everything — the setup, the results, and what Claude actually changed.

You can learn more here — How I’m Using Claude Code /simplify & /batch to x10 My Code Reviews

#2) Auto-Memory (MEMORY.md) — Claude Now Remembers Your Project

Claude now builds and maintains its own memory as it works with you, quietly taking notes on your build commands, code style, architecture decisions, and the bugs you solved together.

How It Works

• Auto-enabled — No configuration needed, works out of the box

• Claude writes it — You don’t touch MEMORY.md; Claude does

• 200-line limit — Only the first 200 lines load at session start

Where it’s located:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # Main index, loaded every session
├── debugging.md       # Detailed debugging notes
└── api-conventions.md # API decisions

CLAUDE.md vs MEMORY.md — What's the Difference?

Both load at session start. Together, they give Claude full context before you start coding.

Managing Memory

Use the /memory command to:

• Toggle auto-memory on/off

• Open your memory folder

• Access user and project memory files

Turn It Off (If Needed)

// Disable for one project (.claude/settings.json)
{ "autoMemoryEnabled": false }

// Disable globally (~/.claude/settings.json)
{ "autoMemoryEnabled": false }

// Force off in CI environments
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

I tested auto-memory from scratch — created a project, worked a session, closed it, and came back cold. Claude remembered everything.

You can learn more here — Anthropic Just Added Auto-Memory to Claude Code — MEMORY.md (I Tested It)

#3) Remote Control — Code From Your Phone

Control your local Claude Code session from any device — phone, tablet, or another browser.

Your laptop stays at your desk running Claude Code. Remote Control creates a secure connection so you can control that session from anywhere.

This is not Claude Code on the web (which runs in Anthropic’s cloud).

Remote Control runs on your machine:

• MCP servers stay active

• Project context stays intact

• Your filesystem is fully available

• All your tools and permissions persist

Three Ways to Connect

1. Session URL — Copy from terminal, paste in any browser

2. QR Code — Press spacebar in terminal, scan with Claude mobile app

3. Session List — Find it at claude.ai/code with a green status dot

Requirements

• Pro or Max plan (not Team/Enterprise yet)

• Authenticated via claude.ai (API keys won’t work)

• Workspace trust accepted

I documented the setup, the flags, multi-device workflows, and managing multiple projects — so you’re ready when it rolls out to you.

You can learn more here — I Tried (New) Claude Code Remote-Control (Before You Waste Your Time)

Finally, this newsletter belongs to all of us. If there’s something that can make it better or something you don’t like, please let me know.

See you in the next issue of Last Week In Claude Code.

Claude Code Masterclass

Let’s Build It Together

— Joe Njenga

Since the first issue of Claude Code Masterclass Introduction, I’ve been overwhelmed by your response — encouragement, support, and so many new pledges. Thank you.

Your feedback made one thing clear: you want structure.

This issue brings you the second article in the Claude Code Masterclass series. — Mastering CLAUDE.md File

Every Claude Code session starts the same way — Claude knows nothing about your project.

• It doesn’t know your tech stack.

• It doesn’t know your folder structure.

• It doesn’t know that you prefer tabs over spaces or that your team uses a specific branch naming convention.

So you should explain your project every single time.

“This is a FastAPI project. We use SQLAlchemy for the database. Tests are in the /tests folder. Run pytest to execute them. Oh, and we follow PEP 8 with 100-character lines.”

This creates a problem of constantly explaining your project details, and that is the problem CLAUDE.md solves.

CLAUDE.md is a markdown file that gives Claude persistent memory about your project. Create it once, and Claude reads it automatically at the start of every session.

In this guide, I’ll take you from creating your first CLAUDE.md to building pro-level configurations that compound with hooks and subagents.

We’ll cover the hierarchy system, the anatomy of a well-structured file, and everything you should know about the CLAUDE.md file.

Let’s start with the basics.

What is CLAUDE.md?

Most developers think of CLAUDE.md as a documentation file, which is wrong!

CLAUDE.md is a configuration file that becomes part of Claude’s system prompt.

This distinction matters because Claude treats system-level instructions differently from user prompts. Here is an illustration :

When you put instructions in CLAUDE.md, Claude follows them more strictly than anything you type in the chat.

Why Claude Will Ignore Your CLAUDE.md

Claude Code wraps your CLAUDE.md with a system reminder that tells Claude to ignore irrelevant content.

The actual wrapper looks like this:

<system-reminder>
  IMPORTANT: this context may or may not be relevant to your tasks. 
  You should not respond to this context unless it is highly relevant to your task.
</system-reminder>

This means if you stuff your CLAUDE.md with instructions that aren’t universally applicable, Claude will ignore them.

This is why “less is more” is the best trick when creating your CLAUDE.md file.

Mental Model

Think of CLAUDE.md as three things:

1. Project Memory — Claude remembers your setup across sessions

2. Operational Boundaries — Rules Claude won’t break

3. Context Primer — Claude starts informed, not blank

When you understand this mental model, you stop treating CLAUDE.md like a README since it’s the best leverage configuration point you have in Claude Code.

CLAUDE.md Hierarchy System

CLAUDE.md files can live in multiple locations, and Claude reads them in a specific order.

Understanding this hierarchy lets you create global rules that apply everywhere and project-specific rules that apply only where needed.

Three Levels

How Each Level Loads

Let’s look at a practical example:

Monorepo Setup

my-monorepo/
├── CLAUDE.md                    # Monorepo-wide rules
├── apps/
│   ├── web/
│   │   └── CLAUDE.md            # Frontend-specific rules
│   └── api/
│       └── CLAUDE.md            # Backend-specific rules
├── packages/
│   └── shared/
│       └── CLAUDE.md            # Shared library rules
└── tests/
    └── CLAUDE.md                # Testing conventions

The nested files only load when Claude accesses files in those directories. This keeps your main context lean until Claude needs that specialized knowledge.

File Naming Options

• CLAUDE.md — Standard, commit to git, share with the team

• CLAUDE.local.md — Add to .gitignore, personal overrides

Use .local.md for personal preferences, you don’t want to push to the repo.

Anatomy of a Great CLAUDE.md

A well-structured CLAUDE.md answers three questions for Claude:

• WHAT — The tech stack, project structure, key files

• WHY — The purpose of the project, what each part does

• HOW — Commands to run, workflows to follow, conventions to respect

Core Sections

# Project Context

Brief description of what this project is and your working philosophy.

## About This Project

Tech stack, architecture pattern, key dependencies.

## Key Directories

- `src/` — Source code
- `tests/` — Test files
- `docs/` — Documentation

## Commands

```bash
npm run dev      # Start development server
npm run test     # Run tests
npm run build    # Production build

Standards

• Coding conventions

• Testing requirements

• Commit message format

Workflows

Step-by-step processes for common tasks.

Notes

Gotchas, warnings, things Claude should know.

Here is an example:

### A Real Example

Here's a CLAUDE.md for a FastAPI project:

```markdown
# Project Context

When working with this codebase, prioritize readability over cleverness. 
Ask clarifying questions before making architectural changes.

## About This Project

FastAPI REST API for user authentication and profiles. 
Uses SQLAlchemy for database operations and Pydantic for validation.

## Key Directories

- `app/models/` — Database models
- `app/api/` — Route handlers
- `app/core/` — Configuration and utilities
- `tests/` — Test files (fixtures in `tests/conftest.py`)

## Commands

```bash
uvicorn app.main:app --reload  # Dev server
pytest tests/ -v               # Run tests
alembic upgrade head           # Run migrations

Standards

• Type hints required on all functions

• pytest for testing

• PEP 8 with 100-character lines

• All routes use /api/v1 prefix

Notes

• JWT tokens expire after 24 hours

• Rate limiting is 100 requests/minute per IP

• Never commit .env files

The best approach is to keep each section focused. If a section grows too long, it’s a sign you should move that content to a separate file and reference it

Claude.md Content

Most CLAUDE.md problems come from including too much, not too little. It’s a delicate balance that can only be measured by my four rules :

1) 150-200 Instruction Limit

Research shows that frontier LLMs can reliably follow approximately 150-200 instructions.

Beyond that, instruction-following quality degrades; not just for new instructions, but uniformly across all of them.

Claude Code’s system prompt already contains ~50 instructions.

That leaves you with roughly 100-150 instructions before Claude starts ignoring things.

This is why less is more, since every unnecessary instruction reduces Claude’s ability to follow the important ones.

Always include:

• Project overview (1-2 sentences)

• Tech stack and key dependencies

• Essential commands (build, test, run)

• Directory structure (key folders only)

• Critical conventions that cause bugs if missed

Include if universally applicable:

• Branch naming conventions

• Commit message format

• Testing requirements

• Deployment process

Never include:

• Sensitive information (API keys, credentials, connection strings)

• Detailed code style guidelines (use a linter instead)

• Task-specific instructions (use separate files)

• Everything Claude could figure out by reading your code

Move to separate files:

• Database schema details

• Complex workflow procedures

• Architecture deep-dives

• Onboarding documentation

2) Progressive Disclosure

Instead of adding everything into CLAUDE.md, keep task-specific instructions in separate files and tell Claude where to find them.

As an example :

project/
├── CLAUDE.md                        # Core instructions only
└── agent_docs/
    ├── building_the_project.md
    ├── running_tests.md
    ├── code_conventions.md
    ├── database_schema.md
    └── deployment_process.md

In your CLAUDE.md, reference these files:

## Additional Documentation

Before starting specific tasks, read the relevant documentation:

- Building: `agent_docs/building_the_project.md`
- Testing: `agent_docs/running_tests.md`
- Database work: `agent_docs/database_schema.md`
- Deployment: `agent_docs/deployment_process.md`

Read only what's relevant to your current task.

Claude loads these files only when needed, keeping your main context lean.

3) Don’t Use CLAUDE.md as a Linter

This is a common mistake I see many developers make: adding extensive code style guidelines.

# Don't do this

## Code Style
- Use 2 spaces for indentation
- Always use semicolons
- Prefer const over let
- Use arrow functions for callbacks
- Add trailing commas in arrays
- Use single quotes for strings
...50 more rules

Use proper tools:

• ESLint/Prettier for JavaScript

• Black/Ruff for Python

• rustfmt for Rust

My approach for this problem is to set up a pre-commit hook or use Claude Code hooks to run your linter automatically.

4) My Golden Rule

If an instruction isn’t relevant to 80%+ of my Claude Code sessions, it doesn’t belong in CLAUDE.md. I move it to a separate file or a custom slash command.

Before we move to the advanced patterns, let’s see how to create the CLAUDE.md file.

How to Create Your CLAUDE.md

You have three ways to create a CLAUDE.md file. Each serves a different purpose.

Method 1: The /init Command

The fastest way to get started. Claude analyzes your entire codebase and generates a starter CLAUDE.md.

cd your-project
claude
/init

Claude examines your package files, existing documentation, configuration files, and code structure. It generates a CLAUDE.md with:

• Build commands

• Test instructions

• Key directories

• Coding conventions it detected

You can also run /init On projects that already have a CLAUDE.md. Claude will suggest improvements based on what it learns from exploring your codebase.

Method 2: Manual Creation

Create the file yourself in any markdown editor:

touch CLAUDE.md

Or use your editor of choice. There’s no required format — save it as CLAUDE.md (all caps) in your project root.

When to use manual creation:

• You want full control from the start

• You’re following a specific template

• You want to avoid the bloat that /init sometimes generates

Method 3: The # Memory Shortcut

Add instructions on the fly while working in Claude Code. Type # followed by your instruction:

# Always run tests before committing

This is powerful for capturing insights as you work. When you find a new potential addition to CLAUDE.md, add it with #.

My Recommendation

Advanced CLAUDE.md Patterns

Once you’ve mastered the basics, these patterns take your CLAUDE.md to the next level.

Pattern 1: Index Files for Large Codebases

For large or unfamiliar codebases, create index files that help Claude navigate efficiently.

Step 1: Generate a general index

# general_index.md

## /src/api/
- `auth.py` — Authentication endpoints, JWT handling
- `users.py` — User CRUD operations
- `products.py` — Product catalog endpoints

## /src/models/
- `user.py` — User model, relationships to orders
- `product.py` — Product model, inventory tracking

## /src/utils/
- `validators.py` — Input validation helpers
- `formatters.py` — Response formatting utilities

Step 2: Reference it in CLAUDE.md

## Navigation

I have provided index files to help you navigate:

- `general_index.md` — File descriptions for each module
- `detailed_index.md` — Function signatures and docstrings

These indexes may or may not be up to date. Verify by checking 
the actual files when needed.

The “may or may not be up to date” line is important — it prevents Claude from relying solely on the index and encourages verification.

Pattern 2: Modular CLAUDE.md Design

Break your CLAUDE.md into clear sections with markdown headers. This prevents instruction bleeding between different functional areas.

# CLAUDE.md

## Development Commands
<!-- Build, test, run instructions -->

## Code Standards  
<!-- Conventions that apply everywhere -->

## Workflow Procedures
<!-- How to complete common tasks -->

## File Boundaries
<!-- What Claude can and cannot modify -->

## Tool Integration
<!-- MCP servers, custom commands -->

Each section is self-contained. Claude can focus on the relevant section without other instructions interfering.

Pattern 3: Workflow Definitions

Define step-by-step workflows for complex tasks.

This prevents Claude from jumping straight into code without planning.

## Workflows

### Adding a New API Endpoint

1. Check if similar endpoint exists in `src/api/`
2. Create schema in `src/schemas/` if new data types needed
3. Implement endpoint in appropriate router file
4. Add tests in `tests/api/`
5. Update API documentation
6. Run full test suite before committing

### Database Schema Changes

1. Describe the change and why it's needed
2. Create migration: `alembic revision --autogenerate -m "description"`
3. Review generated migration file
4. Test migration: `alembic upgrade head`
5. Test rollback: `alembic downgrade -1`
6. Update relevant models and schemas

Pattern 4: Context Swapping

For projects with distinct phases (development vs. deployment, frontend vs. backend), maintain multiple CLAUDE.md variants:

project/
├── CLAUDE.md                 # Active configuration
├── .claude/
│   ├── CLAUDE.development.md # Development focus
│   ├── CLAUDE.deployment.md  # Deployment focus
│   └── CLAUDE.debugging.md   # Debugging focus

Swap them as needed:

cp .claude/CLAUDE.deployment.md CLAUDE.md

This keeps Claude’s focus tight and task-specific.

Pattern 5: Conditional Instructions

Tell Claude to behave differently based on what it’s working on:

## Conditional Rules

When working in `src/api/`:
- All endpoints must have OpenAPI documentation
- Use dependency injection for database sessions
- Return appropriate HTTP status codes

When working in `tests/`:
- Use fixtures from `conftest.py`
- Mock external services, never call them
- Each test file mirrors the source file structure

When working in `scripts/`:
- Scripts must be idempotent (safe to run multiple times)
- Include --dry-run option for destructive operations
- Log all actions for debugging

Pattern 6: MCP Server Documentation

If you use MCP servers, document them in CLAUDE.md so Claude knows when and how to use them:

## MCP Integrations

### Slack MCP
- Posts to #dev-notifications channel only
- Use for deployment notifications and build failures
- Do not use for individual PR updates
- Rate limited to 10 messages per hour

### Database MCP
- Read-only access to production replica
- Use for data exploration, never for writes
- Prefer this over raw SQL when possible

This connects to our upcoming issue on the Claude Code MCP Masterclass.

CLAUDE.md + Hooks & Subagents

CLAUDE.md becomes more powerful when combined with other Claude Code features. Here’s a preview of how they work together.

CLAUDE.md + Hooks

Hooks are automated actions that run at specific points in Claude’s workflow. Your CLAUDE.md can reference and coordinate with them.

Instead of asking Claude to check formatting (slow, expensive), set up a hook:

## Standards

Code must pass linting before commit. 
A pre-commit hook runs `npm run lint` automatically.
Do not manually check formatting — the hook handles it.

The CLAUDE.md tells Claude the rule exists. The hook enforces it. Claude focuses on actual coding.

CLAUDE.md + Subagents

Subagents are isolated Claude instances that handle specific tasks. They have their own context window, preventing information from one task from polluting another.

Your CLAUDE.md helps subagents understand the project quickly without needing the full conversation history.

## Subagent Guidelines

When delegating tasks to subagents:
- Security reviews: Use fresh subagent, don't carry implementation context
- Code exploration: Subagent should read general_index.md first
- Documentation: Subagent can access docs/ freely

CLAUDE.md alone is powerful. Combined with hooks and subagents, it becomes a complete automation system:

• CLAUDE.md defines the rules

• Hooks enforce them automatically

• Subagents handle specialized tasks with a clean context

Claude.md Maintenance

CLAUDE.md isn’t a “set and forget” file.

Projects change, teams learn better patterns, and new tools enter your workflow. Here’s how to keep it current.

Maintenance Best Practices

1. Update with your PRs

Add CLAUDE.md to your PR checklist:

• [ ]Code changes complete

• [ ] Tests passing

• [ ] Documentation updated

• [ ] CLAUDE.md updated if workflows changed

2. Use the # shortcut continuously

When you discover something Claude keeps missing, add it immediately:

# Always run database migrations before starting the dev server

These small additions compound into a CLAUDE.md that reflects reality.

3. Review quarterly

Set a reminder to review your CLAUDE.md every few months:

• Are all commands still accurate?

• Have any workflows changed?

• Is anything outdated or redundant?

• Can anything be removed?

4. Version control it

Commit CLAUDE.md to git. Your team benefits from improvements, and you can track what changed when.

Final Thoughts

CLAUDE.md is the foundation of everything in Claude Code. When you get this right, every other feature (hooks, subagents, and MCP) works better.

Key takeaways:

• CLAUDE.md is a configuration file, not documentation

• Claude treats it as system-level rules, stricter than your prompts

• Less is more — if it exceeds 100-150 instructions, you're doing too much

• Use the hierarchy: global → project → nested

• Progressive disclosure is better than bloated files

• Iterate continuously with the # shortcut

Resources

PS: I am working on our main Claude Code Masterclass Git repo, where I will add all these code snippets and templates for quick and easy access.

For this issue, I have these resources that will be added to the repo soon:

• Claude.md Templates by Project Type

• Claude.md Common Mistakes

• All the Code Snippets Shared In This Newsletter

Next: Coming Up Issues

The next issues in this Masterclass Series will cover:

• Claude Code Hooks Masterclass — Automation that runs without asking

• Claude Code Subagents Masterclass — Building your AI team

• Claude Code MCP Masterclass — Extending Claude’s capabilities

Your CLAUDE.md is the foundation you need before moving to hooks, MCP servers, and subagents.

What’s your CLAUDE.md look like?

Reply to this email with your current setup. I’ll share interesting patterns in a future issue.

Claude Code Masterclass

Let’s Build It Together

— Joe Njenga

Subscribe now

You signed up because you wanted to master it.

Over 3,000 of you came from my Medium articles because I promised something deeper—advanced workflows, production systems, the stuff I couldn’t fit into a 10-minute read.

You’ve been waiting. Now I’m delivering.

This newsletter will keep you updated with practical tutorials and guides as new Claude Code features are released.

I’m also working on the course and a private community—more details on both in future issues.

Why a newsletter?

Medium limits me to 2 posts per day, and my feed mixes Claude Code with other AI topics.

Here, the focus is 100% Claude Code—deep dives, quick tutorials, and production-ready configurations.

If you’re a complete beginner, start with my Claude Code Cheat Sheet and my Medium tutorial collection, which covers features as they have developed over the past year.

Now, let’s look at where Claude Code stands today.

State of Claude Code: January 2026

When Claude Code launched in February 2025, it was a simple terminal tool. You could chat with Claude, edit files, and run bash commands.

Eleven months later, it’s an entirely different beast.

🟢 FOUNDATION ERA
   Feb 2025 → Launch: Terminal, Files, Bash
   Mar 2025 → CLAUDE.md & Project Context  
   Apr 2025 → MCP + Custom Commands

🟡 EXPANSION ERA
   May 2025 → Hooks & Automation
   Jun 2025 → Extended Thinking + Plan Mode
   Jul 2025 → Subagents & Delegation

🟠 MATURITY ERA
   Aug 2025 → Background Tasks + Parallel
   Sep-Dec 2025 → Skills, Sandbox, Checkpoints

🔴 NOW
   Jan 2026 → Production-Ready Platform

• Foundation Era (Feb-Apr 2025) — Claude Code could help you code. You talked, and it edited files. Useful, but limited.

• Expansion Era (May-Jul 2025) — Hooks meant automation. Extended thinking meant complex reasoning. Subagents meant building an AI team.

• Maturity Era (Aug-Dec 2025) — Background tasks, parallel execution, sandboxing, checkpointing. Production-ready.

• Current State (Jan 2026) — Full multi-agent orchestration, enterprise deployment, team collaboration. Not an assistant—a platform.

Where Are You on the Learning Curve?

Claude Code has a steeper learning curve than most tools because the features compound.

Hooks become 10x more powerful when combined with subagents. MCP servers unlock new possibilities for custom commands.

Here’s my honest assessment of the skill levels:

5 Stages of Claude Code Mastery

Self-Assessment: Where Do You Stand?

🟢 Level 1: Foundation (Most developers stop here)

• I can install and run Claude Code

• I know the basic slash commands (/help, /clear, /config)

• I can ask Claude to edit files and run commands
  

🟡 Level 2: Configuration (You’re getting serious)

• I have a CLAUDE.md file in my projects

• I’ve created custom slash commands

• I’ve configured permission modes
  

🟠 Level 3: Automation (You’re ahead of 90% of users)

• I have hooks running automatically

• I’ve connected at least one MCP server

• I use extended thinking for complex problems
  

🔴 Level 4: Orchestration (You’re in the top 5%)

• I’ve created custom subagents

• I coordinate multiple agents on complex tasks

• I use background tasks for parallel work
  

🟣 Level 5: Production (You’re teaching others)

• I’ve deployed Claude Code in CI/CD pipelines

• I manage team-wide configurations

• I’ve integrated with AWS Bedrock or Google Vertex

Most developers who’ve used Claude Code for months are still at Level 1 or 2. Not because they’re not smart—but because the docs and most tutorials don’t show how features combine.

This newsletter takes you from Level 2 to Level 5.

What is the Claude Code Masterclass Newsletter?

Your complete path to Claude Code mastery.

Whether you’re writing your first CLAUDE.md file or orchestrating multi-agent workflows, every issue gives you something you can implement that day.

What to expect:

• Foundational tips for newcomers

• Advanced systems for power users

• Complete configurations you can copy and use

• Tested workflows with the reasoning behind them

• New features covered as they’re released

I cover Claude Code on Medium, but here I go deeper and more practical—100% focused on helping you build real systems.

Claude Code Masterclass Ecosystem

This newsletter is part of something bigger.

I’m building a complete learning ecosystem around Claude Code—each piece designed to meet you where you are and take you further.

• The newsletter delivers weekly insights.

• Medium covers tutorials and new features.

• The course (coming soon) provides structured, hands-on training.

Everything connects. Start anywhere, and grow from there.

What I Need From You

Reply to this email and tell me:

1. Where are you on the skill assessment? (Levels 1-5)

2. What’s the single biggest thing you want to learn?

3. What’s frustrating you right now?

I read every reply. Your answers shape what I write next.

Welcome to Claude Code Masterclass

Let’s build it together

— Joe Njenga

Subscribe now