Skip to content

SpecAgent

DevStar Bot edited this page Nov 18, 2026 · 4 revisions

Spec Agent

Spec Agent 对照已有规格评审工单需求,说明已有覆盖、变更影响和待确认问题。确需变更时才准备规格并按授权交付评审 PR;不修改实现代码、不直接修改默认分支、不自动合并。

开始前

本页的需求评审结论需要支持该能力的 Spec Agent 模板版本;已有实例需更新后重新部署,只升级平台不会自动升级 Agent 的专业能力。

  • 项目仓库已有提交和默认分支。可以完全没有规格文件,不必先手工制作演示规格。
  • 内置 AI 分析无需配置模型;外部 Agent 的模型要求以启动页检查为准,已有配置可复用,提示缺少时再按Agent Team 使用指南补充。
  • 按 Agent Team添加或选择 Spec Agent 模板,在目标项目启动实例,并给予提交规格 PR 所需权限。

创建需求工单

在业务项目而不是 Agent 模板仓库中新建 Issue。例如:

标题:为保存功能建立需求规格
用户保存内容后,成功时显示保存成功;失败时显示错误并保留输入以便重试,
失败时不得显示成功。验收:成功与失败提示匹配实际结果,失败后输入不丢失。
请为这些行为建立需求规格,只修改规格文件,不修改实现代码,不合并。

这是从零建立规格的示例,不要求仓库已有保存实现。修改已有规格时,应改为描述真实业务变化、验收条件及不变范围,例如接口新增请求编号、页面显示同一编号,失败反馈仍保持原行为;不要套用项目中不存在的需求编号。

授权并评审

开启 AI Issues 和讨论规划后,简要分析完成会自动触发 Planner。检查建议是否确实要维护规格,确认目标与范围后授权。已存在的工单可以直接评论目标或使用“分析当前讨论”,不必重复新建工单。

根据所用 Runtime 和本轮授权范围,Agent 可以直接完成任务并提交评审 PR;如果本轮仅授权准备候选,则先查看范围与摘要,再批准发布。不要重复点击已执行操作。需要直接指定时,可使用实际实例支持的命令,如 @spec-agent /author-spec 按本工单维护规格,不改实现,不合并;不要同时重复触发两个入口。

先查看结果评论中的需求评审结论:

结论 接下来怎么做
已有规格覆盖,无需变更 阅读所引用条款,无需为了得到 PR 重复修改规格;若实际行为不符合规格,可继续提出修复和验证目标
需要规格变更 检查涉及条款和变更依据,按本轮授权范围准备或发布 PR
存在待确认冲突 在原工单说明采用哪个规则,或明确哪些旧规则应被替代,再重新评审
缺少必要业务信息 回答具体问题,不需要自己编写规格全文

结论会列出评审基线和覆盖文件。这里只覆盖模板支持目录内的规格及提供的工单内容,不代表已理解项目全部隐含需求或目录外资料;没有规格时也不能声称已有需求已覆盖。

需要变更时,在 PR 文件页评审完整差异,重点检查:

  • 需求是否变成可检查的条款和场景,而不只是复述 Issue。
  • 新增、修改或删除是否有需求依据;关联规格是否一致,无关条款是否保留。
  • 实际文件范围是否符合授权,是否混入实现代码。
  • 来源需求和检查结果是否可追踪;默认分支未改且 PR 未合并。

文本和语义检查不等于实现完成,也不是业务 E2E 测试通过。发现问题直接在该 PR 评论具体修订意见,确认下一轮建议后检查原 PR 增加提交,不应另建无关 PR 或覆盖人工修改。评审结果可供 Planner 判断下一步,但不强制进入编码,也不自动授予其他 Agent 写入权限;继续实现时应确认目标基线和仍未合并的规格变更。

不同维护任务怎么描述

任务 需要说明
从零新建 新能力、边界与可观察的验收条件
增加规格 新能力与现有行为的关系,无关内容保持不变
修改多个规格 行为如何变化、哪些上下游行为需同步,不能凭文件数强行制造影响
删除规格 明确哪个能力退役,以及关联行为和引用如何处理;暂时不用不等于删除授权
增改删组合 分别说明新增、调整和退役的范围,评审一个一致的变更 PR

当前模板评审 docs/specs/、docs/spec/、openspec/specs/ 或 .kiro/specs/ 下的 Markdown。读取预算为最多 300 份规格、每份 256 KiB、合计 4 MiB;超限会停止并提示,不会只读前几份却声称完成全部评审。

评审读取范围与交付范围不同:单次候选最多修改 5 个文件,候选总内容最多 256 KiB。不支持重命名或实现代码修改。候选超限时应拆分变更,不能遗漏必须同步的条款。

已有规格可以使用稳定的规格标识、需求标识和依赖引用帮助追踪,但这些是 Spec Agent 的业务约定,不是使用 DevStar 或其他 Agent 的前提。具体格式和版本限制见模板业务说明。

遇到问题

没有委托建议,先按 Agent Team 排查表检查实例、范围、权限与讨论规划,不需要改写平台代码。只有分析没有 PR 时,先确认是否已由已有规格覆盖,再检查是否在等待澄清或候选发布批准,最后查看任务日志。需求或 PR 已变化时,按最新上下文重新提出目标,不能复用旧发布授权。

Clone this wiki locally