Generate your first CLAUDE.md from the repo with /init

You could open an empty CLAUDE.md and start typing everything the agent keeps forgetting about the payments service. Don’t — at least not first. Most of what you’d write on day one is stuff the agent can find by reading the repo: the test command is in package.json, the directory layout is right there in src/, the linter config announces the style. Making yourself transcribe what the code already states is exactly the kind of toil this chapter is supposed to kill. So you let the agent do the first draft.

One command, a drafted baseline

/init tells Claude to analyze your codebase and write a starting CLAUDE.md for it — build and test commands, project structure, and the conventions it can infer from the code it reads.

> /init

  ⏵ Read  package.json
  ⏵ Read  README.md
  ⏵ Bash  ls src/
  ⏵ Read  src/routes/charges.js
  ⏵ Glob  **/*.test.js

  Wrote CLAUDE.md:

  # payments-service
  ## Commands
  - Test: `npm test`
  - Lint: `npm run lint`
  - Dev server: `npm run dev`
  ## Architecture
  - Charge endpoints in src/routes/, gateway calls in src/services/
  - Migrations in migrations/, run with `npm run migrate`
  ...

What lands is a real, repo-grounded baseline: the test command you were typing every morning is now captured, written down once, loaded into every future session for free. That single entry already pays back the daily tax from the chapter intro.

A few things worth knowing about how /init behaves, because they shape how you use it. If a CLAUDE.md already exists, /init doesn’t clobber it — it reads what’s there and suggests improvements instead. And if your repo already carries an AGENTS.md (the cross-tool convention) or even a .cursorrules file, /init reads those too and folds the relevant parts into the CLAUDE.md it generates, so you’re not re-describing the project for each agent. The exact behavior, including an optional interactive multi-phase flow, is documented on the memory page.

Generated, not finished

/init gives you a baseline, not a final answer. It captures what’s discoverable from the code. It cannot know the things that live only in your head — that charges are stored in cents, that retries must be idempotent, that nobody touches the legacy v1/ routes. Those come next, by hand.

Read the draft, don’t rubber-stamp it

Treat the generated file like a generated plan from the last chapter: useful, fast, and not automatically right. Open it and read it. /init infers, and inference can be subtly off — it might guess yarn test when your team standardized on npm, or describe a directory’s purpose from its name rather than its contents. Every wrong line in CLAUDE.md is worse than no line, because it’s a confident falsehood loaded into every session. Five minutes reading the draft now saves you from an agent that’s been quietly misinformed for a month.

So the workflow is: run /init, read what it wrote, correct what it got wrong, delete what it padded. You’ve turned a blank page into a near-complete first draft in one command, and spent your own effort only on the last mile — the judgment the agent couldn’t supply.

That last mile is the real skill, though, and it’s worth its own lesson. A CLAUDE.md full of the wrong kind of content is just expensive noise the agent drags into every conversation. So what actually earns a place in the file?