1. 项目概述为AI编程助手装上“行车记录仪”如果你和我一样已经深度依赖Claude Code、Cursor或者GitHub Copilot这类AI编程助手来辅助日常开发那你一定经历过这样的“信任危机”时刻你让AI去实现一个功能它信誓旦旦地回复“已完成”结果你一看代码里面全是TODO、pass或者raise NotImplementedError。更让人头疼的是当你第二天打开项目想接着昨天的进度继续时AI助手仿佛得了“健忘症”完全不记得昨天干到哪一步了你又得从头解释一遍需求。这种“AI幻觉”和“上下文丢失”的问题不仅浪费了时间更关键的是它破坏了人机协作中最基本的信任。Agent Checkpoint这个项目就是为了解决这个核心痛点而生的。你可以把它理解为一个专为AI编程助手设计的“控制面板”和“行车记录仪”。它通过一套极其轻量、基于纯文本文件的机制在人类开发者和AI助手之间建立了一个清晰、透明、可验证的协作协议。它的核心目标很简单防止AI说谎确保工作进度可追踪让每一次人机协作都有据可查。无论你用的是Claude、Cursor、Copilot还是Gemini这套方案都能无缝接入因为它不依赖任何特定的API只基于所有AI都能读写的Markdown文件。2. 核心设计思路基于文件的通用控制平面为什么选择文件而不是一个复杂的Web服务或IDE插件这是Agent Checkpoint设计中最精妙也最务实的一点。在深入使用过各种AI助手后我发现它们的交互模式、上下文长度和记忆能力千差万别但有一个共同点它们都能出色地理解和生成文本尤其是Markdown。基于这个最大公约数构建一个文件驱动的控制平面就成了兼容性最高、侵入性最低的方案。2.1 四核心文件的分工与协作整个系统的运转依赖于四个核心文件它们各司其职共同构成了一个完整的监督闭环TASKS.md- 任务清单与控制中心这是整个系统的“大脑”由人类开发者完全掌控。所有需要AI完成的工作都被拆解成一个个原子任务以Markdown任务列表的形式记录在这里。每个任务不仅描述了“做什么”更重要的是通过元数据如verify:、depends:定义了“怎么做”和“如何验收”。这个文件是AI助手每次会话的“必读文档”它告诉AI当前的工作上下文和待办事项。文件被纳入Git版本控制确保了任务状态的持久化完美解决了AI“健忘”的问题。AGENT_LOG.md- 只追加审计日志这是系统的“黑匣子”或“行车记录仪”。它是一个只追加append-only的Markdown文件任何AI助手在执行任务过程中的关键动作——开始任务、提交代码、遇到错误——都必须以标准格式记录到此文件中。这种设计保证了日志的不可篡改性至少篡改会被Git轻易发现为事后复盘、权责划分提供了完整的证据链。每次查看这个日志你都能清晰地知道哪个AI、在什么时间、对哪个任务、声称做了什么。verify.py- 自动化验证引擎这是系统的“质检员”。它是一段独立的Python脚本核心职责是检验AI在AGENT_LOG.md中“声称”完成的工作是否属实。它的验证逻辑非常务实检查文件是否存在、函数/类是否被正确定义、代码中是否包含占位符或存根Stub。对于更高级的任务它还能自动运行单元测试。这个脚本将人类从繁琐的代码审查中解放出来将“信任但要验证”的原则自动化。.agent-rules.md- 通用代理指令集这是系统的“适配器”或“操作手册”。它是一个简短的Markdown文件包含了针对不同AI助手的定制化指令告诉它们如何与上述三个文件交互。例如给Claude Code的指令可能是“每次会话开始时先读取TASKS.md”给Cursor的指令则写入.cursorrules文件。这个文件确保了这套方法论能覆盖几乎所有主流的AI编码工具。这套设计的优雅之处在于它的简单性和普适性。它没有引入任何新的复杂协议或中间件只是巧妙地利用了现有工具Git、Markdown、Python和AI的基本能力文本处理就构建起一个强大的监督框架。下面这张关系图清晰地展示了四者如何协同工作开发者编辑 │ ▼ [TASKS.md] ─── 读取任务 ─── AI代理 │ (Claude/Cursor/等) │ │ │ ▼ 执行并记录 └─────────────── [AGENT_LOG.md] │ ▼ 触发验证 [verify.py] ──── 输出验证结果 │ ▼ 反馈状态 [TASKS.md] (更新任务状态)2.2 状态流转与验证级别任务在TASKS.md中的状态流转是整个流程的直观体现。我设计了一套简洁的状态标记符[ ]任务待开始。[~]任务进行中AI已认领。[x]任务已完成且通过验证。[?]需要人工复核针对verify: human的任务。[!]任务被阻塞通常因为依赖任务未完成。验证级别是控制验收严格度的关键。在定义任务时通过verify:字段指定给了开发者极大的灵活性none不验证。用于“更新文档”这类纯粹的文字工作。auto默认执行基础验证包括文件存在性、非存根检测。这是最常用的级别能过滤掉90%的“AI谎言”。tests在auto的基础上自动运行指定的测试文件通过tests:字段指定。这是实现“测试驱动开发”与AI协作的理想方式。human在auto验证通过后流程会暂停等待开发者进行人工代码审查。审查通过后需要手动运行命令将状态标记为完成。用于核心业务逻辑等关键代码。这种分级验证机制在效率和质量之间取得了很好的平衡。日常的样板代码用auto快速推进涉及业务逻辑的用tests确保质量而系统最核心的模块则必须经过human这道最终关卡。3. 实战部署与配置指南理论讲得再多不如动手配置一遍来得实在。Agent Checkpoint的部署可以用“傻瓜式”来形容但其中一些配置细节却决定了它能否与你现有的工作流完美融合。3.1 一键安装与个性化配置最推荐的方式是使用项目提供的一键安装脚本。它不仅会下载文件还能根据你的主要AI助手进行预配置。# 基础安装仅获取核心文件 curl -fsSL https://raw.githubusercontent.com/akz4ol/agent-checkpoint/main/install.sh | bash # 如果你主要使用Claude Code安装并自动配置CLAUDE.md curl -fsSL https://raw.githubusercontent.com/akz4ol/agent-checkpoint/main/install.sh | bash -s -- --with-claude # 如果你主要使用Cursor安装并自动配置.cursorrules curl -fsSL https://raw.githubusercontent.com/akz4ol/agent-checkpoint/main/install.sh | bash -s -- --with-cursor # 贪心一点把所有常见代理的配置都生成出来 curl -fsSL https://raw.githubusercontent.com/akz4ol/agent-checkpoint/main/install.sh | bash -s -- --all执行后你的项目根目录下会新增四个文件。我强烈建议你立即将TASKS.md和AGENT_LOG.md加入到.gitignore的例外清单中或者直接不忽略.md文件确保它们被版本控制系统追踪。这是保证状态持久化的关键一步。注意一键安装脚本会从网络下载资源。在高度安全敏感的环境下你可以选择手动安装克隆仓库后将四个核心文件复制到你的项目目录即可。手动安装后需要你自行根据.agent-rules.md中的模板去配置对应AI助手的指令文件。3.2 为你的AI助手编写“工作说明书”安装文件只是第一步让AI助手“学会”使用这套系统才是关键。这就是.agent-rules.md和各个AI专属配置文件的作用。你需要根据自己使用的工具将对应的指令“喂”给AI。以Cursor为例你需要编辑或创建项目根目录下的.cursorrules文件将.agent-rules.md中关于Cursor的章节复制进去。核心指令通常包括会话初始化时读取TASKS.md了解当前项目状态和待办任务。开始任务时将任务状态标记为[~]并在AGENT_LOG.md中创建一条STARTED记录。声称完成代码时必须列出修改的文件和行号范围记录到AGENT_LOG.md的CLAIM条目中。被要求验证时知道可以运行python verify.py task_id来检查自己的工作。对于Claude Code操作类似但配置文件是CLAUDE.md。其他如GitHub Copilot.github/copilot-instructions.md、Windsurf.windsurfrules等均有对应的配置位置。实操心得在初次配置时不要一次性把全部规则丢给AI。可以先配置最核心的“读取任务”和“记录日志”两条规则让AI跑通基本流程。在几次成功的协作后再逐步添加更复杂的规则比如自动运行验证。这能帮助你更好地理解AI对指令的反馈也避免了因规则过于复杂导致AI行为错乱。3.3 编写你的第一份任务清单现在打开空白的TASKS.md开始规划你的项目。任务拆分的质量直接决定了AI执行的效率。我的经验法则是一个任务最好对应一个可验证的产出通常是一个文件中的某个类或函数。假设我们要开发一个简单的用户认证模块TASKS.md可以这样写# 用户认证模块开发 ## 1. 用户模型层 - [ ] 1.1 创建用户模型类 src/models/user.py:User - 属性id (int), username (str), email (str), hashed_password (str), created_at (datetime) - 方法__init__, __repr__ - verify: auto - [ ] 1.2 添加密码哈希与验证方法 src/models/user.py:hash_password 和 verify_password - 使用 bcrypt 或 passlib 库 - verify: tests - tests: tests/test_user_model.py::TestPasswordHashing ## 2. 数据库交互层 - [ ] 2.1 创建用户数据库操作类 src/db/user_repository.py:UserRepository - 方法create_user, get_user_by_id, get_user_by_username - 使用 SQLAlchemy Core 或 asyncpg - verify: auto - depends: 1.1 ## 3. API路由层 - [ ] 3.1 创建用户注册端点 src/routes/auth.py:register_user - POST /api/auth/register - 接收 username, email, password - 调用 UserRepository 创建用户 - verify: tests - tests: tests/test_auth_routes.py::TestUserRegistration - depends: 1.2, 2.1 - [ ] 3.2 创建用户登录端点 src/routes/auth.py:login_user - POST /api/auth/login - 返回 JWT 令牌 - verify: human - depends: 3.1这份清单的优点在于原子化每个任务目标明确AI不容易混淆。可验证通过verify:字段和具体的文件、行号、函数名让verify.py有据可查。有依赖通过depends:字段定义了任务顺序AI或开发者能清晰知道工作流。分级控制核心的登录逻辑涉及令牌生成要求human复核安全可控。写好清单后你就可以像分配工作一样把TASKS.md丢给AI助手说一句“请从当前标记为[ ]的任务开始按照依赖关系协助我开发。”协作便正式开始了。4. 验证引擎深度解析与定制verify.py是Agent Checkpoint的“铁面判官”它的可靠性直接决定了整个系统的可信度。让我们深入其内部看看它是如何工作的以及如何根据你的项目特点进行定制。4.1 存根检测如何抓住AI的“小辫子”AI生成的代码中未完成的“存根”形式多样。verify.py内置的检测器会从多个维度进行扫描模式匹配检测代码注释或字符串中是否包含明显的占位符标记如TODO、FIXME、XXX、HACK、# stub、// placeholder等。这是最直接的一层过滤。语法结构分析检测是否抛出了特定的异常例如Python的raise NotImplementedError、TypeScript的throw new Error(Not implemented)。这是函数体未完成的铁证。空洞函数体检测识别那些函数体为pass、...Python Ellipsis或仅有return None的“空壳”函数。逻辑行数检查这是一个启发式规则。一个功能完整的函数通常不会只有1-2行实质性代码扣除定义行和空行。可以设置一个阈值如最少3行有效逻辑过滤掉过于简单的实现。实操心得默认的检测规则适用于大多数情况但对于某些特定场景可能需要调整。例如如果你项目中有很多简单的Getter/Setter方法可能只有一行return那么“逻辑行数检查”就可能产生误报。此时你可以修改verify.py中的_is_likely_stub函数为某些特定模式如函数名以get_或set_开头添加白名单。4.2 测试验证集成当任务标记为verify: tests时verify.py会尝试自动运行测试。它默认支持Python使用pytest运行指定的测试文件、测试类或测试函数。JavaScript/TypeScript使用jest或npm test/yarn test。其工作流程是解析任务中tests:字段格式如tests/test_file.py::TestClass::test_method。构造对应的测试运行命令。在子进程中执行命令并捕获输出和退出码。如果所有测试通过退出码为0则验证成功否则将测试失败信息输出到日志并标记验证失败。注意事项确保你的项目测试环境是准备好的并且测试命令可以在项目根目录下直接运行。对于复杂的测试环境需要额外的数据库、服务等你可能需要先编写启动测试环境的脚本并在verify.py中调用该脚本。4.3 CLI工具的灵活运用verify.py也是一个命令行工具提供了多种使用姿势适应不同场景# 1. 验证单个任务最常用的方式在AI声称完成后手动触发或设置自动化钩子。 python verify.py 1.1 # 2. 批量验证所有进行中的任务在每日工作开始前或提交代码前快速检查AI的总体进度。 python verify.py --all # 3. 快速检查一个代码声明不通过任务系统直接检查某段代码是否属实。适用于临时抽查。 # 格式文件名:起始行-结束行 python verify.py --check src/utils/helpers.py:15-30 # 4. 静默验证不更新日志当你只想看看结果不想留下正式验证记录时使用。 python verify.py 2.3 --no-log # 5. 强制重新验证已完成任务当底层代码发生变动需要重新确认时使用。 python verify.py 3.1 --force一个我常用的工作流我会在本地Git的pre-commit钩子中集成python verify.py --all命令。这样每次我试图提交代码时它会自动检查所有标记为[~]进行中的任务是否真的通过了验证。如果AI谎报了进度提交就会被阻止从流程上杜绝了“半成品”代码进入版本库。5. 审计日志构建完整的可追溯性AGENT_LOG.md远不止是一个简单的日志文件它是一个结构化的、机器可读的协作数据库。每一条记录都是一个标准的Markdown文档片段包含固定的元数据。5.1 日志条目解析让我们看一个完整的日志条目了解其信息密度--- ## 2025-01-25T14:20:0508:00 | cursor | Task 2.1 **Status**: CLAIM **Files**: - src/db/user_repository.py:1-85 (创建了UserRepository类包含create_user和get_user_by_id方法) - src/db/database.py:10-15 (添加了新的数据库连接助手函数) **Code Changes Summary**: - 在 user_repository.py 中实现了基于SQLAlchemy的UserRepository。 - create_user 方法现在会验证用户名唯一性。 - 在 database.py 中新增了 get_db_session 上下文管理器。 **Next Steps**: - 需要实现 get_user_by_username 方法。 - 考虑为 create_user 添加邮箱格式验证。 ---这个条目告诉我们时间与代理2025年1月25日由Cursor代理执行。关联任务任务ID 2.1。状态CLAIM表示AI声称完成了这些工作。变更详情精确到文件的行号范围以及人类可读的变更摘要。后续建议AI甚至可以根据上下文提出下一步工作的建议。当verify.py运行后它会紧接着添加一条VERIFIED或FAILED的记录--- ## 2025-01-25T14:22:3008:00 | verify.py | Task 2.1 **Status**: VERIFIED **Results**: - file-exists: PASS (src/db/user_repository.py) - file-exists: PASS (src/db/database.py) - not-stub: PASS (user_repository.py中的create_user方法实现完整) - not-stub: PASS (database.py中的get_db_session实现完整) **Verified By**: auto ---这两条记录一前一后构成了一个从“声称”到“证实”的完整证据链。5.2 基于日志的洞察与团队协作结构化的日志带来了巨大的分析潜力。你可以编写简单的脚本从AGENT_LOG.md中提取信息生成报告代理效率报告统计每个AI代理Claude、Cursor等完成的任务数量、平均验证通过率。任务耗时分析计算从STARTED到VERIFIED的时间差了解不同类型任务的AI处理时长。常见失败模式分析FAILED记录看看AI最常在哪些地方“说谎”是存根检测失败多还是测试失败多从而优化你的任务描述或验证规则。在团队协作中AGENT_LOG.md的价值更加凸显。当一位同事接手你的项目时他不再需要费力地询问“之前AI做到哪一步了”只需要查看TASKS.md的任务状态和AGENT_LOG.md的详细记录就能立刻掌握全部上下文。这极大地降低了协作成本也让基于AI的结对编程Human-AI Pair Programming成为可能。6. 高级技巧与疑难排解经过一段时间的深度使用我积累了一些超越基础文档的实战技巧和常见问题的解决方法。6.1 任务拆分的艺术如何给AI拆解任务是一门学问。拆得太粗AI容易迷失拆得太细管理成本剧增。黄金法则一个任务一个可交付的代码单元。这个“单元”通常是一个文件、一个类、或者一个功能完整的函数。例如“实现用户注册API”是一个好任务因为它对应一个具体的端点函数。善用depends字段管理依赖清晰地定义任务依赖可以引导AI按正确的顺序工作也让你能一目了然地看到关键路径。对于复杂的模块可以画一个简单的依赖图放在TASKS.md顶部帮助理解和规划。为复杂任务编写“验收标准”子项对于特别复杂的任务如“实现一个支持多种策略的排序算法”除了verify: tests可以在任务描述下面用列表形式写明具体的验收标准例如- [ ] 4.1 实现快速排序算法 src/algorithms/sort.py:quick_sort - verify: tests - tests: tests/test_sort.py::TestQuickSort - 验收标准 - 能正确排序整数数组 - 能处理空数组和单元素数组 - 时间复杂度平均为O(n log n) - 包含详细的代码注释这相当于给AI一份更详细的需求说明书。6.2 应对AI的“创造性误解”有时AI会以一种意想不到的、但并非错误的方式实现需求。例如你要求“从数据库获取用户”AI可能用原始SQL、SQLAlchemy ORM或异步驱动等多种方式实现。在任务描述中锁定技术栈明确指定库、框架或模式。例如“使用asyncpg异步获取用户”“使用Pydantic模型进行数据验证”。利用.agent-rules.md或项目专属规则文件在给AI的全局指令中定义项目的技术偏好和代码风格。例如“本项目使用SQLAlchemy 2.0风格”、“所有API响应必须包裹在BaseResponse模型里”。这能从源头减少歧义。verify: human是你的安全网对于技术选型特别关键的任务直接设置为需要人工复核。在AI提交CLAIM后你花几分钟审查其实现方式如果不符预期直接在AGENT_LOG.md中回复一条HUMAN_REVIEW记录指出问题让AI修正。6.3 验证失败常见原因与排查当python verify.py报告失败时别慌按以下步骤排查失败现象可能原因解决方案file-exists: FAILAI记录的文件路径错误或文件确实未创建。1. 检查AGENT_LOG.md中Files:项的文件路径是否正确。2. 检查项目目录下该文件是否存在。not-stub: FAIL代码中存在占位符或实现过于简单。1. 运行python verify.py --check file:line定位具体问题代码。2. 查看输出信息确认是哪种存根模式TODO、NotImplementedError等。3. 要求AI补充完整实现。tests: FAIL单元测试未通过。1. 查看verify.py输出的具体测试错误信息。2. 可能是AI的实现逻辑有bug也可能是测试用例本身需要更新。3. 将测试失败信息提供给AI让其修复。命令执行错误Python环境问题或依赖未安装。1. 确认在正确的虚拟环境中运行。2. 确认pytest、jest等测试框架已安装。3. 对于复杂项目可能需要先执行python -m pytest而不是pytest。一个典型排查案例 AI声称完成了任务3.1创建注册端点但验证失败。你运行python verify.py 3.1输出显示not-stub: FAIL。接着运行python verify.py --check src/routes/auth.py:50-80发现AI在register_user函数里写了一句# TODO: add email validation。于是你直接在AGENT_LOG.md中AI指出问题所在AI便能快速定位并修复。6.4 与现有开发流程的集成Agent Checkpoint不是要取代你现有的Git工作流或CI/CD而是增强它。与Git分支策略结合可以为每个由AI主导开发的新功能创建一个特性分支如feat/ai-auth。在该分支中TASKS.md和AGENT_LOG.md详细记录了AI的开发过程。功能完成后合并到主分支时这些文件提供了无与伦比的代码审查上下文。集成到CI/CD管道你可以在GitHub Actions、GitLab CI等工具中添加一个验证步骤。例如在针对特性分支的Pull Request检查中运行python verify.py --all如果存在未通过验证但被标记为进行中[~]的任务则CI失败阻止合并。这确保了主分支代码的完整性。作为知识库的一部分项目完成后AGENT_LOG.md是一个宝贵的知识库。新成员可以通过它了解每个模块是如何被构建出来的遇到了哪些问题是如何解决的。这对于维护和后续迭代极具价值。这套工具的本质是将与AI协作过程中模糊的、易失的对话转变成了结构化的、可追踪的、可验证的项目资产。它没有引入魔法只是用工程化的思维为“人机结对编程”建立了一套可靠的流程规范。