# 让 AI 开发过程留下可检查的结果

原文: https://yishto.com/learn/product-building/specifications-and-coding-agents/

作者: [Yishto](https://yishto.com/about/)

围绕资料导出定义行为、权限和失败验收，用小步差异、长任务检查点与结果矩阵复核 AI 开发产物。

首次发布: 2026-11-10
内容更新: 2026-11-10

让 coding Agent “增加资料导出”很容易得到一份改动，难的是知道改动是否符合任务、是否保护权限、失败时能否恢复。规格应定义用户可观察的行为与边界，开发过程再留下差异、检查与恢复点，供人判断是否可以发布。

本课使用虚构资料导出需求：用户导出自己选中的笔记，输出按选定顺序排列，无权限资料不能进入文件。示例只核验验收结果是否完整，不运行 coding Agent，也不创建真实导出服务。

## 规格描述行为与失败条件

写清输入、输出、权限、规模边界与失败。例如输入是一组笔记 ID，输出字段固定，顺序保持，无效 ID 返回明确错误，大任务转成可查询状态。导出失败不能返回部分文件却显示成功，除非规格明确允许部分结果并标注。

同时写非目标与现有约束，避免 Agent 顺手改动不相关系统。不要预先规定每个函数怎样实现，除非它来自兼容或安全要求。规格越细不一定越好，关键是实现者能判断边界，审查者能观察结果。

将每条要求连接到验收证据。保持顺序用多条不同 ID 验证；权限用跨用户样本验证；超时用可控失败条件验证。只写“保证质量”无法告诉 Agent 需要检查什么，也无法在任务结束时判断缺了哪一项。

## 先取得上下文再安排变更

开发前阅读相关代码、接口、测试与仓库约束，确认当前行为和工作区已有改动。用 branch 或 worktree 隔离适当范围，保留可恢复的起点。隔离目录仍共享外部服务或数据库时，需要单独限制权限，不能把目录隔离当作全部副作用隔离。

给 Agent 的上下文包含任务、需要读的文件、允许修改的范围与检查命令。敏感配置不应进入 prompt 或普通日志。相关信息不够时先调查接口或提出明确缺口，避免靠模型猜测文件内容。

小步实现便于检查因果：先处理纯序列化规则，再接权限查询，最后接导出状态与界面。每步有可比较的 diff 和验证结果。大批改动还要明确文件所有权与相互依赖，避免一次重写把无关行为带进去。

## Agent 负责执行，人仍需检查证据

coding Agent 可以读文件、修改代码与调用工具，具体能力取决于产品与权限。模型报告“已完成”只是一份说明，必须与真实 diff、命令退出状态和测试输出对照。未经执行的命令应明确标记为待验证。

审查从需求进入实现：检查每条约束在哪里落实，再看正常与失败测试。还要核对意外删除、依赖变化、密钥、权限扩大与自动生成内容。只读最终摘要容易遗漏实际变更范围。

如果测试失败，先定位是实现、测试假设还是环境问题。保持原错误与修复记录，不要直接删测试让结果变绿。修复之后跑受影响的检查，必要时扩到真实边界；已经通过且无新疑点的检查不需要无意义重复。

## 长任务需要有边界的检查点

持久任务记录包括目标、当前步骤、已完成文件、尚未解决问题、检查证据和恢复点。上下文丢失后，可以据此继续，不能只依赖聊天里一句“快好了”。任务状态要与文件实际内容对应。

给循环设置重试与验证边界。重复同一种失败应分析原因，而不是无限尝试随机修改。涉及外部依赖时记录阻塞条件，继续不依赖它的工作；需要用户决策时给出具体可审查结果与缺口。

恢复应能分别撤回代码与配置。数据库写入、导出文件与远程动作可能已产生，不能靠 Git 撤销全部效果。规格应说明怎样清理失败资产、重试任务与避免重复导出，保留相关状态证据。

## 多 Agent 只有分工明确才有价值

多个 Agent 可以独立调查或实现较少冲突的模块，也会增加上下文、协调与合并成本。先定义产物、文件范围、依赖和审查顺序，再分配。多人同时修改同一文件，容易覆盖行为与测试，数量本身不提高正确性。

Claude Code 的 agent teams 当前文档标明实验性与默认关闭，并列出恢复和协调等限制。产品版本与条件会变化，实施前查对应文档；不能把它写成所有工具都提供的稳定功能。subagent、多个会话与 team 的工作方式也不同。

Remote Control 用于从其他设备继续本地会话，不应直接等同于云端运行。远程入口与执行机器需要分别确定，核对认证、权限与机器可用条件。本文不提供未经执行的远程命令或账号可用性结论。

## Skills 与工具提供流程材料

skill 可以打包说明和脚本，MCP 可以连接外部能力。它们减少重复配置，也把新的代码和权限引入过程。使用前核对来源、执行范围和当前用户授权，不能让其中一段说明自动批准外部写入。

Superpowers 仓库描述一组组合式 skills 与开发流程。流程约定可以指导任务拆解和验证，不能保证每条代码事实正确。根据项目需要选择，并保留真实执行结果，避免把安装某个工作流当作质量认证。

## 验收矩阵拒绝遗漏与假成功

下面固定正常、无效输入、权限拒绝与超时四个检查。字段必须完整，结果必须是布尔 True；字符串 passed 不能作为真实通过状态。

```python
required = {"normal", "invalid_input", "permission_denied", "timeout"}
results = {"normal": True, "invalid_input": True, "permission_denied": False}
def ready(checks):
    return required <= set(checks) and all(checks[name] is True for name in required)
assert not ready(results)
results.update(permission_denied=True, timeout=True)
assert ready(results)
assert not ready(dict(results, timeout="passed"))
print(ready(results))
```

实际输出是 `True`。初始缺超时且权限失败，不能通过；补齐后通过；字符串状态被拒绝。代码只检查结果矩阵，无法证明测试真正运行，所以每个 True 还需要关联输入、命令与输出证据。

真实交付可以让需求、diff、测试与审查通过 issue 或 PR 相连。描述最终行为和限制，核对产物版本与部署环境。若某项必须检查但尚未执行，记录待办而不冒充完成；发布权限仍按用户授权与环境规则处理。

接收其他 Agent 的结果时，保留其任务范围与证据来源。声称某个测试通过，却没有命令、输入或输出，应该标为待核验。合并前核对依赖与文件冲突，再运行受影响检查；一份独立子任务报告不能证明组合之后仍成立。记录整合者实际检查的内容，避免把作者报告直接改名为审校结论。

## 练习：让导出变更可以复核

写一份导出规格，拆成序列化、权限和任务状态三步。为每步规定修改范围、验收输入与恢复点，再制作结果矩阵。模拟跨用户 ID、输出顺序错误、超时与检查缺失。

验收时，检查可以映射到具体需求，真实差异没有扩大权限，失败状态可解释，摘要与执行记录一致。设计一次继续长任务的检查点，另一位开发者应能仅靠记录恢复工作。矩阵通过只是局部规则，代码正确性与实际发布还需各自证据。

## 资料来源与延伸阅读

- [Coding tool overview](https://code.claude.com/docs/en/overview)
- [Extend a coding tool with skills](https://code.claude.com/docs/en/skills)
- [Coordinate coding sessions with agent teams](https://code.claude.com/docs/en/agent-teams)
- [Remote development control](https://code.claude.com/docs/en/remote-control)
- [Structured coding workflow skills](https://github.com/obra/superpowers)
- [Pro Git](https://git-scm.com/book/en/v2)

资料核验：2026-11-10。教学示例不代表线上实测。

## 相关文章

- [AI Agent 与工作流：什么时候需要自主选择](https://yishto.com/learn/agents/workflows-and-agents/)
- [用测试和决策记录支持代码演进](https://yishto.com/learn/data-practice/testing-refactoring-and-decisions/)