What it does
/init scans your codebase and generates a CLAUDE.md file — a living instruction manual for every developer (and every AI agent) who touches your project. It reads your project structure, package dependencies, ESLint/TypeScript config, environment variables, GitHub Actions workflows, database schemas, and git history to reverse-engineer your tech stack and established conventions. It then writes a structured guide covering your architecture, non-negotiable rules (auth patterns, security checks, rate limiting), styling rules, commit conventions, and anti-patterns to avoid.
The resulting CLAUDE.md lives in your repo root and becomes the canonical source of truth. When you (or an AI) run Claude Code in that directory, the entire guide is automatically loaded into context, so every decision respects your project's rules without needing to ask or explain them each time.
When to use it
Run /init when:
- Starting a new project — lets you document your stack and conventions before you write a single line of feature code
- Onboarding a new developer or AI agent — they can read the entire ruleset in one place instead of piecing together patterns from code review feedback
- Refreshing stale docs — your codebase has drifted from old README notes;
/initre-scans and regenerates - Standardizing across a team — you want consistency in how all your projects document themselves
You don't need to run it every day. Once per quarter is typical, or whenever your stack or conventions shift significantly (new framework version, new security rule, new design system).
Try it yourself
Move to your project directory and invoke /init, then review the generated CLAUDE.md. The file will be quite long — skim the section headings first to understand the structure, then dive into the areas most relevant to your work (auth patterns, database rules, component architecture). If the generated output misses something important or gets something wrong, edit the file directly; it's just Markdown. CI can enforce that it stays current by comparing it against git history.
Gotchas
- The output is a starting point, not finished docs. It reverse-engineers conventions from code, but it can't know your reasoning, priorities, or non-obvious constraints. Read it and flesh it out with sections like "Why we chose X over Y" or "Known limitations we accept."
- Secrets in your codebase will be read. If you have
.envfiles or comments that reference API keys, make sure they're.gitignored before running/init. The generatedCLAUDE.mdis meant to be committed, so never let it contain real secrets. - It reflects what you do, not what you should do. If your code violates your own stated rules,
/initmight codify the violation. Before committing the output, sanity-check that the rules match your intent. - It doesn't generate tests or examples. It documents structure and rules, not how to build features. Pair it with a
DESIGN.md(component inventory, design tokens, interaction patterns) for a complete onboarding package.
Try it yourself
Type the command in the fake terminal. Nothing leaves your browser.