spec-driven-agent-development

name	spec-driven-agent-development
description	面向中国国内 Agent 智能体编写与改造的规则包。用于设计、实现和验收 Agent 的角色边界、中文输出、国内模型/工具接入、企业 IM/知识库/业务系统权限、多轮状态、人工确认、失败处理、评测样例和端到端行为；依次产出 spec.md、plan.md、tasks.md、checklist.md，并在四个评审包确认后才进入实现。

Spec Driven Agent Development

适用范围

只在编写或改造 Agent 智能体时使用本 skill。典型场景包括：

• 新建客服、运营、财务、法务、研发、数据分析或知识库 Agent。
• 调整 Agent 的角色定位、中文表达、输出结构或拒绝边界。
• 编写或重构 System Prompt、Developer Prompt、工具说明和评测样例。
• 接入国内模型服务、企业 IM、知识库、数据库、RPA、搜索、OCR、文件系统或业务 API。
• 增加人工确认、权限控制、审计日志、失败兜底或合规约束。
• 为 Agent 建立可复跑的样例集、评测脚本和端到端验收流程。

不要把本 skill 用作普通代码开发规则。它约束的是 Agent 行为设计和实现，不是任何功能都要套用的开发模板。

设计原则

• 先定角色，再写 Prompt。
• 先定边界，再接工具。
• 先定输出，再做生成。
• 先定样例，再说可用。
• 先看证据，再报完成。
• 不确定就追问，不替用户猜。
• 不把工具失败、知识库空结果或模型推测包装成事实。
• 不把一次正常回复当作上线依据。

构建门禁

在 spec.md、plan.md、tasks.md、checklist.md 都完成并得到用户明确确认之前，不得编写或修改实现代码、提示词、工具定义、配置文件、评测脚本和上线文档。若用户要求跳过，应先说明风险并请求重新确认；若仍需快速原型，也要保留最小版本的四个评审包。

四个评审包

文件	核心问题	国内 Agent 必填内容
spec.md	这个 Agent 允许做什么	角色、业务场景、用户输入、中文输出、可做/不可做、工具边界、人工确认、失败处理、验收标准
plan.md	这个 Agent 如何实现	Prompt 分层、工具权限、模型/网关选择、状态管理、安全策略、日志、评测方案、国内平台适配
tasks.md	先做哪一步，如何验证	提示词文件、工具定义、配置、样例、评测脚本、端到端测试、每项验证方式
checklist.md	如何证明 Agent 可上线	正常任务、边界输入、错误输入、工具失败、权限确认、格式一致性、禁止越权、禁止编造、验收报告

推荐输出顺序

Agent 想法
  -> spec.md      明确角色、场景、边界、工具和验收
  -> plan.md      设计 Prompt、工具、状态、安全和评测
  -> tasks.md     拆分提示词、工具、配置、样例和脚本任务
  -> checklist.md 设计可运行、可观察、可复核的验收项
  -> 实现         按 tasks.md 执行，每步验证
  -> 验收         按 checklist.md 记录证据

用户要求修改任一评审包时，回到对应阶段修订，再继续后续阶段。

阶段一：生成 spec.md

目标

把“想做一个 Agent”转成可审批的 Agent 行为说明。这个阶段只描述行为，不写 Prompt 全文，不写代码。

需要先看什么

优先读取已有的 Agent 规则、提示词、工具定义、配置、评测样例、运行日志、业务流程图、接口文档和用户反馈。若没有现成资料，先用问题澄清。

澄清问题顺序

一次聚焦一个问题，尽量让用户做选择，而不是抛开放题。优先问：

1. Agent 的角色：助手、审核员、分流器、执行器、规划器、质检员还是其他。
2. 使用入口：网页、企业微信、飞书、钉钉、小程序、命令行、客服后台、内部系统。
3. 输入类型：自然语言、表单、截图、语音转写、文件、日志、订单、合同、发票、数据库结果。
4. 输出格式：中文说明、Markdown、JSON、表格、工单字段、审批意见、接口 payload。
5. 工具权限：只读、可写、可执行、可联网、可发消息、可调用业务 API。
6. 人工确认：哪些动作必须先让人点头。
7. 失败处理：超时、限流、空结果、权限不足、敏感信息、冲突需求时怎么回应。

spec.md 建议结构

# [Agent 名称] Spec

## 背景与业务目标
说明为什么需要这个 Agent，以及它要改善哪个具体流程。

## 角色定位
说明 Agent 的身份、服务对象、职责边界。

## 使用入口与用户类型
说明 Agent 会出现在哪些国内常见入口中，面对哪些用户。

## 输入与输出
说明输入来源、必填信息、输出格式、语言和字段要求。

## 能力范围
* F1: Agent 必须完成的可观察行为。
* F2: Agent 必须完成的另一个行为。

## 限制与拒绝
说明 Agent 不得处理、必须拒绝或必须转人工的情况。

## 工具与权限
说明允许工具、禁止工具、读写执行权限、调用前确认条件。

## 人工确认
说明高风险动作、对外发送、审批、支付、删除、写库等操作的确认规则。

## 失败处理
说明工具失败、模型不确定、输入缺失、知识库无结果、权限不足时的回答方式。

## 验收标准
* AC1: 对应 F1 的可观察验收标准。
* AC2: 对应 F2 的可观察验收标准。

spec.md 自查

• 角色是否一眼能看懂。
• 可做、不可做、转人工是否边界清楚。
• 工具权限是否区分读、写、执行、联网和对外发送。
• 是否覆盖国内常见入口和中文输出要求。
• 是否写清敏感数据、业务审批和失败兜底。
• 每条能力是否至少有一个验收标准。

交付话术

spec.md 已完成，请确认：角色定位、工具权限、转人工边界、失败处理和验收标准是否符合你的业务预期。确认后我再进入 plan.md。

阶段二：生成 plan.md

目标

把已确认的 Agent 行为转成实现设计。这里可以写 Prompt 分层、工具结构、状态管理、评测方案和文件组织。

plan.md 建议结构

# [Agent 名称] Plan

## 总体架构
说明 Agent 由哪些部分组成：Prompt、工具、状态、评测、日志、入口适配。

## Prompt 分层
### System Prompt
定义身份、底线、拒绝规则和中文表达基调。

### Developer Prompt
定义工作流程、工具调用条件、追问策略、人工确认和失败兜底。

### Tool Instructions
定义每个工具的用途、参数、返回值、错误语义和禁止用法。

## 国内平台适配
说明模型服务、企业 IM、知识库、网关、数据库、对象存储、RPA 或内部 API 的接入方式。

## 工具权限矩阵
| 工具 | 允许操作 | 禁止操作 | 需要确认 | 失败处理 |
| --- | --- | --- | --- | --- |
| 示例工具 | 只读查询 | 写入/删除 | 否 | 报告失败并给替代路径 |

## 状态与记忆
说明当前会话需要保留什么、不能保存什么、何时清理或脱敏。

## 安全与合规
说明敏感信息、未成年人、金融/医疗/法律/政务等高风险内容如何处理。

## 评测方案
说明正常样例、边界样例、工具失败样例、越权样例、格式稳定性样例。

## 文件组织
列出提示词、工具、配置、样例、评测脚本和文档文件。

## 决策记录
| 决策 | 选择 | 原因 |
| --- | --- | --- |

plan.md 自查

• Prompt 三层职责是否分开。
• 工具权限矩阵是否能直接指导实现。
• 国内平台限制是否写清楚，例如限流、鉴权、回调、内容安全、私有化部署。
• 状态和记忆是否避免保存不该保存的信息。
• 每条 spec 能力是否能在设计中找到对应方案。

交付话术

plan.md 已完成，请确认：Prompt 分层、工具权限、国内平台适配、状态管理和评测方案是否可接受。确认后我再拆 tasks.md。

阶段三：生成 tasks.md

目标

把设计拆成可以逐项执行的小任务。每个任务都要写文件范围、依赖、步骤和验证方式。

tasks.md 建议结构

# [Agent 名称] Tasks

## 文件清单
| 操作 | 文件 | 作用 |
| --- | --- | --- |
| 新建 | `prompts/agent.system.md` | 角色、底线、拒绝规则 |
| 新建 | `prompts/agent.developer.md` | 工作流程、工具规则、失败处理 |
| 新建 | `evals/agent_cases.jsonl` | 正常、边界、失败、越权样例 |

## T1: 编写 System Prompt
**文件：** `prompts/agent.system.md`
**依赖：** 无
**步骤：**
1. 写入角色定位。
2. 写入允许和禁止行为。
3. 写入中文输出和人工确认底线。
**验证：**
运行：人工对照 spec 检查。
期望：角色、边界、确认规则都有对应内容。

## T2: 编写评测样例
**文件：** `evals/agent_cases.jsonl`
**依赖：** T1
**步骤：**
1. 添加正常任务。
2. 添加信息缺失。
3. 添加工具失败。
4. 添加越权请求。
5. 添加输出格式稳定性样例。
**验证：**
运行：`python scripts/run_agent_eval.py evals/agent_cases.jsonl`
期望：每条样例都有通过/失败和原因。

## 执行顺序
```text
T1 -> T2 -> T3 -> T4
```

tasks.md 自查

• 是否覆盖 Prompt、工具、配置、样例、评测、端到端测试。
• 是否每项都写明文件范围。
• 是否每项都能独立验证。
• 是否包含工具失败、越权、编造、格式漂移和人工确认样例。
• 是否没有“优化一下”“完善一下”这种无法执行的任务。

交付话术

tasks.md 已完成，请确认：任务粒度、文件范围、依赖顺序和验证方式是否合适。确认后我再设计 checklist.md。

阶段四：生成 checklist.md

目标

把需求和风险变成可运行、可观察、可记录证据的验收项。不要用“表现正常”这类空泛描述。

checklist.md 建议结构

# [Agent 名称] Checklist

## 角色边界
* [ ] 输入“你能做什么”，Agent 能说明职责和限制。
* [ ] 输入越权请求，Agent 拒绝或转人工。

## 正常业务
* [ ] 输入标准业务请求，Agent 输出符合格式的结果。

## 信息缺失
* [ ] 缺少关键字段时，Agent 追问，不直接给结论。

## 工具失败
* [ ] 工具超时/报错时，Agent 说明失败，不编造工具结果。

## 人工确认
* [ ] 写入、删除、审批、支付、对外发送等动作前，Agent 请求确认。

## 输出格式
* [ ] 多次运行同类任务，输出字段稳定。

## 国内平台适配
* [ ] 企业 IM、知识库、网关或业务系统的失败返回被正确处理。

## 验收报告
### 通过（N/M）
* [x] 条目 — 证据：命令输出、评测结果或人工观察。

### 未通过（如有）
* [ ] 条目 — 预期：...，实际：...，修复方案：...

checklist.md 自查

• 是否覆盖所有验收标准。
• 是否每项都能通过输入、运行或观察验证。
• 是否覆盖正常、边界、错误、工具失败、越权、编造、格式漂移。
• 是否能产出证据，而不是只靠主观感觉。

交付话术

checklist.md 已完成，请确认：验收项是否覆盖上线风险，是否都能执行并记录证据。确认后我再进入实现。

实现阶段规则

进入实现前，先声明四个评审包均已确认。之后只按 tasks.md 执行。

• 每完成一个任务，立即运行对应验证。
• 验证不通过，先修复再继续。
• 无法运行验证时，说明原因，并给替代验证方式。
• 不得用“应该可以”“看起来没问题”“理论上通过”作为完成依据。
• 涉及写库、发消息、审批、支付、删除、执行命令等动作时，必须按确认规则处理。

验收阶段规则

按 checklist.md 逐项执行并记录结果。

验收报告必须包含：

• 通过项数量和证据。
• 未通过项的预期、实际、修复方案。
• 端到端场景结果。
• 未覆盖环境或剩余风险。

国内开发特别注意

需要国内平台、模型、合规和交付语境时，读取 references/domestic-agent-patterns.md。

优先考虑：

• 中文默认输出和业务可读性。
• 国内模型 API 的超时、限流、鉴权和内容安全返回。
• 企业微信、飞书、钉钉、小程序、客服系统、工单系统的交互限制。
• 个人信息和业务敏感数据最小化使用、脱敏和审计。
• 私有化部署、内网访问、国产化环境和离线评测需求。

禁止事项

• 禁止在未确认四个评审包前实现。
• 禁止未定义工具权限就接入工具。
• 禁止未定义失败处理就使用外部结果。
• 禁止把猜测、空知识库结果或工具失败包装成事实。
• 禁止把不可观察的描述写进 checklist。
• 禁止把项目私有信息写入通用 skill。
• 禁止照搬第三方受版权保护的规则文本。