CLAUDE.md Design Principles: Build Your Project Constitution

Your CLAUDE.md is the most important file in any Claude Code project. It’s not just configuration—it’s a constitution that defines how Claude understands and works with your codebase.

A well-crafted CLAUDE.md transforms Claude from a generic assistant into a specialized team member who knows your standards, respects your constraints, and produces consistent results.

This guide covers the official memory system and the 7 principles that separate exceptional CLAUDE.md files from the rest.

Understanding Claude Code’s Memory System

The Four-Layer Memory Hierarchy

According to the official Claude Code documentation, Claude Code uses a four-layer memory hierarchy where more specific layers override more general ones:

┌─────────────────────────────────────────────────┐
│  Layer 1: Enterprise/Organization               │
│  Location: /etc/claude-code/settings.json       │
│  Scope: All users in organization               │
│  Control: IT department                         │
│  Purpose: Security policies, MCP allowlists     │
├─────────────────────────────────────────────────┤
│  Layer 2: User Global                           │
│  Location: ~/.claude/CLAUDE.md                  │
│           ~/.claude/settings.json               │
│  Scope: All your projects                       │
│  Purpose: Personal preferences, global tools    │
├─────────────────────────────────────────────────┤
│  Layer 3: Project                               │
│  Location: ./CLAUDE.md or ./.claude/CLAUDE.md   │
│           ./.claude/settings.json               │
│  Scope: Team-shared, version controlled         │
│  Purpose: Project standards, conventions        │
├─────────────────────────────────────────────────┤
│  Layer 4: Project Local                         │
│  Location: ./CLAUDE.local.md                    │
│  Scope: Personal only (gitignored)              │
│  Purpose: Individual overrides                  │
└─────────────────────────────────────────────────┘

Priority order: Project Local > Project > User Global > Enterprise

What Each Layer Controls

Layer	CLAUDE.md	settings.json	Purpose
Enterprise	Org policies	MCP allowlist, tool restrictions	Compliance
User Global	Personal style	Global MCP, plugins	Preferences
Project	Team standards	Project MCP, permissions	Consistency
Project Local	Personal overrides	Local testing	Flexibility

Configuration Files Explained

CLAUDE.md - Natural language instructions Claude reads at session start:

# Project Constitution
- All code must have tests
- Use TypeScript strict mode
- Follow existing patterns

settings.json - Structured configuration for tools and permissions:

{
  "permissions": {
    "allow": ["Read", "Write", "Edit", "Bash(npm:*)"],
    "deny": ["Read(.env)"]
  },
  "enableAllProjectMcpServers": true,
  "ignorePatterns": ["node_modules/**", ".git/**"]
}

Modular Rules with Path-Specific Configuration

For complex projects, use the .claude/rules/ directory (v2.0.20+):

your-project/
├── .claude/
│   ├── CLAUDE.md           # Main constitution
│   ├── settings.json       # Permissions, MCP
│   └── rules/
│       ├── code-style.md   # Coding standards
│       ├── testing.md      # Test requirements
│       ├── security.md     # Security policies
│       └── api.md          # API conventions

Rules can be path-specific using frontmatter:

---
paths: src/api/**/*.ts
---

# API Development Rules
- All endpoints must validate inputs using Zod
- Use standardized error responses from src/lib/errors.ts
- Include OpenAPI documentation comments

This means the rules only apply when Claude is working on files matching src/api/**/*.ts.

The 7 Design Principles

Principle 1: Clarity over Cleverness

Write clear, unambiguous instructions. Claude should understand your intent immediately without interpretation.

Don’t do this:

# Code should be good
Write clean code. Follow best practices.

Do this instead:

# Code Standards
- Use TypeScript strict mode (no `any` types)
- Functions must have explicit return types
- Maximum function length: 50 lines
- Maximum file length: 300 lines
- Use early returns to reduce nesting

Why it matters: Vague instructions lead to inconsistent results. “Good code” means different things to different people. Specific standards produce reproducible outcomes.

Principle 2: Hierarchy of Authority

Layer your configuration from general to specific. Each layer should have a clear purpose.

Structure:

# CLAUDE.md

## Non-Negotiables (Cannot be overridden)
- All PRs require tests
- No credentials in code
- Security review for auth changes

## Project Defaults (Can be overridden per-task)
- Prefer functional programming style
- Use named exports over default exports
- Write documentation for public APIs

## Preferences (Suggestions, not requirements)
- Consider performance implications
- Prefer composition over inheritance

Why it matters: Not all rules are equal. Some are absolute (security), others are guidelines (style). Making this explicit prevents Claude from violating critical rules while allowing flexibility where appropriate.

Principle 3: Permissions, Not Restrictions

Define what Claude CAN do rather than what it can’t. Enable efficient work instead of constantly blocking.

Don’t do this:

# Restrictions
- Don't modify production files
- Don't run destructive commands
- Don't commit without asking
- Don't install packages without approval

Do this instead:

# Autonomous Operations (No confirmation needed)
- Read any file in the project
- Run tests and linting
- Create/modify files in src/ and tests/
- Install devDependencies
- Create local branches

# Requires Confirmation
- Modifying .env or config files
- Installing production dependencies
- Pushing to remote branches
- Deleting files

Why it matters: A restrictive CLAUDE.md creates friction. Claude constantly asks for permission, breaking your flow. A permissive CLAUDE.md with clear boundaries enables autonomous work while protecting what matters.

settings.json Permission Syntax

From the official documentation:

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Bash(npm run:*)",
      "Bash(git:*)"
    ],
    "deny": [
      "Read(.env)",
      "Read(secrets/**)"
    ]
  }
}

Pattern syntax:

• Bash(npm run:*) - Allow all npm run commands
• Bash(git:*) - Allow all git commands
• Read(.env) - Deny reading .env files
• Read(secrets/**) - Deny reading anything in secrets/

Principle 4: Context is King

Provide relevant context upfront. The more Claude knows, the better it performs.

Essential context to include:

# Project Overview
A Next.js 14 e-commerce platform with:
- App Router architecture
- Prisma + PostgreSQL database
- Stripe for payments
- Resend for emails

# Directory Structure
src/
├── app/           # Next.js App Router pages
├── components/    # Shared React components
├── lib/           # Utility functions and configs
├── services/      # Business logic
└── types/         # TypeScript type definitions

# Key Files
- src/lib/db.ts - Database client (Prisma)
- src/lib/auth.ts - Authentication utilities (NextAuth)
- src/services/ - Domain-specific logic

# Commands
- npm run dev - Start development server (port 3000)
- npm test - Run tests (Vitest)
- npm run lint - Check code quality (ESLint)
- npm run build - Production build

Import other files for details:

See @README.md for project overview.
See @docs/architecture.md for system design.
See @package.json for available scripts.

Why it matters: Context eliminates guesswork. When Claude knows your tech stack, file structure, and conventions, it produces code that fits naturally into your project.

Principle 5: Actionable Standards

Every guideline should be actionable. If Claude can’t directly apply it, it’s not useful.

Not actionable:

- Write type-safe code
- Follow security best practices
- Make it performant

Actionable:

# Type Safety
- Enable TypeScript strict mode in tsconfig.json
- Never use `any` - use `unknown` and narrow with type guards
- Define interfaces for all API responses in src/types/

# Security
- Validate all user inputs using Zod schemas
- Sanitize data before database queries
- Use parameterized queries exclusively (Prisma handles this)
- Never log sensitive data (passwords, tokens, PII)

# Performance
- Lazy load components over 50KB using next/dynamic
- Use React.memo for components with expensive renders
- Add database indexes for queries taking >100ms
- Use React Server Components for data fetching

Why it matters: “Best practices” is meaningless without specifics. Actionable standards translate directly into code decisions Claude can make.

Principle 6: Escape Hatches

Define when rules can be broken. Rigid rules cause frustration; flexible rules with clear exceptions enable pragmatism.

# Testing Requirements
All features must have tests.

**Exceptions:**
- Prototypes and experiments (prefix with `_experimental`)
- One-time scripts in `scripts/`
- When explicitly told to skip tests

# Documentation Requirements
Public APIs must have JSDoc comments.

**Exceptions:**
- Internal utilities with obvious names
- Generated code
- Test files

Why it matters: Real-world development requires flexibility. Without escape hatches, you’ll find yourself constantly overriding your own rules. Explicit exceptions are better than implicit rule-breaking.

Principle 7: Living Document

Your CLAUDE.md evolves with your project. Version control it, review it regularly, and update it based on what works.

# CLAUDE.md

Last updated: 2026-01-10
Version: 2.3

## Changelog
- 2.3: Added API error handling standards
- 2.2: Updated test coverage requirements (80% → 85%)
- 2.1: Added security review requirements for payment code
- 2.0: Major restructure for clarity

## Feedback
If these guidelines cause friction, document the issue
in `.claude/feedback.md` for review.

Review triggers:

• After completing a major feature
• When Claude consistently misunderstands something
• When team members join or leave
• When technology stack changes

Agent Delegation Rules

Define when Claude should delegate to specialized agents:

## Agent Delegation

### Automatic Triggers
- Files in auth/, payment/, admin/ → security-auditor
- New API endpoints → code-reviewer
- Performance-sensitive code → benchmark first

### Manual Triggers
- Complex refactoring → Parallel Explore agents
- Full codebase review → Multi-agent analysis
- Architecture decisions → Plan agent

### Agent Configuration
code-reviewer:
  - Check for OWASP Top 10 vulnerabilities
  - Verify error handling patterns
  - Ensure consistent code style

security-auditor:
  - Scan for hardcoded secrets
  - Check authentication flows
  - Verify input validation

Knowledge Graph Memory (MCP)

Claude Code supports persistent memory through the Memory MCP:

# Add Memory MCP with project isolation
claude mcp add --scope project memory \
  -e MEMORY_FILE_PATH=./.claude/memory.json \
  -- npx -y @modelcontextprotocol/server-memory

Important: Always use MEMORY_FILE_PATH for project isolation. Without it, all projects share the same memory.

Memory commands:

• /memory-save - Save important decisions
• /memory-search - Find saved knowledge
• /memory-list - List all entities
• /memory-audit - Check memory health

Practical Template

Here’s a complete CLAUDE.md template incorporating all principles:

# Project Constitution

## Project Overview
[One paragraph describing what this project does]

## Tech Stack
- Framework: [e.g., Next.js 14, App Router]
- Language: [e.g., TypeScript 5.x, strict mode]
- Database: [e.g., PostgreSQL via Prisma]
- Testing: [e.g., Vitest + React Testing Library]

## Directory Structure
src/
├── app/           # [Purpose]
├── components/    # [Purpose]
├── lib/           # [Purpose]
└── services/      # [Purpose]

## Commands
- `npm run dev` - Start development
- `npm test` - Run tests
- `npm run lint` - Check code quality

## Code Standards

### TypeScript
- Strict mode enabled
- No `any` types (use `unknown`)
- Explicit return types on functions

### React
- Functional components only
- Use React Server Components by default
- Client components must be explicitly marked

### Testing
- All features require tests
- Minimum 80% coverage for new code
- Integration tests for API routes

## Autonomous Operations
Claude may freely:
- Read all project files
- Create/modify files in src/ and tests/
- Run tests and linting
- Create local git branches

## Requires Confirmation
- Installing production dependencies
- Modifying environment variables
- Pushing to remote
- Deleting files

## Agent Delegation
- Complex refactoring → Parallel Explore agents
- Security-sensitive changes → security-auditor
- API changes → code-reviewer

## Non-Negotiables
- All code must have tests
- No secrets in code
- Security review for auth/payment code

Common Mistakes

Mistake 1: Too Long

A 500-line CLAUDE.md defeats the purpose. Keep it scannable.

Fix: Extract detailed guides to .claude/rules/ and import them.

Mistake 2: Too Vague

“Write good code” isn’t actionable.

Fix: Convert every guideline into a specific, checkable requirement.

Mistake 3: Too Restrictive

Requiring confirmation for everything creates friction.

Fix: Identify what’s truly risky and permit everything else.

Mistake 4: Never Updated

A stale CLAUDE.md causes confusion.

Fix: Set a monthly review reminder. Update after major features.

Mistake 5: Copy-Pasted

Using someone else’s CLAUDE.md without adaptation.

Fix: Start with a template but customize for your project’s specific needs.

Mistake 6: Ignoring Layer Hierarchy

Putting everything in project CLAUDE.md instead of using appropriate layers.

Fix: Personal preferences in ~/.claude/CLAUDE.md, project standards in project CLAUDE.md, individual tweaks in CLAUDE.local.md.

Getting Started

Today:

1. Run /init in your project to create a basic CLAUDE.md
2. Add your project overview and tech stack
3. Define 3-5 non-negotiable rules

This week:

1. Add directory structure and key files
2. Define autonomous operations vs requires confirmation
3. Add your most important code standards

This month:

1. Refine based on actual usage
2. Add agent delegation rules
3. Extract detailed guides to .claude/rules/ directory
4. Set up Memory MCP for persistent knowledge

Measuring Success

Your CLAUDE.md is working when:

• Claude produces code that matches your style on first try
• You rarely need to correct the same mistake twice
• New team members can onboard faster
• Code reviews have fewer style comments

Your CLAUDE.md needs work when:

• Claude keeps asking clarifying questions
• You’re constantly correcting the same patterns
• Output is inconsistent between sessions
• You find yourself repeating context in prompts

---

The best CLAUDE.md files aren’t written in a day—they evolve through use. Start simple, observe what works, and iterate.

Sources: Claude Code Documentation, Claude Code GitHub, Memory MCP