# claude-md-writer

> Writes and optimizes CLAUDE.md files following Anthropic 2025 best practices with 3-tier modular structure

- Author: sowecanya
- Repository: sowecanya/startup-agents
- Version: 20260126131752
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/sowecanya/startup-agents
- Web: https://mule.run/skillshub/@@sowecanya/startup-agents~claude-md-writer:20260126131752

---

---
name: claude-md-writer
description: Writes and optimizes CLAUDE.md files following Anthropic 2025 best practices with 3-tier modular structure
---

# CLAUDE.md Writer — Best Practices 2025

Transforms CLAUDE.md files into token-efficient, modular documentation.

**Activation:** `claude-md-writer`, `optimize-claude-md`

## Golden Rules

| Rule | Limit | Why |
|------|-------|-----|
| CLAUDE.md | < 200 lines | Loads on EVERY request, burns tokens |
| Rules files | < 500 lines each | Conditional loading saves tokens |
| Critical first | Top 20 lines | LLM attention is front-weighted |
| No duplication | Use `@file` refs | Single source of truth |

## Memory Hierarchy (Load Priority)

```
1. Enterprise:      /Library/Application Support/ClaudeCode/CLAUDE.md
2. Project:         /path/to/project/CLAUDE.md
3. Rules (cond.):   .claude/rules/*.md (via paths: frontmatter)
4. User:            ~/.claude/CLAUDE.md
5. Local:           .claude/CLAUDE.local.md (gitignored)
```

## 3-Tier Documentation System

### Tier 1: Foundation (CLAUDE.md)
**Always loaded. < 200 lines. Universal rules only.**

Contains:
- Stack overview (1-2 lines)
- Key commands (5-10 lines)
- Architecture overview (diagram)
- Critical paths (what to load when)
- Forbidden patterns (3-5 items)

Does NOT contain:
- Code style rules (use ESLint/Prettier/Biome)
- Domain-specific logic (use rules/)
- Implementation details (use co-located docs)

### Tier 2: Component Rules (.claude/rules/)
**Conditional loading via `paths:`. < 500 lines each.**

```yaml
# .claude/rules/api-patterns.md
---
paths:
  - src/api/**
  - src/routes/**
---
# API Development Rules
...
```

Organize by domain:
- `database.md` — SQL patterns, migrations
- `testing.md` — test conventions, fixtures
- `deployment.md` — CI/CD, environments
- `{domain}.md` — domain-specific rules

### Tier 3: Feature (Co-located)
**Lives next to code. Loaded only when reading that code.**

Examples:
- `src/auth/AUTH.md` — auth-specific patterns
- `src/billing/BILLING.md` — billing logic

## Conditional Loading (paths: frontmatter)

```yaml
---
paths:
  - "src/domains/seller/**"   # exact match
  - "**/*_test.py"            # glob pattern
  - "*.sql"                   # extension match
---
```

Rules load ONLY when working with matching files.

## What Belongs Where

| Content Type | Location | Example |
|-------------|----------|---------|
| Universal rules | CLAUDE.md | "Never push to main" |
| Domain logic | .claude/rules/{domain}.md | Billing calculations |
| API patterns | .claude/rules/api.md | REST conventions |
| Test conventions | .claude/rules/testing.md | Fixture patterns |
| Deployment | .claude/rules/deploy.md | CI/CD steps |
| Feature-specific | src/{feature}/FEATURE.md | Auth flow details |
| Code style | .eslintrc / biome.json | Formatting rules |

## Anti-Patterns

| Don't | Do Instead |
|-------|------------|
| Duplicate content | `@file` reference |
| Code style in docs | ESLint/Prettier config |
| Negative-only rules | "Do X" not "Don't do Y" |
| > 200 lines CLAUDE.md | Split to rules/ |
| Inline SQL patterns | .claude/rules/database.md |
| API docs in main | .claude/rules/api.md |
| **Count manually** | Always `grep -c` / `wc -l` |

## Counting Rule (CRITICAL)

**NEVER count components manually** — always verify with commands:

```bash
# Tables
grep -c "CREATE TABLE" supabase/migrations/*.sql

# Tools (seller)
grep -c '"name":' src/domains/seller/tools/definitions/*.py | awk -F: '{sum+=$2} END {print sum}'

# FSM States
grep -c "= State()" src/domains/*/states.py

# Handlers (exclude tests)
ls src/domains/*/handlers/*.py | grep -v test | wc -l

# Keyboards
grep -c "def .*keyboard" src/domains/*/keyboards/*.py

# HTTP Endpoints
grep -c "@router\.\|@app\." src/api/**/*.py

# Prompt versions
ls src/domains/*/prompts/*.md | wc -l

# Lines in file
wc -l <file>
```

**Manual counting = wrong numbers = misleading docs.**

## Migration Checklist

When optimizing existing CLAUDE.md:

1. [ ] **Measure:** Count current lines
2. [ ] **Identify domain content:** SQL, API, testing, deployment
3. [ ] **Create rules files:** `.claude/rules/{domain}.md` with `paths:`
4. [ ] **Move content:** Domain → rules file
5. [ ] **Add references:** `@.claude/rules/domain.md` if needed
6. [ ] **Verify:** Main file < 200 lines
7. [ ] **Test:** Rules load only when expected

## Template: CLAUDE.md (< 200 lines)

```markdown
# CLAUDE.md
[Project name] — [1-line description]

**Stack:** [technologies]

**Commands:**
- `./test` — run tests
- `./build` — build project

---

## Architecture
[Diagram or 3-5 line overview]

## Contexts
| Task | Load |
|------|------|
| [domain1] | `.claude/rules/domain1.md` |
| [domain2] | `.claude/rules/domain2.md` |

## Key Rules
- [Critical rule 1]
- [Critical rule 2]
- [Critical rule 3]

## Forbidden
- [Anti-pattern 1]
- [Anti-pattern 2]

## Structure
[Brief project structure if needed]
```

## Template: Rules File (< 500 lines)

```markdown
---
paths:
  - "src/domains/billing/**"
  - "**/billing_*.py"
---

# Billing Rules

## Principles
...

## Patterns
...

## Examples
...
```

## Quality Checklist (Pre-Completion)

Before finishing optimization:

- [ ] CLAUDE.md < 200 lines
- [ ] Each rules file < 500 lines
- [ ] Critical content in first 20 lines
- [ ] No code style rules (use linter configs)
- [ ] No duplication (use @file refs)
- [ ] paths: frontmatter on all rules files
- [ ] Domain content moved to rules/
- [ ] Architecture diagram present
- [ ] Commands section complete

## Output

After optimization:
```yaml
status: complete
main_lines: [N] (was [M])
rules_files: [list]
tokens_saved: ~[estimate]%
```