The Senior Engineer's Guide to CLAUDE.md: From Generic to Actionable

Claude Code is not a junior developer you manage. It's a force multiplier for senior engineers who know how to direct it. The difference between a productive and frustrating experience almost always comes down to configuration, specifically your CLAUDE.md files.

The CLAUDE.md Hierarchy You're Probably Missing

Most developers drop a single CLAUDE.md in their project root and call it a day. That's leaving power on the table. Claude Code reads a hierarchy of these files, and understanding this is your first leverage point.

• Global: ~/.claude/CLAUDE.md – Your universal preferences (editor, shell, etc.)
• Project: ./CLAUDE.md – The main project rules and architecture
• Directory: ./subdirectory/CLAUDE.md – Sub-project specific conventions

Directory-level files inherit from the project-level. This means you can have a ./src/CLAUDE.md that adds React-specific linting rules without repeating the project's TypeScript config from the root file. Use this to keep context relevant and token-efficient.

Structure Your CLAUDE.md for Maximum Impact

An effective CLAUDE.md isn't a novel. It's a reference manual. Replace vague directives with this actionable structure:

# Project Context
- Stack: Next.js 15, App Router, Tailwind, Prisma with PostgreSQL
- Key Dependencies: `@auth/prisma-adapter` for auth, `react-query` for data fetching
- Architecture: Feature-based structure under `/src/app/(features)`

# Coding Standards
- Linting: ESLint config extends `@vercel/style-guide`. Always run `pnpm lint:fix`.
- Formatting: Prettier with single quotes, trailing commas. Width 100.
- Naming: React components use PascalCase. Utility functions and hooks use camelCase.

# Tool Preferences
- Package Manager: `pnpm` only. Never use `npm` or `yarn`.
- Testing: Vitest for unit, Playwright for E2E. Place tests in `__tests__` directories.
- Building: Use `pnpm build`. The output is in `/.next`.

# Workflow Patterns
- Branch: Prefix with `feature/`, `bugfix/`, or `hotfix/`.
- PRs: Always include a changeset (`pnpm changeset`) for our monorepo.
- Deployment: Merges to `main` auto-deploy via Vercel.

# Conventions
- `/src/components/ui/` contains shadcn/ui components. Do not modify directly.
- Files in `/src/lib/` are pure utilities without side effects.
- Environment variables are loaded from `.env.local`.

This structure works because it answers the specific questions Claude Code has when operating on your codebase.

Kill These Three CLAUDE.md Anti-Patterns

1. Too Generic: "Follow TypeScript best practices." This is useless. Instead, specify: "Use strict tsconfig. Prefer interface over type for object definitions. Use readonly for array props."
2. Too Verbose: A 500-line manifesto won't be read or followed. Be concise. If a rule is in your linter config, reference the config—don't copy it.
3. Out of Sync: A CLAUDE.md that says "We use Jest" when your package.json shows Vitest creates confusion. Treat CLAUDE.md as living documentation. Update it with the same PR that changes the related code or tooling.

Match the Workspace Mode to the Task

Don't just use Auto mode for everything. Be strategic:

• Ask Mode: Use for architecture discussions, code reviews, or learning a new codebase. It's a conversation without autonomous action.
• Auto Mode: Deploy for multi-step tasks like generating tests across multiple files, executing a refactoring sequence, or writing documentation. Claude Code will execute commands and modify files until completion.
• Preview Mode: Essential for security-sensitive changes. Claude Code will show you proposed changes (diffs) and ask for approval before executing each step.

Configure Guardrails, Not Handcuffs

You can configure allowedCommands and blockedCommands in your settings. The goal is safety, not paralysis.

{
  "allowedCommands": ["git", "pnpm", "docker build"],
  "blockedCommands": ["rm -rf /", "git push --force", "docker system prune -a"]
}

Similarly, use allowedDirectories and blockedDirectories to fence off areas. For example, allow ./src and ./tests but block ./infrastructure or secret directories. Remember: these are guardrails. Critical infrastructure changes should always require human review, regardless of configuration.

Prompt with Precision, Not Hope

Your prompts are the final layer of configuration. Move from weak to strong:

• Weak: "Fix the bug."
• Strong: "Fix the null pointer exception in src/api/users.ts:42. The error occurs when user.organization is undefined. Prefer fixing the root cause in the data loader over adding a defensive null check in the UI component."

For complex tasks, explicitly request a chain of thought: "Think through this database schema change step-by-step, considering: write volume, index performance, and our zero-downtime deployment constraint."

Most importantly, set boundaries to prevent scope creep in Auto mode: "Implement the new auth endpoint. Do not modify the existing login UI component. Do not change the deployment config. Focus on the happy path and the 'invalid token' error case."