Spec Kit 流程改造实践01：让 AI 编码从重流程走向可复用经验

Spec Kit 流程改造实践01：让 AI 编码从重流程走向可复用经验

前言

Spec Kit 的价值在于把需求、方案和实现串成一条可执行链路。它让 AI 编码不再只依赖一句模糊 Prompt，而是基于结构化的 Spec 和 Plan 逐步推进。

但实际用下来，一个问题也很明显：标准流程对小需求来说偏重。尤其是 tasks.md，在复杂需求里很有价值，在简单需求里却容易变成形式化产物。

这次实践的目标，是把 Spec Kit 改造成更适合个人项目、中文团队和中后台业务开发的轻量流程。

目录

一、问题：标准流程的三个痛点

标准流程通常是：

Spec
→ Plan
→ Tasks
→ Implementation

这套流程的问题不在于流程本身错误，而在于所有需求都套完整流程时，成本会被放大：

1. 强制 Task 导致小需求流程过重

简单需求代码改动小，但强制生成 tasks.md 会增加上下文和 token 消耗。文档成本可能高于收益，让流程变成形式主义。

2. 英文模板对中文团队不够友好

原版英文模板 Agent 可以理解，但中文使用者维护、复盘和二次阅读成本较高。全量翻译又会破坏 Agent 对关键结构的识别。

3. 实现完成后缺少复盘沉淀

代码写完不代表经验被沉淀。真正可复用的判断、决策、风险和教训，容易散落在对话或临时笔记里。

二、改造一：模板中文化，保留英文技术锚点

模板中文化最容易踩的坑，是把所有英文都翻译掉。

对 Agent 来说，很多英文并不是普通文案，而是稳定锚点：

  • API、SDK、Hook、Service
  • Workflow、Requirement、Acceptance Criteria、Scope、Risk
  • 文件名、命令、路径、字段、变量占位符

中文化原则

可以中文化：

  • 说明性文本、步骤说明、验收说明、复盘说明
  • 需求描述、方案描述、任务描述、风险说明
  • 标题采用"中文（English）"格式

必须保留英文：

  • 技术术语（API、Workflow、Hook 等）
  • 文件名、命令、路径、字段、占位符
  • Agent 指令中的关键结构（Language、Output Format、Constraints 等）

示例

功能规格说明（Feature Specification）
验收标准（Acceptance Criteria）
风险与边界（Risks & Scope）

个人判断规则：

如果内容是给人读的说明，可以中文化；如果内容是给 Agent 定位结构、执行命令或匹配变量的锚点，不翻译。

三、改造二：Task 可选，Plan 承担简单需求的实施步骤

改造后的流程：

Spec
→ Plan
→ (Optional Task)
→ Implementation

tasks.md 不再是强制产物，而是按复杂度决定是否需要：

Complexity Task 策略
XS/S 不要求生成 tasks.md
M 可建议生成，由用户决定
L/XL 建议生成，但缺失时仍允许依据 Plan 实施

Plan 的职责增强

Plan 里必须包含足够的实施信息：

  • 文件和模块影响范围
  • 数据结构或状态变化
  • API Changes
  • 异常处理
  • Implementation Steps
  • Acceptance Criteria

简单需求可以直接从 Plan 进入 Implementation，复杂需求再额外拆 Task。

适用场景判断

适合使用轻量流程（不生成 Task）：

  • 单页面改动
  • 小型后台表单、表格、弹窗需求
  • 明确 Bug 修复
  • 已有结构清楚的局部功能扩展
  • 个人项目中的快速验证

建议保留完整 Task：

  • 涉及多模块、多端、多角色权限
  • 涉及数据库结构或跨服务契约
  • 涉及复杂状态机、长流程、并发或回滚
  • 多人协作，需要明确任务归属
  • 需求还不稳定，需要先拆解澄清

四、改造三：Implementation 后增加 Review 和 Skill

只完成代码是不够的。真正能复用的，往往是实现过程中的判断：

  • 为什么采用这个方案？
  • 放弃了哪些方案？
  • 遇到了什么问题？
  • 问题根因是什么？
  • 有哪些风险和遗留事项？
  • 哪些经验可以沉淀成下次的规则？

新增流程阶段

Implementation
→ Review
→ Skill
  • Review：复盘当前需求。重点记录技术决策、问题原因、风险遗留和可复用经验，不复述"完成了什么"。
  • Skill：从 Review 中去除业务背景，提炼通用 Checklist 和最佳实践，变成跨项目可执行的规则。

Review 示例方向

一个好的 Review 应该回答：

  • 技术决策的权衡依据是什么？
  • 实施过程中遇到了哪些非预期问题？
  • 问题的根因是什么？
  • 有哪些风险被识别但暂时搁置？
  • 哪些经验可以沉淀成后续项目的规则？

Skill 的价值

一个好的 Skill 不应该绑定某个业务页面，而应该变成：

  • 跨项目可执行的 Checklist
  • 下次遇到类似场景可直接引用的最佳实践
  • Agent 可识别并自动应用的规则模板

五、实践案例

案例 1：Bug 排查误用完整流程

两周前使用 Spec Kit 排查 Bug 时，直接生成了 spec.md、plan.md、tasks.md 等多个文件，但没有先定位 Bug 根因。

结果：

  • 排障没有先找到根因
  • 文档产物变多，但没有提升修复准确性
  • 代码改动方向偏离问题点
  • 产生返工，浪费 token 资源

经验：

Bug 修复不能直接套完整 Spec Kit 产物链。排障场景应先定位根因，再决定是否需要 Spec/Plan；如果根因未确认，生成长篇 Spec、Plan、Task 只会放大偏差。

案例 2：小需求实践时流程过重

今天实施代码时，需求简单，代码改动小。强制走完整流程后，tasks.md 的成本高于收益。

经验：

小需求可以保留 Spec 和 Plan，但不应强制生成 Task。Plan 中补足 Implementation Steps 后，可以直接进入实施。

案例 3：新项目部署后可读性不足

在新项目内部署 Spec Kit 后，默认英文模板对中文团队可读性不足。全量翻译又会破坏 Agent 识别。

经验：

新项目部署后，优先做中文化模板改造；改造目标是提升人的阅读效率，而不是把所有英文都翻译掉。

六、最终工作流

Spec
↓
Plan
↓
(Optional Task)
↓
Implementation
↓
Review
↓
Skill
↓
未来项目复用

这个流程保留了 Spec Kit 的规范性，又避免了小需求被重流程拖慢。

七、总结

Spec Kit 更适合被当成"可调节流程"，而不是固定模板。核心经验：

  1. 中文化只翻译说明性文本，不翻译占位符、命令、路径、字段和 Workflow 关键字。
  2. tasks.md 应该服务复杂需求，不应该成为所有需求的强制门槛。
  3. Review 和 Skill 是让 AI 编码经验长期复用的关键环节。

验收规则

  • Spec 是否清楚描述目标、边界和验收标准。
  • Plan 是否足够支撑实施。
  • 实现结果是否符合 Acceptance Criteria。
  • 风险和遗留问题是否被记录。

不得因为缺少 tasks.md 直接判定失败。只有当 Complexity 为 L/XL 且实现严重偏离 Plan 时，才建议补充 Task。

后续方向

  • 把这套流程沉淀成个人 Agent Skill
  • 补充更多实践案例验证边界
  • 持续优化 Review Template 和 Skill Template

附录：实践工具

A. Review 生成命令

请基于以下资料，按照项目 Review 模板生成 review.md：

- spec.md
- plan.md
- 当前代码改动
- Git Diff（如有）
- 实施过程中的问题记录（如有）

重点关注：
1. 技术决策
2. 问题与原因
3. 风险与遗留事项
4. Skill 候选项

不要只描述完成了什么。

B. Skill 生成命令

请基于 review.md 生成 skill.md。

要求：
- 去除业务背景
- 提炼通用经验
- 输出 Checklist
- 输出最佳实践

C. Review 模板核心结构

# Review

## 需求概述
简要说明本次需求目标（3~5句话）。

## 实施结果
- 完成了哪些内容
- 与 Plan 是否一致
- 是否存在范围变更

## 技术决策
- 为什么采用当前方案
- 放弃了哪些备选方案
- 方案的优缺点

## 遇到的问题
### 问题
### 原因
### 解决方案
### 影响

## 风险与遗留事项
- 已知风险
- 未解决问题
- 后续可优化项

## 本次需求的经验总结
- 哪些做法有效
- 哪些做法低效
- 哪些步骤下次应提前处理

## 可沉淀为 Skill 的内容
- 可复用的设计模式
- 可复用的代码结构
- 可复用的工程实践
- 可复用的 Agent 协作经验

## Skill 候选项
建议生成的 Skill 标题（如：Optional Task Workflow 使用规范）

D. 中文化提示词关键原则

# 总体原则

## 文件名保持不变
禁止修改：.agent.md、.specify.md、.plan.md、.tasks.md

## 输出语言
采用：中文优先 + 英文辅助

## 标题规范
采用：中文（English）格式

示例：
# 功能规格说明（Feature Specification）
## 验收标准（Acceptance Criteria）

## 保留英文的内容
技术术语：API、SDK、Hook、Middleware、Service、Workflow
软件工程术语：Requirement、Acceptance Criteria、Scope、Risk
代码示例：全部保持英文

## 中文化内容
说明文字、步骤说明、需求描述、方案描述、验收说明、复盘说明

## Agent 指令规范
保留英文关键词：Language、Workflow、Requirements、Output Format、Constraints
正文说明改为中文

E. Optional Task Workflow 的 AI_RULES.md 结构

# Workflow

Spec
→ Plan
→ (Optional Task)
→ Implementation
→ Review
→ Skill

# Task Policy

- tasks.md 为可选文件
- 缺少 tasks.md 不属于阻塞项
- Agent 不得要求补齐 tasks.md 才能实施
- Agent 应优先依据 spec.md 和 plan.md 开发

# Complexity Rules

XS/S：禁止要求生成 tasks.md
M：Agent 可建议生成，用户可自行决定
L/XL：建议生成，但缺失时仍允许实施

# Acceptance Rules

验收时：
- 检查 Spec
- 检查 Plan
- 检查实现结果
- 检查验收标准

不得因为缺少 tasks.md 判定失败。
只有当 Complexity=L/XL 且实施严重偏离 Plan 时，才提示建议补充 Task。
posted @ 2026-06-15 17:43  bleemyoung  阅读(12)  评论(0)    收藏  举报