Bootstrapping a New Project with /init

/init is a Claude Code slash command that scans a fresh (or existing) repo and drafts a starting CLAUDE.md for you, so you are not writing project memory from a blank page.

Summary

Every new project eventually needs a CLAUDE.md describing its conventions, structure, and rules.

Writing one from scratch means re-deriving things Claude Code can already see for itself, like the language, the folder layout, and the test setup.

/init closes that gap by having Claude Code look at the project first and produce a draft, which you then read and correct.

It is the fastest path from "no project memory" to "a working CLAUDE.md," even though the result still needs a human pass.

Recipe

Quick-reference recipe card - copy-paste ready.

cd my-project
claude
# once inside the Claude Code session:
/init

When to reach for this:

• Starting a brand-new project and want project memory in place from day one.
• Inheriting an existing repo that has no CLAUDE.md yet.
• The project's conventions have shifted enough that the existing CLAUDE.md is worth regenerating and re-reviewing.
• You want a quick first pass at documenting structure before refining it by hand.

Working Example

Here is a full session from an empty CLAUDE.md to a reviewed one, on a small Node.js API project.

# 1. Start Claude Code inside the project root
cd order-service
claude
 
# 2. Run /init inside the session
/init
 
# Claude Code scans package.json, the folder structure, existing
# README content, test setup, and any config files, then writes
# a first-pass CLAUDE.md to the project root.
 
# 3. Review what it produced
cat CLAUDE.md

A typical first draft from /init looks something like this:

# Project: order-service
 
## Overview
A Node.js REST API for managing customer orders.
 
## Tech Stack
- Node.js, Express
- PostgreSQL via `pg`
- Jest for testing
 
## Structure
- `src/routes/` - Express route handlers
- `src/services/` - business logic
- `src/db/` - database access

# 4. Edit the draft to add anything /init couldn't infer,
#    like team-specific rules and hard constraints.

## Hard Rules
- Never query the database directly from a route handler - go through `src/services/`.
- Always add a test in `__tests__/` for any new route.
- Do not commit directly to `main`.

# 5. Commit the finished file
git add CLAUDE.md
git commit -m "Add CLAUDE.md via /init"

What this demonstrates:

• /init produces a structural first draft (stack, folders, commands) from what it can observe in the repo.
• Team-specific rules and hard constraints are rarely inferable from the code alone - you still add those by hand.
• The generated file is meant to be reviewed and committed like any other project file, not accepted blindly.
• Running /init is quick enough to redo whenever the project's shape has changed significantly.

Deep Dive

How It Works

• /init reads the project's files (package manifests, folder structure, existing docs, config) to infer the tech stack and layout.
• It writes the result to CLAUDE.md at the project root, in plain markdown.
• If a CLAUDE.md already exists, running /init again updates it based on the current state of the project rather than creating a duplicate file.
• The command does not run tests, install anything, or modify code - it only produces documentation.
• What it writes still gets loaded exactly like a hand-written CLAUDE.md at the start of every future session.

What /init Reliably Captures vs What It Doesn't

Re-running /init on an Existing Project

# CLAUDE.md already exists and is a bit stale
/init
 
# Claude Code re-scans the project and updates CLAUDE.md
# to reflect the current structure, rather than starting over

Gotchas

• Accepting the draft without reading it. /init infers what it can see, but it cannot know unwritten team conventions. Fix: always read the generated file end to end before committing it.
• Losing hand-written rules on a re-run. Re-running /init updates the file based on current project state, which can blur together with prior manual edits if you're not paying attention. Fix: diff the file after re-running /init and confirm your hard rules are still there.
• Treating the draft as exhaustive. /init documents what exists, not what should never happen. Fix: add an explicit "Hard Rules" section by hand for anything non-negotiable.
• Running /init in the wrong directory. If run outside the actual project root, the scan produces an inaccurate or empty picture of the project. Fix: confirm you are in the project root (pwd, check for the project's manifest file) before running it.
• Letting the draft go stale. A CLAUDE.md generated once at project start can drift as the codebase evolves. Fix: re-run /init periodically, or update the file by hand when structure changes meaningfully.

Alternatives

FAQs

Related

• What CLAUDE.md Actually Does - the concept /init is bootstrapping.
• Context Management Basics - where /init fits among the section's core tools.
• Writing a CLAUDE.md File That Actually Gets Followed - refining the draft /init produces.
• Nested CLAUDE.md Files and How Scope Inheritance Works - adding scoped rules beyond what /init generates at the root.

Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.