The /init command

Claude Code can bootstrap project memory with /init. The sections below condense the official docs and spell out a practical split between generated CLAUDE.md content and AGENTS.md you maintain yourself.

What /init is

According to How Claude remembers your project in the Claude Code documentation:

• /init generates a starting CLAUDE.md. Claude analyzes your repository and drafts a file with build commands, test commands, and conventions it infers from the tree.
• If CLAUDE.md already exists, /init suggests improvements instead of blindly overwriting it.
• Optional interactive flow: with CLAUDE_CODE_NEW_INIT=1, /init can run a multi-step setup where you choose artifacts (for example CLAUDE.md, skills, hooks). A subagent explores the codebase, may ask follow-up questions, and shows a proposal before anything is written.

So /init is a convenience for creating or refining Claude’s project instruction file. It is not a substitute for your own judgment about what the team should standardize on.

Why we do not want to live in that generated file

The output of /init is auto-discovered content meant to give Claude a quick picture of the repo. It tends to be long, generic in places, and tied to Claude Code’s filename (CLAUDE.md). For a real team repo you usually do not want that blob to be the only place where human-curated standards live.

Do not treat the raw /init output as the file your team evolves over months. Running it once to see what Claude infers is fine; keep long-term standards in a short, intentional instructions file you own (for example AGENTS.md imported from CLAUDE.md).

CLAUDE.md vs AGENTS.md

CLAUDE.md is Claude Code’s project instruction file. Other tools do not standardize on that name the same way.

AGENTS.md is the portable convention many coding agents and teams use for shared project rules (build, test, style, architecture). It is the right place to put everything you want the project to know so any agent (or human) can read one file.

The same Claude documentation recommends bridging the two: Claude Code reads CLAUDE.md, not AGENTS.md. If the repo already uses AGENTS.md, you should create a CLAUDE.md that pulls it in so you do not duplicate or fork your rules.

Instructions are suggestions, not guarantees

The documentation frames project memory as context, not enforced configuration. That applies to everything you put in CLAUDE.md, AGENTS.md, or imported rules: you are steering the agent, not flipping a switch.

Think of it as politely asking the model to prefer certain commands, patterns, or guardrails. It may still ignore, forget, or reinterpret what you wrote, especially under pressure, long sessions, or conflicting instructions. There is no guarantee it will follow every line every time.

When something must hold (security, API contracts, release process), treat markdown as one signal among many. Keep human review, tests, and CI as the real backstops.

What we do in practice

Per the docs, imports use @ syntax. A minimal root CLAUDE.md can look like this:

@AGENTS.md

## Claude Code

Add only instructions that apply specifically to Claude Code here, if needed.

That way one file (AGENTS.md) stays canonical, and Claude Code still loads everything because CLAUDE.md includes it at session start.

When you outgrow a single file, split topics in ways your team agrees on (for example more markdown files under .claude/rules/ for Claude-scoped rules) but keep shared, agent-neutral guidance in AGENTS.md so you are not locked to a single vendor’s layout.

Example prompts

After /init produced a long CLAUDE.md:

CLAUDE.md was generated with /init and it is huge. Compare it to the repo and propose what belongs in AGENTS.md as human-maintained standards versus what to delete or trim. Then show a minimal root CLAUDE.md that only @imports AGENTS.md plus a short "## Claude Code" section if truly needed. Do not edit files yet, outline the diff you would apply.

Once AGENTS.md is canonical:

Rewrite root CLAUDE.md to stay under ~30 lines: @AGENTS.md first, then "## Claude Code" with only Claude-specific notes (hooks, paths). Apply the change.

See also