/project-memory

name: project-memory
description: Generates project instruction files (AGENTS.md or CLAUDE.md) that transfer institutional knowledge. Use when setting up projects or onboarding. For lessons from a finished project or investigation, use project-retrospective.

Project memory generator

Create a project instruction file that transfers institutional knowledge, not obvious information. Think like a senior journalist onboarding a competent colleague. Do not explain how journalism works; explain this project's quirks.

Choose the canonical instruction file

Resolve the target before writing:

1. If `AGENTS.md` exists, update it. If no `CLAUDE.md` exists, then in Claude Code, also create a one-line `CLAUDE.md` that imports it with `@AGENTS.md`. Claude Code loads `CLAUDE.md`, not `AGENTS.md`. 2. If only `CLAUDE.md` exists, update it. 3. If both exist and one imports the other, edit the imported canonical file. 4. If neither exists, create `AGENTS.md`. In Claude Code, also create the same one-line `CLAUDE.md` import.

Do not create competing copies of the same guidance. Keep nested instruction files only when a subdirectory needs narrower rules than its parent.

Project instructions are advisory

A project instruction file gives standing context to the active client. It does not enforce a rule by itself.

In Claude Code, `CLAUDE.md` content is delivered as user context after the system prompt. Claude reads it and tries to follow it, but the file does not guarantee strict compliance with vague or conflicting instructions. Source: https://code.claude.com/docs/en/memory

| Mechanism | Use for | Behavior | |---|---|---| | Project instruction file | Standing facts, commands, conventions, and boundaries | Advisory context | | Skills | Multi-step procedures and on-demand workflows | Loaded when relevant | | Client enforcement | Actions that must block or run every time | Deterministic only when the client blocks, for example, a Claude Code hook that exits 2 or returns a PreToolUse deny. A prompt hook only adds a reminder |

Do not use a client hook as load-bearing shared behavior. If a rule must work in both Claude Code and Codex, state the rule in the project instruction file and document any optional client enforcement separately.

If an instruction is "block writes to `published/`" or "run an accessibility check before commit," use client enforcement. If it is a "fact-check workflow" or "FOIA-letter drafting," use a skill. Keep standing project facts and rules in the project instruction file.

Claude Code guidance for effective instruction files includes an explicit include/exclude list. Source: https://code.claude.com/docs/en/best-practices

What belongs in the file

Include information an agent cannot infer reliably from the repository:

• Project-specific build, test, lint, and validation commands.
• Code or editorial rules that differ from common defaults.
• Repository etiquette, branch conventions, and approval boundaries.
• Architecture decisions and non-obvious dependencies.
• Environment requirements, named variables, and credential pointers without

secret values.

• Common failure modes and the smallest known recovery steps.
• Source-handling, publication, privacy, or legal constraints specific to the

project.

Exclude information the agent can discover cheaply:

• Standard language conventions and generic advice.
• Detailed API documentation that has a canonical source.
• File-by-file repository descriptions.
• Session logs, status updates, and facts that change often.
• Long tutorials or narrative history.
• Credentials, tokens, private values, or personal data.

For journalism projects:

• Include AP-style preferences that override defaults, source-citation rules,

byline policy, embargo handling, source-protection invariants, and CMS quirks (for example, "story slugs must be unique across all desks, not just metro").

• Exclude "verify facts before publishing" and "use AP Style" without

specifics. Every newsroom already knows both.

For every line, ask: Would removing this make a capable agent more likely to make a project-specific mistake? If not, remove it.

Keep the file small and scoped

Use short sections and direct instructions. Treat 200 lines as a review threshold, not a target. When the file grows:

• Move multi-step procedures into skills.
• Link to canonical reference documentation.
• Put narrow directory rules in a nested instruction file.
• Move transient notes into the client's memory feature or a gitignored local

notes file.

• Remove duplicated and superseded rules.

If both supported clients are used, keep shared guidance in `AGENTS.md` and let `CLAUDE.md` import it. Add client-specific guidance only when the behavior cannot be expressed portably, and label the client.

Client-specific scoping options:

• Claude Code: `.claude/rules/` files with `paths:` frontmatter load only when

the agent works on matching files. An `@import` loads in full at launch, so it does not reduce context size.

• Codex: a nested `AGENTS.md` applies to its directory and below.

Client-specific locations

In Claude Code, more specific locations take precedence. Source: https://code.claude.com/docs/en/memory

| Scope | Claude Code 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` | Organization standards that individual settings cannot exclude | | Project | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Team-shared instructions checked into version control | | User | `~/.claude/CLAUDE.md` | Personal preferences across projects | | Local | `./CLAUDE.local.md` | Gitignored personal project notes |

In Codex, instructions load from global scope through the current working directory. Later directories override earlier ones, and `AGENTS.override.md` takes precedence over `AGENTS.md` in the same director