CLAUDE.md Authoring

Core Principles

.claude/rules/

@imports

Degrees of Freedom

• High freedom (guidance): Multiple valid approaches, context-dependent decisions
• Medium freedom (patterns): Preferred approach exists, some variation acceptable
• Low freedom (strict rules): Operations are fragile, consistency critical, specific sequence required

File Locations

./CLAUDE.md

./.claude/CLAUDE.md

./.claude/rules/*.md

./CLAUDE.local.md

~/.claude/CLAUDE.md

~/.claude/rules/*.md

Creating a New CLAUDE.md

Quick Start

/init

Essential Sections

# Project Name

Brief context (1-2 sentences): what this is, primary language/framework.

## Before Starting Work

Before exploring the codebase via file reads or bash commands, ask the user for:
- Existing architecture diagrams or documentation
- File tree documentation or codebase maps
- Relevant context from previous sessions
- Links to design docs, ADRs, or wikis

This avoids redundant exploration. After any significant discovery, update this CLAUDE.md.

## Project Structure

[Key directories and their purposes - avoids repeated `find` and `ls` commands]

- `src/api/` - REST endpoints, organized by resource
- `src/services/` - Business logic, one service per domain
- `src/models/` - Database models (Prisma)
- `tests/` - Mirrors src/ structure

## Commands

- Build: `pnpm run build`
- Test: `pnpm run test`
- Lint: `pnpm run lint`

## Architecture

[Non-obvious patterns, key abstractions, data flow]

## Conventions

- [Specific, actionable rules]
- [Things Claude wouldn't know from reading code]

What to Include

• Before Starting Work section - instruct agent to ask for existing context before exploring
• Project structure map - key directories and purposes (avoids repeated file tree crawling)
• Frequent commands - build, test, lint, deploy (avoid repeated discovery)
• Architecture overview - key patterns, data flow, module boundaries
• Non-obvious conventions - naming patterns, file organization choices, commit style
• Critical warnings - "never modify X directly", "requires Y before Z"

What to Exclude

• Claude's existing knowledge: Generic language idioms, standard library usage, common patterns
• Redundant content: Already in README.md, package.json, or inferable from code
• Vague directives: "Write clean code", "follow best practices", "be thorough"

The Living Document Workflow

1. Request comes in
2. Read files, explore codebase, do the work
3. Before ending session: update CLAUDE.md with what was learned or changed

• Directory structures discovered (so future sessions don't re-crawl)
• Key files and their purposes
• Patterns identified in the codebase
• Gotchas or non-obvious behaviors
• New conventions established during the work

## Project Structure (updated 2024-01)

After exploring the codebase:

- `src/handlers/` - Lambda handlers, one per API route
- `src/lib/` - Shared utilities
  - `src/lib/db.ts` - Database connection singleton
  - `src/lib/auth.ts` - JWT validation middleware
- `infrastructure/` - CDK stacks (not Terraform as README suggests)

• "Let me update CLAUDE.md with what we learned"
• "I should document this discovery"
• "Future sessions will benefit from knowing..."

Using Imports

@path/to/file

See @README.md for project overview.
Standard commands in @package.json.

## Team Conventions
- Git workflow: @docs/git-workflow.md
- API patterns: @docs/api-standards.md

## Individual Setup
@~/.claude/personal-prefs.md

Modular Rules with .claude/rules/

.claude/
├── CLAUDE.md              # Minimal root
└── rules/
    ├── typescript.md      # Language conventions
    ├── testing.md         # Test patterns
    ├── api.md             # API design rules
    └── frontend/
        ├── react.md
        └── styles.md

Path-Scoped Rules

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

# API Layer Rules

- All endpoints require input validation
- Use standard error response format from @docs/errors.md

**/*.ts

src/**/*

*.{ts,tsx}

{src,lib}/**/*.ts

Refactoring a Bloated CLAUDE.md

1. Analyze: Identify conflicting or redundant instructions
2. Extract: Keep only universal content in root (description, critical commands, overrides)
3. Categorize: Group remaining content by topic
4. Split: Move to

   .claude/rules/

   or imported files
5. Prune: Remove vague directives, defaults Claude already knows, outdated refs

Markdown Formatting

~/.claude/rules/

• Code blocks: Always specify a language. Use

  text

  for file trees and non-code content.
• Tables: Use spaces around inner pipe edges (

  | cell | cell |

  not

  |cell|cell|

  ).

Quality Checklist

• Every instruction is specific and actionable
• No duplication with README or other docs
• Root file under 50 lines (for larger projects)
• No generic advice Claude already knows
• Commands are accurate and tested
• Path-scoped rules use correct glob patterns
• Imports resolve to existing files
• Recent explorations/discoveries have been captured