iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Run /init from an interactive Claude Code session opened in your repository. Claude Code examines the project and writes a starting CLAUDE.md containing discoverable facts such as build commands, test commands, project structure, and conventions. Treat that file as a reviewed, living briefing: add decisions and team expectations that source files cannot reveal, keep it concise, and verify that Claude loaded it with /context.
This workflow gives Claude better context on every task, but it does not create a security boundary. Anthropic states that Claude treats instruction files as “context, not enforced configuration.” Use hooks or other technical controls when an action must be blocked.
What /init creates and why it matters
/init is a Claude Code slash command that analyzes the repository in your current working directory and creates (or improves) a project CLAUDE.md. The generated file can record facts Claude can infer from the tree, including how to build, test, lint, and run the application, important directories, and coding conventions. See the official explanation of memory and project instructions in How Claude remembers your project.
That first pass is useful because Claude no longer has to rediscover the same commands and layout in every session. It is not a complete specification of your project, however. Repository files rarely explain why a team chose an architecture, which compatibility promises must not change, or which recurring mistakes reviewers reject. Your review turns an automatically discovered outline into reliable project guidance.
#1 Best Overall
What the command does not guarantee
- It does not know every team decision, unstated workflow, or business constraint.
- It does not overwrite an existing
CLAUDE.md; when one is present, Claude Code suggests improvements instead. - It does not enforce the instructions. A sentence such as “never edit generated files” is guidance, not a technical prohibition.
- It does not replace tests, permissions, hooks, code review, or CI policy.
Before running /init
Install and authenticate Claude Code according to your organization’s setup, then make sure your shell is in the repository you want to document. The current setup instructions show launching Claude Code with claude from the project directory; the official reference is Advanced setup.
- Open a terminal.
- Change to the repository root, for example
cd path/to/your-project. - Start an interactive session with
claude. - Confirm that the displayed working directory is the intended project before allowing analysis or edits.
Run the command at the repository root when you want instructions shared by the whole project. A nested directory can be appropriate for a separately scoped component, but choose that location deliberately so the resulting file is loaded where you expect.
Standard workflow: generate, review, and verify
1. Generate a starting file
At the Claude Code prompt, enter:
/initClaude Code analyzes available project material and proposes or writes a starting CLAUDE.md. Depending on the repository, the result may mention package-manager commands, test runners, source and documentation directories, build artifacts, and visible formatting conventions. The exact content depends on what can be discovered from the files.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →2. Read every generated section
Open CLAUDE.md in your editor and check each command and path against the project’s actual workflow. Remove guesses, obsolete scripts, and details that are true only for one developer’s machine. A short, correct file is more useful than a comprehensive-looking file containing stale instructions.
If a file already existed, compare Claude’s suggestions with the current text rather than accepting them wholesale. Preserve deliberate team decisions, and change wording only when the new version is demonstrably clearer or more accurate.
3. Add information the repository cannot reveal
Write down durable facts that repeatedly save explanation or investigation time. Good additions include:
- The exact build, test, lint, type-check, migration, and local-development commands, including required environment setup.
- Architectural boundaries, such as which package owns database access or which directory is generated and must not be edited.
- Naming, formatting, API, and error-handling conventions that a reviewer can verify.
- Required checks before a pull request or commit, such as a specific test command.
- Compatibility promises, supported runtime versions, and decisions that should not be revisited casually.
- Known corrections that have been repeated in code review and remain valid.
Prefer an instruction such as “Use two-space indentation in src/” over “Format code properly.” Prefer “Run npm test before committing” over “Test your changes.” Concrete wording gives Claude and human reviewers something observable to follow.
4. Keep the always-loaded file focused
Anthropic recommends recording facts Claude should hold in every session and moving specialized material elsewhere. Do not paste an entire operations manual into the root file. Put a multi-step release procedure, a subsystem-specific workflow, or a large reference in a skill or path-scoped rule and link to it from the relevant project instructions. Organize related guidance under descriptive Markdown headings and delete material that no longer reflects current practice.
5. Start a fresh session when validating changes
After editing the file, begin a new Claude Code session when possible. This avoids confusing a newly written instruction with text already present in the current conversation and makes the loading check easier to interpret.
What to put in CLAUDE.md
A practical file answers the questions Claude would otherwise ask or discover repeatedly. The following outline is intentionally compact; adapt the headings to your repository.
# Project overview
## Common commands
- Install: `...`
- Develop: `...`
- Test: `...`
- Lint and type-check: `...`
## Layout and boundaries
- `src/...` owns ...
- `generated/...` is produced by ...; do not edit it directly.
## Working conventions
- Use ... naming in ...
- Run `...` before opening a pull request.
## Decisions and constraints
- Keep ... compatible with ...
- Changes to ... require ...Use exact paths, commands, flags, and prerequisites. Explain an unusual rule in one sentence so Claude understands its purpose, but avoid speculative rationale or instructions that cannot be checked. If a command differs by operating system or package manager, state the supported variant instead of leaving an ambiguous placeholder.
Choose the correct instruction scope
Claude Code can load instructions from several locations. Scope determines who receives the guidance and whether it belongs in version control.
Rank #3
| Location | Best use | Sharing and cautions |
|---|---|---|
./CLAUDE.md |
Project-wide guidance for a repository | Normally committed and shared with teammates. |
./.claude/CLAUDE.md |
Project instructions stored in the Claude-specific directory | Also suitable for team-shared guidance; choose one project convention and keep it consistent. |
~/.claude/CLAUDE.md |
Your preferences across projects | Personal and cross-project; do not put repository-specific rules here. |
./CLAUDE.local.md |
Personal instructions for one project | Keep it out of version control, commonly by adding it to .gitignore. |
| Managed organization instructions | Organization-wide behavioral guidance | Configured by administrators; separate behavioral context from technical settings and enforcement. |
Use the project scope for commands and conventions every contributor should receive. Use the user scope for preferences such as how you like explanations formatted. Use the local scope for private, machine-specific details that teammates should not inherit.
Nested files and path-specific guidance
For a monorepo or a large application, a root file can describe shared rules while a nested instruction file describes one service. Keep each file relevant to the directory where it applies. A narrow rule is less likely to conflict with unrelated work than a root file containing every subsystem’s procedure.
Checking that Claude loaded the instructions
In a Claude Code session, run:
/contextInspect the output’s Memory files section. It should show the project instruction file you intended Claude to load. This check confirms loading; it does not prove that every sentence is correct or that Claude will follow a request in every situation.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →If the expected file is missing
- Check that you launched Claude Code from the repository or directory whose scope you intended.
- Confirm the filename and location exactly:
CLAUDE.md,.claude/CLAUDE.md, or the appropriate personal/local path. - Look for a parent or nested instruction file that changes the effective scope.
- Restart the session after moving or renaming a file.
- Ask Claude to display the applicable instruction sources, then compare that explanation with
/context.
If instructions conflict or appear stale
Separate a factual error from a scope conflict. Correct wrong commands or paths in the file that owns them. If two files give different directions, decide which scope should control, remove the duplicate, and state the surviving rule once. The current slash-command documentation also describes /doctor prompt-audit, an instruction audit that checks CLAUDE.md files, skills, and other configuration for outdated or conflicting guidance. It requires Claude Code v2.1.283 or later; see Extend Claude with skills.
Standard /init versus the new interactive flow
Most users should start with the standard command. An optional mode, enabled with the environment variable CLAUDE_CODE_NEW_INIT=1, changes /init into a multi-phase setup flow.
| Characteristic | Standard /init |
CLAUDE_CODE_NEW_INIT=1 |
|---|---|---|
| Primary result | A generated starting CLAUDE.md |
A proposed instruction setup after a guided exploration. |
| Interaction | Minimal; you review the generated file afterward. | Asks follow-up questions and lets you choose artifacts to set up. |
| Artifacts in scope | Project instructions. | CLAUDE.md files plus possible skills and hooks. |
| Review point | Your editor review after generation. | A reviewable proposal is presented before files are written. |
Use the interactive mode when you want Claude to explore the codebase with a subagent, discuss which artifacts belong in the project, and review a proposal before writing. Regardless of mode, inspect the resulting instructions yourself and test the commands they contain.
AGENTS.md, imports, and version-specific behavior
Claude Code can read AGENTS.md as project instructions, but the selection behavior depends on whether a CLAUDE.md exists in or above the working directory. The documentation states that direct AGENTS.md reading requires Claude Code v2.1.277 or later, and that some sessions may need an import from CLAUDE.md.
If your repository already uses AGENTS.md, do not assume every session will select it identically. Check /context. When the documented default does not produce the scope you want, Anthropic documents importing it from CLAUDE.md with an @AGENTS.md reference. Keep one authoritative version of each rule so edits do not drift between duplicate files.
Context is guidance, not enforcement
Anthropic’s wording is explicit: “Claude treats them as context, not enforced configuration.” An instruction file can strongly influence how Claude plans and edits, but it cannot guarantee that a command will never run or that a protected file will never change.
For a hard restriction, use a technical control such as a PreToolUse hook, repository permissions, protected branches, CI checks, or a review requirement. Put the human-readable explanation in CLAUDE.md and the machine-enforced rule in the appropriate control system. This combination tells Claude what the rule means and makes violations fail or require approval.
Maintenance checklist
Review project instructions whenever the repository’s workflow changes, not only when /init is first run.
Recommended Free Tools
- Run every listed command and confirm its prerequisites.
- Remove scripts, paths, and versions that no longer exist.
- Check that generated directories and ownership boundaries are still accurate.
- Replace vague language with a command, path, naming rule, or verifiable condition.
- Move subsystem-only procedures into a skill or path-scoped rule.
- Check
/contextafter changing scope, filenames, or imports. - Use
/doctor prompt-auditwhen you need a systematic check for stale or conflicting instructions and your Claude Code version supports it. - Keep personal preferences out of the committed project file.
A practical decision path
- No project instruction file: run standard
/init, then add team decisions and exact commands. - A project file already exists: review the suggestions, merge only verified improvements, and preserve intentional rules.
- A large or multi-service repository: keep shared facts at the root and move specialized procedures into scoped files or skills.
- You need proposal review and artifact selection: enable
CLAUDE_CODE_NEW_INIT=1before running/init. - You need to confirm loading: run
/contextand inspect Memory files in a fresh session. - You need a guarantee: do not rely on
CLAUDE.md; add a hook, permission, branch protection, or CI enforcement.
Common mistakes to avoid
Accepting generated guesses
A command inferred from a package file may omit a required service, environment variable, or working directory. Run it yourself and document the prerequisite beside the command.
Writing a handbook into the root file
Long, rarely used procedures consume context in every session. Keep the always-loaded file to durable, project-wide facts and link specialized instructions from a scoped location.
Mixing personal and team rules
A preference that makes sense for one developer can surprise the rest of the team when committed. Put it in ~/.claude/CLAUDE.md or CLAUDE.local.md instead.
Confusing visibility with compliance
/context proves that a file was loaded, not that a requested action is technically blocked. Pair context with enforcement when the consequence matters.
Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minutePC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Frequently Asked Questions
Does running /init overwrite an existing CLAUDE.md?
No. When a project file already exists, Claude Code suggests improvements rather than overwriting it. Review those suggestions and merge only changes that match the repository’s current practice.
Which command shows whether project instructions loaded?
Run /context in Claude Code and inspect the Memory files section. Start a new session after changing instruction files so the result reflects the current scope.
Can CLAUDE.md prevent Claude from running a command?
No. Anthropic describes these files as context, not enforced configuration. Use a PreToolUse hook, permissions, CI, or another technical control for a hard restriction.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minute
