| 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 规则、提示词、工具定义、配置、评测样例、运行日志、业务流程图、接口文档和用户反馈。若没有现成资料，先用问题澄清。
澄清问题顺序
一次聚焦一个问题，尽量让用户做选择，而不是抛开放题。优先问：
- Agent 的角色：助手、审核员、分流器、执行器、规划器、质检员还是其他。
- 使用入口：网页、企业微信、飞书、钉钉、小程序、命令行、客服后台、内部系统。
- 输入类型：自然语言、表单、截图、语音转写、文件、日志、订单、合同、发票、数据库结果。
- 输出格式：中文说明、Markdown、JSON、表格、工单字段、审批意见、接口 payload。
- 工具权限：只读、可写、可执行、可联网、可发消息、可调用业务 API。
- 人工确认：哪些动作必须先让人点头。
- 失败处理：超时、限流、空结果、权限不足、敏感信息、冲突需求时怎么回应。
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。
- 禁止照搬第三方受版权保护的规则文本。
