项目记忆与交接

---
name: codex-project-memory
description: Create or refresh Codex-oriented project memory for a repository. Use when initializing a new project for Codex, asking to design or maintain AGENTS.md, onboarding future agents to a codebase, documenting project context, tech stack rules, architecture routing, safety zones, verification commands, or cross-session memory such as MEMORY.md and docs/agent-context files.
---

# Codex Project Memory

## Purpose

Turn a repository into a readable operating system for future Codex sessions. The output is not a one-time config dump; it is a living project memory made of:

- `AGENTS.md`: Codex-facing operating guide and constraints.
- `MEMORY.md`: durable decisions, traps, and context that should survive sessions.
- `docs/agent-context/PROJECT_CONTEXT.md`: product, users, goals, and current priorities.
- `docs/agent-context/TECH_STACK.md`: versions, package managers, forbidden dependencies, and commands.
- `docs/agent-context/ARCHITECTURE_ROUTER.md`: where to look before changing each concern.
- `docs/agent-context/SAFETY_ZONES.md`: high-risk paths, review gates, and verification rules.

For Codex, the initialization file is `AGENTS.md`. Use that exact plural filename. `AGENT.md` is not the Codex convention.

## Workflow

1. Inspect the repository before writing:
   - List top-level files with `rg --files -g '!node_modules' -g '!dist' -g '!build' -g '!coverage'`.
   - Identify package managers, frameworks, language versions, test/lint/typecheck commands, environment files, deployment files, and high-risk directories.
   - Read existing `README*`, `AGENTS.md`, `MEMORY.md`, package manifests, workspace config, and key app entry points.

2. Generate a first draft:
   - Prefer the bundled script `scripts/create_codex_project_memory.py`.
   - Run from the repo root: `python <skill>/scripts/create_codex_project_memory.py .`
   - Use `--force` only when the user asks to overwrite existing generated sections.

3. Refine from real evidence:
   - Replace placeholders with facts found in the repo.
   - Mark unknowns explicitly as `TBD`, not guesses.
   - Keep `AGENTS.md` short and operational; put larger explanations in `docs/agent-context/`.

4. Validate the memory system:
   - Confirm all links and referenced commands are real.
   - If commands are documented as required, run the cheap ones or clearly mark unverified commands.
   - Ensure high-risk directories have explicit review/verification guidance.

## Document Rules

Write `AGENTS.md` as the router, not the encyclopedia. It should answer:

- What is this project and what outcome matters?
- Which documents should Codex read for deeper context?
- Which commands verify work?
- Which paths require extra care?
- What project conventions must be followed?
- What should be recorded in `MEMORY.md` after important changes?

Write `MEMORY.md` as a chronological and curated log:

- Durable decisions and why they were made.
- Known traps, flaky tests, migration state, and architectural pressure.
- Recent important changes with dates.
- Do not store secrets, credentials, or private personal data.

Write `docs/agent-context/ARCHITECTURE_ROUTER.md` as a navigation table. For each concern, include:

- Concern or feature area.
- Primary files/directories.
- Tests or commands to run.
- Notes and risks.

Write `docs/agent-context/SAFETY_ZONES.md` for boundaries:

- Authentication, billing, permissions, data migration, infrastructure, release, analytics, and security-sensitive paths.
- What requires user confirmation.
- What checks must pass before claiming completion.

## Maintenance Pattern

When a future task changes behavior, update memory in the same turn if the new knowledge helps the next agent:

- Add a concise `MEMORY.md` entry for durable decisions or traps.
- Update the relevant `docs/agent-context/*.md` file when paths, commands, architecture, or safety rules change.
- Keep old entries if they explain why the system is shaped that way; delete only stale facts that would mislead.

## Reference

Read `references/codex-memory-design.md` when you need the full design rationale, templates, or a review checklist for a more thorough setup.