Claude Code Configuration & Workflows

CLAUDE.md files are markdown instructions Claude reads at the start of every session. They exist in a hierarchy loaded from broadest to most specific scope, so more-specific files appear later in context and effectively override broader ones on conflict. The order is: managed policy (e.g. macOS /Library/Application Support/ClaudeCode/CLAUDE.md, org-wide, cannot be excluded), user (~/.claude/CLAUDE.md, personal, all your projects), project (./CLAUDE.md or ./.claude/CLAUDE.md, shared with the team via version control), and local (./CLAUDE.local.md, personal per-project, gitignored). Claude also walks up the directory tree concatenating ancestor files, and discovers subdirectory CLAUDE.md files on demand when it reads files there.

The critical scoping rule for diagnostics: user-level settings apply only to you and are never shared with teammates via git. If a new team member isn't receiving an instruction, it likely lives in ~/.claude/CLAUDE.md (or CLAUDE.local.md) rather than the committed project CLAUDE.md. The fix is to move it to ./CLAUDE.md.

Keep files modular. The @path/to/import syntax expands external files into context at launch; both relative (resolved relative to the importing file) and absolute/~/ paths work, and imports can recurse up to a maximum depth of four hops. This lets each package's CLAUDE.md selectively import only the standards files its maintainer knows are relevant. The first time Claude encounters imports in a project it shows an approval dialog.

For larger codebases, prefer the .claude/rules/ directory: drop topic-specific files like testing.md, api-conventions.md, deployment.md. All .md files there load automatically (no import needed) with the same priority as .claude/CLAUDE.md, are committed to source control, and are easier for teams to maintain than one monolithic file. Target under ~200 lines per CLAUDE.md; bloated files reduce adherence.

Use the /memory command to list every CLAUDE.md, CLAUDE.local.md, and rules file loaded in the current session. If a file isn't listed, Claude can't see it - the first step in diagnosing inconsistent behavior across sessions.

Skills extend Claude Code with reusable instructions packaged as a SKILL.md file inside a skill directory. Where the skill lives sets its scope: project skills in .claude/skills/<name>/SKILL.md are committed and shared with the team; personal skills in ~/.claude/skills/<name>/SKILL.md apply across all your projects and aren't shared. Custom commands have merged into skills - a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. The directory name becomes the command you type; the frontmatter name is only a display label.

Key frontmatter fields: description (how Claude decides when to load it - put the key use case first), argument-hint (autocomplete hint like [issue-number] shown when the developer invokes without args), allowed-tools (pre-approves listed tools so Claude uses them without prompting while the skill is active - it grants, it does not by itself restrict), context: fork (run in an isolated subagent), agent (which subagent type when forking: Explore, Plan, general-purpose), and disable-model-invocation: true (only you can trigger it - use for side-effecting workflows like deploy/commit).

context: fork is the isolation lever: the SKILL.md content becomes the subagent's prompt, it runs without your conversation history, and only a summary returns to the main session. Use it for skills that produce verbose output (codebase analysis) or exploratory context (brainstorming alternatives) you don't want polluting the main conversation. Forking only makes sense for skills with an actual task, not pure reference guidelines.

For personal customization without affecting teammates, create a personal variant in ~/.claude/skills/ under a different name rather than editing the shared project skill.

Choosing skills vs CLAUDE.md: CLAUDE.md is always-loaded universal standards (facts that apply in every session); skills load on demand only when invoked or deemed relevant, so long task-specific procedures cost almost nothing until needed. Move a CLAUDE.md section to a skill once it becomes a multi-step procedure rather than a standing fact.

Path-specific rules let conventions load conditionally, only when Claude works with files matching a glob pattern, instead of consuming context in every session. They live as markdown files in .claude/rules/ with YAML frontmatter containing a paths field of glob patterns. A rule WITHOUT a paths field loads unconditionally (same priority as .claude/CLAUDE.md); a rule WITH paths triggers only when Claude reads files matching the pattern, not on every tool use.

Glob patterns match by extension, directory, or any combination - for example **/*.ts (all TypeScript anywhere), src/**/* (everything under src/), *.md (markdown in the project root), src/components/*.tsx (a specific directory). You can list multiple patterns and use brace expansion to cover several extensions in one entry, e.g. src/**/*.{ts,tsx}.

The central skill is choosing path-specific rules over subdirectory (directory-level) CLAUDE.md files when a convention applies to files by TYPE regardless of where they live. Test files, for instance, are scattered throughout a codebase; a single .claude/rules/testing.md scoped to paths: ["**/*.test.tsx"] applies your testing conventions everywhere those files appear and loads only when one is opened. Achieving the same coverage with directory-level CLAUDE.md files would require duplicating the convention into every directory that contains tests, and those files would still load whenever Claude works anywhere in that directory tree. Path scoping reduces irrelevant context and token usage by loading the convention precisely when it's relevant.

The paths glob format is the same one used by skill frontmatter paths, so the mental model transfers between rules and skills. Rules in .claude/rules/ are committed to source control, so the whole team inherits the conditional conventions, and they support symlinks for sharing across projects.

Plan mode tells Claude to research and propose changes without making them: it reads files and runs read-only exploration but does not edit your source until you approve a plan. Enter it by pressing Shift+Tab to cycle (default -> acceptEdits -> plan), prefixing a single prompt with /plan, or starting with claude --permission-mode plan; set permissions.defaultMode: "plan" in .claude/settings.json to make it the project default. Press Ctrl+G to open the proposed plan in your editor before Claude proceeds; approving exits plan mode into an execution mode (auto, accept edits, or manual review).

Plan mode is designed for complex work: large-scale changes, multiple valid approaches, architectural decisions, and multi-file modifications - for example microservice restructuring, a library migration affecting 45+ files, or choosing between integration approaches with different infrastructure requirements. It enables safe exploration and design before committing, preventing costly rework from solving the wrong problem.

Direct execution is appropriate for simple, well-scoped changes where you already know what needs to happen: a single-file bug fix with a clear stack trace, adding one date-validation conditional, a typo, a log line, or a rename. The official heuristic: 'If you could describe the diff in one sentence, skip the plan.' Plan mode adds overhead, so don't apply it to trivial changes.

The two combine well: plan mode for investigation, then direct execution for the planned implementation (plan a library migration, then execute the approved approach). For the verbose discovery phase, use the Explore subagent - a read-only agent optimized for codebase exploration that runs investigation in an isolated context and returns only a summary, so raw file contents never enter and exhaust your main conversation. This is the recommended pattern for multi-phase tasks: explore (in a subagent), plan, then implement.

Iterative refinement is the practice of converging on correct output through tight feedback loops rather than expecting a perfect first pass. The most reliable lever when prose is interpreted inconsistently is concrete input/output examples: provide 2-3 example pairs that pin down the exact transformation you expect. Natural-language descriptions of a transformation are ambiguous; examples are not.

Test-driven iteration is the strongest verification loop. Write a test suite first that covers expected behavior, edge cases, and performance requirements, then iterate by sharing the failing test output back to Claude so each pass is guided by a concrete pass/fail signal. Giving Claude a check it can run itself (tests, a build, a screenshot diff) is what lets it close the loop without you as the verification bottleneck. For a specific edge case (e.g. null values in a migration script), hand over a precise test case with example input and expected output.

The interview pattern surfaces design considerations you may not have anticipated before any code is written. Start with a minimal prompt and ask Claude to interview you using the AskUserQuestion tool - it probes technical implementation, UI/UX, edge cases, failure modes, and tradeoffs (such as cache invalidation strategies), then can write a self-contained spec. This is especially valuable in unfamiliar domains. Run the implementation in a fresh session against the written spec.

Knowing how to batch feedback matters: when problems interact (a fix for one affects another), provide all of them in a single detailed message so Claude can reason about them together; when problems are independent, fix them sequentially. Correcting the same issue more than twice usually means context is polluted with failed approaches - clear it and restart with a sharper prompt incorporating what you learned, rather than piling on more corrections.

Claude Code runs non-interactively for CI/CD with the -p (or --print) flag, which sends a single prompt and prints the result without starting an interactive session - essential so a pipeline never hangs waiting for input. Pair it with --allowedTools (or a locked-down permission mode like dontAsk) so tool calls don't block on approval prompts, and --append-system-prompt to inject a role such as a security reviewer.

For machine-parseable findings, use --output-format json to wrap the response with metadata (result, session_id, cost, usage). To enforce a specific shape, add --json-schema with a JSON Schema definition; the structured result is returned in the structured_output field (the plain text answer is in result). This produces deterministic objects you can pipe into jq and post as inline PR comments. (Note: text, json, and stream-json are the three output formats; stream-json is for real-time streaming.)

CLAUDE.md is the mechanism for giving CI-invoked Claude project context it can't infer: testing standards, valuable-test criteria, available fixtures, and review criteria. Documenting these improves test-generation quality and cuts low-value output. Provide existing test files in context so generated tests don't duplicate scenarios already covered, and include prior review findings when re-running after new commits, instructing Claude to report only new or still-unaddressed issues to avoid duplicate comments.

Session context isolation is the key quality principle: the same session that generated code is biased toward it and is a weaker reviewer than an independent instance. A fresh-context review (a new claude -p invocation, a subagent, or the bundled /code-review in interactive use) sees only the diff and criteria, so it evaluates on its own terms. Remember that user-invoked skills and built-in commands like /code-review are interactive-only and not available in -p mode; in headless runs, describe the task directly instead.