| name | spec-dev-flow |
| description | SPEC 开发全流程编排技能。当用户要求开发某个 SPEC、实现某个功能规格、开始 SPEC 开发时触发。 覆盖从确认 SPEC 编号到文档同步推送的完整 11 步工作流: 确认编号(读取 .agent/specs/INDEX.md 列出未实现项)→ 阅读 memory 文档 → 阅读 spec → 规划任务 → 实现 → review → code-lint → 推送分支 → 等待人工建 PR → CI 验证修复 → doc-sync 文档同步推送。
|
| agent_created | true |
SPEC 开发全流程编排
概述
本 skill 将 SPEC 开发全流程标准化为 11 个步骤,确保每个 SPEC 的实现质量一致、文档同步完整。
执行时严格按步骤顺序推进,每步完成后确认再进入下一步。
前置条件
- 在 game-dev-studio 项目根目录下执行
- 当前分支为
main 且代码已更新到最新
- 已加载
code-lint、ci-verification、doc-sync 三个子 skill
Skill 发现规则
子 skill 的安装路径可能因环境而异。查找时按以下优先级搜索 SKILL.md:
{game-dev-studio}/.agent/skills/{skill-name}/SKILL.md — 项目级 skill
~/.workbuddy/skills/{skill-name}/SKILL.md — 用户级 skill
- 加载后使用
Skill 工具调用
工作流
Step 1 — 确认 SPEC 编号
流程:
- 读取 SPEC 索引:读取
.agent/specs/INDEX.md,解析索引表
- 筛选未实现项:提取所有状态为
设计中 的 SPEC,按编号从小到大排序
- 展示可选列表:将未实现的 SPEC 以编号表格形式呈现给用户选择:
示例:
| 编号 | 标题 |
|------|------|
| SPEC-011 | 游戏打包微服务规范 |
| SPEC-012 | 游戏运行微服务规范 |
| SPEC-013 | 游戏测试微服务规范 |
| SPEC-018 | 分层架构重构规范 |
| SPEC-020 | OpenTelemetry 分布式链路追踪 |
| SPEC-021 | Team Building Agent 指示灯 |
- 用户选择:
- 用户可能输入完整编号(
SPEC-011)、纯数字(11、011)
- 自动补全:纯数字自动补全为
SPEC-XXX 格式(不足三位前面补零)
- 校验:确认所选编号在未实现列表中,如果不是则提示用户重新选择
- 确认后告知用户将要开发的 SPEC 全称和文件路径
Step 2 — 阅读 memory 文档
依次阅读以下文档,建立项目全貌认知:
.agent/memory/INDEX.md — 项目记忆索引,定位相关经验文档
.agent/memory/MEMORY.md — 关键工程决策记录
.agent/memory/CONVENTIONS.md — 工作约定、Bug 修复、被纠正的错误做法
.agent/memory/ARCHITECTURE.md — 项目架构
.agent/memory/E2E_TESTING.md — E2E 测试经验(如涉及 UI 变更)
注意:只阅读与当前 SPEC 相关的 memory 文档,不需要全部读完。根据 SPEC 内容判断哪些文档相关。
Step 3 — 阅读 SPEC 文档
- 查找路径:
.agent/specs/{spec-file}.md
- SPEC 文件名通常在
.agent/specs/INDEX.md 中可查到
- 完整阅读 spec 文档,理解设计意图、验收标准、UI Test 要求
- 如 spec 文档中有不明确之处,向用户澄清后再继续
Step 4 — 规划任务列表
- 基于 spec 设计将实现工作分解为具体任务
- 使用
TaskCreate 创建结构化任务列表
- 每个任务应包含明确的验收标准
- 将任务列表展示给用户确认
Step 5 — 实现 SPEC 设计
- 从
main 创建功能分支:
- 分支命名:
feat/SPEC-XXX-{简短描述}
- 示例:
feat/SPEC-017-tool-search
- 按 Step 4 规划的任务顺序逐步实现
- 每完成一个子任务,标记为完成
- 遵循
.agent/memory/CONVENTIONS.md 中的编码规范
Step 6 — Review 代码
- 自查代码质量:
- 是否满足 spec 验收标准
- 是否有遗漏的边界情况
- 是否引入了不安全的代码(XSS、SQL 注入等)
- 是否有硬编码的敏感信息(token、密码等)
- 日志是否充分(便于后续 CI 调试)
- 如发现问题,立即修复
Step 7 — 调用 code-lint 检查修复
- 加载 code-lint skill:使用
Skill 工具加载 code-lint
- 对变更文件执行 lint 检查
- 如有 lint 错误,修复后重新检查,直到通过
- 当前 lint 规则:R1(未转义的反引号)
Step 8 — 推送分支
Step 9 — 等待人工创建 PR
- 推送完成后,告知用户:
- 分支名称
- 变更摘要
- 提醒用户手动在 GitHub 上创建 PR
- 等待用户明确告知 PR 已创建,不要自动轮询
Step 10 — CI 验证修复
用户确认 PR 已创建后执行:
- 加载 ci-verification skill:使用
Skill 工具加载 ci-verification
- 检查 CI 状态(
check-ci.sh)
- 修复-重试循环(最多 10 次):
- 获取失败 job 的日志(
get-logs.sh --failed-only)
- 分析失败原因
- 修复代码(禁止删除测试用例、禁止降低断言、禁止修改业务逻辑绕过测试)
- 推送修复
- 等待 CI 重新运行
- 即使 CI 变绿也要做假性成功检查(Step 6:下载全量日志检查隐藏的 HTTP ≥400 错误)
- CI 全部通过(sonar-check ✅ + ui-tests ✅)才算完成
Step 11 — doc-sync 文档同步
CI 完全通过后执行:
- 加载 doc-sync skill:使用
Skill 工具加载 doc-sync
- 按 doc-sync 的 8 区遍历(A → H)同步所有相关文档
- 重点检查项(来自 doc-sync Top 10 常见遗漏):
README.md spec 状态更新
README.md 工具/服务数量更新
E2E_TESTING.md 标题数字匹配
.agent/specs/INDEX.md spec 状态一致
.agent/memory/ 相关文档更新
AI_AGENT_COMMON_INSTRUCTIONS.md 工具列表更新
- 将文档变更提交并推送
- 在 workspace memory(
.workbuddy/memory/YYYY-MM-DD.md)中记录本次开发完成
编码规范引用
实现过程中必须遵循的规范(详见 .agent/memory/CONVENTIONS.md):
- Git 分支命名:
feat/SPEC-XXX-xxx 格式
- Commit message:
feat(SPEC-XXX): xxx 格式
- 禁止直接修改
main 分支
- data-testid:UI 组件使用
data-testid 属性便于 E2E 测试
- Mock 数据契约:测试 toolCalls.arguments 必须与
tools.ts zod schema 完全匹配
- 禁止删除/降级 UI test case
- 禁止修改功能逻辑绕过测试
中断与恢复
如果流程被中断:
- 记录当前步骤编号
- 恢复时从断点继续,但需先检查 Step 2(memory 文档)和 Step 3(spec 文档)是否有更新
- 如
main 分支有新提交,先 git checkout main && git pull 再 git rebase main