spec-workflow

name	spec-workflow
description	本仓库的任务记录、风险分级和规格确认工作流。用于实现、修改、重构、修复、生成代码、改配置、改 Wire、改 Proto、改测试或执行有副作用命令时判断是否可直接执行、是否需要记录、是否需要确认。

Spec Workflow

Overview

本 skill 只负责任务记录、风险分级和确认边界，不负责仓库架构细节。修改代码时同时遵循：

• AGENTS.md：常驻硬规则
• .agents/skills/my-project/：仓库架构、Go 规范、生成命令和相邻实现入口
• 本 skill：低风险快速路径、规格文档、确认节点、执行记录和风险分级
• ~/.codex/skills/spec-driven-development：可作为通用规格方法参考，但不覆盖本 skill 的文档路径、确认节点和风险等级

任务文档是临时过程记录。长期规则应沉淀到 AGENTS.md、repo-local skill、模块 README 或稳定 docs。

When To Use

当任务涉及以下行为时使用：

• 实现、修复、重构或生成代码
• 修改配置、Wire、Proto 或测试
• 运行格式化、构建、测试、生成器等有副作用命令
• 用户明确提到 specs、规格、计划、风险分级、Kiro 模式或流程调整

只读解释或方案讨论通常不用创建任务文档；一旦要推进到改文件或执行有副作用命令，应按风险选择快速路径、记录路径或确认路径。

Fast Path

用户已明确要求且属于低风险本地改动时，可以先读相关文件后直接执行，不必停下等待确认。完成后在任务文档或最终回复中记录目标、修改文件、验证命令和残余风险。

低风险快速路径适用于：

• 读取、搜索、分析文件
• 修改用户指定的文档、prompt、README、注释、示例文本
• 小范围修 typo、格式、链接、命令说明
• 修改当前仓库内相关普通源码或测试，且不改变公共接口、配置结构、生成文件或跨模块契约
• 为小修补充对应单元测试
• 运行 gofmt、go test、go vet、go list、make -n ...、git diff、git status 等本地验证命令
• 新增或调整低风险辅助 Makefile 目标，但不自动执行批量破坏性动作
• 用户明确要求调整 repo-local skill 或 AGENTS.md 中的流程文字，且不放宽高风险限制

低风险任务可以不创建规格文档；若已经创建或任务涉及多文件，继续把执行记录补进去即可。

Workflow

1. 生成简短 kebab-case 任务名，默认文档路径为 .agents/specs/<task-name>/spec.md。
2. 判断风险等级：低风险走 Fast Path；中风险写清范围后可继续；高风险或范围不清必须先确认。
3. 需要规格文档时，创建或更新规格文档，写清背景、目标、非目标、影响范围、方案、任务、验收标准、风险与回滚。
4. 中风险任务若用户目标已明确，写完规格后继续执行；若影响范围、方案取舍或验收标准不清，停止并询问。
5. 高风险任务创建或更新规格后停止执行，等待用户明确确认。
6. 执行中在 spec.md 的“执行记录”记录关键步骤、修改文件、验证命令和结果。
7. 若方案变化扩大影响范围、改变核心设计或引入中高风险，先更新规格；中风险可继续，高风险必须再次等待确认。
8. 完成后总结实际修改、验证结果、未完成事项和残余风险；最终回复不要把临时任务文档作为长期入口。

Feedback Handling

当用户纠正代理行为、要求沉淀文档或要求以后不要反复提醒时：

1. 判断反馈属于临时偏好、当前任务规则还是跨任务常驻规则。
2. 常驻规则补到 AGENTS.md；细节补到 repo-local skill、模块 README 或稳定 docs。
3. 当前任务规则补到任务文档执行记录或方案变更。
4. 如果分层或风险不清楚，主动提出 1-3 个具体问题。

Spec Template

# <Task Title>

## 背景

说明当前问题、用户目标、现有约束和为什么需要做。

## 目标

- 本次要达成的结果

## 非目标

- 本次明确不处理的范围

## 影响范围

- 预计新增、修改或需要重点阅读的文件和模块

## 方案

说明准备采用的实现方式、关键设计选择和与现有结构的关系。

## 任务列表

- [ ] 任务一
- [ ] 验证

## 验收标准

- 可判断任务完成的标准

## 风险与回滚

说明可能风险、规避方式和回滚办法。

## 执行记录

- 已创建任务规格文档，等待用户确认。

大任务可拆分多文件；普通任务优先使用单个 spec.md，避免流程负担。低风险小任务可跳过规格文档，只在最终回复中记录。

Risk Levels

Low Risk

用户已明确要求时可直接执行，完成后记录：

• 读取和搜索文件
• 修改当前仓库内与任务相关的普通源码、测试或文档，且不改变公共接口、配置结构或跨模块契约
• 修改用户指定的 prompt、README、注释、示例文本、typo、格式、链接和命令说明
• 运行 gofmt、go test、go vet、go list、make -n ...、git diff、git status
• 运行仓库约定的本地生成命令 dry-run；实际生成命令按影响范围判断是否升为中风险
• 创建或更新任务相关的 .agents/specs/<task-name>/ 文档
• 新增低风险本地辅助命令或 Makefile target，但不自动执行批量破坏性动作

Medium Risk

需要在规格中明确影响范围；若用户目标已明确，可记录后继续执行：

• 批量重构
• 多文件文档补全或多包低风险测试补充
• 小型重构，不改变公共 API 和外部行为
• 新增本地工具脚本或调整 repo-local skill 流程规则
• 修改公共接口或配置结构但影响范围清晰且有兼容方案
• 修改 Wire 装配、Proto、测试基线或示例服务行为且影响范围清晰
• 调整跨模块依赖关系

High Risk

必须单独确认：

• 删除大量文件
• 改写 Git 历史或丢弃未确认修改
• 安装或修改系统级依赖
• 发布、部署、推送线上变更
• 请求第三方或线上 API 修改数据
• 处理未脱敏敏感信息
• 修改数据库数据或执行真实环境迁移
• 大范围重构、公共 API/配置结构破坏性变更或影响范围不清的 Proto/Wire 改动
• 任何风险不确定的操作

Practical Notes

• 用户明确要求跳过文档时可以跳过，但最终回复中说明。
• 用户只问方案时先回答方案，不擅自改文件。
• 用户确认后又提出新方向，以最新消息为准，必要时更新规格后继续。
• 不为小任务过度拆分文档；规格的价值是降低歧义和留下上下文，不是阻塞低风险动作。
• 全局 skills 中的 commit、push、发布、安装依赖、打开 GUI、删除文件、改写 Git 历史或访问线上资源建议，必须服从 AGENTS.md 和当前会话权限规则。