AI编程助手防忽悠指南：用文件契约与自动化验证提升协作效率

1. 项目概述：为AI编程助手装上“行车记录仪”

如果你和我一样，在日常开发中深度依赖Claude Code、Cursor、GitHub Copilot这类AI编程助手，那你一定也经历过那种“信任崩塌”的时刻。助手信誓旦旦地说：“功能已全部实现，请验收。”你满怀期待地运行代码，结果要么是抛出一个NotImplementedError，要么是发现核心逻辑里躺着一个刺眼的# TODO: implement this。更让人头疼的是，当项目中断几天再回来，你完全记不清上次助手做到哪一步了，哪些是它吹的牛，哪些是真正可用的代码。这种缺乏透明度和可追溯性的协作，就像在闭着眼睛走钢丝。

Agent Checkpoint 就是为了解决这个痛点而生的。它不是一个全新的AI助手，而是一个轻量级的“控制平面”或“审计层”。你可以把它理解成给AI编程助手装上的“行车记录仪”和“任务清单管理器”。核心思路非常朴素：将任务定义、执行过程和验证结果，通过几个简单的Markdown文件进行标准化和持久化。这样一来，人与AI之间的协作就从一次性的、黑盒的对话，变成了可追踪、可审计、可复现的工程项目管理。

它的核心价值在于“防忽悠”和“保进度”。通过一套简单的文件约定（TASKS.md任务清单、AGENT_LOG.md审计日志）和一个Python验证脚本（verify.py），它强制AI助手在声称完成某项工作后，必须经过代码层面的实质验证。这直接针对了AI助手目前最普遍的“幻觉”（Hallucination）问题——即生成看似合理但实际不完整或错误的代码。项目引用了一项2024年的研究数据：高达42%的AI生成代码包含这种“幻觉”。Agent Checkpoint 就是通过工程化的手段，将这个比例尽可能压到零。

这套工具几乎没有任何使用门槛。它不绑定任何特定的AI服务，只要你的助手能读写Markdown文件（现在哪个不能呢？），就能接入。无论是独立开发者管理个人项目，还是小团队希望规范AI辅助编程的流程，它都能立刻带来透明度和掌控感的显著提升。接下来，我会带你深入它的设计哲学、手把手配置使用，并分享我在实际落地中总结出的实战技巧和避坑指南。

2. 核心设计哲学：为何简单的文件约定如此有效

在深入代码细节之前，理解 Agent Checkpoint 背后的设计哲学至关重要。它没有采用复杂的微服务、数据库或API，而是回归了Unix哲学和Web基础架构中经久不衰的智慧：纯文本文件是最高效、最通用、最可追溯的接口。

2.1 以文件为契约，建立人机协作的单一事实来源

所有软件开发，无论是人与人还是人与AI的协作，最大的成本之一就是“状态同步”。AI助手本质是一个有状态的、但状态极易丢失的服务。你关闭聊天窗口，或开始一个新话题，之前的上下文就可能变得模糊或丢失。Agent Checkpoint 的核心创新在于，它把人机协作的“状态”从AI服务的内存中，提取出来，固化到项目仓库的版本控制文件里。

• TASKS.md是计划与契约：它取代了模糊的、非结构化的自然语言需求描述。当你将需求拆解为具体的、可验证的原子任务（例如“创建用户模型类User于src/models/user.py”）并写入此文件时，你就为AI助手提供了一份精确的“施工图纸”。这不仅减少了歧义，更重要的是，这个文件本身成为了项目待办事项的权威来源，可以被git管理，可以被团队成员共同编辑。
• AGENT_LOG.md是过程与审计：这是一个只追加（append-only）的日志文件。AI助手每进行一个关键操作（开始任务、声称完成、遇到错误），都需要在此留下带有时间戳的记录。这解决了“黑盒”问题。任何时候，你都可以回溯整个开发过程，了解“这个函数是谁（哪个AI模型）在什么时候声称实现的？当时它说了什么？”。这对于调试和厘清责任至关重要。
• verify.py是验收与质检：这是将承诺落地的关键。它根据TASKS.md中定义的验证级别，去检查代码仓库的实际情况。文件是否存在？函数是否被正确定义？里面有没有藏TODO或pass？相关的单元测试是否通过？这个脚本充当了客观的、自动化的“质检员”，杜绝了AI的口头承诺。

这种“文件契约”模式的美妙之处在于其极致的简单性和通用性。它不依赖于任何特定的API或SDK，因此能够无缝适配几乎所有AI编程助手。

2.2 普适性优先：拥抱最低公分母（Markdown）

项目作者做了一个非常明智的取舍：为了获得最大的兼容性，放弃了可能更“强大”但更封闭的集成方案。当前主流的AI编程助手，无论是IDE插件（Cursor, Claude Code, Windsurf）还是云端服务（GitHub Copilot Chat, Gemini），它们与用户项目交互的核心方式之一，就是读取项目根目录下的特定指导文件（如.cursorrules,CLAUDE.md）。

Agent Checkpoint 巧妙地利用了这一点。它的TASKS.md和AGENT_LOG.md就是标准的Markdown文件，而.agent-rules.md则是一个通用的指导文件，其内容可以被轻易地复制或适配到任何AI助手特定的配置文件中。例如，你可以在.cursorrules里写上：“请优先查看并遵循TASKS.md中的任务列表，并在执行后更新状态和AGENT_LOG.md”。这样，你就用最小的成本，为所有助手统一了工作流程。

这种设计使得项目具有惊人的生命力。即使未来出现新的AI编程工具，只要它支持读取文本文件，就能融入这套体系。这比为一个特定工具开发深度插件要可持续得多。

2.3 验证分级：平衡效率与可靠性的艺术

不是所有代码都值得用同样的严格程度去验证。Agent Checkpoint 设计的四级验证策略（none,auto,tests,human）体现了实用的工程思维。

• none: 用于纯粹的组织性任务，如“更新README文档”。无需验证，完全信任AI或后续人工检查。
• auto: 这是默认的、最常用的级别。它执行基础的“防忽悠”检查：文件存在吗？声称实现的函数/类存在吗？里面有没有明显的存根（Stub）代码？这层检查能过滤掉80%的低级“幻觉”。
• tests: 在auto的基础上，运行指定的测试套件。这是确保代码不仅存在，而且行为符合预期的关键。它要求项目本身有良好的测试基础设施，将AI编程纳入到团队的CI/CD质量门禁中。
• human: 最高级别，在自动检查后暂停，等待人工代码审查。用于核心算法、安全模块或架构关键点。这承认了当前AI的局限性，将最终决策权留给人。

这种分级机制让开发者可以根据任务的风险和重要性分配验证资源，而不是一刀切地增加所有环节的耗时，保证了工具在提供安全保障的同时不拖慢开发节奏。

3. 实战部署：一步步将Checkpoint集成到你的工作流

理解了“为什么”之后，我们来看“怎么做”。我会以一个典型的Python Web后端项目为例，展示如何从零开始部署并使用Agent Checkpoint，并分享一些超越官方文档的配置心得。

3.1 环境准备与安装决策

官方提供的一键安装脚本非常方便，但我强烈建议，尤其是第一次使用时，采用手动安装的方式。这能让你更清楚地知道有哪些文件被放入你的项目，理解它们各自的作用。

# 进入你的项目根目录 cd /path/to/your/project # 克隆Agent Checkpoint仓库（可以克隆到一个临时位置） git clone https://github.com/akz4ol/agent-checkpoint.git /tmp/agent-checkpoint # 将核心文件复制到你的项目 cp /tmp/agent-checkpoint/TASKS.md . cp /tmp/agent-checkpoint/AGENT_LOG.md . cp /tmp/agent-checkpoint/.agent-rules.md . cp /tmp/agent-checkpoint/verify.py . # 检查verify.py的依赖，通常只需要标准库，但测试验证需要pytest # 可以选择安装pytest，如果项目本身就在用的话 pip install pytest # 或 pip3 install pytest

现在，你的项目根目录下会多出四个文件。第一步，也是最重要的一步，就是立即将它们加入.gitignore的例外清单，并提交到版本库。因为它们是协作流程的一部分，而非构建产物。

# 确保它们没有被 .gitignore 忽略（通常不会，但检查一下） # 然后将它们加入版本控制 git add TASKS.md AGENT_LOG.md .agent-rules.md verify.py git commit -m “feat: integrate Agent Checkpoint for AI agent audit”

注意：AGENT_LOG.md文件在后续会被AI助手频繁写入。为了避免合并冲突，一个最佳实践是：个人开发时，可以正常提交它；在团队协作中，可以考虑将其加入.gitignore，仅作为本地审计工具使用，或者团队约定以谁的最新日志为准。因为它的内容是追加的，冲突解决起来比较麻烦。

3.2 配置你的AI助手：以Cursor和Claude Code为例

复制文件只是第一步，让AI助手“意识”到这些规则并遵守它们，需要进行配置。以下是针对两个最流行助手的配置方法。

为Cursor配置：Cursor的配置文件是.cursorrules，它直接影响Cursor Agent的行为。打开（或创建）项目根目录下的.cursorrules文件，将以下内容加入其中：

# .cursorrules - Agent Checkpoint Integration ## Primary Workflow 1. **Always first check `TASKS.md`** for pending tasks when I ask you to work on this project. This is the single source of truth. 2. **Before starting any task**, ensure its status in `TASKS.md` is `[ ]` (pending), then change it to `[~]` (in progress). 3. **Immediately after changing the status**, append a “STARTED” entry to `AGENT_LOG.md` with timestamp, your agent name (“cursor”), and task ID. 4. **When you believe a task is complete**: a. Update its status in `TASKS.md` to `[x]` tentatively. b. Append a detailed “CLAIM” entry to `AGENT_LOG.md`, listing **every file and line range** you created or modified (e.g., `src/models/user.py:15-45`). c. **Run the verification command** `python verify.py <task_id>` in your mind to simulate checks. Do not claim completion if verification would fail. 5. **If I ask you to verify a task**, run the actual command `python verify.py <task_id>` and report the results. ## Code Quality Rules - Never leave `TODO`, `FIXME`, `pass`, `raise NotImplementedError` in delivered code unless explicitly requested. - Write concise, production-ready code. - If a task depends on others (`depends:` field in TASKS.md), complete those first.

为Claude Code配置：Claude Code（或Claude Desktop IDE插件）通常读取CLAUDE.md文件。创建或编辑它：

# CLAUDE.md - Project Guidelines with Agent Checkpoint ## Development Protocol Your primary directive is to follow the task management system defined in `TASKS.md`. Treat it as your assignment sheet. **Workflow:** 1. On each new session, first read `TASKS.md` to understand current project state. 2. To begin a task, mark it `[~]` in `TASKS.md` and log a STARTED entry in `AGENT_LOG.md`. 3. Upon completion draft, mark it `[x]` and log a CLAIM entry with **specific file:line references**. 4. **Crucially**: You must internally validate that your code does not contain stubs, TODOs, or missing implementations before claiming completion. Assume `verify.py` will be run. ## Logging Format When logging to `AGENT_LOG.md`, use this exact format:

YYYY-MM-DDTHH:MM:SSZ | claude-code | Task

Status:Task:

[Optional details, file lists, etc.]

Status can be: STARTED, CLAIM, ERROR, INFO. ## Verification Awareness Know that all tasks have a verification level (`auto`, `tests`, `human`, `none`). For `auto` and `tests`, your delivered code MUST be immediately functional and test-passing. For `human`, note that your work will be reviewed.

关键技巧：你可以把.agent-rules.md的内容作为模板，根据你主要使用的助手，将其精华部分复制到对应的配置文件中。不要只是让AI助手“阅读”.agent-rules.md，而是把规则“内化”到它主动读取的配置文件里，这样约束力更强。

3.3 定义你的第一个任务清单：TASKS.md的艺术

TASKS.md的编写质量直接决定了协作效率。它不仅仅是待办列表，更是一份设计文档。以下是一个为创建用户认证API模块的详细任务清单示例：

# 项目：用户认证模块实现 ## 目标 实现一个安全的用户注册、登录和JWT令牌刷新API端点。 ## 1. 用户模型层 - [x] 1.1 创建基础用户模型 `src/models/user.py` - verify: auto - details: 定义User类，包含字段 id (UUID), email (唯一索引), username, hashed_password, created_at, is_active。使用SQLAlchemy ORM。 - depends: (无) - [ ] 1.2 实现密码哈希与验证函数 `src/models/user.py` - verify: tests - details: 创建 `hash_password(plain_password) -> str` 和 `verify_password(plain_password, hashed_password) -> bool` 函数。使用 bcrypt 或 argon2-cffi。 - tests: `tests/test_user_model.py::test_password_hashing` - depends: 1.1 ## 2. 数据库迁移 - [ ] 2.1 生成用户表迁移脚本 `alembic/versions/` - verify: auto - details: 基于1.1中定义的User模型，使用Alembic生成创建`users`表的升级脚本。 - depends: 1.1 ## 3. API端点 (FastAPI) - [ ] 3.1 用户注册端点 `POST /api/v1/auth/register` `src/api/v1/endpoints/auth.py` - verify: tests - details: 接收email, username, password。验证输入，哈希密码，创建用户记录，返回201 Created及用户基本信息（不含密码）。 - tests: `tests/test_auth_api.py::test_register_success`, `test_register_duplicate_email` - depends: 1.2, 2.1 - [ ] 3.2 用户登录端点 `POST /api/v1/auth/login` `src/api/v1/endpoints/auth.py` - verify: tests - details: 接收email/username和password。验证凭证，若成功则生成并返回JWT访问令牌和刷新令牌。 - tests: `tests/test_auth_api.py::test_login_success`, `test_login_wrong_password` - depends: 3.1 - [ ] 3.3 令牌刷新端点 `POST /api/v1/auth/refresh` `src/api/v1/endpoints/auth.py` - verify: human - details: 接收有效的刷新令牌，颁发新的访问令牌。实现刷新令牌的轮换策略（可选）。 - depends: 3.2 - notes: 此端点涉及安全，请实现后标记为`[?]`等待人工审查。 ## 4. 安全中间件 - [ ] 4.1 JWT认证中间件 `src/core/security.py` - verify: tests - details: 创建依赖项 `get_current_user`，用于解析和验证访问令牌，并注入到需要认证的端点。 - tests: `tests/test_security.py::test_jwt_decode`, `test_missing_token` - depends: 3.2

编写心得：

1. 原子化：每个任务应该只做一件事，并且对应到一个可验证的交付物（如一个文件中的特定函数）。避免“实现用户认证”这样的大而化之的任务。
2. 可验证：verify标签是关键。对核心逻辑用tests，对简单的样板代码用auto，对安全关键代码用human。
3. 依赖明确：使用depends字段理清任务顺序，这能帮助AI（和你自己）理解工作流的先后关系。
4. 细节充足：在details里提供实现要点，比如使用的库（bcrypt）、预期的行为，这能极大减少AI的猜测和返工。

4. 核心环节解析：验证脚本与审计日志是如何工作的

Agent Checkpoint 的“魔法”主要来自于verify.py和AGENT_LOG.md的联动。让我们深入其内部，理解它如何做到“防忽悠”。

4.1 verify.py：拆解自动化验证的逻辑

verify.py脚本是客观的仲裁者。它的工作流程可以拆解为以下几个步骤：

1. 解析任务：读取TASKS.md，解析出指定任务（或所有[~]状态的任务）的详细信息，包括待验证的文件路径、函数名、验证级别和关联的测试命令。
2. 提取声明：扫描AGENT_LOG.md，找到该任务ID下最近的一个CLAIM条目。AI助手应该在这里详细列出它修改了哪些文件（例如src/models/user.py:10-50）。这是验证的基准。
3. 执行验证：根据验证级别逐项检查：
   • 文件存在性：检查CLAIM中提到的文件是否真的存在于项目中。
   • 非存根检测：这是核心。脚本会分析目标代码行，查找“谎言模式”：
     • 模式匹配：扫描TODO,FIXME,XXX,HACK等注释。
     • 异常占位：查找raise NotImplementedError,raise NotImplemented,pass（尤其是在函数体唯一语句的情况下）。
     • 存根注释：查找包含stub,mock,placeholder,fake的注释。
     • 体量检查：对于函数，如果去空行和注释后有效代码行数过少（例如少于3行），会触发警告，因为这可能是一个空壳。
   • 测试执行：如果验证级别是tests，脚本会调用pytest（针对Python）或npm test/jest（针对JS/TS）来运行指定的测试路径。它会捕获测试结果和输出。
4. 生成报告并更新状态：将所有检查结果汇总。如果全部通过，则将TASKS.md中对应任务的状态从[~]或[x]（临时）更新为正式的[x]，并在AGENT_LOG.md中追加一条VERIFIED日志。如果任何一项失败，则状态保持为[~]，并在日志中记录详细的失败原因。

一个关键细节：verify.py的检查是基于AI助手在CLAIM日志中的声明。如果AI助手偷懒，没有在CLAIM里列出它实际修改的所有关键文件，那么即使它写了代码，验证也可能因为“未声明”而失败或遗漏。这反过来强制了AI助手必须规范、详细地记录其工作。

4.2 AGENT_LOG.md：构建不可篡改的审计线索

审计日志的价值在于其只追加（append-only）性和结构化。我们来看一个更丰富的日志示例：

--- ## 2024-05-27T14:20:05Z | cursor | Task 1.1 **Status**: STARTED **Task**: Create user model `src/models/user.py` **Context**: User requested to implement the core User ORM model as foundation for auth. --- ## 2024-05-27T14:35:22Z | cursor | Task 1.1 **Status**: CLAIM **Files**: - `src/models/user.py:1-62` (Created User class with fields: id, email, username, hashed_password, created_at, is_active. Used SQLAlchemy declarative base.) - `src/__init__.py:0-0` (Updated to ensure proper module imports) **Implementation Notes**: Used UUID for primary key. Added unique constraint on email. Set `is_active` default to True. --- ## 2024-05-27T14:36:01Z | verify.py | Task 1.1 **Status**: VERIFIED **Results**: - file-exists: PASS (src/models/user.py) - not-stub: PASS (No TODO/FIXME, no NotImplementedError, function bodies sufficient) **Verified By**: auto --- ## 2024-05-27T15:10:00Z | human | Task 3.3 **Status**: REVIEW_REQUESTED **Notes**: 已完成令牌刷新端点实现。代码位于 `src/api/v1/endpoints/auth.py:120-155`。请审查JWT刷新逻辑和密钥轮换策略的安全性。 ---

这份日志提供了完整的叙事：

1. 时间线：精确记录了每个步骤发生的时间。
2. 执行者：区分了是cursor、claude-code还是human执行的操作。
3. 状态流转：清晰展示了任务从STARTED->CLAIM->VERIFIED的生命周期。
4. 上下文与细节：CLAIM条目中的文件范围和实现说明，为后续的验证和人工审查提供了精确坐标。REVIEW_REQUESTED状态则完美支持了human验证级别的工作流。

实操建议：鼓励AI助手在CLAIM中尽可能详细。除了文件行号，简单的“实现说明”对后期维护非常有帮助。你可以通过修改.cursorrules或CLAUDE.md来要求AI助手提供这些细节。

5. 高级技巧与避坑指南：来自实战的经验

使用Agent Checkpoint一段时间后，我积累了一些能极大提升体验和效率的技巧，也遇到过一些坑。这里分享给你。

5.1 任务拆分的黄金法则

如何把一个大需求拆解成TASKS.md里的任务，是成功的关键。我的法则是“一个任务，一个可交付的代码单元，一次验证”。

• 反面例子：[ ] 实现用户认证系统。这个任务太大，验证困难，AI容易中途迷失。
• 正面例子：就像前面示例那样，拆分成模型、迁移、API端点、中间件等原子任务。每个任务都对应一个具体的文件（和行号范围）以及一个验证级别。
• 依赖管理：善用depends字段。当任务3.1依赖于1.2和2.1时，AI（或你自己）在动手前会先检查这些前置条件是否已完成（标记为[x]）。这天然形成了工作流管理。

5.2 与现有测试框架的深度集成

verify: tests级别非常强大，但它依赖于你项目本身的测试框架。为了让AI助手更好地编写可测试的代码，你可以在配置文件中加入测试规范。

在.cursorrules中添加：

## Testing Standards - When a task has `verify: tests`, you MUST also write or update the corresponding tests in the file specified under `tests:`. - Follow the existing project test patterns (e.g., pytest fixtures, Jest `describe`/`it`). - Tests should be independent, fast, and cover the happy path and key edge cases. - After writing code, run the specific test locally (if possible in your environment) to ensure it passes before making a CLAIM.

这样，当你要求AI完成一个verify: tests的任务时，它会在声称完成前，主动去运行或至少检查相关的测试，从而提前发现错误，减少verify.py运行时的失败率。

5.3 处理复杂任务与“谎言”的边界情况

有时AI助手会玩一些“文字游戏”。例如，它可能声称完成了任务，但代码里写的是：

def complex_calculation(data): # TODO: Implement the actual algorithm based on requirements doc # For now, returning a mock value to satisfy the interface. return 42

verify.py的存根检测能抓住明显的TODO。但更隐蔽的情况是，它实现了一个简单但错误的算法。这时，verify: tests就至关重要了。你的单元测试必须覆盖核心逻辑的正确性。

另一个边界情况是“部分完成”。AI可能完成了文件创建和函数框架，但函数内部调用了另一个尚未实现的函数。verify.py的静态分析可能无法发现这种跨文件的逻辑缺失。应对策略是：

1. 在任务details里明确要求“实现完整逻辑，不依赖未实现的函数”。
2. 对于复杂模块，使用verify: human级别，在关键节点进行人工代码审查。
3. 编写集成测试或端到端测试，作为更高层级的验证门禁。

5.4 性能与规模化考量

对于大型项目，TASKS.md文件可能会变得很长。管理建议：

• 按模块或功能拆分多个TASKS_<模块名>.md文件。然后在主TASKS.md中通过引用或链接来组织。你需要稍微修改verify.py的逻辑来支持多文件读取，或者简单地让AI助手同时查看几个文件。
• AGENT_LOG.md文件会随时间增长。可以定期（如每周或每个里程碑）将其归档（例如重命名为AGENT_LOG_2024_W22.md），然后新建一个空的AGENT_LOG.md。确保在归档前所有任务状态都已更新。

5.5 团队协作下的使用规范

在团队中使用Agent Checkpoint需要一点约定：

1. 配置文件共享：确保所有成员的本地IDE中，AI助手的配置文件（.cursorrules,CLAUDE.md）都包含了Agent Checkpoint的工作流规则。
2. 日志冲突处理：如前所述，AGENT_LOG.md的合并冲突很麻烦。建议的方案有：
   • 方案A（推荐）：将AGENT_LOG.md加入.gitignore，仅作为个人本地审计工具。团队进度同步完全通过TASKS.md中的任务状态（[ ],[~],[x]）来进行，这些状态标记冲突较少且易解决。
   • 方案B：团队约定，每次开始工作前先pull最新代码，如果遇到AGENT_LOG.md冲突，优先接受远程版本（因为日志是追加的，时间线最新的通常包含更全的信息），然后手动将本地的几条新日志追加进去。
3. 统一验证：在CI/CD流水线中，可以加入一个步骤，针对所有标记为[x]的任务运行python verify.py --all，确保没有“漏网之鱼”。这可以作为合并请求（Pull Request）的一道质量关卡。

6. 常见问题排查与解决方案实录

即使设计得再完善，在实际操作中还是会遇到各种问题。下面是我遇到的一些典型情况及其解决方法。

最后，我想分享一点最深的体会：Agent Checkpoint 最大的价值，与其说是“管住AI”，不如说是“规范人”。它强迫我们在让AI动手之前，先把自己的需求拆解清楚、定义明白。它建立了一个可追溯的沟通记录，让模糊的协作变得清晰。这个工具本身很简单，但背后体现的——通过工程化、显式化的契约来管理不确定性——这一思想，对于任何涉及人机协作或多人协作的软件开发场景，都是极其宝贵的。