AI 编程 Agent 总在换会话时失忆？用 Flightwake 把交接证据留在 Git 里
让 Claude Code、Codex 或 Gemini 连续完成一个多日任务时，最难的部分往往不是下一段代码，而是重新建立上下文：上次做到了哪里、为什么放弃某条路线、哪些验证尚未做完、目前有没有隐患。Git 能告诉后来者“改了什么”，却很难回答“当时为什么这样改”。如果这些信息只存在于一次对话里，换会话、换模型或换同事后，就会重新进入一轮 Git 考古。
Flightwake 是一个面向 AI 编程 Agent 的轻量工作记录框架。它把自己比作“飞行记录器”，而不是替 Agent 规划每一步的导航：不要求先填满复杂的任务表，而是让关键决定、踩坑和验证证据在工作发生后沉淀为 Git 中的 Markdown 文件。项目采用 MIT 许可证，核心实现是 JavaScript；仓库创建于 2026 年 7 月，仍处于非常早期阶段，因此更适合作为一个可审阅的工作约定来试用，而不是不加检查地纳入所有团队流程。
真正缺的不是更多提示词，而是可接管的状态
一次 Agent 会话的“完成”不等于项目状态完整。常见的断点至少有四类：
- 会话结束，模型上下文随之消失；
- commit 记录结果，却不记录被否决方案和根因；
- 长任务中，Agent 可能在测试未跑完时过早宣称完成；
- Claude、Codex、Gemini 与人类协作者各自看到的上下文不同。
Flightwake 的思路是把这些差异收敛到仓库：状态、决策、陷阱和工作记录以纯 Markdown 保存并由 Git 跟踪。这样交接时不是把一段很长的聊天记录粘贴给新 Agent，而是让它读取一份面向接管的摘要，再从 Git 历史回溯必要细节。
它刻意不试图替代需求拆解或项目管理。README 把同类“逐步导航”框架与它区分开：前者决定路线，Flightwake 只负责留下行车记录、警示灯和路标。这个边界很重要——若团队还没有明确的验收标准，增加记录文件不会自动让需求变清楚。
安装后到底写进了什么
官方安装方式是从目标仓库运行 npx：
cd your-repo npx flightwake init
初始化会创建 .flightwake/ 模板与 Stop hook，复制 4 个 skills 到 .claude/skills/，并把 Stop hook 合并进 .claude/settings.json。它还会向已存在的 CLAUDE.md、AGENTS.md 或 GEMINI.md 写入带 flightwake:begin/end 标记的触发义务表；若这些文件都不存在，则创建 AGENTS.md。需要明确指定目标 Agent 时，可使用官方提供的参数：
npx flightwake init --agents=claude,codex,gemini
这里有两个值得在合并前检查的细节。第一，框架是“文件复制”式安装，运行时没有依赖；但 Node.js 18 或更高版本仍用于安装和 hooks。第二，--force 只更新框架拥有的文件，不应覆盖用户的 STATE、DECISIONS 或 TRAPS 数据。即便如此，在已有复杂 hooks 配置的仓库中，也应先在分支上执行并审阅 .claude/settings.json 的差异，而不是直接对主分支初始化。
一次交接可以怎样进行
首次安装后，官方建议让 Agent 用 /fw-record 初始化 STATE，并把新增的 .flightwake、.claude 和指令文件提交到 Git。之后的工作循环很短：会话开始时运行 /fw-coldstart；作出会关闭其他选择的决定时写入 DECISIONS；遇到不显而易见的坑时记录到 TRAPS；收尾时用 /fw-record 更新工作记录和状态。
新会话：/fw-coldstart Agent：读取 STATE 与最新记录，说明上次停点和未验证项 工作中：关键取舍写入 DECISIONS，异常经验写入 TRAPS 收尾：/fw-record 更新记录、STATE，并进行敏感信息自检
这不是一个“输入命令就自动治理”的机制。它依赖模型能够读取并遵循项目指令，也依赖人类愿意对状态质量负责。Flightwake 提供了一个很实用的检查视角：新会话能否在大约 5 分钟内安全接管。如果不能，应让 Agent 诊断是 STATE 过长、上次没有收尾，还是 TRAPS/DECISIONS 出现过时内容，然后提出可审阅的合并与标记方案。
文件结构决定了它能否真的被接管
安装后的核心目录是 .flightwake/：STATE.md 保持当前位置和下一步入口，DECISIONS.md 以追加方式记录取舍及原因，TRAPS.md 保存非显而易见的陷阱，records/ 则按有意义的收尾保存工作记录。这样的划分避免把所有信息塞进一个越来越长的交接文档：新 Agent 先读短小、当前的 STATE.md，需要理由时再查决策和记录。
官方把触发条件写得很具体：开始改仓库先冷启动；做出排除其他方案的决定就补一行决策；碰到坑就登记；触及 schema、生产环境或约 3 次以上提交时写记录；确定跨会话时才在停止前写 handoff。它是一种“事件触发”约定，而不是先研究、规划、执行的固定阶段流水线。已有 GSD .planning/ 的项目可以共存，旧规划可继续作为历史档案。
Stop hook 适合做提醒，不适合伪造保障
README 说明：当 STATE 落后 Git 提交达到 3 次时，Stop hook 会在会话结束前阻止一次，提醒补记录；--ci 可以把同类门槛带给其他 Agent 或人类协作者。这种设计适合防止“忘了收尾”的低成本失误，也能把“测试是否已验证”“生产变更是否留证据”变成仓库可见的问题。
但它不是安全边界，更不是 CI 的替代品。hook 能否运行取决于本地配置，记录也可能写得空泛。因此，涉及发布、数据库迁移或权限调整时，仍应由 CI、代码审查和真实环境验证承担最终把关。Flightwake 最有价值的部分，是让这些把关的结论和例外原因不再只留在临时对话中。
安全边界也要看清：官方说明 installer 不执行安装脚本、不访问网络，hook 仅用 git 做只读查询；但 hook 文件本身保存在仓库中，拥有提交权限的人也能修改它，信任级别与其他仓库配置相同。若记录不应进入共享仓库，可用 npx flightwake init --private；它会改用本地 settings、CLAUDE.local.md 与 .git/info/exclude。代价是记录不随 clone 共享，新的克隆仍需重新初始化。项目当前标为积极 dogfood 的 v0.x，约定仍可能演进，锁定版本并先审阅变更会比盲目升级更稳妥。
哪些团队值得先试
它尤其适合三种场景：同一仓库被多个 AI 编程 Agent 接力处理；修复周期跨越多个会话；团队需要把“为什么这么改”和“还没验证什么”保存在代码旁边。对一次性脚本、小型原型或节奏极快的探索任务，额外记录也可能成为负担。
一个稳妥的试行方式是：挑一个非关键仓库，只要求记录状态、关键决策和陷阱三类信息；两周后回看新会话接管是否更快、记录是否真的被读取，再决定是否把 Stop hook 与 CI 门槛推广。可以在试行结束时随机抽几条记录，检查它们是否回答了四个问题：当前代码状态、下一步入口、未验证风险、关键取舍原因。若记录不能帮助陌生协作者在不翻遍聊天记录的前提下接续工作，就应压缩模板或降低强制频率，而不是继续增加字段。还应避免把密钥、客户数据、生产日志或可识别个人信息直接写进状态文件；记录只需保留复现判断所需的最小证据，并把敏感值替换为引用位置或脱敏摘要。Flightwake 的价值不在于制造更多文件，而在于把 Agent 的工作痕迹变成可以审阅、可以交接、可以随 Git 演进的工程资产。
相关链接