claudemd-writer by markmdev

---
name: claudemd-writer
description: Create or update CLAUDE.md files. Use when adding a new module, explaining patterns, or fixing repeated agent mistakes.
---

# CLAUDE.md Writer

CLAUDE.md files provide context to Claude Code when working in a directory. Claude reads them automatically based on the files being accessed.

## Core Principle: Less is More

Claude Code's system prompt tells Claude to **ignore CLAUDE.md content if it seems irrelevant**. The more irrelevant content, the more likely Claude ignores everything.

Frontier LLMs reliably follow ~150-200 instructions. Claude Code's system prompt uses ~50. Every line in CLAUDE.md competes for attention.

## Hierarchical Injection

CLAUDE.md files inject based on path depth. When reading `modules/payments/lib/checkout.ts`, Claude receives CLAUDE.md from: project root → modules/ → payments/ → lib/

**Closest file wins** if instructions conflict. Keep each CLAUDE.md focused on its level — don't duplicate parent content.

## What Goes Where

**Root CLAUDE.md**: Commands (install/dev/test/build/lint), project purpose, stack overview, project-wide conventions.

**Domain CLAUDE.md** (e.g., `modules/`, `services/`): What the domain handles, shared patterns, cross-module dependencies.

**Module CLAUDE.md** (e.g., `payments/`, `auth/`): Module-specific test commands, what it does, how it works, why it's designed this way, gotchas.

## Writing Guidelines

### Describe What, How, Why — Concisely

- **What** this module does
- **How** it works (architecture, data flow, key patterns)
- **Why** it's designed this way (rationale, constraints)
- **Gotchas** that cause mistakes

Don't write API reference documentation. Write context that helps agents make good decisions.

### Use Pointers, Not Copies

Reference canonical examples by file and line number: "Follow the pattern in `src/services/UserService.ts:45-60`"

Code snippets go stale. File references can be verified.

### Provide Alternatives to "Never"

"Never use `--force`" leaves Claude stuck. "Never use `--force`, use `--force-with-lease` instead" gives a path forward.

### Don't Use CLAUDE.md as a Linter

Style rules (indentation, semicolons, quotes) belong in ESLint/Prettier. Claude learns style from existing code.

## When to Create

- New module or significant directory
- Patterns need explanation
- Agent repeatedly makes wrong assumptions
- You fix a bug caused by missing context

## When NOT to Create/Update

- Bug fixes that don't change behavior
- Refactoring that preserves API
- Internal implementation details
- Small utility files or tests

## Structure

No rigid template. Common sections, in order of usefulness:

1. **Commands** — Put runnable commands first (test, dev, lint)
2. **How It Works** — Architecture, data flow, key components
3. **Why This Design** — Rationale, constraints, tradeoffs
4. **Key Patterns** — Reference canonical examples by file:line
5. **Gotchas** — Non-obvious things that cause mistakes

Include only sections that help agents work effectively in this directory.

## Checklist

Before saving:

- [ ] Explains what, how, and why — concisely?
- [ ] Includes gotchas not obvious from code?
- [ ] Every line relevant to this directory?
- [ ] File references instead of code snippets?
- [ ] Every "never" has an alternative?
- [ ] Concise enough that Claude won't ignore it?