tomevault-io CLAUDE.md Writer
Creates and refactors CLAUDE.md files following official Anthropic best practices (2025).
Golden Rules
| Rule | Why |
|---|---|
| CLAUDE.md < 200 lines | Loads on EVERY request, costs tokens |
| Rules files < 500 lines each | Official recommendation per file |
| Critical rules FIRST | Top = highest priority |
Modular rules → .claude/rules/ |
Conditional loading, organized |
Use paths: frontmatter |
Load rules only for matching files |
| No linting rules | Use ESLint/Prettier/Biome instead |
| Pointers over copies | Files change, references stay valid |
Memory Hierarchy
Claude Code loads memory in this order (higher = higher priority):
| Priority | Type | Location |
|---|---|---|
| Highest | Enterprise | /Library/Application Support/ClaudeCode/CLAUDE.md |
| ↓ | Project | ./CLAUDE.md or ./.claude/CLAUDE.md |
| ↓ | Rules | ./.claude/rules/*.md (conditional) |
| ↓ | User | ~/.claude/CLAUDE.md |
| Lowest | Local | ./CLAUDE.local.md (gitignored) |
Use /memory command to see currently loaded files.
3-Tier Documentation System
Official recommendation for large projects:
| Tier | Location | Loads | Target |
|---|---|---|---|
| 1. Foundation | CLAUDE.md |
Always | < 200 lines |
| 2. Component | .claude/rules/{component}/ |
When working in component | < 500 lines |
| 3. Feature | Co-located with code | When working on feature | As needed |
Example structure:
.claude/
├── CLAUDE.md # Tier 1: always loaded
└── rules/
├── database.md # Tier 2: SQL, migrations
├── api.md # Tier 2: API patterns
└── frontend/ # Tier 2: subdirectory
├── components.md # paths: src/**/*.tsx
├── layout.md # paths: src/pages/**/*.tsx
└── tokens.md # paths: **/*.tsx
Structure Template
# Project Name
One-line description.
## Commands
- `npm run dev` - Development
- `npm run build` - Production
- `npm run test` - Tests
## Architecture
| Path | Purpose |
|------|---------|
| `lib/` | Core logic |
| `app/api/` | API routes |
## Key Patterns
**Pattern Name**: One-line explanation.
## Database (if applicable)
| Table | Key Fields |
|-------|------------|
## Modular Docs
See `.claude/rules/` for:
- `database.md` - queries, schema
- `deploy.md` - deployment
## Tech Stack
One line: Next.js 15, PostgreSQL, TypeScript
Conditional Rules (Path-Specific)
Use YAML frontmatter for file-type-specific rules:
---
paths: "src/api/**/*.ts"
---
# API Rules
- All endpoints must validate input
- Use standard error format
Glob Patterns
| Pattern | Matches |
|---|---|
**/*.ts |
All .ts files anywhere |
src/**/* |
All files under src/ |
*.md |
Markdown in project root |
src/components/*.tsx |
Components in specific dir |
Combining Patterns
# Multiple extensions
paths: "src/**/*.{ts,tsx}"
# Multiple directories
paths: "{src,lib}/**/*.ts, tests/**/*.test.ts"
Note: Wrap patterns in quotes for YAML safety.
Rules with paths: only load when working with matching files → saves tokens.
Workflow: New Project
- Run
/initfor base CLAUDE.md - Review and trim generated content
- Identify critical rules — what breaks if ignored?
- Create
.claude/rules/for domain-specific docs - Keep main file < 100 lines
Workflow: Refactor Existing
- Count lines — if > 300, must split
- Find task-specific content — SQL, debugging, deploy → extract
- Create
.claude/rules/:database.md- queries, schema, connectiondeploy.md- deployment processmessaging.md- integrations (Telegram, etc.)
- Use
@filereferences — don't duplicate - Keep in CLAUDE.md — only what applies to EVERY task
What Goes Where
| Content | Location |
|---|---|
| Project description | CLAUDE.md |
| Critical constraints | CLAUDE.md (top!) |
| Quick start (3 commands) | CLAUDE.md |
| Architecture overview | CLAUDE.md |
| Key patterns (1-liners) | CLAUDE.md |
| SQL queries/schema | .claude/rules/database.md |
| Deployment steps | .claude/rules/deploy.md |
| API documentation | .claude/rules/api.md |
| Git workflow | .claude/rules/git.md |
| Personal preferences | CLAUDE.local.md (gitignored) |
| Code style rules | .eslintrc / biome.json (NOT docs) |
Import Syntax
Reference files instead of duplicating:
@README.md
@docs/architecture.md
@~/.claude/snippets/common.md
- Relative:
@docs/file.md - Absolute:
@~/path/file.md - Max depth: 5 hops
CLAUDE.local.md
Personal project settings (auto-gitignored):
# My Local Settings
- Prefer verbose output
- Run tests after every change
- My worktree location: .trees/
Common Mistakes
| Mistake | Fix |
|---|---|
| 500+ lines | Split into .claude/rules/ |
| SQL examples inline | → rules/database.md |
| "Run prettier" rules | Use tool config files |
| Full API docs | → rules/api.md |
| Deployment instructions | → rules/deploy.md |
| Code in CLAUDE.md | Use @file:line references |
| Negative rules only | Add alternatives: "Don't X; use Y instead" |
Quality Checklist
Before finishing:
- CLAUDE.md < 200 lines?
- Each rules file < 500 lines?
- Critical rules at top?
- No task-specific content in main file?
- No code style rules (use ESLint/Prettier)?
-
.claude/rules/for domain-specific docs? - Subdirectories for components (frontend/, backend/)?
-
paths:frontmatter for conditional loading? -
@references instead of duplication? - CLAUDE.local.md for personal prefs?
Useful Commands
| Command | Purpose |
|---|---|
/init |
Generate initial CLAUDE.md |
/memory |
View loaded memory files |
Sources
Official:
- code.claude.com/docs/en/memory (Memory management, paths, globs)
- anthropic.com/engineering/claude-code-best-practices
- claude.com/blog/using-claude-md-files
Community:
- thedocumentation.org/claude-code-development-kit (3-Tier System)
- claudefa.st/blog/guide/mechanics/rules-directory
- humanlayer.dev/blog/writing-a-good-claude-md
Updated: Jan 2026
Converted and distributed by TomeVault — claim your Tome and manage your conversions.