Agents & Tool Use
CLAUDE.md Configuration and Claude Code Workflows
CLAUDE.md hierarchy, .claude/rules/ with glob patterns, custom commands and skills, plan mode vs direct execution, and CI/CD integration.
intermediate · 10 min read
Claude Code's power comes from configuration that shapes how it operates across your codebase and team.
Configuration Hierarchy
Three levels of CLAUDE.md, each with different scope:
User level (~/.claude/CLAUDE.md): Personal preferences. Applies only to you. NOT shared via version control. If you put critical team conventions here, new team members won't have them.
Project level (.claude/CLAUDE.md or root CLAUDE.md): Team coding standards, testing conventions. Shared via version control. Every developer who clones the repo gets these instructions.
Directory level (subdirectory CLAUDE.md): Package-specific rules. Applies when editing files in that directory.
Use @import syntax to keep CLAUDE.md modular by referencing external files. The .claude/rules/ directory organizes topic-specific rules as an alternative to a monolithic CLAUDE.md.
Path-Specific Rules
Create files in .claude/rules/ with YAML frontmatter glob patterns:
Rules with paths: ["**/*.test.tsx"] load only when editing matching files. This is superior to directory-level CLAUDE.md when conventions span multiple directories (test files spread throughout a codebase).
Custom Commands and Skills
Commands in .claude/commands/ are project-scoped (shared via VCS) or ~/.claude/commands/ for personal use. Skills in .claude/skills/ support richer frontmatter: context: fork for isolated execution, allowed-tools to restrict tool access, and argument-hint for parameter prompts.
Plan Mode vs Direct Execution
Plan mode is for complex tasks: large-scale changes, multiple valid approaches, architectural decisions. It enables safe exploration before committing to changes.
Direct execution is for well-scoped changes: single-file bug fix, adding a validation check. The scope is clear and there's one obvious approach.
CI/CD Integration
The -p flag runs Claude Code in non-interactive mode (required for CI). Combine with --output-format json and --json-schema for machine-parseable structured output. Always use an independent Claude session for code review, not the same session that generated the code.