Start Here: Student Follow-Along Guide

This workbook is the student version of the one-day intensive. It removes instructor-only delivery notes and turns the course into a practical follow-along reference. Keep the GitHub repository open while you read, because the examples, anti-patterns, pre-work, and commands are part of the exercise flow.

How to use each module

1. Read the framing and vocabulary before the live block starts.
2. Open the linked example and anti-pattern artifacts from the repo.
3. Build the named artifact for that block.
4. Use the critique prompt: What would make this better as a downstream input?
5. Keep your final artifacts short enough for another operator to use without reopening the whole conversation.

Module 1 · Block 1 · 70 minutes

Build Claude Code Primitives

Claude Code becomes useful at team scale when engineers stop treating it as a single chat box and start treating it as a primitive build lab: a collection of tools, commands, skills, agents, subagents, plugins, execution modes, and model choices. This module teaches the primitive design judgment that keeps work small, explicit, and repeatable.

Why primitive design is the first skill

Most failed AI-assisted engineering sessions do not fail because the model is incapable. They fail because the work is routed to the wrong primitive. A developer asks for a broad implementation when the real need is investigation. A team writes a permanent rule into a one-off prompt. A repeated checklist stays trapped in someone’s memory instead of becoming an executable skill. A heavyweight model is used for cheap file discovery, while a complex design decision is handed to a fast model with insufficient reasoning depth.

The first day of a Claude Code operating model therefore begins with vocabulary. Not vocabulary for its own sake, but vocabulary that gives the team a shared way to decide where work should live. Once the team can say “this is a command,” “this is a skill,” “this belongs in memory,” “this should be a subagent,” “this is a hook,” or “this needs a headless run,” the tool stops being mysterious and starts becoming an engineering system.

The primitive build lab

Think of Claude Code as a workbench with several surfaces. The interactive session is where a human and model negotiate a task. Tools are the model’s hands: reading files, running commands, searching repositories, editing code, and interacting with configured integrations. Commands are named entry points that standardize common activities. Skills package reusable procedures. Agents and subagents isolate specialized work. Plugins and marketplace content extend what is available across projects or organizations. Headless execution turns the same operating model into automation.

The practical question is not “which feature is coolest?” The practical question is: where should this work be represented so that another engineer can reuse it without rediscovering it?

Interactive versus headless work

Interactive mode is for discovery, negotiation, and judgment. A human can interrupt, correct assumptions, ask for alternatives, and decide whether the model’s next step is safe. Headless mode — Claude Code’s non-interactive print mode, invoked with claude -p (--print) — is for work that has already been bounded. It needs clear inputs, allowed tools, expected outputs, and stop conditions. If the task still requires a human to decide what the task is, it is not ready for headless execution.

A good rule is this: interactive sessions produce artifacts; headless sessions consume artifacts. During a live session you might create an Implementation Plan, Explore findings, or Review. Once those artifacts are stable, a headless run can implement a bounded change, run a review, or generate a report from known inputs.

Goal mode and debate mode

Two conversational modes matter today. Goal mode is useful when you want the model to drive toward a defined outcome. Debate mode is useful when you want the model to challenge a plan before code is written. Goal mode helps with forward motion; debate mode helps with error prevention. Both are most useful when paired with artifacts.

For example, a developer might ask Claude to draft an Implementation Plan in goal mode. Once the brief exists, the developer can switch into a debate posture: “Challenge this brief. Identify hidden assumptions, underspecified acceptance criteria, and likely regression risks.” The output of the debate should not be a wandering conversation. It should be a better brief.

Model selection for the job

Model selection is part of work primitive design. Cheap, fast models are appropriate for bounded lookup, file discovery, and summarizing known material. Balanced models are appropriate for routine implementation and review. The strongest reasoning models are appropriate for architecture, tricky debugging, multi-file refactors, and decisions where a bad plan is more expensive than slower planning.

Building the Claude Code primitive kit

The primitive kit is the first durable artifact of the day. It is the set of primitives you have actually crafted — a tool posture, a command, a skill, a subagent, and a plugin decision — each written down with explicit boundaries. Give every primitive a compact spec so another engineer can pick it up without guessing: what it does, which mode and model it runs in, what it needs as input, what it produces, and when it should stop. Keep the kit small enough to live in a repo, onboarding guide, or team operating doc, and concrete enough to describe the actual next version of the team’s workflow rather than an aspiration.

Below is a real, working code-review plugin that bundles every primitive in one place. Use the dropdown to walk through each: the plugin manifest that ties them together, a command, a skill, a subagent, a hook, and a bundled tool (a CLI script). Edit any of them — the box turns green when the format is valid.

It is one connected plugin, not six unrelated files: the /review-pr command runs the pr-review skill and delegates to the pr-reviewer subagent, which runs the check-diff tool and the github MCP server. That is how primitives stitch into a workflow. The layout mirrors a real plugin — closedloop-ai/claude-plugins/plugins/code.

A note on tools: you rarely “define” a tool. Claude already uses its built-in tools and any CLI binary on your PATH — run via Bash under your permission rules — so it is usually smart enough to just use them. The two ways to extend the set are to ship a helper script in the plugin (like check-diff.sh) or to add an MCP server, which exposes entirely new tools.

Task: Review a PR for auth regressions
Primitive: security-reviewer agent + /code-review command
Mode: interactive for local development; headless only after the rule set is stable
Model: balanced model for normal review, stronger reasoning for high-risk auth changes
Inputs: diff, Implementation Plan, REVIEW.md, relevant auth rules
Output: findings-first review with severity, evidence, and recommended fix
Stop condition: no important findings or explicit residual risk accepted by human

What good looks like

A good primitive kit has three qualities. First, it is specific. “Use Claude for coding” is not useful; “use an explorer subagent to identify files before reading them into the main session” is useful. Second, it is bounded. Each entry says what the primitive should and should not do. Third, it is teachable. A new engineer should be able to read the kit and make the same primitive design decision as a senior engineer most of the time.

Anti-patterns

• The mega-prompt: A long prompt that mixes stable policy, one-time instructions, codebase facts, and a workflow checklist. Split it into memory, project instructions, skill, and task prompt.
• The everything-agent: A custom agent named “senior engineer” that can do anything. Specialized agents should have a narrow lens, clear tools, and a predictable output shape.
• Premature plugin packaging: A workflow is packaged before the team has run it enough times to know its inputs, failure modes, and stop conditions.
• Headless ambiguity: A non-interactive run is launched with vague goals and no acceptance criteria. Headless work should consume a brief, not invent one.

From primitives to workflows

Crafting primitives is only half of Module 1. The other half is noticing that primitives are meant to be stitched together. A real task rarely uses one primitive in isolation: an explorer subagent finds the files, a command kicks off the change, a review agent checks the diff, a skill packages the verification. The sequence that connects them is a workflow — and Module 5 is where you design one deliberately.

That immediately raises the question this course spends the rest of the day answering: once you can stitch primitives into a workflow, how do you tell that workflow what to accomplish? A workflow with no clear goal, no boundaries, and no definition of done will wander no matter how good its primitives are. That is exactly the problem Module 2 picks up.

Module recap

The foundation of effective Claude Code use is not prompt cleverness. It is primitive design discipline. Teams that craft the right primitives — and know how those primitives stitch into workflows — can preserve knowledge, reduce repeated prompting, avoid context-window waste, and turn successful sessions into reusable operating assets.

Module 2 · Block 2 · 55 minutes

Planning and Context Management

Module 1 ended on a question: once you can stitch primitives into a workflow, how do you tell it what to accomplish? Planning is the answer. In Claude Code, planning is not a ceremonial step before coding — it is the act of shaping context so the next operator (human, model, agent, or headless workflow) can act without reopening the entire problem.

The plan is a compression artifact

Claude Code sessions can accumulate enormous context: pasted requirements, file contents, terminal output, attempted fixes, test failures, screenshots, and corrections from the human. Without deliberate compression, the session becomes expensive and fragile. The model is forced to infer what still matters from a long transcript. Humans are forced to remember why earlier decisions were made. Downstream operators inherit noise instead of a plan.

A useful plan is not a transcript. It is a lossily compressed representation of the work. It preserves the facts, decisions, constraints, risks, and next actions that matter. It discards the conversational path that produced them. That is why this session treats planning as context management.

Separate facts, assumptions, and open questions

The simplest improvement to most AI coding sessions is to stop blending known facts with guesses. Models are very good at continuing a confident narrative. If the prompt says “the auth middleware probably owns refresh-token invalidation,” the model may proceed as if that is true. A disciplined brief separates evidence from inference.

The Implementation Plan

The Implementation Plan is the central planning artifact. It should fit on one or two pages, but it should be complete enough for another operator to execute. The brief is not just a summary. It is an instruction-bearing artifact with a clear contract: here is the problem, here is the known context, here are the boundaries, here is the proposed path, and here is how we will know whether the work is done.

# Implementation Plan

## Goal
Implement refresh token rotation without changing the existing login response contract.

## Known facts
- JWT validation happens in src/auth/middleware.ts.
- Session persistence is implemented in src/auth/session-store.ts.
- Existing tests cover login success and expired access tokens.

## Assumptions to verify
- Old refresh tokens are not currently invalidated after rotation.
- Token reuse should be treated as suspicious but not immediately lock the account.

## Open questions
- Should reuse detection emit an audit event?
- Is token family tracking already present in the database schema?

## Context map
- Auth middleware: request validation and session lookup
- Session store: token persistence and expiration
- Test suite: integration tests under tests/auth/

## Work packages
1. Verify current token rotation behavior.
2. Add invalidation logic or token-family tracking.
3. Extend integration tests for old-token reuse.
4. Produce Review.

## Acceptance criteria
- New refresh token is issued on rotation.
- Previous refresh token cannot be reused.
- Existing login response shape is unchanged.
- Tests demonstrate success, expiration, and reuse behavior.

Context maps

A context map tells the model where to look and why. It is not a full dump of file contents. It is a pointer layer: directories, files, functions, commands, external systems, and documents that are likely relevant. Good context maps reduce token use because Claude can read the right files in the right order instead of scanning the repository blindly.

A context map should include both primary and secondary context. Primary context is required to make the change. Secondary context helps review risk, verify behavior, or understand why the system is shaped the way it is.

## Context map
Primary:
- src/auth/middleware.ts — request authentication boundary
- src/auth/session-store.ts — refresh token persistence
- db/schema.sql — session and token tables
- tests/auth/refresh-token.test.ts — integration behavior

Secondary:
- docs/security/auth-model.md — intended auth posture
- .claude/rules/api-security.md — project-specific security rules
- recent PRs touching auth middleware — intent and regression context

Debate review before coding

Before code is written, ask Claude to attack the plan. The goal is not to win the debate; the goal is to improve the artifact. A debate review should look for ambiguous goals, missing constraints, unsupported assumptions, hidden coupling, risky files, weak acceptance criteria, and likely regression paths.

Review this Implementation Plan as a skeptical senior engineer. Identify unsupported assumptions, missing context, and acceptance criteria that would fail to catch a regression. Do not implement. Return a revised brief outline and a list of questions that must be answered before coding.

The output of debate review should be folded back into the brief. If the debate produces useful insights that remain trapped in conversation history, the next operator still cannot use them. Artifact-first planning means the artifact is the durable memory.

What makes a plan reusable downstream?

A reusable plan has clear boundaries. It names the exact goal, the non-goals, the files likely involved, the evidence already gathered, the assumptions still open, and the stop condition. It also includes enough review criteria to prevent the model from declaring success too early.

Goal

What outcome should exist after the work is complete?

Non-goals

What tempting adjacent work should not be done?

Facts

What has been directly observed?

Assumptions

What might be true, but needs verification?

Context map

Where should the next operator look first?

Work packages

What are the smallest implementation units?

Acceptance criteria

What evidence will prove the work is complete?

Review focus

What risks should review emphasize?

Module recap

Planning in Claude Code is not about slowing down. It is about preserving momentum by producing a compact artifact that can survive compaction, handoff, review, and automation. The better the brief, the less the model has to infer and the easier it is for humans to hold the work accountable.

Module 3 · Block 3 · 60 minutes

Intent Recovery and Dynamic Evidence

A plan tells the model what to do; this module makes sure the plan is built on why the code looks the way it does. When a codebase is old enough, the current code is rarely the whole story. You will recover intent from Git history, issues, PRs, logs, tests, command traces, and screenshots before asking Claude to change behavior.

Find the why before the what

Claude can usually explain what code does from the current files. The harder question is why it does that. Was a strange branch added for a customer-specific edge case? Did a test encode a production incident? Was a confusing abstraction introduced to support a migration that has since finished? Current code often hides the reason for its own shape.

Intent recovery is the discipline of gathering enough historical and runtime evidence to avoid undoing deliberate behavior. It is especially important when the requested change appears simple. Simple changes are dangerous when they cut across hidden intent.

Static code is not enough

Reading the current file gives one kind of evidence. Git history gives another. Tests reveal expected behavior. Issues and PRs reveal tradeoffs. Logs reveal runtime reality. Screenshots reveal UI states that code alone may not make obvious. CLI traces reveal exact failure modes. Documentation and MCP-backed systems can provide external context that is not stored in the repository.

Evidence versus inference

A strong Explore findings labels evidence. It does not say “the bug is caused by stale cache” unless there is direct evidence. It says “the failure appears after the cache read path; logs show cache hit with outdated value; no write-through event appears in the trace; inference: stale cache is likely.” This distinction matters because the next model turn will use the memo as context. If guesses are written like facts, the model will build on them.

# Explore Findings
# Builds on the Module 2 Implementation Plan: "refresh token rotation".

## Question
Why is an old refresh token still accepted after rotation issues a new one?

## Evidence gathered
- Reproduces: pnpm test tests/auth/refresh-token.test.ts — old-token reuse returns 200, expected 401.
- Server logs show the session store resolves the previous token after rotation.
- Git history shows rotation added in PR #184 with no invalidation step.
- src/auth/middleware.ts validates tokens but never deletes the prior record.

## Inferences
- Rotation issues a new token but does not invalidate the previous one.
- Invalidation likely belongs in the session store, not the middleware.

## Open questions
- Where should the previous token be invalidated — session store or middleware?
- Should reuse of an old token emit an audit event?

## Recommended next step
Trace refresh-token writes and invalidation in src/auth/session-store.ts before changing code.

Dynamic evidence sources

Dynamic evidence is information that changes with execution: logs, test runs, database state, browser behavior, CLI output, screenshots, observability traces, and external tool responses. It is powerful because it grounds the model in reality. It is also noisy. A good operator does not paste raw dynamic output indiscriminately. They capture the relevant excerpt, label how it was produced, and explain why it matters.

When collecting dynamic evidence, include command provenance. The model should know not only the output, but the command, environment, timestamp or branch, and whether the result was reproducible.

Command: pnpm test tests/auth/refresh-token.test.ts --runInBand
Branch: refresh-token-rotation
Result: failed, 1 test
Relevant output:
  expected old refresh token reuse to return 401
  received 200
Interpretation:
  Existing implementation issues a new refresh token but does not invalidate the previous token.

Why “that didn’t work” fails as feedback

The phrase “that didn’t work” is almost useless to the model. It omits what was attempted, what was expected, what actually happened, what evidence was observed, and what changed between attempts. Good feedback is a bundle: action, expectation, observation, evidence, hypothesis, and next constraint.

The Request Changes pattern

A Request Changes is a structured correction that improves the next model turn. It should be short, but it must contain enough evidence for the model to update its plan. Use it whenever Claude’s first implementation fails, when a test result contradicts an assumption, or when a human reviewer spots a gap.

# Request Changes

## Attempted change
Added token rotation logic in src/auth/middleware.ts.

## Expected result
Old refresh token reuse should return 401.

## Actual result
Old refresh token reuse returns 200.

## Evidence
Test: pnpm test tests/auth/refresh-token.test.ts
Failure: expected 401, received 200
Trace: old token still resolves in session-store lookup.

## Updated hypothesis
Middleware is not the right layer for invalidation. The session store accepts both token records.

## Next instruction
Inspect session-store token persistence and invalidation. Do not change response shape.

Module recap

Intent recovery prevents well-intentioned regressions. Dynamic evidence prevents hallucinated debugging. Request Changess convert failure into useful context. Together, they turn Claude Code from a code generator into an evidence-driven collaborator.

Module 4 · Block 4 · 60 minutes

Review, Test, and Verify

The work is not done when code changes. It is done when the diff has been reviewed against the plan, the verification evidence is explicit, and the residual risk is clear enough for a human to accept or reject.

Review the diff against the plan

A Claude-assisted review should not ask “does this code look good?” That question is too broad and too subjective. The stronger question is: “does this diff satisfy the Implementation Plan without violating constraints or introducing unacceptable risk?” The brief becomes the review contract.

Findings-first review means the reviewer leads with issues, not narrative. Each finding should state severity, evidence, affected file or behavior, why it matters, and a recommended fix. If there are no blocking findings, the review should still describe what was checked and what residual risk remains.

# Review Finding

Severity: Important
Area: Refresh token invalidation
Evidence: tests/auth/refresh-token.test.ts covers successful rotation but not reuse of the old token.
Why it matters: The acceptance criteria require old refresh tokens to be rejected.
Recommended fix: Add a regression test that attempts reuse of the previous token after rotation and expects 401.

Scope drift

Scope drift is any change that is not required by the brief. Some drift is harmless cleanup. Some drift is dangerous because it changes behavior the team did not intend to change. Claude can drift when it sees adjacent improvements, especially if the prompt rewards broad helpfulness. Review must therefore compare the diff against explicit goals and non-goals.

Testing is one gate, not the only gate

Passing tests are necessary evidence, but they are not proof of correctness. Tests only cover what they assert. A Review should include test results, manual checks when relevant, static review, diff review, command outputs, and residual risk. The point is not to create paperwork. The point is to prevent the phrase “tests pass” from hiding an unreviewed assumption.

For LLM-assisted work, verification should also include provenance: what files changed, what commands were run, what evidence was observed, and what the model did not check. This gives the human reviewer a clear map of confidence and uncertainty.

The Review

# Review

## Plan alignment
Goal: Refresh token rotation rejects old token reuse.
Status: Implemented and tested.

## Changed files
- src/auth/session-store.ts — invalidates previous refresh token on rotation
- tests/auth/refresh-token.test.ts — adds old-token reuse regression test

## Evidence
- pnpm test tests/auth/refresh-token.test.ts — passed
- pnpm test tests/auth/login.test.ts — passed
- Manual API check: old refresh token returns 401 after rotation

## Scope review
No public response contract changes observed.
No unrelated auth routes modified.

## Residual risk
Database cleanup of invalidated token records is not addressed. Existing retention behavior remains unchanged.

## PR handoff note
Reviewer should focus on token-store concurrency and whether invalidated token retention meets audit expectations.

Regression risk

Regression risk is not just the probability that something breaks. It is the product of likelihood, blast radius, and detectability. A small likelihood with a huge blast radius still deserves attention. A likely bug with easy rollback may be acceptable if the release path is safe. Claude can help enumerate risks, but the team must decide what risk is acceptable.

What makes a handoff PR-ready?

A PR-ready handoff gives the reviewer the shortest path to an informed decision. It should contain the problem statement, brief link or summary, changed files, review focus, verification evidence, known non-goals, and residual risk. The reviewer should not need to reconstruct the story from chat history.

Module recap

Review and verification discipline turns model output into engineering evidence. The goal is not to make Claude “sound confident.” The goal is to make the work auditable: what changed, why it changed, how it was checked, and what remains uncertain.

Module 5 · Block 5 · 45 minutes

Workflow Design and Minimal Improvement Loop

Module 1 introduced workflows as the way to stitch primitives together; this is where you design one deliberately. The session closes by turning the day’s isolated practices into a single named workflow — with handoffs, gates, stop conditions, and one lightweight Workflow retro — so the next run can improve without expanding into a full operating-system redesign.

From good sessions to repeatable workflows

A strong Claude Code session can still be a dead end if the team cannot repeat it. Workflow design captures the sequence that made the session successful: how the work was framed, what artifacts were produced, which agents or skills were used, where human review occurred, and what evidence counted as done. The workflow does not need to be elaborate. It needs to be named, bounded, and reusable. A named workflow is an asset: you run it again next week, apply it to the next project, and hand it to a new teammate without re-teaching the whole system. That is leverage that compounds.

This module is intentionally compact. The goal is not to design a full engineering operating system — it is to leave with one workflow you can try next week and improve after one run.

A compact multi-agent workflow

Multi-agent workflow design should begin with work boundaries, not agent names. Each agent or subagent should own a distinct lens or phase. If two agents need the same broad context and produce overlapping output, the workflow is probably not decomposed well.

# Workflow

Name: Evidence-first bug fix

Trigger:
A bug report has enough detail to reproduce or investigate.

Artifacts:
1. Explore findings
2. Compact Implementation Plan
3. Implementation diff
4. Review

Roles:
- Explorer subagent: identify relevant files, history, and evidence sources
- Planner: compress evidence into Implementation Plan
- Implementer: make bounded code changes from the brief
- Reviewer: compare diff against brief and produce findings

Gates:
- Do not implement until facts, assumptions, and open questions are separated.
- Do not review until acceptance criteria are explicit.
- Do not hand off until verification evidence and residual risk are written.

Stop condition:
The change is PR-ready or blocked by a named open question.

Handoffs

A handoff is where one operator’s output becomes another operator’s input. In Claude Code workflows, handoffs should be artifact-based. The explorer hands off an Explore findings. The planner hands off an Implementation Plan. The implementer hands off a diff plus notes. The reviewer hands off findings and verification evidence. If a handoff requires the next operator to read the entire chat transcript, the handoff failed.

Gates and stop conditions

Gates prevent premature motion. Stop conditions prevent infinite motion. A gate says what must be true before the workflow can advance. A stop condition says when the workflow is complete, blocked, or unsafe to continue. Claude workflows need both because models tend to continue helping unless told what “done” means.

Good gates are observable. “Make sure the plan is good” is not a gate. “The brief includes goal, non-goals, facts, assumptions, open questions, context map, work packages, and acceptance criteria” is a gate. Good stop conditions are explicit. “Continue until fixed” is vague. “Stop when the Review shows the acceptance criteria pass, or when an open question blocks safe implementation” is actionable.

One lightweight Workflow retro

The improvement loop should be small enough that the team actually uses it. Pick one Workflow retro that can be completed after a workflow run in five minutes. The Workflow retro should measure the workflow, not the model’s personality. It should ask whether artifacts were reusable, whether evidence was sufficient, whether context was controlled, whether review caught issues, and what should change next run.

# Workflow Retro

Workflow name:
Date:
Task:

1. Was the Implementation Plan usable without reopening the original conversation? 0 / 1 / 2
2. Did the Explore findings separate evidence from inference? 0 / 1 / 2
3. Did the implementation stay inside the stated scope? 0 / 1 / 2
4. Did verification include more than passing tests? 0 / 1 / 2
5. Was residual risk explicit? 0 / 1 / 2

One thing to keep:
One thing to change next run:
One artifact or rule to update:

What to improve on the next run

Do not try to improve everything after the first run. Choose one improvement. Maybe the context map was too vague. Maybe the review agent needs a narrower rubric. Maybe the Implementation Plan omitted non-goals. Maybe verification evidence was too thin. The Workflow retro turns that observation into a small change: update a template, add a rule, refine a skill, or adjust a gate.

Closing synthesis

The five modules form one loop. Craft the right primitives. Compress the plan. Recover intent with evidence. Review against the plan. Preserve the workflow that worked. That loop is small enough to teach in a day and strong enough to become the foundation for team-scale Claude Code adoption. The payoff is not abstract: less rework, faster shipping, and a library of reusable assets that make every future run cheaper and more reliable.

Appendix: Student Desk Reference and Repo Links

Core commands and settings

Context pointers

• Search before reading: use grep/file search to find paths and line numbers first.
• Read narrowly: use offsets and limits instead of loading entire files.
• Label evidence: command run, source, timestamp, relevant excerpt, and why it matters.
• Separate facts, assumptions, open questions, and inferences.
• Compact between tasks and tell compaction what to preserve.

Primary repo links

• Training repository root
• One-day intensive presentation guide
• One-day live agenda
• Demo artifacts and anti-patterns
• Plugins, skills, commands, and models
• Claude Code changelog

Concrete Examples, File Locations, and Repo Links

Tools and permissions

Tools are the model action surface: reading, searching, editing, running commands, fetching context, and calling integrations. The course examples emphasize matching tool access to task risk rather than allowing everything by default.

Permission prompt pattern:
What must Claude read?
What may Claude write?
What requires approval?
What would be dangerous if Claude guessed?
What evidence is required before widening permissions?

Commands

Commands are for short, prompt-shaped, directly invoked operations. Use them when the behavior repeats but does not need a full method, bundled assets, or a specialist role.

# .claude/commands/summarize-failing-test.md
Summarize the failing test evidence in this shape:
1. Command run
2. First failing assertion or error line
3. Relevant file and line pointer
4. Likely failure category
5. Next narrow read or command

Do not propose a fix until the failure category is grounded in evidence.

Skills

Skills are for repeatable methods with structure: required inputs, context gathering, workflow, output artifact, verification checklist, and safety rules.

# .claude/skills/flaky-test-investigation/SKILL.md
# Skill: flaky-test-investigation

## Purpose
Investigate a flaky test using evidence before proposing a fix.

## Required inputs
- failing command
- test name or file
- relevant CI/local output

## Workflow
1. Capture exact command and failure excerpt
2. Classify the failure mode
3. Identify dynamic evidence needed
4. Produce an Explore findings
5. Propose the next narrow action

## Outputs
A short Explore findings with evidence, inference, and next step.

Agents and subagents

Agents and subagents are bounded workers with a mission, explicit tools, output shape, and stop condition. Use them when you need separate context or specialist review.

# .claude/agents/security-reviewer.md
---
name: security-reviewer
description: Review code changes for security vulnerabilities. Use proactively.
tools: Read, Grep, Glob, Bash
model: sonnet
maxTurns: 10
---

You are a security specialist. For every code change:
1. Check for injection vulnerabilities
2. Verify input validation at system boundaries
3. Check for exposed secrets or API keys
4. Verify authentication and authorization checks

Report findings by severity. Do not edit files unless explicitly asked.

Plugins and marketplace evaluation

Plugins are a distribution abstraction. A plugin can package multiple reusable units such as commands, subagents, MCP servers, hooks, skills, or workflow assets. Evaluate a plugin like dependency surface area, not like a shortcut.

Demo artifacts and anti-patterns

Setup and supporting files

• Lab 00 setup
• One-day prework checklist
• One-day live agenda
• One-day intensive presentation guide
• Demo artifacts directory
• Latest Claude Code changelog

Token Efficiency Throughout the Course

Token efficiency is not a separate optimization topic. It is the connective tissue across primitive design, planning, investigation, review, and workflow design — and it is money: tokens are cost and context is speed, so disciplined context means lower cost-to-serve and more work shipped per hour. The habits below should show up in every exercise.

Module-by-module token habits

Token-efficient prompt patterns

Search first. Return only matching file paths and line numbers. Do not read full files yet.

Read only <file> lines <start>-<end>. Summarize the relevance in 3 bullets.

Delegate to a subagent. Return only: finding, evidence pointer, confidence, next action. Limit to 10 bullets.

/compact focusing on decisions made, evidence pointers, files touched, unresolved questions, and residual risk.

Review this diff against the compact plan. Return findings only with severity, file pointer, and suggested next action.

Alignment With the 15-Minute Modules

Three ideas worth carrying through the whole day

Coverage checklist

Concrete examples to keep open

• Primitive framework: plugins, skills, commands, agents, and model selection
• Tool and permissions examples
• Skill template
• Primitive framework and examples
• Explore findings example
• Review example
• Workflow Workflow retro example

Token Savings Field Guide

Token savings are not about making Claude think less. They are about keeping the context window focused on the material that changes the outcome. The tips below should show up during every module, not only during the token-efficiency portion of the day.

1. Enable RTK for noisy command output

RTK is useful when shell output is large, repetitive, or noisy. The impact compounds because command output does not just cost tokens once; it remains in the session and can be re-read on later turns.

rtk gain              # cumulative token savings this session
rtk gain --history    # per-command breakdown with savings
rtk discover          # find missed compression opportunities

Good RTK targets:
- test output
- build logs
- git status and diff noise
- package manager output
- long formatter or type-checker traces

2. Move repeated tasks to executable scripts

Repeated prompts are expensive because they require the user to re-describe a workflow and require Claude to re-infer what should happen. A stable script is cheaper and more reliable.

# Example: scripts/check-pr-ready.sh
#!/usr/bin/env bash
set -euo pipefail
npm run lint
npm run typecheck
npm test
git status --short

# Prompt Claude:
# Run scripts/check-pr-ready.sh and summarize only failures,
# evidence pointers, and the next command to run.

3. Do not say “explore” without intention

Broad words such as “explore,” “look around,” “understand this,” or “check the repo” often cause broad reads. That may be appropriate for onboarding, but it should be intentional.

4. Use permission posture as a productivity lever, not a safety shortcut

Permissions shape token efficiency because unnecessary approval prompts interrupt loops, but broad permissions can create risk. Start with read-heavy, write-light permissions, then widen only when the task and verification path are clear.

{
  "permissions": {
    "defaultMode": "bypassPermissions"
  }
}

5. Enable and curate memory

Memory saves tokens when it prevents repeated corrections. It wastes tokens when it becomes stale, vague, or bloated.

• Use /memory to inspect what Claude has learned.
• Put durable project conventions in CLAUDE.md, not in chat history.
• Use path-scoped rules for standards that only apply to certain files.
• Use @ imports for shared docs instead of repeated pasted text.
• Prune stale assumptions and overly broad memories.

6. Share context and investigation across tasks

The cheapest context is the context already summarized well. Do not make the next task rediscover what the last task proved.

7. Bound subagent output

Subagents are powerful because they can absorb noisy exploration without polluting the main context. That benefit disappears if the subagent returns a transcript-sized report.

Delegate this investigation to a subagent.

Scope: auth middleware and token refresh only.
Tools: Read, Grep, Glob, Bash for git history.
Do not edit files.

Return exactly:
1. Findings, max 8 bullets
2. Evidence pointers: file:line or commit SHA
3. Confidence: high/medium/low
4. Recommended next action

8. Prompt with a token budget

Return paths only. Do not read files yet.

Read 40 lines around the match, not the whole file.

Summarize logs into failures, evidence, and next command.

Cap the answer at 10 bullets unless a blocking risk requires more.

/compact focusing on decisions made, evidence pointers, files touched,
unresolved questions, and residual risk.

9. End-of-task token checklist