当AI编码助手有了＂记忆＂:repo-harness如何把Claude/Codex的临时会话变成可复用的工作流

你有没有遇到过这种情况：用 Claude 或 Codex 写代码，聊了一下午终于把功能调通了，第二天打开新会话，发现 AI 对昨天的上下文一无所知——又得从头开始解释项目结构、之前做了什么、卡在哪里。

更头疼的是，一个项目可能同时用到 Claude 和 Codex，两个 AI 各聊各的，完全不知道对方做了什么。项目状态散落在不同的聊天记录里，无法审查、无法恢复、无法交接。

如果 AI 编程会话不再是"聊完就忘"的一次性对话，而是像 Git 一样有状态、可恢复、可审查的呢？

这就是 repo-harness 在做的事情。

它解决的核心问题

repo-harness 把 Claude/Codex 的 AI 编程会话变成可复用、可恢复、可检查的仓库本地工作流。它提供 CLI 和运行时钩子，把上下文、计划、交接、检查结果和审查证据写回项目文件。

简单说，它主要解决三件事：

• 快速接入已有仓库：用 tasks-first 的 agent 合约，让 AI 理解你的项目结构
• Claude 和 Codex 共享同一套工作流：计划、检查、交接、上下文边界完全统一
• 省 Token：用 CodeGraph 索引和渐进式上下文加载，减少重复扫描仓库结构

会话状态在文件里，不在聊天记录中

这是 repo-harness 最核心的设计理念。

传统的 AI 编程流程是：你在聊天窗口里告诉 AI 项目背景 → AI 理解后开始写代码 → 会话结束，一切归零。

repo-harness 的做法是：所有状态都写在仓库文件里。.ai/harness/handoff/resume.md 记录上一会话的进度，tasks/current.md 记录当前任务，plans/ 目录存放已批准的计划。

新会话启动时，钩子自动注入上一会话的恢复包。会话结束时，下一份交接文档写回仓库。任务可以在中途断开，下一个会话直接接上准确的下一步、阻塞点和改动文件，不需要重新推断。

这意味着你可以：

• 随时关闭会话，明天再继续
• 在 Claude 和 Codex 之间来回切换，它们读同一套文件
• 团队成员 review 的不是聊天记录，而是仓库里的结构化文档

天生省 Token

用过 AI 编程的人都知道，Token 消耗是大问题。每次新会话 AI 都要重新扫描项目结构——读 package.json、看目录树、翻源代码。

repo-harness 用两个机制解决这个问题：

CodeGraph 索引：预建的项目结构索引，支持结构化查询（谁调用谁、定义在哪里），不需要每次 grep+read 循环。

渐进式上下文加载：.ai/context/context-map.json 和 capabilities.json 提供一份小而稳定的根上下文（约 12KB），加上只在改到对应文件时才加载的能力块。AI 读一份 1KB 的能力合约或查索引，而不是花上千 Token 重新摸清结构。

三层架构

repo-harness 的整体设计分三层：

源码包层：本仓库维护 CLI、模板、钩子脚本、工作流合约和测试。

目标仓库合约层：执行 repo-harness adopt 后，目标仓库会写入 docs/spec.md、plans/、tasks/、.ai/context/、.ai/harness/ 等文件和目录。

Host 适配器层：用户级别的 ~/.claude/settings.json 和 ~/.codex/hooks.json 把 Claude/Codex 的事件路由到 repo-harness 的钩子。钩子入口先检查当前仓库是否存在 .ai/harness/workflow-contract.json，没接入就静默退出。

核心不变量：持久事实在仓库里，不在聊天窗口里。钩子只是加速器和护栏，真正的权威是 Plan、Contract、Review、Checks 和 Handoff 这些文件。

任务工作流：从 Plan 到 Closeout

repo-harness 定义了一套完整的工作流：

1. Plan：从 Sprint backlog 或用户任务出发，完成前置调查，形成可执行计划
2. Contract：将已批准的计划投射到执行面，生成 contract、review、notes 等文件
3. Worktree：需要时 checkout 隔离工作树，避免污染主分支
4. Implement：在钩子的保护下编辑代码，Pre-edit 钩子检查 Plan 状态、Contract 范围、Worktree 策略
5. Verify：运行测试和工作流检查，产出结构化 evidence
6. Review：审查者 review，外部验收
7. Closeout：提交 Contract 分支 → Fast-forward 合并 → 归档 Plan → 清理 Worktree

整个流程中，每一个步骤都有文件记录，每一个决策都有据可查。

钩子系统：8 条托管路由

repo-harness 定义了 8 条托管钩子路由，覆盖 AI 编程会话的完整生命周期：

路由	触发时机	作用
SessionStart.default	会话开始	注入上次的 Handoff、Sprint 状态和安全配置检查
PreToolUse.edit	编辑文件前	Worktree 守卫、Pre-edit 守卫
PostToolUse.edit	编辑文件后	Post-edit 守卫，记录 trace、检测 drift
PostToolUse.bash	执行命令后	观察命令结果，捕获验证证据
PostToolUse.always	每次工具调用	低噪音的运行时跟踪
UserPromptSubmit.default	用户提交提示	分类提示意图，路由到规划/检查/排查
Stop.default	会话结束	最终 Handoff，防止未完成的 Draft Plan 丢失

5 分钟快速上手

评估一个仓库是否适合接入 repo-harness，只需几步：

1. 安装 CLI

curl -fsSL https://raw.githubusercontent.com/Ancienttwo/repo-harness/main/install.sh | sh

2. Host 运行时引导

repo-harness install

3. 预览仓库合约

在目标仓库根目录运行 dry-run，看看会改什么：

npx -y repo-harness adopt --dry-run

4. 应用并验证

npx -y repo-harness adopt
bash scripts/check-task-workflow.sh --strict
bun test

应用后，目标仓库会得到一套可审查的 file-backed 合约。

适用场景

repo-harness 适合以下团队和项目：

• 多人协作的 AI 辅助开发：Claude 和 Codex 混用，需要统一的工作流
• 复杂项目的长期开发：会话跨越数天甚至数周，需要可恢复的状态
• 对代码质量有要求的项目：每一个改动都有 Plan、Review、Checks 的完整证据链
• 希望节省 Token 的团队：渐进式上下文加载和 CodeGraph 索引大幅减少重复消耗

写在最后

repo-harness 代表的是一种思路的转变：AI 编程不应该停留在"聊天框里写代码"的阶段。当 AI 的会话状态像 Git 一样落在文件里，当计划、审查、验证形成完整的证据链，AI 辅助开发才能真正从"玩具"变成"工具"。

项目地址：https://github.com/Ancienttwo/repo-harness

如果你正在深度使用 Claude 或 Codex 写代码，不妨试试给项目装上这个"记忆系统"。