给 AI 装上「长期项目记忆」的一个 Agent Skill。让 Codex、Claude Code 等 AI 助手把项目记忆沉淀成项目里的文件,而不是锁在某一次聊天里——这样换窗口、换模型、换工具、隔了一个月回来,下一个 AI 都能接着干。
A reusable agent skill that keeps long-term project memory in files inside the project, not only in chat — so the next agent (Codex, Claude Code, or any other) can pick the work up across sessions, models, and tools.
用 AI 做一个稍微长一点的项目,几乎都会遇到:
- 聊天窗口一长,AI 开始「变笨」,旧方案、废弃判断混进当前任务;
- 一换新对话 / 新模型 / 新工具,AI 又什么都不记得,你得从头解释一遍;
- 关键决定、数据口径、下一步计划散落在聊天记录里,过一阵子自己也找不回。
这个 skill 的思路很简单:把该长期记住的东西,从聊天里搬到项目文件里。新项目可以采用一套标准结构；已有项目先兼容现有规则，需要迁移时再单独确认。
对新项目或已明确采用该协议的项目，在根目录维护下列记忆文件：
项目根/
├── AGENTS.md # 唯一入口 / 启动协议:读取顺序、口径铁律、避坑、冲突仲裁规则
├── CLAUDE.md # 只有一行 @AGENTS.md —— 让 Claude Code 自动加载同一份记忆
├── README.md # 业务背景:项目是什么、为什么、边界
├── handoff.md # 现状快照:一句话状态 / 目标 / 产物 / 最近决策 / 下一步(一屏)
└── docs/
├── progress-log.md # 编年史,按日期追加,不改历史
├── open-questions.md # 悬而未决、影响结论的问题
├── 口径与数据源.md # (分析类)数据源 / 口径 / 校验钩子
└── evidence.md # (数据报告)结论 → 证据映射,每个数字可溯源
核心设计取舍:
- 两个入口文件,一个源头:新项目或经批准迁移的项目用
AGENTS.md写指令，CLAUDE.md只写@AGENTS.md。已有项目的入口文件若含用户规则，在迁移批准前保持原样。 - 骨架先行,按需生长:第一遍只建最小骨架,其余文件等真有内容了再拆出来,绝不预建空壳。
- 冲突仲裁有优先级:同一事实打架时,信任顺序
脚本实时计算 > 口径/reference > handoff > README/背景 > progress-log/归档。 - 沉淀要留反例:每条沉淀 = 决定 + 为什么 + 被否决的方案 + 怎么复验。
- 状态标签:操作型记忆文件头部标
Status: current | reference | append-only | archived,历史不会被误当成现状。README.md是面向人的项目背景页，检查器不强制它带状态头。 - 待办只写用户确认过的:
handoff.md的 Next Steps 只收用户明确提出或认可的事项;agent 自己推断的"接下来可以做 X"记入open-questions.md标「建议·未确认」——否则下一个 agent 会把猜测当成既定任务直接执行。 - 较大迭代后请求沉淀:Skill 指令要求在口径、核心结论或重要决策变化后主动沉淀；是否会被隐式调用取决于宿主的 Skill 发现与匹配机制，不是强制 Hook。需要确定执行时，请显式调用。
| 意图 | 会做什么 | 不会顺带做什么 |
|---|---|---|
| 查看交接情况 | 只读授权项目，说明现状、缺口和建议 | 不建文件、不改入口、不迁移或删除 |
| 更新项目交接 | 只在授权项目内更新约定的记忆文件 | 不扩展到相邻项目，不顺手重组现有文档体系 |
| 迁移旧交接结构 | 先列源文件、目标文件、引用影响和保留方案，批准后执行 | 不自动扫描其他项目；删除旧文件前再确认 |
扫描根目录只能是当前项目或用户明确指定的范围。符号链接、嵌套仓库、外部挂载和文件中提到的外部路径都不自动扩权。隐式调用是宿主选中了 Skill，不是用户已授权写入。
| 宿主 | 用户级目录 | 显式调用 | 当前验证状态 |
|---|---|---|---|
| Codex 本地 | ~/.agents/skills/project-handoff-memory/ |
$project-handoff-memory |
按官方目录和语法整理；尚未做宿主加载实测 |
| Claude Code 本地 | ~/.claude/skills/project-handoff-memory/ |
/project-handoff-memory |
按官方目录和语法整理；尚未做宿主加载实测 |
| 其他 Agent | 以对应宿主文档为准 | 以对应宿主为准 | 未验证，不承诺自动发现或隐式调用 |
目录与调用语法参考 OpenAI Codex Skills 文档和 Claude Code Skills 文档。
安装前先确认目标目录不存在；如已有同名目录，请先检查来源、版本和未提交改动，不要直接覆盖。以下命令只克隆仓库，不会运行校验脚本或修改目标项目：
# Codex
git clone https://github.com/yangliangyl/project-handoff-memory.git \
~/.agents/skills/project-handoff-memory
# Claude Code
git clone https://github.com/yangliangyl/project-handoff-memory.git \
~/.claude/skills/project-handoff-memory多宿主共用同一实体目录并建立软链接可以减少分叉，但属于进阶配置；先确认各宿主实际加载路径，再自行选择。
进入目标项目后显式调用，并写清模式和授权范围。例如在 Codex 中说：
使用
$project-handoff-memory只读查看当前项目的交接情况，不要改文件。
使用
$project-handoff-memory更新当前项目的 handoff，只读取和修改当前项目；不要迁移或删除旧文件，先列出建议变更。
更新模式会：
- 定位项目根目录;
- 仅扫描授权项目树(不只看聊天上下文),跳过
.git、node_modules、大文件等噪声; - 读已有的交接信号,按项目类型(analysis / product / content / skill / knowledge)决定该强调什么;
- 更新约定的记忆文件，保留已有用户规则；
- 可选运行只读校验脚本，把超出授权修改范围的红项保留为报告，不为了全绿而扩权。
隐式调用是否发生取决于宿主；即使宿主选中了 Skill，也不应把“被发现”理解为已经获得跨目录读取、迁移或删除授权。
scripts/check_handoff.py 用来做只读结构诊断(标准文件、入口兼容性、Status 头、指针和 handoff 新鲜度等)。默认 compatible 模式保留已有入口规则，并把含“交接/沉淀”的文件视为迁移候选而非自动违规；只有项目已明确采用标准结构时才使用 strict。始终显式传入授权项目路径；无参数模式仅为向后兼容保留，不建议作为日常入口。
# 兼容诊断（默认）
python3 scripts/check_handoff.py --mode compatible /path/to/your/project
# 仅用于已明确采用标准结构的项目
python3 scripts/check_handoff.py --mode strict /path/to/your/project
# 只有另一个根目录也获得读取授权时，才允许验证指向它的相对 Markdown 路径
python3 scripts/check_handoff.py --allow-root /path/to/authorized-peer /path/to/your/project红项会让脚本 exit 1;黄项只提醒。超出授权根的 ../ Markdown 指针只标“未验证”，不会探测目标；mtime 新鲜度只作启发式提醒。检查结果是诊断，不是覆盖用户规则、迁移或删除的授权。
project-handoff-memory/
├── SKILL.md # skill 主定义(触发条件 + 工作流)
├── agents/openai.yaml # Codex 侧展示名与默认提示词
├── references/ # 工作流引用的规则细则
│ ├── file-contract.md # 每个文件的职责、更新模式、生长触发表
│ ├── project-types.md # 五类项目各自强调什么、该建哪些文件
│ ├── handoff-template.md # handoff.md 模板
│ ├── tree-scan.md # 项目树扫描规则
│ └── update-checklist.md # 收尾前自查清单
├── scripts/check_handoff.py # 结构合规机器校验
├── tests/test_check_handoff.py # 兼容、边界与只读回归测试
├── README.md
├── LICENSE
└── .gitignore
MIT © 2026 阿亮 (liangyls)