← Blog

I Turned a Stanford Syllabus Into a Self-Improving Claude Code Setup

26 August 2026

You don’t need to train models to use agent research. Half of the Stanford CS329A syllabus maps directly onto how you configure a coding agent you already use. This post is what happened when I applied it to my own Claude Code setup, plus the complete instruction, free, that builds the same thing on yours.

Updated 26 August 2026, version 2. I published version 1, then sent it to someone who builds this kind of system for a living. He found five real flaws in about ten minutes, and the biggest one goes to the heart of the idea. The instruction below has been rewritten to fix what could be fixed and to state plainly what can’t. Skip to the review if you read version 1 and want the delta.

The rabbit hole

It started with a Medium headline: “Stanford Just Put an $850K/Year Skill on YouTube”. The framing was irresistible. Anthropic advertising salaries of $500,000 to $850,000 for engineers who build self-improving AI agents, and Stanford uploading the course that teaches exactly that to YouTube, free, no enrollment.

The course is CS329A: Self-Improving AI Agents, a graduate seminar covering how agents improve through interaction: verification, test-time compute scaling, reinforcement learning, tool use, memory, planning, and evaluation. The lectures are on the Stanford Online channel.

But when I actually dug into the course site, the lectures weren’t the gold. The reading list was. A curated, ordered syllabus of the best agent research of the past few years, all free on arXiv. And buried in those papers was a realisation that changed how I work.

The translation

I’m a solo developer. I use Claude Code daily across multiple products. Like most heavy users, my global configuration had grown organically: useful, but bloated, unversioned, and improving only when I remembered to improve it.

Reading the syllabus, four research threads jumped out as directly applicable to configuration rather than training.

Grounded feedback (ReAct, RLEF). Agents work better when every action is checked against real feedback: run the code, read the error, act again. Config translation: a hard rule that nothing is “done” with failing checks, and every project defines a verify command that actually gets run.

Repeated sampling with verification (Large Language Monkeys, CodeMonkeys). Multiple fresh attempts plus a verifier beats one long, increasingly polluted session. Config translation: a /fresh command that packages a stuck problem into a clean brief (goal, attempts, exact errors, verify command) for a new session that must propose competing root-cause hypotheses before touching code.

Tiered memory (MemGPT, Cartridges). Agents need cheap always-available memory and deeper on-demand memory, not one giant context. Config translation: a lean, line-capped global CLAUDE.md holding only rules, with everything detailed pushed into reference docs loaded via a sharp trigger index.

Plan-execute separation with escalation (ADaPT and the planning literature). Decompose with a strong planner, execute cheaply, and escalate back to planning when execution fails. Config translation: an explicit rule that two failed verifications on the same problem means stop and re-plan, not a third blind attempt.

The part nobody builds: selection pressure

Capturing lessons is easy. Every “always update your CLAUDE.md” tip on the internet covers that. What nothing covers is what the research calls the verifier side: a system that only accumulates will degrade. Lessons pile up, contradict each other, go stale, and bloat the context they live in.

So the heart of the setup is a periodic /evolve cycle that applies selection pressure:

/evolve presents a single consolidated diff, and I approve it. That gate is deliberate. A config that rewrites itself unattended will drift, and the thing that would catch the error is the thing that made it. Git sits underneath as the rollback net. Every /evolve commits before and after itself, so any bad change is one revert away.

That was version 1. Then it got reviewed.

Then someone who knew better took it apart

I sent the published post to someone who has been circling the same problem for his own work. He skimmed it on the way out the door and came back with a voice note that was more useful than the post it was critiquing. Five things, and the first one is the one that matters.

1. I was asking Claude to grade its own homework. This is the fatal one. Version 1 had a /health check that scanned “this session” for rules the model had broken, and a session-end trigger that asked it to distill lessons from its own failures. Both ask a model to be an accurate witness to its own behaviour, in the session where it was pursuing a goal it is disposed to report success on. You don’t ask the agent that just built something whether it left bugs in it; you open a fresh session, ideally on a different model, and audit the output. Automating self-assessment doesn’t make it rigorous. It makes it fast and wrong.

The fix: every audit now runs in a session whose only job is auditing, with an instruction to refuse if it’s been doing implementation work. And its evidence comes from the transcript record, the .jsonl session files Claude Code already writes to ~/.claude/projects/, rather than from recollection. There’s a ground rule at the top of the instruction now: cite a file, a transcript line, or a URL, or don’t report the finding.

Worth knowing, and I didn’t when I wrote version 1: Claude Code already ships /insights, which generates a report analysing your recent sessions from exactly those files. Native-first says use it. The curation cycle now runs it first and treats its output as input.

2. My spec flagged vague rules using vague rules. Version 1 told the audit to “flag rules that are vague” and to “not silently preserve stale rules”, and defined neither word. Stale how? Unused for a week? Not updated recently? If it’s the latter you get updates for the sake of updates, which is churn dressed as improvement.

Both now have hard definitions. A rule is vague if and only if you cannot complete the sentence “here is an observation that would prove this rule was violated”. “Write good code” fails that test. “Never commit directly to master” passes it. A rule is stale only if it names something that no longer exists, the current docs contradict it, it works around a fixed limitation, or it duplicates a native feature. Age and low usage are explicitly not evidence, and the default action on every rule is keep.

3. “Three failed attempts” is not a signal. Version 1 auto-captured a lesson after any three-attempt task, failed verification, or correction. In practice most of those are an expired token, a rate limit, a 403, an API that needed topping up, a service you weren’t authenticated to, or a tool that misfired. None of that is knowledge. Capture it and you fill your memory store with noise and then promote the noise.

There’s now an explicit exclusion list (401, 402, 403, 429, 5xx, permission denials, missing installs, anything a plain retry fixed) and a two-part positive test: would knowing this have changed the first action, and will the condition still exist next month? If either answer is no, nothing gets written.

4. The typecheck hook was a bad idea. Version 1 put a PostToolUse hook on every edit that ran the project’s typecheck. He called it immediately, and he’s right: it fires in the middle of a multi-file change, when the project is legitimately broken between edit one and edit five, and reports errors that are an artifact of editing order. Then it does that again on the next edit, and spends the project’s full check time each go. Sessions get impeded for no upside.

It’s gone. If you want the automation, it belongs on a Stop hook that runs the project’s verify command once at the end of a turn, which is a point where “is this broken?” is a fair question. Mid-edit isn’t.

5. Nothing tested whether any change helped. The deepest one. The system proposes a config change, I approve it, it’s applied, and no part of that loop establishes that the config that came out is better than the one that went in. His sketch of the honest version: pull the session transcripts on a schedule, clean them with a script rather than burning context on raw JSON, store the refined snapshots so you can compare across runs, derive recommendations from patterns across at least thirty sessions rather than one, then replay a fixed task set through headless claude -p sessions against both the old and the candidate config, score them against a rubric, and only keep changes that win. Version the config so every change has provenance and a rollback.

I’ve built the parts of that a prompt can honestly build: transcript-derived evidence, a stored digest, promotion thresholds of three sessions across two projects, a cadence of thirty sessions or seven days, and a provenance log recording every applied change with the citation that justified it. The eval harness at the end is a real piece of software, not a prompt, and I haven’t built it. So the instruction now says so, in a “Known limitations” section, instead of implying it’s covered.

The honest name for this is self-curating, not self-improving. It keeps the config lean, current, and evidence-backed, and it stops it accumulating garbage. That’s genuinely worth having. It is not the same claim as making the agent measurably better, and version 1 blurred the two.

Two rules I found by running it myself

Before the review, running the instruction at a real config surfaced two of its own flaws, and both survive into version 2 unchanged.

Native-first. Before building anything the spec describes, check whether Claude Code now provides it natively, and if it does, use the built-in as the foundation and point the spec’s commands at it rather than building a parallel version. Two systems doing the same job will drift, and the custom one always loses.

In practice this rewrites the memory design. Claude Code’s built-in auto memory becomes the capture layer, so the custom ”## Lessons” ledger survives only as a fallback for installs that don’t have it. It’s also the rule that caught /insights: had I applied native-first properly the first time, the transcript-analysis feature I needed was already sitting in the tool.

What does not get handed over is /evolve. Native memory captures. It applies no selection pressure. Nothing merges duplicate lessons, prunes stale ones, promotes a lesson that keeps recurring across projects, or caps the size of what it accumulates. Capture is native; curation isn’t. That split is the genuine gap, and it’s the piece worth building.

Roles, not names. Every directory and file name in the spec describes a role, not a requirement. My on-demand layer was already a docs/ directory, with that name baked into two other commands, the gitignore, and every cross-reference in the config. Renaming it to references/ because the spec said references/ would have broken all of that for exactly zero benefit. So the audit adopts whatever already plays the role and outputs a map of spec-role to existing-name instead.

Why this matters for solo builders

That Medium piece framed the course as a path to an $850K job. Fair enough. But for those of us building alone, the same knowledge has a different payoff: configuration that doesn’t rot. Rules that name dead tools get caught. Detail that shouldn’t be in every prompt gets demoted. Lessons that recur across projects get promoted, and one-off incidents don’t.

What I won’t claim any more is that the agent gets measurably better, because nothing here measures that. What I can claim is that the config stops decaying, and that the maintenance is a session every few weeks instead of a rewrite every few months. For a solo operator that’s still the right trade, and it’s a smaller promise than the one I made three drafts ago.

Get the instruction

Below is version 2, with the review’s fixes baked in. It assumes nothing about you. It audits whatever config you have (or a completely fresh install), defers to anything Claude Code already does natively, adopts your existing directory names rather than imposing its own, questions anything that meets a hard definition of stale, inventories your personalisations so nothing you’ve built gets broken, and only then builds the system. It ends by telling you what it did not verify.

How to run it: open a fresh Claude Code session in any directory, switch to your strongest model in plan mode, and paste the whole thing. Phase 1 is conversational: you get an audit report and a batch of keep, update, or drop questions before a single file changes. Approve the plan and it does the rest.

If you ran version 1: the flawed pieces are a PostToolUse typecheck hook in settings.json, a “rules violated this session” check in /health, and any session-end lesson-writing hook. Remove those three, then re-run this version. If you committed your ~/.claude to git as version 1 instructed, git log will show you the exact commit to revert to.

Download the instruction (.md)

No email gate, no signup. If you’d rather copy and paste, the full text is right here.

Build the global Claude Code configuration at ~/.claude/ into a lean, self-curating system. Operate on ~/.claude/ regardless of the current working directory. This instruction must work equally on a mature personalized config or a completely fresh install. Proceed in two phases: AUDIT first, then IMPLEMENTATION only after my approval of the audit findings.

═══ GROUND RULES (apply to both phases and to every command you build) ═══

EVIDENCE RULE. Every finding, every proposed change, and every lesson must cite something you actually read: a file path and line, a transcript entry with its session file and timestamp, or a URL you fetched. You may not cite your own recollection of what happened in a session, your impression of how well work went, or your sense of which rules were followed. A model is not a reliable witness to its own behaviour, least of all inside the session it is reporting on. If you cannot produce a citation, the finding does not go in the report. Say "no evidence found" instead.

DEFAULT TO KEEP. Absence of evidence for a rule is not evidence against it. A rule that no citation contradicts stays exactly as it is, unchanged, and is not mentioned in the report. Do not propose a change to demonstrate thoroughness. Churn is a failure mode of this system, not a sign it is working. A run that proposes nothing is a valid and common outcome; say so plainly and stop.

SAMPLE SIZE. A single session proves nothing. Do not derive a rule, promote a lesson, or delete anything on the basis of one occurrence. Thresholds are defined per operation below, and they are minimums, not targets.

NEVER GRADE THE SESSION YOU ARE IN. Any audit, curation, or health check must run in a session whose only job is that audit, started fresh, with no implementation work in its history. Where the tool allows it, run it on a different model from the one that did the work being audited. If you are asked to audit and the current session has been doing implementation work, say so and refuse to grade it: report on files and transcripts only, and tell me to re-run in a clean session.

NATIVE-FIRST. Before building anything specified below, check whether current Claude Code natively provides that capability (built-in auto memory, per-project topic files, a MEMORY.md index, native checkpointing, and the built-in /insights session-analysis report). If it does, USE the native feature as the foundation and adapt this spec's commands to operate ON it. Never build a parallel custom system duplicating a built-in; two systems doing the same job will drift. Report each native substitution in the audit.

ROLES, NOT NAMES. Every directory and file name in this spec (references/, patterns.md, stack-notes.md, and so on) describes a ROLE, not a required name. If an existing structure already plays that role under a different name (for example a docs/ directory as the on-demand layer), ADOPT the existing name and structure. Do not rename or migrate it, since its name may be baked into other commands, gitignores, and cross-references. Map spec-role to existing-name in the audit report.

═══ PHASE 1: AUDIT (no file changes in this phase) ═══

- Assume NOTHING about the user, their stack, their projects, their tooling, or their preferences. Derive facts only from files you actually read in ~/.claude/. Where something needed is absent, ASK. Never fill gaps with guesses.
- Read every existing file in ~/.claude/ (CLAUDE.md, supporting .md docs, templates, commands/, settings.json, hooks). On a fresh install with nothing present, say so, skip to the audit summary, and note the build will be baseline-only.

Produce an AUDIT REPORT with these sections. Every item in every section carries its citation.

1. HEALTH GRADE: score the existing config against Claude Code best practices.
   - Bloat: is CLAUDE.md carrying content that shouldn't be always-loaded (catalogs, walkthroughs, examples, one-off notes)? Give the measured line and byte count, and what percentage is rules versus detail. If bloated, say so plainly and quantify the reduction available.
   - Rule quality. Apply this test to each rule, and quote the rule with your answer: "describe, in one sentence, an observation in a transcript or a file that would prove this rule was violated." A rule is VAGUE if and only if you cannot complete that sentence. "Write good code" fails, because no observation proves it. "Never commit directly to master" passes, because a commit on master proves it. Report only the rules that fail, each with a proposed testable rewrite or a recommendation to delete. Do not report a rule as vague because you would have worded it differently.
   - Contradictions: two rules that cannot both be satisfied by the same action. Quote both, and the action that trips them. Overlapping wording is not a contradiction; do not report it.
   - Dead weight, which means one of exactly these: a hook whose script file does not exist on disk; a command referencing a path that does not exist; a doc listed in the reference index with no matching file, or a file with no index entry; a plugin in settings.json that fails to load. Verify each by checking the path. Do not report anything as dead because it "appears unused".
   - Structure: is there separation between always-loaded rules and on-demand detail? For each reference-index trigger, state what observable condition fires it. A trigger nobody can evaluate ("read when relevant") is dull; propose sharper wording.

2. OUTDATED REQUIREMENTS CHECK: for each substantive requirement or preference stated in the existing CLAUDE.md (tool choices, model policies, workflow rules, banned or mandated practices), test it against this definition and nothing else.
   A rule is STALE if one of these is true and you can cite it:
   (a) it names a tool, model, flag, command, or file path that no longer exists or has been renamed;
   (b) the current official Claude Code documentation or changelog now contradicts it;
   (c) it mandates a workaround for a limitation that has since been fixed;
   (d) it duplicates a capability the tool now provides natively.
   A rule is NOT stale because it is old, because it has not come up recently, or because you could phrase it more elegantly. Age and low usage are not evidence. Updating for the sake of updating is the exact failure this definition exists to prevent.
   Consult the current official Claude Code documentation and changelog (via web search or fetch if available) rather than relying on training knowledge alone. For each rule that meets the definition, QUOTE it, cite the specific doc or changelog line that makes it stale, and ask whether to keep, update, or drop it. Batch these questions together. Rules that do not meet the definition are not mentioned at all.

3. PERSONALIZATION INVENTORY: every custom command, hook, skill, template, and workflow found. These are the user's investments; none may be lost or broken without explicit agreement. For each: keep as-is / integrate with the new structure (for example, any sync, backup, or propagation command must be extended to cover new directories and git state) / flag as redundant and ask.

4. PROPOSED TARGET STATE: summarize what Phase 2 will build, sized against the findings, including the projected always-loaded footprint versus today's measured one.

STOP after the audit report and my answers to your questions. Do not modify anything until I approve.

═══ PHASE 2: IMPLEMENTATION (only after audit approval) ═══

Apply the approved findings, then build the following. Show me a diff of every file before writing it. Preserve all existing rules that survived the audit: relocate, don't delete.

ARCHITECTURE, TWO LAYERS:
- ~/.claude/CLAUDE.md = always-loaded, rules only. Hard line cap set at ~120% of the lean rewrite; state the cap number.
- ~/.claude/references/ = on-demand detail. Migrate catalog, guide, and toolkit-style docs here (keep names). Create references/patterns.md (worked examples) and references/stack-notes.md (one section per stack component found in the config; on a fresh install create it empty with a purpose header, and do not invent components).
- CLAUDE.md contains a reference index (max 15 lines): one line per doc with a sharp "read when" trigger, plus: "Reference docs are authoritative over general knowledge; read the relevant one before working in its domain."

GLOBAL CLAUDE.md SECTIONS:
1. Identity and defaults: populate ONLY from existing config and audit answers; ask for anything still missing, including model policy.
2. Anti-assumption rule: "Never assume details about the user, the project, or prior decisions. Verify from files in the repo or config, or ask. If forced to make an assumption, state it explicitly."
3. Verification: never report a task done with failing checks; every project defines a VERIFY command (propose a minimal one if missing before starting work); two failed verifications on the same problem means stop, return to plan mode, re-decompose.
4. Memory tiers: global = durable cross-project rules only; project CLAUDE.md = project conventions plus VERIFY command; references/ = detail; nothing session-specific in global.
5. Reference index.
6. Lesson capture (NATIVE-FIRST applies): if Claude Code's built-in auto memory exists, it IS the capture layer. Do not create a custom "## Lessons" ledger; instead add a short rule stating that native memory is the single source of lessons and the curation command is its curator. Only if no native memory exists, fall back to a "## Lessons" section with entries formatted "- [date, session-id] one-line lesson". Do not add a self-reported use-counter to lesson entries. Nothing reliably increments one, and a number the model maintains about its own behaviour is exactly the kind of evidence this config does not accept.
7. Canary: "When asked 'config check', reply CONFIG-ACTIVE-vN, lesson count (from whichever lesson store is in use), and the date of the last curation run."
8. CAPTURE RULES. If native auto memory handles capture, skip the custom capture rule entirely and rely on the native layer. Otherwise add these, exactly as scoped:
   - The trigger to CONSIDER writing a lesson is a failed verification, a user correction, or a task that took three or more attempts. The trigger only opens the question. It does not justify a lesson on its own. Attempt count measures nothing by itself.
   - EXCLUSIONS. Do not write a lesson when the root cause was any of: an expired, missing, or wrong credential; a quota, billing, or rate limit (401, 402, 403, 429); a provider outage, network failure, or DNS failure (5xx, timeouts); a tool call that misfired or was denied by permissions; a missing local install or wrong runtime version; or anything a plain retry fixed with no change of approach. These are environment conditions, not knowledge. They cause the majority of failed attempts and none of them is worth a rule.
   - POSITIVE TEST. Write the lesson only if both are true: knowing it would have changed the FIRST action taken, and the condition that caused it will still exist next month. If either is false, write nothing.
   - Every lesson records the session id it came from, so a later curation run can count occurrences instead of trusting a summary.
   - A lesson written by capture is a candidate, not a rule. It stays in the project-level store. Nothing is promoted to global by capture, ever.
9. "If verification passed but the user later reports the change was wrong: propose a check that would have caught it and add it to that project's VERIFY command."
10. "When starting work in a project with no project CLAUDE.md, scaffold it from the template automatically and say so in one line."

SLASH COMMANDS (in ~/.claude/commands/, never overwrite an existing command of the same name; if a name collides, ask):

- /learn: only create this if capture is NOT native; it manually triggers the capture rules above, exclusions and positive test included. With native memory, skip it, or keep it only as a one-line "distill this session into memory now" nudge if the user wants a manual trigger.

- /fresh: output a standalone brief of the current unsolved problem: goal, attempts made, exact error output, VERIFY command, ending with a request for 3 distinct root-cause hypotheses and a discriminating test before any code changes. Paste-ready for a new session.

- /evolve: the curation cycle, and the only gated step. Its command file must open with this line: "Run this in a fresh session with no implementation work in its history, and on a different model from the one that did the work being audited if your setup allows it. If this session has been doing implementation work, stop and tell me to re-run it clean." Then:
   0. Commit current ~/.claude/ state to git with a dated message, as the rollback point.
   1. GATHER EVIDENCE FIRST, before forming any opinion. Run the built-in /insights report if this Claude Code build has one, and read its output. Then read the raw session transcripts under ~/.claude/projects/ covering the period since the last curation commit. Those files are large and noisy, so do not pull them into context directly: write or reuse a small script that extracts only what is needed (user corrections, failed verifications, repeated errors, rules that fired) into a compact digest, and save that digest under ~/.claude/audit/<date>/ so later runs can compare against it rather than re-deriving it. State how many sessions the digest covers.
   2. CADENCE AND THRESHOLDS. Do not run this at the end of a working session, and do not run it once per session. Run it when at least 30 sessions or 7 days have accumulated, whichever comes first, so patterns are visible above noise. State the count in the report. Then: merge duplicates within a project, one file survives and the index is updated; PROMOTE to global only what appears in at least 3 distinct sessions AND at least 2 distinct projects, each cited by session id, and below that threshold a lesson stays where it is, because one vivid incident is not a rule; DELETE only on the staleness definition from Phase 1 section 2, cited, never because something looks unused, and present deletions for a yes or no rather than auto-deleting; rewrite vague entries as testable one-liners in place, using the same one-sentence-observation test.
   3. MINI-AUDIT against CURRENT Claude Code: consult the official documentation and changelog (via web search or fetch if available) for features, config conventions, or deprecations introduced since the last run. Evaluate against THOSE, not training knowledge, cite what changed, and apply the staleness definition. DEFAULT TO KEEP applies here: report only rules that meet the definition.
   4. Enforce the CLAUDE.md line cap via demotions to references/, and verify the reference index matches the actual files.
   5. ECOSYSTEM SCAN: check current official Claude Code docs and the plugin, skill, and MCP ecosystem for capabilities relevant to the stack components and workflows actually present in this config. At most 3 candidates per run, and zero is a fine answer. ELIGIBILITY: a candidate must be either (a) official, published by Anthropic or by the vendor of the tool it integrates, such as a database vendor's own MCP server, or (b) widely adopted with verifiable signals: substantial GitHub stars, high npm download counts, AND commit activity within the last 6 months. Reject anything unverifiable, abandoned, or niche regardless of how good it looks. For each suggestion state the official-or-adoption evidence with numbers, what it replaces or adds, the concrete benefit, and the cost (setup effort, token footprint, new dependency). Only suggest things that map to friction visible in the digest from step 1. Never install anything: suggestions only, for my decision.
   6. METRICS, restricted to what can be counted without self-report: always-loaded line and byte count, lesson count, number of rules added, changed and deleted this run, sessions covered by the digest, and days since the last run. Do not report a "rules violated" figure, or any other number derived from a model's account of its own behaviour.
   7. PROVENANCE: append an entry to ~/.claude/audit/history.md for every applied change: date, config version, what changed, and the citation that justified it. This is what lets a later run find a change and reverse it. It is a record, not a measurement: it does not establish that the change helped.
   8. Present ONE consolidated diff and WAIT. On approval: apply, bump the canary version, commit again. If the config contains a user sync or propagation command, end by reminding the user to run it.

- /health: audit only, and it applies nothing. Same fresh-session rule as /evolve, stated at the top of the command file. Checks, all citation-backed: contradictions between rules; dead weight as defined in Phase 1 (path checks, not impressions); reference-index entries with no matching file, and files with no entry; dull index triggers. It must NOT contain a "rules violated this session" check, or any other check that asks the model to grade its own conduct. If you want that signal, it comes from the transcript digest in /evolve step 1, produced by a session that did not generate the transcripts. Same sync reminder rule as /evolve.

HOOKS (in settings.json, merged carefully with existing hooks, never replace them; document setup in references/setup-guide.md):
- Do NOT add a PostToolUse hook that runs a typecheck, test suite, linter, or build after every edit. It fires while a multi-file change is legitimately half-applied, so it reports errors that are an artifact of editing order, and it spends the project's full check time on every single edit. The cost is real and the signal is noise. Version 1 of this instruction specified one; that was a mistake.
- If you want automated verification, put it on a Stop hook that runs the project's declared VERIFY command ONCE at the end of a turn, and only when the project actually declares one. A turn boundary is a point where "is this broken?" is a fair question. Mid-edit is not. Make it easy to disable with an environment variable, and say so in the setup doc.
- SessionStart: check the date of the last git commit in ~/.claude/ from a curation run; if more than 21 days ago, print one line saying curation is overdue, with that date. Max 2 lines, silent otherwise.
- Do not add a session-end hook that writes lessons. Session end is exactly when the model is least able to judge which of its failures were worth recording, and a hook makes that judgement unattended. Capture belongs to the native memory layer, or to an explicit manual trigger.

GIT SAFETY NET:
git init ~/.claude/ if not already a repo; sensible .gitignore; rule: the curation command always commits before and after itself. Git is the rollback mechanism for all config changes, and audit/history.md is the index that tells you which commit to roll back to and why. If a separate sync or propagation mechanism exists, git remains the source of truth for history: sync propagates, git rolls back.

MULTI-MACHINE AWARENESS (generic):
If evidence of multi-machine use exists (a sync command, symlinks, machine-specific notes), ensure everything created here is covered by that mechanism and list manual steps for other machines in the final summary. If no evidence exists, don't invent a sync system: note the config is machine-local.

PROJECT TEMPLATE: project CLAUDE.md template containing VERIFY command, escalation note, "## Lessons", and a pointer to the global reference index.

CONSTRAINTS: the always-loaded footprint must not grow versus today's config (fresh install: keep the baseline lean). Finish with: a one-screen summary of changes, final CLAUDE.md line count versus cap, the personalization inventory with what was integrated, audit findings resolved versus deferred, and any multi-machine manual steps.

FINAL HONESTY REQUIREMENT: end the summary by stating plainly that this system curates the configuration and does not measure whether the configuration works, and that no change made here has been tested against outcomes.

What this does not do

The instruction ships with these limitations written into it, and they’re worth reading before you run it.

Nothing here validates a change. The cycle proposes edits, you approve them, they’re applied. No run establishes that the config that came out is better than the one that went in. The honest fix is an eval harness: replay a fixed task set through headless claude -p sessions against both configs, score against a rubric, keep the winner. That’s software, not a prompt, and it isn’t built.

The auditor is still a language model. Moving judgement into a separate session that reads transcripts instead of recalling reduces the self-report problem. It doesn’t remove it. Running that session on a different model helps more than anything else here.

The thresholds are crude. Three sessions across two projects, a seven-day or thirty-session cadence: chosen to be cheap rather than statistically correct. Enough to stop the config learning from noise. Not a measurement.

The cost isn’t two minutes. Version 1 said two minutes a month. A real curation run is a dedicated session that reads a digest, checks the current docs, and produces a diff worth reading. Budget a proper sitting, monthly at most.

Frequently asked questions

Do I need a mature Claude Code config for this to work? No. The instruction detects a fresh install, says so, and builds a lean baseline instead of pretending to audit files that aren’t there.

Will it overwrite my existing commands and hooks? No. Phase 1 inventories every custom command, hook, skill, and template you already have, and Phase 2 is instructed never to overwrite a name collision without asking. Hooks are merged into settings.json, not replaced.

Can Claude reliably audit its own configuration? Not from inside a working session, no. That was version 1’s central flaw. Version 2 pushes every judgement into a dedicated audit session with no implementation work in its history, requires it to cite files and transcript entries rather than recollection, and tells it to refuse the job if it’s been coding. Run it on a different model from the one that did the work and you’ve done what’s available to you short of building an eval harness.

Why is /evolve gated on my approval? Because a config that rewrites itself unattended will drift, and the only thing positioned to catch the error is the thing that made it. One consolidated diff a cycle is a cheap price for that safety, and git makes any bad change one revert away.

Doesn’t Claude Code’s built-in memory already do this? It does the capture half, and the instruction defers to it: where native auto memory exists, it becomes the lesson store and no custom ledger gets built. What it doesn’t do is apply selection pressure. Nothing merges duplicates, prunes stale entries, promotes cross-project lessons, or caps size. That curation half is what /evolve exists for. Claude Code also ships /insights, which analyses your recent sessions, and version 2 runs it as the first step of the cycle rather than duplicating it.

Will it rename my directories to match the spec? No. Every name in the spec is a role, not a requirement. If a docs/ directory already serves as your on-demand layer, the audit adopts it and reports the mapping, because that name is usually baked into other commands, gitignores, and cross-references.

I ran version 1. What do I need to undo? Three things: the PostToolUse typecheck hook in settings.json, the “rules violated this session” check inside /health, and any session-end hook that writes lessons. Delete those, then run version 2. If you followed version 1’s instruction to put ~/.claude under git, the pre-run commit is your clean rollback point.

Does this need the Stanford course? No. The course is where the ideas came from, and the reading list is worth your time, but the instruction stands alone.

What does it actually cost to run? One long planning session to build it, then a dedicated session every few weeks for the curation cycle. Lesson capture and project scaffolding run without you, but the capture rules are deliberately strict, so expect most incidents to be correctly ignored.


Credit to Valerie’s article for surfacing the course, to Stanford for publishing CS329A openly, and to the reviewer who took ten minutes on version 1 and saved everyone who runs version 2 a great deal of noise.

I build free Claude Code tools and write the occasional deep post like this one. There’s more at Resources, or follow along at @jon_egb.