project-memory

# Project memory generator

Create CLAUDE.md files that transfer institutional knowledge, not obvious information. Think like a senior journalist onboarding a competent colleague — you don't explain how journalism works, you explain YOUR project's quirks.

## CLAUDE.md is advisory, not enforced

Anthropic is explicit on this point: CLAUDE.md content is delivered as a user message after the system prompt. Claude reads it and tries to follow it, but there's no guarantee of strict compliance — especially with vague or conflicting instructions. Source: https://code.claude.com/docs/en/memory

This affects how you write a CLAUDE.md and what you put elsewhere:

| Mechanism | Use for | Source-of-truth |
|---|---|---|
| **CLAUDE.md** | Standing facts, conventions, "always do X" rules | Advisory |
| **Skills** | Multi-step procedures, on-demand workflows | Loaded when invoked |
| **Hooks** | Actions that must happen every time, no exceptions | Deterministic — runs as a shell command (e.g., `hooks/one-way-door-check.md`) or as a prompt the harness enforces (e.g., `hooks/enforce-test-first.md`) |

If an instruction is "block writes to `published/`" or "run accessibility check before commit," that belongs in a hook, not CLAUDE.md. If it's "fact-check workflow" or "FOIA-letter drafting," that's a skill. CLAUDE.md is the place for things Claude must hold in every session.

## What belongs in CLAUDE.md

Anthropic publishes an explicit include/exclude table for what makes an effective CLAUDE.md. Source: https://code.claude.com/docs/en/best-practices

| ✅ Include | ❌ Exclude |
|---|---|
| Bash commands Claude can't guess | Anything Claude can figure out by reading code |
| Code style rules that differ from defaults | Standard language conventions Claude already knows |
| Testing instructions and preferred test runners | Detailed API documentation (link to docs instead) |
| Repository etiquette (branch naming, PR conventions) | Information that changes frequently |
| Architectural decisions specific to your project | Long explanations or tutorials |
| Developer environment quirks (required env vars) | File-by-file descriptions of the codebase |
| Common gotchas or non-obvious behaviors | Self-evident practices like "write clean code" |

For journalism projects, translate to:

- **Include:** AP-style preferences that override defaults, "always cite source URLs," byline policy, embargo handling, source-protection invariants, CMS quirks (e.g., "story slugs must be unique across ALL desks, not just metro").
- **Exclude:** "We verify facts before publishing" (every journalist knows this), "use AP Style" without specifics (every journalism stack does this), framework documentation, generic git commands.

## The deletion test

For every line you write, ask: "Would removing this cause Claude to make mistakes?" If not, cut it.

## Size guidance: target under 200 lines

Anthropic's explicit guidance as of 2026: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence. Bloated CLAUDE.md files cause Claude to ignore the actual rules. Source: https://code.claude.com/docs/en/best-practices

Going over 200 lines is a signal to use one of these instead:

- **`.claude/rules/` with `paths:` frontmatter** — file-pattern-scoped rules that load only when Claude works with matching files. Replaces `@import` chains as the size-management mechanism. (Note: `@imports` no longer help with context size — Anthropic explicitly notes that imports load fully at launch.)
- **Skills** — for multi-step procedures that don't need to be in every session.
- **Hooks** — for deterministic enforcement.

## Where to put CLAUDE.md files

CLAUDE.md location precedence (more specific wins). Source: https://code.claude.com/docs/en/memory

| Scope | Location | Use case |
|---|---|---|
| **Managed policy** | Linux/WSL: `/etc/claude-code/CLAUDE.md`<br/>macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br/>Windows: `C:\Program Files\ClaudeCode\CLAUDE.md` | Org-wide standards (IT/DevOps managed; cannot be excluded by individual settings) |
| **Project** | `./CLAUDE.md` OR `./.claude/CLAUDE.md` | Team-shared instructions (check into git) |
| **User** | `~/.claude/CLAUDE.md` | Personal preferences across all projects |
| **Local** | `./CLAUDE.local.md` | Personal project-specific notes (add to `.gitignore`) |

The `./.claude/CLAUDE.md` location and managed-policy tier are 2026 additions to Anthropic's documented locations. Templates that say "put this at project root" should mention `./.claude/CLAUDE.md` as an equally valid location.

## AGENTS.md interop

If your repo already has `AGENTS.md` for other coding agents (Cursor, Codex, etc.), don't duplicate the content. Anthropic's recommended pattern is `@AGENTS.md` import (or symlink) with Claude-specific overrides appended:

```markdown
@AGENTS.md

## Claude Code
- Use plan mode for changes under `src/billing/`.
```

For journalism teams using multiple agents, this matters — shared editorial standards (AP-style preferences, source-handling invariants, fact-check protocols) belong to the org, not one agent.

## Anti-patterns to warn about

Anthropic now names these explicitly. Source: https://code.claude.com/docs/en/best-practices and https://code.claude.com/docs/en/memory

1. **The over-specified CLAUDE.md.** Bloat causes Claude to ignore real rules. If Claude keeps doing something despite a CLAUDE.md rule, the file is probably too long and the rule is getting lost.
2. **Conflicting instructions across nested CLAUDE.md files.** Claude picks one arbitrarily. Review periodically to remove outdated rules.
3. **Hand-coded standard conventions Claude already knows.** "Use proper indentation," "write clean code" — delete.
4. **Detailed API docs / file-by-file descriptions / info that changes frequently.** Link to the canonical source instead.
5. **Secrets in CLAUDE.md.** It's checked into git. Use `CLAUDE.local.md` (gitignored) for sandbox URLs, test credentials,