project-memory

项目记忆生成器

创建项目指令文件，传递机构知识，而非显而易见的信息。设想一位资深记者正在帮助一位能力出众的同事熟悉工作。不要解释新闻工作如何开展；要说明这个项目有哪些特殊之处。

选择规范指令文件

开始写作前，确定目标文件：

1. 如果存在 AGENTS.md，就更新它。如果不存在 CLAUDE.md，那么在 Claude Code 中也创建一个只包含一行内容的 CLAUDE.md，通过 @AGENTS.md 导入它。Claude Code 加载的是 CLAUDE.md，而不是 AGENTS.md。
2. 如果只存在 CLAUDE.md，就更新它。
3. 如果两个文件都存在，且其中一个导入另一个，就编辑被导入的规范文件。
4. 如果两个文件都不存在，就创建 AGENTS.md。在 Claude Code 中也创建相同的单行 CLAUDE.md 导入文件。

不要创建相互竞争、内容重复的副本。只有当子目录需要比父目录更具体的规则时，才保留嵌套指令文件。

项目指令仅供参考

项目指令文件为当前客户端提供持续适用的背景信息。文件本身不会强制执行规则。

在 Claude Code 中，CLAUDE.md 内容会在系统提示词之后作为用户上下文提供。Claude 会读取并尝试遵循，但对于模糊或相互冲突的指令，该文件无法保证严格遵循。来源：https://code.claude.com/docs/en/memory

机制	用途	行为
项目指令文件	持续适用的事实、命令、约定和边界	参考性上下文
技能	多步骤流程和按需工作流	在相关时加载
客户端强制执行	必须阻止或每次都要运行的操作	只有客户端会阻止时才确定执行，例如退出码为 2 或返回 PreToolUse deny 的 Claude Code 钩子。提示钩子只会添加提醒

不要把客户端钩子当作共享行为的关键保障。如果某条规则必须同时适用于 Claude Code 和 Codex，就要在项目指令文件中写明，并单独记录任何可选的客户端强制执行方式。

如果指令是“禁止写入 published/”或“提交前运行无障碍检查”，就使用客户端强制执行。如果是“事实核查工作流”或“FOIA 信函撰写”，就使用技能。将持续适用的项目事实和规则保留在项目指令文件中。

Claude Code 关于如何编写有效指令文件的指南明确要求列出应包含和排除的内容。来源：https://code.claude.com/docs/en/best-practices

文件应包含哪些内容

包含 Agent 无法从仓库中可靠推断的信息：

• 项目特定的构建、测试、代码检查和验证命令。
• 与常见默认做法不同的代码或编辑规则。
• 仓库协作礼仪、分支约定和审批边界。
• 架构决策和不明显的依赖关系。
• 环境要求、指定变量，以及不含机密值的凭证指引。
• 常见故障模式和已知的最简恢复步骤。
• 项目特定的来源处理、发布、隐私或法律限制。

排除 Agent 可以轻易查明的信息：

• 标准语言约定和通用建议。
• 有权威资料可查的详细 API 文档。
• 按文件逐一介绍仓库内容。
• 会话日志、状态更新和经常变化的事实。
• 冗长的教程或历史叙述。
• 凭证、令牌、私人信息或个人数据。

对于新闻项目：

• 包含覆盖默认做法的 AP 风格偏好、来源引用规则、署名政策、禁发期处理方式、来源保护的不可违反要求，以及 CMS 的特殊之处（例如，“新闻稿 slug 必须在所有部门间保持唯一，而不只是都市版内部唯一”）。
• 排除“发布前核实事实”和“遵循 AP 风格”这类没有具体说明的要求。所有新闻编辑室都知道这两点。

逐行自问：删除这一行，是否会让能力出众的 Agent 更有可能犯下项目特定的错误？如果不会，就删掉。

保持文件精简且范围明确

使用简短的章节和直接的指示。将 200 行视为审查阈值，而不是目标。文件变长时：

• 将多步骤流程移入技能。
• 链接到权威参考文档。
• 将范围较窄的目录规则放入嵌套指令文件。
• 将临时备注移入客户端的记忆功能，或放入由 git 忽略的本地备注文件。
• 删除重复和已被取代的规则。

如果同时使用两个受支持的客户端，请将共用指南放在 AGENTS.md 中，并让 CLAUDE.md 导入它。只有在无法用可移植的方式表达行为时，才添加特定于客户端的指南，并标明适用客户端。

特定于客户端的范围设置选项：

• Claude Code：.claude/rules/ 文件可使用 paths: frontmatter，仅在 Agent 处理匹配文件时加载。@import 会在启动时完整加载，因此不会减少上下文大小。
• Codex：嵌套的 AGENTS.md 适用于其所在目录及其下级目录。

特定于客户端的位置

在 Claude Code 中，位置越具体，优先级越高。来源： https://code.claude.com/docs/en/memory

范围	Claude Code 位置	使用场景
托管策略	Linux/WSL：/etc/claude-code/CLAUDE.md macOS：/Library/Application Support/ClaudeCode/CLAUDE.md Windows：C:\Program Files\ClaudeCode\CLAUDE.md	个人设置无法排除的组织标准
项目	./CLAUDE.md 或 ./.claude/CLAUDE.md	纳入版本控制、供团队共享的指令
用户	~/.claude/CLAUDE.md	适用于多个项目的个人偏好
本地	./CLAUDE.local.md	由 git 忽略的个人项目备注

在 Codex 中，指令从全局范围开始加载，逐级覆盖至当前工作目录。后续目录会覆盖较早的目录；同一目录中的 AGENTS.override.md 优先于 AGENTS.md。来源： https://developers.openai.com/codex/guides/agents-md

范围	Codex 位置	使用场景
用户	~/.codex/AGENTS.md	适用于多个项目的个人指令
项目及嵌套目录	从仓库根目录到当前工作目录中的 AGENTS.md	适用范围较窄的共享规则
覆盖文件	AGENTS.override.md	需要临时或更强覆盖规则时，替代同一目录中的 AGENTS.md

对于使用多个 Agent 的新闻团队，请将共用的编辑标准、来源处理约束和事实核查流程放在权威共用文件中。这些规则属于组织，而非某个客户端。

反模式

1. 指令过于详尽。 重要规则会淹没在泛泛的建议中。在 Claude Code 中，如果 Claude 总是忽略某条规则，文件可能太长，导致该规则被埋没。
2. 嵌套文件相互冲突。 宽泛规则和细化规则彼此矛盾，却未说明哪个范围优先。
3. 重复的客户端文件。 两份副本会逐渐不一致，给出不同的指导。
4. 过时的运行状态。 端口、负责人或当前状态在实际情况变化后仍被保留。
5. 指令中包含机密。 文件已纳入版本控制。

表达风格

• 使用简短、直接的句子。
• 仅在项目需要时写明准确的命令和路径。
• 说明谁有权批准会产生重大影响的工作。
• 删除欢迎语、营销语言和泛泛的提醒。
• 标题使用句首字母大写格式。

自动记忆与项目指令相互独立

在 Claude Code v2.1.59 及更高版本中，自动记忆会将备注存储在 ~/.claude/projects/<project>/memory/ 下。每个会话都会加载 MEMORY.md 的前 200 行。来源：https://code.claude.com/docs/en/memory

不要让用户记下 Claude 通过纠正学到的内容。自动记忆会处理这些备注。项目指令用于记录团队编写并审查的持久信息。

示例：好与坏

不好，因为它解释了显而易见的设置步骤，却没有提供任何组织特有的信息：

# Project instructions

## Overview

Welcome to our newsroom's story tracking system. This React and Node.js app
helps editors and reporters collaborate on stories.

## Getting started

npm install
npm start

好，因为它只记录了项目特有的行为：

# Project instructions

## Overview

Story tracker for the metro desk. React + Supabase.

## Gotchas

- Story slugs must be unique across all desks, not only metro.
- "Hold" does not stop the autopublish cron. Use "Kill."
- The reporter dropdown caches for one hour. New hires do not appear sooner.

## Commands

npm run sync-ap  # Pull latest from AP. Runs automatically at :15.

## Credentials

The Supabase key is in the 1Password "Metro Desk" vault, not `.env`.

模板

模板位于 templates/ 目录：

模板	用途
editorial-tool.md	新闻编辑室工具、事实核查工具和 AI 助手
event-website.md	会议、研讨会和活动网站
publication.md	新闻简报、播客和持续出版物
research-project.md	调查和范围明确的数据研究
content-pipeline.md	CMS 工作流和发布自动化
digital-archive.md	历史资料集和文档库

工作流

1. 根据上述规则确定规范的指令文件。
2. 阅读现有文件，以及所有适用于目标范围的上级或嵌套指令文件。
3. 选择最合适的模板。只复制项目需要的部分。
4. 保留现有指南和顺序，除非用户要求重写。
5. 用已核实的项目事实替换占位符。不要编造命令、负责人、路径或服务状态。
6. 将适用范围不同的规则保留在各自适用的目录中。
7. 检查最终文件，排查重复、冲突、过时信息和机密信息。
8. 如果在 Claude Code 中创建了 AGENTS.md，请创建上文所述的单行导入文件。

最小起步模板

# Project instructions

## Commands

- Test: [exact command]
- Lint: [exact command]

## Project rules

- [Non-obvious rule that changes how work is done.]
- [Approval or safety boundary.]

## Known failure modes

- [Symptom]: [Cause and verified recovery.]

从小处着手。只有在项目表明 Agent 需要某条规则后，才添加该规则。

参考文件

当多个 Agent、运行时或人员在同一代码库中协作时，请阅读固定的代码库清单。

最近一次时效性核查

2026-05-09。已核实来源：https://code.claude.com/docs/en/memory 和 https://code.claude.com/docs/en/best-practices。Codex 指令范围已于 2026-10-23 根据 OpenAI 官方文档核查。