CLAUDE.md and Settings: What Teams Should Actually Configure

Put stable, repo-specific facts in CLAUDE.md

A good CLAUDE.md tells Claude what it cannot infer cheaply: package manager, test commands, code style exceptions, review etiquette, architecture constraints, generated-file rules, and deployment boundaries.

A bad CLAUDE.md becomes a private wiki. Long API docs, tutorials, file-by-file explanations, and frequently changing notes should live elsewhere. If a section only matters for one workflow, make it a skill and load it on demand.

Primary-source anchor: Anthropic advises keeping CLAUDE.md concise and reserving it for commands, style rules, workflow rules, repo etiquette, and non-obvious behavior.

Match settings scope to ownership

Claude Code settings have different scopes. Managed settings suit organization policy. User settings suit personal preferences across projects. Project settings suit repository-wide collaboration. Local settings suit private, repo-specific overrides.

Do not commit personal defaults as project policy. Do not rely on local settings for team safety. If a setting matters to everyone in the repo, document it and commit it where the team expects shared configuration.

• Managed Organization or machine policy for requirements that should not be optional.
• User Personal defaults that follow one developer across projects.
• Project Shared repository configuration committed for collaborators.
• Local Private repository overrides that should stay out of git.

Primary-source anchor: Anthropic documents managed, user, project, and local scopes, with different locations and sharing behavior.

A starter CLAUDE.md structure

The best structure is boring: commands, constraints, review rules, and gotchas. Avoid prose that sounds important but never changes behavior.

Keep links to deeper docs instead of pasting them. Claude can fetch or read referenced files when needed, and you preserve context for the current task.

# Commands
- Build: npm run build
- Focused tests: npm test -- <name>

# Workflow
- Inspect existing patterns before editing.
- Run the smallest relevant test first; run the full build before final handoff.
- Do not edit generated files directly.

# Review
- Final response must list changed files and verification output.

# Gotchas
- API responses use snake_case at the wire boundary and camelCase internally.

Use local overrides for personal workflow, not team truth

Personal machine details, preferred editor, private test data paths, or local credentials should not leak into shared instructions. Keep them in local settings or a local instruction file that your gitignore excludes.

When local knowledge becomes team knowledge, promote it deliberately: add the stable command or gotcha to CLAUDE.md, link to the source, and remove the stale local workaround.

Review instructions after failures

When Claude repeatedly misses a project rule, do not immediately add more text. First ask whether the rule is hidden in a long file, ambiguous, contradicted by code, or better enforced by a hook.

Treat CLAUDE.md as production documentation. It should be reviewed in PRs, pruned after migrations, and tested by observing whether it changes future sessions.