4. Project setup
"/init reads the codebase and writes a starter CLAUDE.md with the build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, it suggests improvements instead of overwriting it. /import brings an existing setup over from Codex, Gemini CLI or Cursor: instruction files, MCP servers, commands, subagents and skills. Both give you a first draft, once. The real setup work is deciding what the team commits, what stays personal, and how instruction files stay in step afterwards."
For a customer, the point that lands: Claude Code setup is a few plain files in the repo, reviewed and versioned like code.
7 pictures, in order.
Use the arrow keys or the dots. Tap a picture to see it full size.
The facts someone can check.
Day one, in order
/initto generate a starter CLAUDE.md./memoryto refine it with what Claude can't discover on its own./mcpto connect the servers the project needs.- Ask Claude to create any subagents you want.
/permissionsto set approval rules.
Then confirm with /context in the next session (CLAUDE.md should appear under Memory files), and run /doctor, which proposes cuts for checked-in CLAUDE.md content Claude can derive from the codebase.
/init has two modes
Default /init |
With CLAUDE_CODE_NEW_INIT=1 |
|
|---|---|---|
| How it runs | Analyzes the code and writes CLAUDE.md, no questions | Asks what to set up, explores with a subagent, asks follow-ups, shows a proposal before writing |
| What it can create | CLAUDE.md | CLAUDE.md files, skills, hooks, and a gitignored CLAUDE.local.md |
| Other tools' files it reads | .cursor/rules/ or .cursorrules, .github/copilot-instructions.md |
Those, plus AGENTS.md, .devin/rules/, .windsurf/rules/ or .windsurfrules, .clinerules |
If /init finds Codex or Gemini CLI configuration, it offers to bring it over with /import. The environment variable only changes how /init runs, so it can stay set.
Moving in from another tool
/init blends other tools' instruction files into the CLAUDE.md it writes. /import carries a whole tool's setup: it appends a one-time copy of instruction files such as AGENTS.md to the matching CLAUDE.md, and brings MCP servers, commands, subagents and skills across.
"One-time copy" is the architect's detail. After an import, the two files drift. For one live source, make @AGENTS.md the first line of CLAUDE.md and put Claude-only lines below it, or symlink CLAUDE.md to AGENTS.md (Claude then edits the target file, and the @AGENTS.md import is the safer choice if anyone clones on Windows).
/import, piece by piece
/import [codex|gemini|cursor] [--dry-run] [--yes].--dry-runpreviews and writes nothing;--yesskips the interactive picker.- With
-p, it lists what it found and prints the command that confirms the import. claude import codex --dry-rundoes the same from your shell (v2.1.213 or later). Importing from Cursor needs v2.1.265 or later.- Not available on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Claude Platform on AWS, through a Claude apps gateway, or when feature-flag fetching is off (for example with
DISABLE_TELEMETRY,DO_NOT_TRACKorCLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICset). Enterprise customers on a cloud provider migrate with/initand an@AGENTS.mdimport instead.
Where each piece of setup lives
| File | What it's for | Shared? |
|---|---|---|
CLAUDE.md |
Instructions loaded every session | Commit |
CLAUDE.local.md |
Your private notes for this project | Personal, gitignore it |
.mcp.json |
MCP servers the team shares | Commit |
.claude/settings.json |
Permissions, hooks, env vars, model defaults | Commit |
.claude/settings.local.json |
Your own overrides | Personal, gitignored when Claude Code saves to it |
.claude/rules/, skills/, agents/, workflows/, output-styles/ |
Rules, skills, subagents, workflows, response styles | Commit |
Managed settings beat every one of these files, and flags such as --permission-mode beat settings.json for one session.
What belongs in a project CLAUDE.md
Include the bash commands Claude can't guess, style rules that differ from defaults, test instructions, repo etiquette, project-specific architecture decisions, environment quirks and non-obvious gotchas. Leave out anything Claude can read from the code, standard conventions, detailed API docs, fast-changing information, tutorials and file-by-file tours. The test for every line: would removing it cause Claude to make mistakes? If not, cut it. Keep the file under 200 lines; workflows go in skills, and anything that must never happen goes in permissions or hooks (Module 1).
Answer out loud, then flip the card.
Mark each one honestly. Cards you miss stay flagged for review, in this browser.
A team is starting a new repo with Claude Code. Walk me through day one.
/init for a starter CLAUDE.md, /memory to add what Claude can't discover, /mcp for the servers the project needs, ask Claude to create any subagents, and /permissions for approval rules. Commit CLAUDE.md, .claude/settings.json and .mcp.json so the whole team gets the same setup. Next session, /context proves CLAUDE.md loaded.
"We spent months on our CLAUDE.md. Will /init wreck it?"
No. When a CLAUDE.md exists, /init suggests improvements instead of overwriting it. That makes it a reasonable audit tool for a mature file, alongside /doctor, which proposes cuts for content Claude can derive from the codebase.
"Half our developers use Cursor and Codex. How do we bring them over without losing their setup?"
Run /import codex --dry-run (and the same for cursor) to preview, then import for real. That carries instruction files, MCP servers, commands, subagents and skills. Then fix the drift problem: the instruction copy is one-time, so make @AGENTS.md the first line of CLAUDE.md, keep shared rules in AGENTS.md, and put only Claude-specific lines in CLAUDE.md. One source of truth for every tool.
"We run Claude Code on Bedrock and /import isn't there." Why, and what now?
/import isn't available on Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry, Claude Platform on AWS, through a Claude apps gateway, or where feature-flag fetching is off. Use /init, which reads Cursor and Copilot rules (and, with CLAUDE_CODE_NEW_INIT=1, AGENTS.md and more), and reference AGENTS.md from CLAUDE.md with @AGENTS.md. MCP servers move by hand into .mcp.json.
What should and shouldn't go in a project CLAUDE.md?
In: commands Claude can't guess, non-default style rules, testing instructions, repo etiquette, architecture decisions, environment quirks, gotchas. Out: anything readable from the code, standard conventions, detailed API docs, information that changes often, tutorials, file-by-file descriptions. Ask of each line whether removing it would cause mistakes. Under 200 lines. Workflows become skills; hard limits become permissions or hooks.
Developers keep committing their personal permission tweaks to the shared settings. What's the pattern?
Personal changes go in .claude/settings.local.json, which is gitignored when Claude Code saves a setting to it, and personal instructions go in CLAUDE.local.md, which you gitignore yourself. .claude/settings.json is for what the team agrees on. Anything the organization requires goes in managed settings, which beat every file in the repo.
"We want setup to also create skills and hooks, and we want to review before anything is written."
Set CLAUDE_CODE_NEW_INIT=1 and run /init. It asks which artifacts to set up (CLAUDE.md, skills, hooks), explores the codebase with a subagent, asks follow-up questions, and shows a proposal to review before writing any files.
How do you prove the setup actually took?
/context for CLAUDE.md under Memory files and the skills listing; /mcp for server status; /hooks for registered hooks; /permissions for the resolved rules; /status for which settings sources are active. Each is a check you can show on screen, which beats saying "it's configured."
Wrong answers that sound right.
Before you tap, say why each one is wrong.
Three moves in a fresh project.
Facts checked against code.claude.com/docs/en/commands, memory, best-practices, claude-directory, cli-reference, env-vars and features-overview on 2026-10-25. Claude Code ships fast: confirm anything that matters against the official docs.