Claude Code Configuration & Workflows

You want a /review command that every developer gets when they clone or pull the repo — so create it in the project-scoped .claude/commands/ directory (shared via version control), not ~/.claude/commands/, which is personal. Skills are different: they live in .claude/skills/ as SKILL.md files whose frontmatter configures behavior — context: fork runs the skill in an isolated sub-agent context so its verbose output never pollutes the main conversation, allowed-tools restricts which tools it may call, and argument-hint prompts the developer for required parameters when they invoke it bare.

The choice between a skill and CLAUDE.md is about loading: a skill is invoked on-demand for a task-specific workflow, while CLAUDE.md is always loaded as universal standards. To customize a team skill without affecting teammates, create a personal variant in ~/.claude/skills/ under a different name.

Key Behaviors

• Project commands go in .claude/commands/ (shared via version control); personal commands in ~/.claude/commands/
• Skills are .claude/skills/ + SKILL.md; frontmatter supports context: fork, allowed-tools, and argument-hint
• context: fork isolates verbose (codebase analysis) or exploratory (brainstorming alternatives) output in a sub-agent, keeping the main session clean
• allowed-tools restricts tool access during skill execution (e.g. limit to file writes to prevent destructive actions); argument-hint prompts for missing parameters
• Skills = on-demand task-specific workflows; CLAUDE.md = always-loaded universal standards; personal skill variants go in ~/.claude/skills/ under a different name

How It Works

Distractor Traps (common wrong answers)

• Putting a team-shared command in ~/.claude/commands/ — that location is personal and not shared via version control
• Treating CLAUDE.md as a command container — it holds project instructions and context, not command definitions
• Defining commands in a .claude/config.json with a commands array — no such mechanism exists in Claude Code
• Letting a verbose skill pollute the main conversation instead of isolating it with context: fork

Faded Example (SKILL.md frontmatter)

---
name: review-checklist
description: Run the team's standard code-review checklist
context: fork          # isolate verbose output in a sub-agent
allowed-tools: Read, Grep, Glob   # restrict tool access during execution
argument-hint: <pr-number>        # prompt when invoked without arguments
---

Recommended Material

Your test files sit next to the code they test (Button.test.tsx beside Button.tsx), scattered across every directory, and you want all of them to follow the same conventions automatically. A .claude/rules/ file with YAML frontmatter paths globs does exactly this: paths: ["**/*.test.tsx"] makes the rule load only when Claude edits a matching file, applying conventions by file type regardless of location — and irrelevant rules stay out of context, reducing token usage.

This beats a subdirectory CLAUDE.md, which is directory-bound and can't follow files spread throughout the codebase. Choose glob-pattern path rules whenever a convention must apply to files of a type wherever they live (e.g. paths: ["terraform/**/*"] for all Terraform); reserve directory-level CLAUDE.md for conventions that really are confined to one directory.

Key Behaviors

• .claude/rules/ files use YAML frontmatter paths: globs for conditional activation (paths: ["terraform/**/*"])
• Path-scoped rules load only when editing matching files — irrelevant context stays out, cutting token usage
• Glob patterns apply conventions by file type regardless of directory (**/*.test.tsx for every test file)
• Choose path-specific rules over a subdirectory CLAUDE.md when conventions span multiple directories
• A subdirectory CLAUDE.md is directory-bound; it cannot cover files scattered across the codebase

How It Works

Distractor Traps (common wrong answers)

• Consolidating conventions in the root CLAUDE.md "under headers for each area" — relies on Claude inferring which section applies, not explicit matching
• Creating "skills for each code type" as automatic convention loaders — skills require manual invocation, not automatic path matching
• Placing a separate CLAUDE.md in each subdirectory for cross-directory conventions — directory-bound, can't handle files spread across many directories

Faded Example (.claude/rules/test-conventions.md — YAML frontmatter)

---
description: Conventions for all test files, wherever they live
paths: ["**/*.test.tsx"]   # loads only when editing a matching file
---
- Use Testing Library queries; avoid container.querySelector
- One behavioral assertion per test where practical

Recommended Material

You're asked to restructure a monolith into microservices — dozens of files, decisions about service boundaries and module dependencies. Start in plan mode: it lets Claude explore the codebase and design an approach before committing to any change, which prevents the costly rework that comes from discovering dependencies late. Plan mode is for complex tasks — large-scale changes, multiple valid approaches, architectural decisions, multi-file modifications.

Reserve direct execution for simple, well-scoped changes: a single-file bug fix with a clear stack trace, adding one date-validation conditional. During verbose discovery phases, hand the work to the Explore subagent so its output is isolated and only a summary returns — keeping the main conversation's context window from filling up. The combined pattern is the expert move: plan the migration in plan mode, then switch to direct execution to implement it.

Key Behaviors

• Plan mode: large-scale changes, multiple valid approaches, architectural decisions, multi-file modifications (e.g. a library migration affecting 45+ files)
• Direct execution: simple, well-scoped changes — a single validation check, a one-file bug fix with a clear stack trace
• Plan mode enables safe exploration and design before committing to changes, preventing costly rework
• The Explore subagent isolates verbose discovery output and returns summaries, preserving the main context window
• Combine both: plan mode for investigation, then direct execution for the planned implementation

How It Works

Distractor Traps (common wrong answers)

• "Start with direct execution and make changes incrementally" for an architectural task — risks costly rework when dependencies surface late
• "Switch to plan mode only if you encounter unexpected complexity" — the complexity is already stated in the requirements, not something that might emerge
• Direct execution "with comprehensive upfront instructions" — assumes you already know the right structure without exploring the code
• Entering plan mode for a trivial, well-scoped single-file change — unnecessary overhead

Recommended Material

When a prose description gets interpreted inconsistently, the most effective fix is to show 2–3 concrete input/output examples of the transformation you want — examples communicate intent that adjectives can't. Pair that with test-driven iteration: write a test suite covering expected behavior, edge cases, and performance first, then iterate by sharing the failing tests so Claude converges on correct behavior. To fix a specific edge case (null values in a migration script), give a test case with the exact example input and expected output.

In an unfamiliar domain, use the interview pattern — have Claude ask you questions up front to surface considerations you might not have anticipated (cache-invalidation strategy, failure modes) before it implements. Finally, batch your fixes by dependency: put multiple interacting issues in one detailed message so the fixes account for each other; handle independent issues sequentially.

Key Behaviors

• Provide 2–3 concrete input/output examples when natural-language descriptions produce inconsistent results
• Test-driven iteration: write tests for behavior, edge cases, and performance first, then iterate by sharing failures
• Interview pattern: have Claude ask questions to surface design considerations (cache invalidation, failure modes) in unfamiliar domains
• Give a specific test case with example input and expected output to fix edge-case handling (e.g. null values in migration scripts)
• Interacting issues → one detailed message (fixes interact); independent issues → fix sequentially

How It Works

Distractor Traps (common wrong answers)

• Adding more prose description when it's interpreted inconsistently, instead of giving concrete input/output examples
• Fixing independent issues all in one message, or interacting issues one at a time — mismatching batching to dependency
• Implementing in an unfamiliar domain without the interview pattern to surface hidden considerations first
• Iterating without a test suite, so there is no concrete failure signal to guide progressive improvement

Recommended Material

Your pipeline runs claude "Analyze this pull request" and the job hangs forever — Claude Code is waiting for interactive input. The fix is the -p (--print) flag, which runs it non-interactively so automated jobs don't hang. To make the output machine-parseable for posting as inline PR comments, pair --output-format json with --json-schema so findings come back in a fixed, enforced structure.

Feed project context through CLAUDE.md — testing standards, fixture conventions, review criteria — so CI-invoked Claude Code generates higher-value output. When re-running a review after new commits, include the prior findings in context and instruct Claude to report only new or still-unaddressed issues so it doesn't post duplicate comments; likewise, provide existing test files so generated tests don't duplicate scenarios already covered. One subtlety of session context isolation: the same session that generated the code is less effective at reviewing its own changes — use an independent review instance.

Key Behaviors

• -p (--print) runs Claude Code non-interactively so CI jobs don't hang waiting for input
• --output-format json with --json-schema produces machine-parseable structured findings for automated inline PR comments
• Provide project context via CLAUDE.md (testing standards, fixtures, review criteria) to CI-invoked Claude Code
• Re-running after new commits: include prior findings and instruct Claude to report only new/unaddressed issues to avoid duplicate comments; supply existing test files to avoid duplicate test scenarios
• An independent review instance reviews more effectively than the session that generated the code (session context isolation)

How It Works

Distractor Traps (common wrong answers)

• Setting CLAUDE_HEADLESS=true to run in CI — that environment variable does not exist
• Adding a --batch flag for non-interactive mode — no such flag exists
• Redirecting stdin from /dev/null as the CI fix — a Unix workaround that doesn't address Claude Code's command syntax
• Reusing the same session that generated the code to review it — less effective than an independent review instance

Faded Example (CI step — non-interactive, structured output)

# CI pipeline step — non-interactive run, machine-parseable findings
claude -p "Review this diff for security issues" \
  --output-format json \
  --json-schema ./review-schema.json

Recommended Material