Domain 3: Claude Code Configuration & Workflows
20% of examConfigure CLAUDE.md files with appropriate hierarchy, scoping, and modular organization
Key Points
- Hierarchy: user-level (~/.claude/CLAUDE.md), project-level (.claude/CLAUDE.md or root CLAUDE.md), directory-level (subdirectory CLAUDE.md).
- User-level settings apply only to that user and are NOT shared via version control.
- Use .claude/rules/ directory for topic-specific rule files as an alternative to a monolithic CLAUDE.md.
- Use @import syntax to reference external files and keep CLAUDE.md modular.
- New team members not receiving guidelines? Check if instructions are in user-level (~/) rather than project-level (.claude/).
Decision Rules
When: A guideline must apply to all team members (current and future)
→Place it in project-level .claude/CLAUDE.md or .claude/rules/, NOT in user-level ~/.claude/CLAUDE.md.
When: CLAUDE.md exceeds 400+ lines mixing multiple concerns
→Split into topic-specific files in .claude/rules/ (e.g., testing.md, api-conventions.md).
When: A new team member is not receiving project guidelines
→Verify the guideline exists in project-level config, not just in existing developers' user-level config.
✗ Anti-Patterns to Reject
- Putting team-wide guidelines in ~/.claude/CLAUDE.md (user-level) instead of project-level, so new members miss them.
- Using README.md files as instruction sources -- only CLAUDE.md and .claude/rules/ are recognized by Claude Code.
Create and configure custom slash commands and skills
Key Points
- Project-scoped commands in .claude/commands/ (shared via version control); user-scoped in ~/.claude/commands/ (personal).
- Skills in .claude/skills/ with SKILL.md support frontmatter: context: fork, allowed-tools, argument-hint.
- context: fork runs the skill in an isolated sub-agent context, preventing output from polluting the main conversation.
- Project skills take precedence over personal skills with the same name; use a different name for personal variants.
- Skills are on-demand (invoked via slash command); CLAUDE.md is always-loaded for universal standards.
Decision Rules
When: A skill produces verbose output that causes Claude to lose track of the original task
→Add context: fork to the skill's frontmatter to run in an isolated sub-agent context.
When: A developer wants a personal variant of a team skill without affecting teammates
→Create a personal skill in ~/.claude/skills/ with a DIFFERENT name (project skills shadow same-named personal ones).
When: Context is only useful for a specific workflow (e.g., endpoint generation) and not general work
→Create a skill with the exemplar code; invoke on-demand via slash command instead of putting it in CLAUDE.md.
✗ Anti-Patterns to Reject
- Creating a personal skill with the same name as a project skill -- the project version shadows it.
- Putting task-specific workflow guidance in CLAUDE.md (always loaded) instead of a skill (on-demand).
Apply path-specific rules for conditional convention loading
Key Points
- Use .claude/rules/ files with YAML frontmatter paths field containing glob patterns for conditional rule activation.
- Path-scoped rules load only when editing matching files, reducing irrelevant context and token usage.
- Glob patterns apply conventions by file type regardless of directory location (e.g., **/*.test.tsx for all test files).
- Path-specific rules are better than subdirectory CLAUDE.md files when conventions span multiple directories.
Decision Rules
When: Different coding conventions apply to different file types (React components vs API handlers vs tests)
→Create .claude/rules/ files with YAML frontmatter paths glob patterns for each file type.
When: Test files are spread throughout the codebase alongside source files
→Use path-specific rules with **/*.test.tsx glob rather than subdirectory CLAUDE.md files.
When: You want conventions to apply to terraform files in any directory
→Use paths: ['terraform/**/*'] in rule frontmatter instead of a terraform/CLAUDE.md file.
✗ Anti-Patterns to Reject
- Relying on Claude to infer which conventions apply by putting all rules in a single root CLAUDE.md.
- Using subdirectory CLAUDE.md files for cross-cutting concerns like test conventions that span multiple directories.
Determine when to use plan mode vs direct execution
Key Points
- Plan mode: complex tasks with multiple valid approaches, architectural decisions, multi-file changes, unfamiliar domains.
- Direct execution: simple, well-scoped changes with a clear implementation path (e.g., single-file bug fix).
- The Explore subagent isolates verbose discovery output and returns summaries, preserving main conversation context.
- Combine plan mode for investigation with direct execution for implementation (e.g., plan migration, then execute).
Decision Rules
When: Task involves ambiguous requirements with multiple valid integration approaches (e.g., adding Slack support)
→Enter plan mode to explore options and architectural implications before implementing.
When: Task is a well-understood change with clear scope (e.g., bug fix with a clear stack trace)
→Use direct execution -- no need for plan mode.
When: Discovery phase generates verbose output that fills the context window
→Use the Explore subagent to isolate verbose output and return a concise summary to the main conversation.
✗ Anti-Patterns to Reject
- Starting direct execution on an ambiguous architectural task without exploring trade-offs first.
- Using plan mode for a simple, well-scoped change that has an obvious implementation.
Apply iterative refinement techniques for progressive improvement
Key Points
- Concrete input/output examples are the most effective way to communicate transformations when prose is interpreted inconsistently.
- Test-driven iteration: write test suites first, then iterate by sharing test failures to guide improvement.
- The interview pattern: have Claude ask questions to surface design considerations before implementing in unfamiliar domains.
- Address multiple interacting issues in a single message when fixes interact; use sequential iteration for independent issues.
Decision Rules
When: Claude interprets prose requirements differently each iteration, producing inconsistent output structure
→Provide 2-3 concrete input/output examples showing the expected transformation.
When: You are implementing in an unfamiliar domain and want to surface edge cases
→Use the interview pattern: have Claude ask about design considerations before implementing.
When: Multiple bugs interact with each other
→Describe all interacting issues in a single message rather than fixing them sequentially.
✗ Anti-Patterns to Reject
- Continuing to refine prose descriptions when Claude consistently misinterprets them -- provide examples instead.
- Fixing interacting bugs one at a time, leading to regressions when each fix invalidates the others.
Integrate Claude Code into CI/CD pipelines
Key Points
- Use the -p (or --print) flag for non-interactive mode in automated pipelines -- prevents hanging on interactive input.
- Use --output-format json with --json-schema for enforced structured output in CI contexts.
- CLAUDE.md provides project context (testing standards, review criteria) to CI-invoked Claude Code.
- A second independent Claude instance reviewing code is more effective than self-review -- eliminates confirmation bias.
- Include prior review findings in context when re-running after new commits to avoid duplicate comments.
Decision Rules
When: Running Claude Code in an automated CI pipeline
→Use the -p flag for non-interactive mode; use --output-format json with --json-schema for structured output.
When: The same Claude session generated code and you need a review
→Use a second, independent Claude instance without access to the generator's reasoning context.
When: Re-running review after developer pushes fixes, and getting duplicate findings on already-fixed code
→Include prior review findings in context, instructing Claude to only report new or still-unaddressed issues.
✗ Anti-Patterns to Reject
- Running claude without -p flag in CI, causing the job to hang waiting for interactive input.
- Asking Claude to self-review its own generated code in the same session -- confirmation bias persists.