Create Environment-Specific CLAUDE.md Files for Dev, CI, and Review Contexts

A single CLAUDE.md works for most projects, but sometimes you need different behaviour in different contexts — CI should be strict and read-only, development should be exploratory, and code reviews should focus on quality. You can achieve this with a combination of --append-system-prompt and CLAUDE.md design.

Structure your CLAUDE.md with a shared base and environment-specific overrides:

# CLAUDE.md — shared base

## Common Commands
- Tests: `pnpm test`
- Lint: `pnpm lint:fix`

## Code Conventions
- Use TypeScript strict mode
- Follow existing patterns in sibling files

Then use --append-system-prompt in different contexts to add environment-specific rules:

# Development — exploratory, can modify files freely
claude --append-system-prompt "Dev mode: feel free to experiment, run tests, and iterate."

# CI — strict, read-only analysis
claude --print --append-system-prompt \
  "CI mode: Do NOT modify any files. Only analyze and report issues. \
   Focus on: test failures, lint errors, and type errors." \
  "Analyze the changes in this PR"

# Code review — quality focused
claude --append-system-prompt \
  "Review mode: Focus on code quality, naming, patterns, and test coverage. \
   Don't fix things — explain what should change and why."

For teams, wrap these in scripts or aliases:

# In package.json or Makefile
"scripts": {
  "claude:dev": "claude",
  "claude:review": "claude --append-system-prompt 'Review mode: ...'",
  "claude:ci": "claude --print --append-system-prompt 'CI mode: ...'"
}

You can also use .claude/rules/ files with path-based scoping to load specific rules for different parts of the codebase — stricter rules for the API layer, more flexible rules for internal tooling.

The key insight: the base CLAUDE.md stays the same, but the context changes how Claude applies those rules.

One codebase, many contexts — shape Claude's behaviour for each one instead of finding a one-size-fits-all middle ground.

via Claude Code