CLAUDE.md Management

Create and maintain CLAUDE.md files that give Claude Code persistent context about your project, coding standards, and preferences.

Prerequisites

• A project directory to configure
• Understanding of the project's tech stack and conventions
• Knowledge of team coding standards and preferences

Workflow

Step 1: Assess the Project

Scan the project to understand its structure:

1. Read package.json, pyproject.toml, Cargo.toml, or equivalent for tech stack
2. Check for existing linter configs (.eslintrc, .prettierrc, ruff.toml)
3. Look for existing documentation (README.md, CONTRIBUTING.md)
4. Identify the test framework and test directory structure
5. Check for CI/CD configuration files
6. Note the directory layout and naming conventions

Step 2: Gather Preferences

Ask the user about preferences not discoverable from the codebase:

1. Code style - beyond what linters enforce (naming conventions, file organization)
2. Architecture patterns - MVC, hexagonal, functional, etc.
3. Commit conventions - conventional commits, ticket references, etc.
4. Testing philosophy - TDD, coverage targets, test naming
5. Tool preferences - preferred commands for build, test, deploy
6. Forbidden patterns - things Claude should never do in this project

Step 3: Structure the CLAUDE.md

Organize the file with these sections:

# Project Overview
Brief description of what the project does and its key technologies.

# Tech Stack
- Language, framework, and major dependencies
- Database and infrastructure details

# Project Structure
Key directories and their purposes.

# Coding Standards
- Naming conventions
- File organization rules
- Import ordering
- Error handling patterns

# Commands
- Build: `<command>`
- Test: `<command>`
- Lint: `<command>`
- Deploy: `<command>`

# Testing
- Framework and test file conventions
- How to run specific tests
- Coverage expectations

# Git Workflow
- Branch naming conventions
- Commit message format
- PR requirements

# Important Notes
- Critical warnings or gotchas
- Things Claude should always or never do

Step 4: Write the CLAUDE.md

Generate the file using the Write tool. Place it at the project root:

1. Use clear, imperative language ("Use camelCase for variables")
2. Keep each section concise and scannable
3. Include actual commands, not placeholders
4. List concrete examples for ambiguous rules
5. Add warnings for common pitfalls

Step 5: Validate the Configuration

Verify the CLAUDE.md is effective:

• Commands listed actually work when run
• Referenced directories and files exist
• Coding standards match existing code patterns
• No contradictory instructions
• File is under 200 lines for optimal context usage
• Critical rules are near the top of the file

Step 6: Maintain Over Time

Update the CLAUDE.md when:

• New dependencies or tools are added
• Coding standards evolve
• Project structure changes
• New team conventions are adopted
• Common mistakes are identified

Output Format

A single CLAUDE.md file at the project root containing:

• Project overview in 2-3 sentences
• Tech stack list
• Project structure summary
• Coding standards as bullet points
• Runnable commands for common tasks
• Testing conventions
• Git workflow rules
• Important warnings and notes

Examples

Example 1: Node.js Web Application

User: "Set up CLAUDE.md for our Express API"

Action: Scan package.json for dependencies, check for ESLint/Prettier configs, identify test framework, and generate a CLAUDE.md with API-specific conventions (route naming, middleware patterns, error response format).

Example 2: Python Data Pipeline

User: "Create CLAUDE.md for our data pipeline project"

Action: Read pyproject.toml, check for ruff/mypy configs, identify the pipeline framework, and generate a CLAUDE.md with data engineering conventions (typing requirements, logging standards, idempotency rules).

Example 3: Monorepo Setup

User: "Configure CLAUDE.md for our monorepo"

Action: Scan the workspace root and each package, identify shared tooling, and generate a root CLAUDE.md with cross-package rules plus guidance on per-package conventions.

Best Practices

1. Be specific over general - "Use zod for validation" beats "validate inputs"
2. Keep it short - Claude reads this every session; respect the context window
3. Put critical rules first - most important instructions at the top
4. Use imperative mood - "Run tests before committing" not "Tests should be run"
5. Include real commands - paste actual CLI commands, not descriptions
6. Update regularly - stale CLAUDE.md causes incorrect behavior
7. Version control it - commit CLAUDE.md so the whole team benefits
8. Avoid duplication - do not repeat what linter configs already enforce

Error Handling