Claude Code Configuration & Workflows

Three levels. User-level ~/.claude/CLAUDE.md applies to you alone and is not shared through version control. Project-level — .claude/CLAUDE.md or a root CLAUDE.md — travels with the repository and reaches everyone who clones it. Directory-level CLAUDE.md files apply within their subtree.

That hierarchy explains the classic bug report: a new team member does not get the conventions everyone else seems to have. The instructions were in someone's user-level file, which was never in the repo at all.

Keep large configurations modular. @import references external files so each package's CLAUDE.md pulls in only the standards its maintainers care about. Alternatively, split a monolith into .claude/rules/ topic files — testing.md, api-conventions.md, deployment.md — which reads better and is easier to review.

When behaviour differs between sessions and you cannot see why, /memory shows which memory files are actually loaded.

A command in .claude/commands/ is version-controlled and available to everyone who pulls the repository. The same command in ~/.claude/commands/ is yours alone. If the requirement contains the words "every developer", the answer is the project directory.

Skills live in .claude/skills/ as SKILL.md files with frontmatter. Three options matter on the exam. context: fork runs the skill in an isolated sub-agent context, so a verbose codebase analysis or an exploratory brainstorm does not pollute the main conversation. allowed-tools restricts what the skill can do while it runs — limiting it to file writes, for instance, so it cannot take destructive action. argument-hint prompts the developer for parameters when they invoke the skill bare.

To customise a shared skill for yourself, create a variant in ~/.claude/skills/ under a different name rather than editing the team's copy.

The choice between a skill and CLAUDE.md is about loading: CLAUDE.md is always-loaded universal standards, a skill is on-demand invocation for a task-specific workflow.

Files under .claude/rules/ can carry a YAML frontmatter paths field with glob patterns. The rule loads only when the file being edited matches. That does two things: it keeps irrelevant conventions out of context, and it makes the association deterministic rather than inferential.

The case that decides this objective is conventions for files spread across the tree. Test files sit next to the code they test — Button.test.tsx beside Button.tsx — so a directory-level CLAUDE.md cannot catch them; you would need one in every directory. A rule with paths: ["**/*.test.tsx"] catches all of them wherever they live.

Compare the alternatives honestly. A consolidated root CLAUDE.md with headers relies on the model inferring which section applies. Skills need to be invoked or chosen. Only path-scoped rules give you automatic application keyed on the file path.

Plan mode is for large-scale change, multiple valid approaches, architectural decisions and multi-file work. It buys safe exploration and design before you commit to anything, which is what prevents expensive rework when a dependency surfaces late.

Direct execution is for well-scoped, well-understood change: a single-file bug fix with a clear stack trace, adding a date validation conditional. Planning those is ceremony.

Read the question for whether complexity is already stated. "Restructure the monolith into microservices, dozens of files, decisions about service boundaries" is not complexity that might emerge — it is complexity in the requirements, so starting direct and switching later is the wrong answer.

The two combine well: plan the library migration, then execute the planned approach directly. And during a plan's discovery phase, the Explore subagent isolates verbose output and returns a summary, which is how a multi-phase task avoids exhausting its context window.

When prose keeps being interpreted differently, stop writing prose. Two or three concrete input/output examples communicate a transformation better than any paragraph, because they leave nothing to interpret.

Test-driven iteration is the same idea with a feedback loop attached: write the suite first — expected behaviour, edge cases, performance requirements — then iterate by sharing the failures. Each round is grounded in something observable.

The interview pattern is for unfamiliar domains. Have Claude ask you questions before implementing, and it surfaces the considerations you had not thought of — cache invalidation strategy, failure modes — while changing them is still cheap.

One decision worth getting right: when several problems interact, put them all in one detailed message so the fixes are designed together. When they are independent, fix them sequentially.

The -p (or --print) flag runs Claude Code non-interactively: it processes the prompt, writes the result to stdout and exits. Without it, a pipeline job waits for interactive input and hangs. This is the documented mechanism — there is no CLAUDE_HEADLESS variable and no --batch flag.

For machine-readable output, --output-format json with --json-schema produces structured findings you can post as inline PR comments without parsing prose.

CLAUDE.md is how CI-invoked Claude Code learns your project: testing standards, fixture conventions, review criteria. Documenting what makes a test valuable and which fixtures exist is the difference between generated tests worth merging and generated noise. Passing existing test files in context stops it from proposing scenarios you already cover.

On re-runs after new commits, include the prior findings and instruct it to report only new or still-unaddressed issues — otherwise every run re-posts the same comments. And remember that the session that wrote the code is not the best reviewer of it: an independent instance without the generator's reasoning context catches more.