/project-memory

name: project-memory
description: Generates CLAUDE.md project memory files that transfer institutional knowledge. Use when setting up projects or onboarding.

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:

@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