Good instructions to Claude Code is the difference between an app that ships and a buggy mess nobody wants to debug. The new project onboarding flow simplified that work a lot, basically an interview. It extracts what's non-obvious, sets up hooks and skills, asks the questions you'd forget to answer. But you still need to know what happens when it finds your CLAUDE.md already there.
And what happens is not what most posts have described.
TLDR: /init isn't an improved generator. On a repo with an existing CLAUDE.md, it switches to audit mode: it reads your file, cross-references against lockfiles and configs, and surfaces what stopped matching while the code moved forward. On the 4th repo, 64 lines, it found 5 silent lies. The difference between generating and correcting is the whole article.
On a fresh repo, yes, it generates. The community ran with that, reasonably. "Setup 10x easier," the CLAUDE.md writes itself now. True for a blank slate. But the most common case is a repo that already has documentation, written early, before the codebase became what it actually is. The moment /init detects an existing file, it doesn't replace: it audits. Cross-references the CLAUDE.md against lockfiles, configs, schemas, and surfaces what no longer matches. That's the job.
I ran it on 4 repos over a few days.
I Expected a Generator. I Got an Auditor.
Thariq from the Claude Code team posted the env var flag in March: CLAUDE_CODE_NEW_INIT=1, preview mode, interview-based setup flow. A thread on r/ClaudeAI from the same week had 118 comments on a question that stuck: "Be honest: when Claude writes a long plan, do you actually read it? Or do you just say looks good?" The doc nobody rereads was already a live pain point in the community.
I set the flag and ran /init across the 4 repos.
What I expected on each: a CLAUDE.md with a stack section, a commands block, some conventions. Boilerplate I'd clean up manually. The kind of output that gives you a starting point and needs a human pass to be actually useful.
What I got instead: on 3 of the 4 repos, /init detected an existing file and immediately shifted behavior. On a blank repo it generates from scratch. With a file already present, the approach is different. It reads the current CLAUDE.md, reads the codebase, finds the gaps where what you wrote no longer matches what the code actually is.
Documentation drift doesn't announce itself. It's not like a build error or a failing test. It's more like corruption in a save file: the game keeps running, the numbers look fine, and then the boss fight hits and the stats don't add up to what was promised. By the time you notice, you've been playing on wrong assumptions for a while.
Claude Code's docs describe the new /init as following the "only include what Claude wouldn't infer on its own" principle. On an existing repo that means: first determine what the code actually is, then compare that to what's documented, then surface the delta. The delta is what matters.
2 Repos That Already Knew Themselves
Repo 1 was my main product dashboard: the central project, about 150-line CLAUDE.md, written early and updated occasionally. /init returned 11 new lines.
The additions were architectural facts that weren't in the file: the central data entity the whole system revolves around, a routing rule that funnels all helper logic to a specific module, 2-level auth (end-user vs machine-to-machine), an isolated scheduled task that runs outside the normal request cycle. None documented. All inferable from the code if you read deeply and cross-reference the imports.
Then it flagged 1 lie. The CLAUDE.md referenced npm install and localhost:3000. bun.lock was in the root. The project had been running on a different port for months. Both had been true at some point, both had quietly stopped being true, and nothing had broken. npm commands still execute on a bun project, mostly. The wrong port just means you try the wrong URL once, then the right one, and forget about it. Easy to miss. Easy to leave.
Repo 2 was a different problem. A project with close to 700 lines of carefully maintained CLAUDE.md, updated after each significant change. /init read the whole thing, scanned the codebase, came back with 3 lines. The bun test runner had been added recently and wasn't documented. No rewrite, no structural changes, just the missing commands.
And a verdict: "Your CLAUDE.md is already well beyond what /init would generate here."
(I keep a 500-line internal doc on a completely separate project, nothing to do with any of this, that I've been updating for 2 years because I find the writing clarifying. My daughter walked in once while I was rewriting a section header and asked why I was writing a book about my code. I didn't have a good answer. Anyway.)
A tool that knows when to stop is as rare as one that knows when to start.
The Repo With No Map
The 3rd repo: a multi-frontend catalog delivery system. Multiple Astro frontends, a Hono backend, SQLite, no CLAUDE.md, no README at the root. Started quickly because the shape was clear, documentation was for later, and later kept moving.
/init returned a complete architecture map in 4 parallel tool passes. The independent reads go out simultaneously: root config, Hono routes, Astro configs, build scripts, deploy notes. The reconstruction is fast because the calls don't wait on each other.
The same principle applies here as in how Claude Code builds project context from an existing codebase: a structured, accurate map is almost always the work that makes subsequent sessions stop going sideways. The map either exists and is correct, or the model improvises, and improvising on the wrong picture compounds quickly.
The key invariant it surfaced that I wouldn't have written down: Astro runs under Node, everything else under Bun. That detail was buried in a comment in the deploy script and a fnm use 22 call in the build script. An architectural constraint specific to how Astro's build process works, completely undocumented. Every Claude Code session on this repo had been operating without it.
What the 4 passes assembled concretely: the SQLite schema, an export pipeline serializing content to per-site JSON bundles, the Astro build sequence under Node 22 (not Bun, because Astro's SSG renderer required it), an rsync step to nginx with rewrite rules already defined, and a Cloudflare Worker handling edge routing in front of the whole thing. The full delivery chain from raw SQLite rows to rendered static files behind Cloudflare, documented in one pass. No directory tree, no generic project advice. Specific enough to navigate without asking.
5 Lies in 64 Lines
The 4th repo: my product processing pipeline. Full stack, Convex backend, Vite/Express frontend, secrets managed through Infisical. The CLAUDE.md had 64 lines, written 3 months earlier, accurate at the time.
/init found 5 places where the documentation had quietly become fiction.
1. The package manager
The CLAUDE.md instructed: npm install, npm run dev. bun.lock was in the root. The migration to bun had happened at some point and the docs hadn't followed. Claude Code had been running npm commands on a bun project, silently, without error, because most npm commands still execute. The incompatibility hides until dependency resolution diverges and you spend an afternoon figuring out why.
2. The missing workflow states
The CLAUDE.md documented 3 order status codes in the Convex schema: draft, published, archived. The actual schema had 7. The 4 missing ones handled edge cases: processing, failed, review, scheduled. The states that matter for any non-trivial operation. Every Claude Code session had been writing logic against a model of the system that was 4 states short.
3. The Convex folder
The CLAUDE.md described convex/ as the main processing layer. That had been true early. Over 3 months, the heavy work had migrated into server.js: PDF generation for product sheets, image resizing, webhook dispatch to partner integrations. The Convex functions became thin routing. The actual processing happened in a file the docs had stopped mentioning.
4. The undocumented mode switch
A shell script in the root toggled the stack between managed Convex Cloud and a self-hosted Convex instance depending on deployment target. Zero mention in the CLAUDE.md. Every Claude Code session had been assuming a static backend connection, when there was a manual switch step with real consequences for where data landed.
5. The port that takes 3 files to find
The CLAUDE.md said the dev server runs on port 3150. The actual port: 3002. Vite proxied to Express on 3002, PORT was injected by Infisical, vite.config.ts was the bridge between all 3. To find the real port, you needed to cross-reference 3 files. /init did that cross-reference. I had not. For 3 months.
Nobody lied deliberately. The CLAUDE.md had been accurate. The code had moved the way code always moves: not in dramatic rewrites but in 10 decisions per week, each one too small to feel like it warranted a doc update. After 3 months, 5 of those decisions had drifted past what was written.
Interlude: the dirty git tree
This repo had uncommitted state. A deleted package-lock.json, an untracked backup file sitting in the root. /init didn't skip the repo, didn't force the tree, didn't write over the working directory.
It ran 5 git steps in sequence: created a worktree on a dedicated branch, made edits in isolation, committed with a conventional commit message, fast-forward merged into main, then cleaned up the worktree and deleted the branch. WIP untouched, git history clean.
The reason this worked cleanly: versioned git hooks that enforce this workflow. The model didn't choose caution. It operated within project constraints it couldn't bypass. That's a different guarantee than relying on the model's goodwill, and it's worth understanding the difference between model goodwill and real tooling discipline before you decide how much trust to put in either.
What /init Cannot Do
/init audits what's traceable. Files it can read, configs it can cross-reference, schemas it can compare against documentation. That's a real capability, underrated because the output looks simple. The port lie alone saved me a debugging session I didn't want to have.
But there's a category of knowledge it can't touch.
The git hook that forced the worktree workflow exists because, months before /init existed, I came close to wiping a live working session by letting a Claude Code run commit directly to main on a dirty tree. The hook was the fix I coded that afternoon. It's documented in its own code but not in any CLAUDE.md. /init saw the hook and referenced it correctly, but it couldn't tell me why the sequence mattered, or what would happen if someone deleted it assuming it was boilerplate cleanup, or what the afternoon that produced it had cost in lost work.
That knowledge lives in the incident. The most valuable project rules tend to come from something that broke, not from a file scan or an onboarding interview. You can document the what but not the history of why, and the why is usually the part that keeps the mistake from repeating. /init is an audit tool, not a retrospective. It finds present lies, not past lessons, and knowing that difference is most of the reason to trust what it surfaces.
I think the other half of making /init useful is getting your documentation to a state worth auditing in the first place. If you're early in a project, the gap between "what I intend this codebase to be" and "what Claude Code actually needs documented" is the work that Vibe Coding, For Real maps out, specifically the distinction between intent documentation and implementation documentation. /init is only useful on implementation. The intent is still yours to write.
Launch /init tonight on your oldest repo. Not to get a clean CLAUDE.md. To find out how many lines are already lying. 😬
Sources
- Thariq (@trq212), Claude Code team: X post announcing CLAUDE_CODE_NEW_INIT=1, March 2026
- Claude Code Docs, Week 16 changelog (April 13-17, 2026)
- r/ClaudeAI, GummySearch community data, June 2026
- wmedia.es: "/init in Claude Code: way more than a CLAUDE.md template," April 2026
This post may contain affiliate links. If you click them, I might earn a small commission (costs you nothing, and helps me keep shipping quality articles every day for your reading pleasure).
Top comments (0)