jamiebrynes7/dotfiles/writing-claude-md-files

Writing CLAUDE.md Files

REQUIRED: Load the writing-claude-directives skill for foundational guidance on token efficiency, compliance techniques, and directive structure.

Core Principle

CLAUDE.md files bridge Claude's statelessness. They preserve context so humans don't re-explain architectural intent every session.

The whole hierarchy turns on one distinction:

• Top-level — HOW to work in this codebase: commands, conventions, structure. "How to work here."
• Subdirectory — WHY this piece exists and what it PROMISES: contracts, decisions, invariants. "Why this exists and what it promises."

Claude reads these from the current directory up to the root, so a subdirectory file inherits its parents and should never repeat them. Depth is typically one level (domain), occasionally two (a subdomain like auth/oauth2), rarely more.

Top-Level CLAUDE.md

Leave out code style rules (that's what linters are for), exhaustive command lists (reference package.json or the justfile), anything that belongs in a domain file, and secrets.

Subdirectory CLAUDE.md (Domain-Level)

The code already shows WHAT. These files explain intent.

A domain file earns its place when the domain has non-obvious contracts with other parts, when architectural decisions constrain how the code should evolve, when invariants exist that the code doesn't make obvious, or when new sessions keep needing the same context re-explained. Skip it for trivial utility folders, for implementation details that churn, and for anything better said in a code comment.

Example

# Auth Domain
 
Last verified: 2025-12-17
 
## Purpose
 
Verifies user identity exactly once at the system edge; downstream
services trust the token without re-validating.
 
## Contracts
 
-**Exposes**: `validateToken(token) → User | null`, `createSession(credentials) → Token`
-**Guarantees**: Tokens expire after 24h. User objects always include roles.
-**Expects**: Valid JWT format. Database connection available.
 
## Dependencies
 
-**Uses**: Database (users table), Redis (session cache)
-**Used by**: All API routes, billing (user identity only)
-**Boundary**: Do NOT import from billing or notifications
 
## Key Decisions
 
-JWT over session cookies: stateless auth for horizontal scaling
 
## Invariants
 
-Deleted users are soft-deleted (`is_deleted`), never hard deleted
 
## Gotchas
 
-Token validation returns null on invalid — it doesn't throw

Note what the Purpose section does not say: "handles authentication." That is recoverable from the directory name. "Verified exactly once at the edge, downstream trusts the token" is not.

Freshness Dates: MANDATORY

Every CLAUDE.md MUST carry a Last verified: date, because a stale one is worse than none — the date is what tells a reader when the contracts were last confirmed.

Get the real date from Bash. Do NOT write one from memory:

date +%Y-%m-%d

Referencing Files

Name key files plainly (service.ts - main implementation). Do NOT use `@` syntax (@./service.ts) — it force-loads the file into context on every read of the CLAUDE.md, burning tokens whether or not anyone needed it.

Updating

1. Update the freshness date from date +%Y-%m-%d
2. Verify the contracts still hold — read the code, don't trust the diff
3. Remove stale content; short and accurate beats long and wrong
4. Stay within budget: <300 lines top-level, <100 lines subdirectory