OCDevel Claude Code

Building a Claude Code skill that turns bug reports into a four-part reproduction note before any code changes, including how skills differ from CLAUDE.md and hooks and how to test and fix a skill's description. Also covered: early October Claude Code updates to hooks, debug logging and Sonnet 5.5 cache pricing.

This episode is narrated by AI-generated synthetic voices.

Episode page & show notes

Visit website

Skills, CLAUDE.md and hooks

The routine for reproducing a bug is a method, and it only matters for certain tasks. CLAUDE.md is read in full every session, so it suits standing rules. A hook is a command Claude Code runs at a set moment whether or not the model remembers. A skill is a method written down once. At startup only its name and short description are read. The model loads the full body with the Skill tool when a request matches. The rule of thumb: a procedure belongs in a skill, and anything a machine must enforce belongs in a hook.

Building reproduce-bug

A project skill is a folder under .claude/skills/ containing a SKILL.md with frontmatter. The frontmatter needs a name and a description, and the description is the only part the model sees when it decides whether to load the skill (Claude Code skills docs). This skill's description does three things: it names the result, lists the words real bug reports use, and excludes feature requests, refactoring and styling. disable-model-invocation stays off because the skill has no side effects. The body sets out five steps. The agent restates the report as exact steps, records the data, reproduces the bug twice from a clean state, and traces the code read-only. Then it stops with a four-part note: steps, data, observed result and expected result. The body stays well under the guidance of roughly five hundred lines (skill authoring best practices).

Testing and fixing the description

To test, restart the session and check /skills. Then run a positive test with an emoji bug report, which should load the skill, and a negative test with a sort-button feature request, which should not. A vague description like "Helps with problems in the app" loads the skill on feature work. A narrow one like "Use for reproduction notes" never loads it. Both are fixed by rewording the description, not the body.

The disappearing item

On the made-up report "Sometimes when I add things fast, one of them disappears," the trace points at a second submit while the first save is still in progress. In the illustrative manual check, the item vanished both times and came back on reload: it was saved, and the screen dropped it. The fix is left for a separate task. The skill gets committed, and CLAUDE.md gains one line pointing to it. Bringing in real issues and logs is left to MCP.

Early October Claude Code updates

According to the Claude Code changelog, versions 2.1.289–2.1.296 shipped these changes:

Moving the type check from something you remember to run into a PostToolUse hook that Claude Code runs after every edit, feeding errors back so the agent fixes them before finishing. Also covers this fortnight's Claude Code changes to hook failure handling, sandbox fixes and headless time limits.

This episode is narrated by AI-generated synthetic voices.

Episode page & show notes

Visit website

Turning the type check into a hook

The routine still relied on memory for two steps: running the type check and running the tests. An example shows the gap. A request to add an optional note field to list items looks fine in the browser. Then the compiler fails on a shared-view component the agent never opened, because the note was marked required by mistake. CLAUDE.md is an instruction the model can skip. A hook is a command Claude Code itself runs at a defined moment, every time.

The chapter wires the project's no-emit TypeScript check to the PostToolUse event with an Edit|Write matcher, as described in the hooks guide. It lives in the committed project settings file so everyone working in the repository gets it. Exit codes carry the meaning, per the hooks reference:

The build starts small: a hook that only logs "hook fired." It is confirmed with /hooks, and a file read is shown not to trigger it. The logger is then replaced with a committed script. The script reads the event JSON with jq, skips non-TypeScript files, and checks the whole project, because the note bug lived in an untouched file. It runs through CLAUDE_PROJECT_DIR with a 120-second timeout. The test suite stays out of the hook because it is too slow to run after every edit.

The hook is proven by breaking types on purpose, then by making a correct edit that should produce no output.

Where hooks go wrong

Four risks are covered:

disableAllHooks turns off custom hooks but not hooks from an organization's managed settings. The work ends with a commit and one line in CLAUDE.md explaining where the type errors come from.

This fortnight's releases

The Claude Code changelog covers versions 2.1.286 through 2.1.288:

How to carry a multi-step change across several Claude Code sessions by keeping its plan, decisions and progress in committed files. It covers continue and resume, reading /context, compaction and what it loses, and a deliberate fresh start, plus recent fixes to resuming and compaction.

This episode is narrated by AI-generated synthetic voices.

Episode page & show notes

Visit website

A change that outlasts one sitting

The conversation with Claude Code is not memory you can rely on. The repository is. The worked example is a done checkbox for items in the shared-list app. It needs a schema migration, a way to set the flag through the database client, a checkbox and crossed-out style in the React interface, and tests. The check at the end is to tick an item, reload the page, and see it still ticked. Planning happens in plan mode. The plan goes into a committed file of numbered steps, each with a check that proves it is done. A second file records decisions and rejected options, such as choosing a boolean column over a status text field because the app has only two states and a boolean cannot hold a typo.

Stopping halfway and coming back

After two committed steps the session ends. claude --continue reopens the most recent session. claude --resume opens a picker with preview, rename and filter, all described in the guide to managing sessions. Resuming restores the conversation, tool results, model and recent checkpoints. It does not restore launch-time folders or elevated permission modes. It also brings back stale guesses and knows nothing of hand edits made since.

When the context window fills

/context breaks usage into messages, memory files, tool schemas and skills, and the messages row is the one that grows. Compaction replaces older turns with a summary. The root CLAUDE.md is reread and the active goal survives, but exact names and the reasons behind decisions tend to get lost. You can steer the summary with instructions after /compact or with a compact instructions section in CLAUDE.md. A summary is still written by the model. When it and the committed decisions file disagree, the file wins.

A deliberate fresh start

The handoff has four steps:

The new session reads the task files, git log and the diff, then reports the state of the work before editing anything. If its account is wrong, the gap is in the files. Keep plans to steps and checks. Rules for every task go in CLAUDE.md, and notes for one task go in the task files. Auto-memory stays on your machine and is not committed, so it cannot replace the task files.

Recent fixes to resume and compaction

The Claude Code changelog records several relevant changes:

Claude Opus 5.5 defaults to a one-million-token window, so auto-compaction triggers later, which makes the handoff habit more important.

A vague pasted-text bug report gets turned into a reproduction, then traced with an agent that is blocked from editing anything, then fixed one narrow diff at a time. Includes how plan mode actually enforces its limits, how to check an agent's account of your code, and the case where the tests pass but the browser is still broken.

This episode is narrated by AI-generated synthetic voices.

Episode page & show notes

Visit website

A vague report becomes a reproduction

"It keeps saying the name is too long when it isn't. Only happens when I copy the name in from somewhere else." No file, no error text, no browser. The work starts by turning that sentence into four written things: exact steps, exact data, observed result, expected result. The data is the clue — a line copied from a notes app, nine visible characters, carrying a trailing space and a newline. Reproduced twice from a clean state, so there is a before to measure against.

Trace first, edit later

The code that enforces the length rule has never been opened. Instead of asking for a fix, the request is a trace that forbids edits — done in plan mode, where file editing and writing tools are mechanically blocked rather than merely discouraged. Ways in: the permission-mode flag at launch, Shift+Tab to cycle modes, the slash-plan command, or a default mode set in settings. The caveat: plan mode gates edits, not process execution. Read-only shell commands run unprompted from a built-in allowlist you cannot edit; anything else goes to a safety classifier unless you turn off auto mode during plan. Launching with dangerously-skip-permissions overrides the gate entirely. Tool-level alternatives: allowed-tools or disallowed-tools flags, or edit and write in the deny list.

The trace may be delegated to the built-in read-only Explore subagent, which keeps file contents in its own context and returns a summary. Two consequences: intermediate work vanishes from the transcript, and the built-in Explore and Plan subagents skip the project instructions file to save tokens — so your constraints must be restated in the prompt.

Ninety seconds of checking

The account names a form component, a route handler, and a validation function comparing raw length before trimming. That is a claim until the files are opened. A confident specific you cannot find means stopping and re-asking, not waving it through — the details arrived as one story, not independently.

Green tests, broken browser

A failing test comes before the fix, read to confirm it fails for the right reason. Three lines change. The suite passes. The browser still fails, because the form component counts characters too. Why a wide diff was wrong the first time and justified the second. Then a branch, one commit, and a message naming the behavior. Three things that went wrong, each with a one-line detection method.

Recent changes worth knowing

A persistent side-by-side diff pane from slash-diff; grep and glob now returning explicit errors instead of silent "no matches" on large result sets; slash-ultrareview handling a clean tree; Control+Enter to interrupt tool work and submit at once; and AGENTS.md as a fallback when no CLAUDE.md is present.

This chapter explains how to write and test a CLAUDE.md file so a fresh Claude Code session knows a project's commands, layout, and definition of done without being told each time, and covers a recent change to which parts of a session actually read that file.

This episode is narrated by AI-generated synthetic voices.

Episode page & show notes

Visit website

The founding charter

The core of this chapter is CLAUDE.md, the file Claude Code loads automatically at the start of every session before your first request arrives — no attaching, no pasting, just a file sitting at the project root or inside the .claude directory that gets read on its own. It walks through the four places instructions can live — the shared project file, a personal file in your home directory, an untracked local variant, and organization-wide settings — and explains that Claude Code doesn't let the narrowest file override the others; it concatenates all of them into context, broadest first, and leans on the model to treat the more specific instruction as the one that wins.

From there the chapter builds an actual file for a shared-list app: starting from a /init draft, keeping only the commands that aren't obvious (the dev server, the type check, the one authoritative test command), naming the manual click-through journey that tests alone can't replace, writing down two or three real architectural constraints, and stating flatly what "finished" means. It explains why the file should stay short — it's re-injected on every turn, so bloat taxes every future question — and points to /context, /doctor, and /memory as ways to check what's loaded and trim what doesn't earn its place. It draws a hard line between guidance, which the model can still talk itself past, and real enforcement through a permissions deny list, and closes with a repeatable loop for testing whether an instruction actually changes agent behavior: fresh session, one-line request, watch what's skipped, edit one sentence, retest.

What changed in how instructions get loaded

A shorter section covers a real gap in that mental model: the built-in Explore and Plan subagents skip reading CLAUDE.md and skip checking Git status entirely, while custom subagents you define still inherit it. It also notes a new flag for passing subagent rules via a file instead of a command-line string, and a fix in recent releases removing an approval prompt that used to stall scripted runs using organization-delivered instructions — all catchable with the same /context check.

This chapter installs Claude Code, opens it inside a small shared-list web app, and walks through fixing one real bug — blank items being addable — end to end: describing the project, requesting a narrow change, reading the diff, running tests, manually verifying the behavior, adding a test, and committing. It closes with two recent changes to the tool, Auto permission mode and default model updates, and what to check about each.

This episode is narrated by AI-generated synthetic voices.

Episode page & show notes

Visit website

Getting the tool onto your machine

The chapter walks through installing Claude Code as a standalone application rather than through npm, explaining why the native installer (fetched with curl or the PowerShell script) is the recommended path — it updates itself and needs no Node.js runtime — while noting Homebrew, WinGet, and Linux package repositories as valid alternatives, per the setup instructions. It covers system requirements, the sign-in flow through a browser, and the built-in diagnostic reached with slash doctor for fixing installation and network problems, drawn from the CLI reference.

Opening a real project

Once launched inside a small shared-list web app, the chapter shows the workspace trust prompt, the live session display showing model and context usage, and the two permission modes — Manual, which asks before every write or command, and Auto, now the default for Pro, Max and Team plans, which only interrupts for destructive operations. It draws on the permissions documentation and the interactive mode guide to explain what each mode actually shows you and why reading a diff before approving it matters.

Making one change and proving it

The core of the chapter is a single fix: stopping blank or whitespace-only list items from being added. It shows the tool describing the project first, proposing a small diff, running the test suite after a command-approval prompt, and then a manual click-through of the app to confirm the behavior actually changed — because a passing suite only proves what it already tested. A new test is added, deliberately watched failing and then passing, before a single readable commit closes the loop.

What changed recently in Claude Code

A short section flags two changes that affect a first session directly: Auto mode becoming the default permission mode on Pro, Max and Team plans, and Sonnet 5 becoming the default model with support for pinning a default model via environment variable, both listed in the Claude Code changelog and the what's new page.

A working session on a Next.js and Postgres project is used to demonstrate moving repeated instructions — formatting, migration safety, route-handler conventions — out of prompts and into hooks, slash commands, skills, subagents, and MCP servers, followed by a rundown of recent Claude Code releases and model updates.

Episode page & show notes

Visit website

Turning repeated instructions into repository rules

The chapter walks through five places to put an instruction so it stops living in the same three sentences typed at the top of every session. A hook is a shell command wired to a fixed point in the loop — format the changed file and run the typecheck after every write, no memory required — and the Claude Code hooks documentation covers how they can also block an action outright, which is distinguished from a flat permissions deny rule by the fact that a hook can inspect state before refusing. A custom slash command turns a retyped personal habit, like a pre-commit diff review, into a named file the whole team shares. A skill goes further: a folder whose short description is always visible but whose full body — doctrine plus a real example file — only loads when the work actually matches, exactly as laid out in the Claude Code skills documentation. A one-off subagent handles the heavy-input, light-output question — search forty files, report three paragraphs — per the Claude Code subagents documentation. And an MCP server connects to a system outside the repo entirely — an issue tracker, a read-only database — as described in the guidance on connecting Model Context Protocol servers, best added only for a system you keep pasting from. The chapter closes on the risk of over-wiring — too many hooks, skills and servers making a failure's cause unreadable — and the fix of stripping back to a bare session and re-adding one layer at a time.

This week's releases

A short rundown of recent changes: a new diagnostic command flags which skills are eating context, new models default to a million-token window with a much cheaper cache-read price, and a supply-chain fix stops a cloned repo from silently redirecting a client's configuration.

This chapter builds a layered permissions system for coding sessions — allow, ask, and deny rules split across user, project, and local settings files — so routine actions stop requiring attention while irreversible ones still get a pause, then extends the idea into plan mode and a rundown of recent tool updates.

Episode page & show notes

Visit website

The founding charter

The core problem: every permission prompt spends a little of your attention, and by the thirtieth approval in a session you've stopped reading before you say yes. The fix isn't discipline — it's deciding, calmly and in advance, what a session may do freely, what it must ask about, and what it may never do, written into a file rather than negotiated in the moment.

That file lives in three places, layered from general to specific: a user-level settings file that travels with you across every project, a committed project-level file that belongs to the whole team and shows up in code review, and an uncommitted local file for machine-specific quirks. More specific layers override broader ones, though a managed policy file (the kind an IT department deploys) sits above all of them and can't be overridden.

Inside these files, permission rules sort into three lists. Allow lets a matched action through without a prompt — pure convenience, buying back attention for boring, repeatable calls like running tests or reading files. Deny blocks an action outright with no prompt and no override, reserved for anything irreversible: touching production data, reading credentials, force-pushing or rewriting git history. Ask sits in between and always interrupts. Deny beats everything; ask beats allow. Applied to a typical TypeScript/Next.js/Postgres project, this produces a short, deliberate file — narrow allow rules for test, typecheck and lint commands, ask rules for writes outside the repo and package installs, deny rules for env files, cloud credentials, and destructive git or database commands.

The payoff is counterintuitive: locking things down doesn't feel restrictive, it makes the prompts that remain actually mean something, because the noise is gone.

The same logic scales up through plan mode, which stops a session from editing anything while it reads, traces and proposes — useful for unfamiliar code or multi-file changes, skippable for one-line fixes. An approved plan is not a contract; work in progress can reveal files the plan never listed, so the habit is to compare the plan's file list against what actually changed. Built-in commands like permissions, config, context, and status let you inspect and edit the live configuration mid-session rather than restarting — which matters because configuration drift is real: a rule quietly added to a local file weeks ago can silently override what the team believes is running. Checking the resolved permissions at the start of a session catches this before it costs anything.

The show's news beat, skewed hard

A new restricted mode for the command-line tool strips out command execution, code running and web fetching, and confines edits to the working directory — and it ignores your settings files entirely, offering a hard ceiling for working with untrusted code. Authentication can now log in directly against console billing alongside SSO and email options. Smaller additions include a readline-style keybinding option, per-prompt frontmatter controls for effort level and cache duration, and a statusline metric exposing rolling five-hour and seven-day rate-limit usage. A native VS Code extension brings inline diffs and sidebar progress, and community projects bundling sub-agents, skills and hooks — including one collection called Everything Claude Code and a planning-focused framework called Superpowers — offer working examples of the extension layer ahead.

This chapter walks through running a single Claude Code session end to end on a real app — writing a strong first prompt, reading and correcting the model's plan, building a trustworthy project memory file, and cleanly resuming work the next day — then closes with a roundup of recent pricing, rate limit, and SDK changes.

Episode page & show notes

Visit website

Learning your codebase, one session at a time

The core of this chapter is a single hands-on walkthrough of running one Claude Code session properly, using an ordinary TypeScript/Next.js app with Postgres behind it as the running example. It opens with the problem of a session that keeps rediscovering the same facts about a repository — how to run the tests, where things live — because nothing was ever written down for it to read. From there it builds out a full first prompt: naming the goal in outcome terms, scoping what not to touch, pointing at the real files or an existing pattern to imitate, and stating a concrete done-condition such as a test that fails without the change. It covers how to read the plan that comes back — checking the file list, the silent assumptions, and whether the approach matches the project's actual conventions — and makes the case for interrupting the moment an assumption is wrong rather than after several files have been built on top of it.

From there it turns to project memory: generating a starter file with the init command, then cutting it down to only what's true and verified — real commands, real layout, real conventions — while stripping out prose, philosophy, and anything nobody will maintain. It explains how these memory files stack rather than override each other, how nested files load lazily, and how imports work. It closes with finishing a unit of work cleanly and picking it back up, covering the continue and resume flags, the from-pr option, and the naming and forking commands that make sessions easier to find again.

This week in Claude Code

The main item is pricing: Sonnet 5's standard rates are now set at $2 per million input tokens and $10 per million output tokens, cancelling a planned increase, alongside removal of peak-hour throttling and doubled five-hour rate limits on paid plans.

A recent changelog entry adds separately configurable prompt cache lifetimes for main sessions and subagents, finer usage telemetry, an organisation-configurable model picker, and a fix for remote tool servers dropping their connection in print mode. Recent releases also brought a design-drafting command preview, a Concise output style, persistent goal conditions across resumes, and an environment variable for setting a default model. On the SDK side, the Python Agent SDK picked up in-process Model Context Protocol server support and a structured error type, and the platform Python SDK reached version 1.0 on a new HTTP transport.

A hands-on walkthrough of driving Claude Code on a real codebase — writing and maintaining a project memory file, running a scoped bug fix from request to committed diff, and resuming sessions the next day — followed by a quick roundup of recent CLI, desktop, and SDK releases.

Episode page & show notes

Visit website

The founding charter

The core loop for driving Claude Code by hand: open a session in your project, ask for a change in plain English, review the diff, run tests, commit. The real subject is the gap between a session that starts cold and one that already knows your codebase, and how a request that names a file, a current behaviour, a wanted behaviour, and a constraint outperforms a vague ask, because the model fills any gap with its own taste rather than yours.

That gap gets closed with a Markdown memory file, written by running the in-session init command, which surveys the package manifest, test setup, build, and git history before drafting instructions. The file should stay short: how to run the app, how to run the tests, and two or three conventions a new contributor always gets wrong — nothing derivable by reading the code. These files stack from broadest to most local at session start, and the automatically maintained per-project memory file is capped at roughly two hundred lines or twenty-five kilobytes, while everything else is not.

A worked example — moving email validation from submit-time to on-blur — shows the loop end to end: Claude reads the form and schema, proposes a scoped fix, runs the test command from memory unprompted, surfaces a failing existing test, and waits for a human call on which behaviour is correct. The diff stays small because the request stayed narrow.

Sessions persist as transcripts on disk automatically, restarted with a continue flag for the most recent one or a resume flag for a picker across past sessions, with branching and renaming available mid-session — though transcripts older than thirty days get cleaned up by default. The closing warning: an unmaintained memory file rots into a wiki of contradictory, stale instructions that Claude will obey confidently anyway, so it needs treating as short, living, and checked every quarter.

The show's news beat, skewed hard

The current CLI release adds a per-loop breakdown to the usage command and separate cache lifetime settings for main sessions versus subagents, plus a model-picker setting and managed pricing for enterprise contracts. Recent releases also fixed lost plan-mode state on restarted remote workers and added automatic resumption after a rate limit, with a matching auto-continue toggle on the desktop app's limit notification. A research-preview design command now opens an editable canvas for implementing frontend interfaces, and the Python SDK has hit version one with a CLI migration helper for teams still on the old client conventions.