Configuration worth having | AI-Assisted Development Wiki

Files and what to do with them

Locations from the official documentation; check the pages linked below for your version
File	Scope	Commit?
`CLAUDE.md` or `.claude/CLAUDE.md`	Project instructions, shared	Yes
`CLAUDE.local.md`	Your personal instructions for this project	No. Add it to `.gitignore`.
`~/.claude/CLAUDE.md`	Your instructions for all projects	Not in a repository
`.claude/settings.json`	Project settings, shared (permission rules, for example)	Yes
`.claude/settings.local.json`	Your settings for this project	No. The tool adds it to your global git excludes when it writes the file; add it to `.gitignore` yourself if you create it by hand.
`~/.claude/settings.json`	Your settings for all projects	Not in a repository
`.claude/worktrees/`	Worktrees created by `--worktree`	No. The documentation recommends ignoring it.

Settings precedence, highest first: managed, command line (--settings), project local, project shared, user. List-type settings such as permissions.allow merge across the non-managed files. Transcripts are kept outside the repository, under ~/.claude/projects/; treat that directory as holding source and command output. See settings, memory and the .claude directory.

.gitignore entries

.gitignore

# AI assistant: local only
.claude/settings.local.json
CLAUDE.local.md
.claude/worktrees/

Also ignore whatever local environment files the repository already uses, such as .env files, so they never become readable by accident through a commit. The tool can copy ignored files into new worktrees if you list them in a .worktreeinclude file; decide deliberately what goes there.

Verify

Shell

git check-ignore -v .claude/settings.local.json CLAUDE.local.md .claude/worktrees/x
git status --short    # nothing under .claude/ should appear as untracked

git check-ignore -v prints the rule that matches each path and prints nothing for a path that is not ignored.

What CLAUDE.md should contain

The file is read at the start of a session from the working directory and its parents; files in subdirectories are read when needed. Keep it short and specific to the repository. /init generates a first draft to edit. Put in it only what the tool cannot learn by reading the code.

Naming conventions for files, branches, commits, tests and identifiers, with one example each.
Build and test commands, exactly as typed, including which one is the single check to run before finishing a change.
Repository-specific traps: a script that must run after editing a source file, generated output, a case-sensitive path, a flag that must not be changed.
What must not be edited automatically: generated files, lock files, the frozen test directory, migrations already applied, anything holding credentials.
Git rules: whether it may create branches or commit, and the message format if it may.

CLAUDE.md skeleton

# Project instructions

## Commands
- Build: <build command>
- Test (run before finishing any change): <test command>

## Conventions
- Branches: <pattern>      Commits: <format>
- Tests live in <dir> and mirror the source layout.

## Traps
- <file> is generated by <script>; edit the source, then re-run <script>.
- <trap specific to this repository>

## Do not edit
- <generated files>, <lock files>, <frozen test directory>
- Do not create branches, commit or push unless asked.

Instructions are guidance, not enforcement

A line in CLAUDE.md asks; it does not prevent. Anything that must hold, such as “do not edit the test directory” or “do not push”, also needs a permission rule or a CI check. See the CI checklist.

Permission modes by kind of work

The modes below are those listed in the permission-modes documentation; the CLI accepts manual as an alias of default. Defaults changed between versions (in recent releases the interactive default is auto, and claude -p defaults to default), so start a session with an explicit --permission-mode when it matters, and watch the mode indicator.

Kind of work	Mode	Why
Reading an unfamiliar codebase, reviewing, designing a change	`plan`	Reads are allowed; edits stay blocked until you approve a plan.
Edits where you read each diff	`default` (Manual)	Asks before most edits, shell commands and network access.
Repetitive edits in a branch you will review as a whole	`acceptEdits`	Runs file edits and common filesystem commands in the working directories without asking; shell commands still prompt.
Unattended runs in CI	`dontAsk` with an explicit allow list	Anything that would prompt is denied, so a run cannot stall or widen its own access.
An isolated container or VM with no credentials and no route out	`bypassPermissions`	Runs everything; deny rules still apply. Not for a workstation or a shared runner.
Routine work where a classifier reviewing each action is acceptable	`auto`	Runs actions after a classifier reviews them. Decide per environment whether that is sufficient.

auto and bypassPermissions are ignored when set in project or local settings files, so a committed file cannot switch them on for everyone. Official page: permission modes.

Unofficial notes, not affiliated with or endorsed by Anthropic. Command names, flags and behaviour change between versions; the official documentation and the tool's own help output are authoritative.