本文用到的SpecKit Skill下载地址：speckit-skills
在去年coding过程中，一直在探索让AI参与业务需求开发。 最开始是纯手工模式——自己总结提示词，把需求拆成设计文档，再拆成任务清单，最后让AI生成代码。这种方式看似可行，但问题很快暴露出来：每次都要重复这一整套流程，更关键的是：每次都需要组装提示词，而且文档碎片化，所有产出都散落在聊天记录中，难以版本控制和追溯。
后来我了解到SpecKit，它采用的规格驱动开发（SDD）理念正好解决了之前的痛点，于是开始使用SpecKit来进行需求开发。在使用了两个多月、进行了一些沉淀后，前不久我在公司内部进行了技术分享，今天将分享材料脱敏后整理成文，希望能和大家交流交流。
这篇博客内容是我从手工组装提示词模式到SpecKit模式的比较，以及它在一次复杂需求开发中的实际应用。
两种模式的对比
传统分步提示词模式
用户维护提示词库
↓
手动 Copy-Paste 上下文
↓
组装下一个提示词
↓
生成输出
↓ (循环)
重复上述过程
这种模式的痛点很明显：
上下文丢失：随着对话变长，AI 容易遗忘最早设定的代码规范或架构原则。你需要在每个提示词里重复这些要求，否则生成的代码就可能不符合项目规范。
依赖记忆：用户必须记住当前执行到哪一步，而且要手动检查上一步输出是否符合下一步的输入要求。忘记某个环节就可能导致后续生成的内容全部无效。
人工组装 Prompt：大部分精力花在组装 Prompt 和优化 Prompt 技巧上，而不是思考业务逻辑本身。你成了"提示词搬运工"而不是业务开发者。
文档碎片化：所有产出都散落在聊天记录中，难以版本控制和追溯。几个月后想回顾某个需求的决策过程，基本找不到。
纠错机制后置：代码写出来运行报错了才发现逻辑漏洞。这时候再回头修改规格或设计，成本已经很高了。
SpecKit Skill 模式
导入 SpecKit Skill
↓
用自然语言描述需求，AI 自动识别意图并执行相应 Skill
↓
定义项目宪章
↓
生成需求规格
↓ [可选]
需求澄清
↓
生成技术计划
↓
任务拆分
↓
一致性分析
↓ [可能循环]
问题修复 + 二次验证
↓
任务实施
SpecKit 的核心优势：
持久化记忆：所有的规范、计划、任务都被写入项目目录下的 .specify 文件夹。AI 每次执行任务都会自动读取这些"宪法"和档案"，确保不忘初心。
可执行的规范：规范文档不仅仅是文本，它们是生成下一步任务的直接输入源。修改 plan.md 后重新运行任务生成，会自动更新任务列表。
工程化闭环：提供了 Clarify（澄清）和 Analyze（分析）环节，强制在写代码前进行"编译级"的逻辑检查，而非写完代码后再修补。
文档即代码：产出物直接存为 Markdown 文件，可 Git 版本控制。规格、计划、任务都可以回溯和审查。
Shift Left 纠错：在写代码前发现逻辑漏洞，大幅降低返工率。
SpecKit 核心概念
SpecKit 是 GitHub 官方推出的开源工具包，核心理念是 Spec-Driven Development (SDD)：
Intent-driven（意图驱动）：先定义"做什么"和"为什么"，再关注"怎么做"。
Structured Process（结构化流程）：将开发拆解为 原则 -> 规格 -> 计划 -> 任务 -> 实现 的严谨链路。
AI Native（AI 原生）：利用 AI 强大的阅读和理解能力，让它自己维护和遵守一套复杂的项目"宪法"。
SpecKit Skill：让使用更简单
SpecKit 本身提供了一套完整的命令体系，但在实际使用中，每次都需要手动执行对应的命令，还要关心当前处于哪个阶段。
为了进一步简化使用流程，博主使用将 SpecKit 每一个命令都封装成了 Skill。可以把它理解为一个"技能包"——将 SpecKit 开发过程中的每个指令都封装成独立的 Skill，通过 AI 自动识别用户意图，智能匹配并执行相应的 Skill。
使用 SpecKit Skill 的核心价值：用户使用时不需要关心现在处在什么阶段，要使用 SpecKit 什么命令，从而简化开发流程、提升工作效率。
Skill 的工作原理：当用户发出请求时，技能的触发和加载过程会动态地改变 AI 的上下文窗口。代理会识别出需要使用某个技能，然后读取对应的指令文件，加载完成后开始执行任务。
如何获取 SpecKit Skill：你需要准备一份 SpecKit Skill 工具包，将其导入到你的开发环境中。这边我已经生成了一份放在如下地址：speckit-skills
导入后的使用方式：导入完成后，你就可以直接用自然语言描述你的需求，AI 会自动识别你的意图并调用相应的 Skill，无需手动输入具体的命令。
实战案例：复杂业务逻辑的改造
去年我接手了一个需求：增强系统的数据关联追溯能力，支持多级数据的向上追溯。
这个需求涉及多个业务场景、不同的数据来源、复杂的递归处理逻辑。在旧流程下，这类需求最容易出问题——理解不到位、边缘情况没考虑到、不同场景间逻辑不一致。
我用 SpecKit 完整走了一遍流程，以下是详细记录。
第一步：定义项目宪章
SpecKit 要求做的第一件事是生成项目宪章。听起来有点仪式感，但实际价值很高。
你只需要输入：
请为本项目制定"宪法/原则"，重点覆盖：
- 代码质量与审查标准（必须可执行）
- 测试策略（单测/集成/契约测试最低要求）
- 性能与稳定性门槛（p95、超时、降级策略）
- 安全与合规（鉴权鉴别、敏感数据、审计日志）
- 可观测性（结构化日志、指标、追踪）
AI 会生成一份 constitution.md 文件，包含以下内容：
- 分层架构规范
- 命名规范（类名、包名、注释）
- 统一响应与请求封装
- 代码结构规范
- 日志规范
- 测试策略
宪章生成后，需要审核并进行补充。比如我发现宪章缺少对注释的要求，就通过对话补充了注释规范。
重要经验：宪章生成一次后可持续复用，后续需求开发直接引用即可。一个项目工程只需生成一份宪章，上传 Git 后团队成员共用。
第二步：生成需求规格
有了 SpecKit Skill 后，开始处理具体需求就变得很简单了。直接用自然语言把需求描述告诉 AI：
下面是我本次需求，请生成规格文档
## 需求描述
修改数据追溯功能，增强数据关联向上追溯能力
## 业务背景
现有数据处理逻辑在以下场景存在不足：
1. 某些特殊类型的数据无法追溯到原始数据
2. 合规数据未能参与规则计算
3. 不同场景间处理逻辑不一致
## 核心要求
1. 支持递归追溯数据来源
2. 合规数据按场景类型差异化处理
3. 统一处理逻辑
## 需求范围
- 场景类型1
- 场景类型2
- 场景类型3
- 场景类型4
对于复杂需求，为了让 AI 更准确地理解，建议结构化包含以下内容：
- 需求描述
- 核心要求
- 需求范围
- 业务规则详细说明
- 外部接口依赖（如有）
- 历史逻辑说明（迭代类需求提供）
AI 会生成一份结构化的规格文档 spec.md，包含：
- 功能需求清单（FR-001 ~ FR-025）
- 用户故事划分
- 边缘案例分析
- 业务规则详细说明
- 验收标准
- 异常场景处理
这个阶段最让我惊喜的是，AI 会主动标记出它不确定的边缘情况。这给了我们一个很好的机会，在动代码之前就把这些棘手的问题讨论清楚。
第三步：需求澄清（可选）
如果需求描述足够清晰，首次生成的规格质量很高，可以跳过这个阶段。但对于复杂需求，我强烈建议执行需求澄清。
执行澄清后，AI 会针对模糊点提出关键问题：
问：当追溯链路断开时应该如何处理？
答：使用追溯起点的数量作为最终数量
问：追溯深度是否需要限制？
答：需要限制，架构上保证不会超过 5 层
问：多个合规数据如何选择优先级？
答：主要来源 > 次要来源 > 其他
澄清完成后，AI 会更新 spec.md 并生成一份需求检查清单。
经验提示：需求细节越早明确，成本越低。建议在计划开始前执行需求澄清。
第四步：生成技术计划
需求澄清完成后，进入设计阶段。
这个阶段会分两个 Phase 执行：
Phase 0：实施计划总览
生成 plan.md（实施计划）和 research.md（技术调研与决策日志）
Phase 1：详细设计文档 生成以下文档：
data-model.md：数据模型定义contracts/api.md：接口契约quickstart.md：开发环境搭建指南
在设计阶段，AI 会自动搜索和读取现有的代码，了解历史逻辑。为了让 AI 读取更高效，可以补充说明本次需求涉及的代码位置：
本次需求涉及的代码：
- src/main/java/com/example/service/core/strategy/impl/PrimaryStrategy.java
- src/main/java/com/example/service/core/strategy/impl/SecondaryStrategy.java
- src/main/java/com/example/service/core/strategy/impl/TertiaryStrategy.java
- src/main/java/com/example/service/core/common/DataQueryService.java
经验提示：如果你有更好的技术方案或想法，可以直接在对话中告诉 AI 进行调整。
第五步：任务拆分
设计完成后，AI 会生成可执行的任务清单 tasks.md。
对于我们的案例，生成了 46 个任务，按以下结构组织：
Phase 1: Setup (T001~T003) - 项目初始化
Phase 2: Foundational (T004~T008) - 核心基础设施
Phase 3: US1 (T009~T018) - 用户故事 1
Phase 4: US2 (T019~T025) - 用户故事 2
Phase 5: US3 (T027~T032) - 用户故事 3
Phase 6: US4 (T033~T037) - 用户故事 4
Phase 7: Polish (T038~T046) - 质量保障
任务粒度建议：最好 0.5~2 天/任务。太大不可控，太小管理成本高。
每个任务都应该带"完成判据"：对应测试、接口契约、验收点。
任务顺序要体现依赖：契约和数据模型要先于实现；基础设施要先于业务。
第六步：一致性分析
这是 SpecKit 最有价值的功能之一。
执行一致性分析后，AI 会自动分析所有文档之间的一致性，生成一份详细的分析报告。
我们的第一次分析发现了以下问题：
| 问题类型 | 数量 | 严重程度 |
|---------|------|---------|
| CRITICAL | 1 | 关键问题 |
| HIGH | 2 | 高优先级 |
| MEDIUM | 4 | 中等 |
| LOW | 2 | 低优先级 |
最关键的问题是：规格文档中提到 4 种场景类型，但任务清单只实现了 3 个策略类。这明显是一个不一致的地方。
按照分析报告的修复建议，AI 自动读取现有代码，发现其中一个场景类型确实与另一个共用策略类，然后更新了任务描述。
第二次分析后：
- CRITICAL 问题：1 → 0
- HIGH 问题：2 → 0
- MEDIUM 问题：4 → 0
- 需求覆盖率：100%
- 宪章合规性：100%
文档质量达到了"实施就绪"状态。
经验提示：不要用代码"绕过"规格或宪章的要求。发现问题时，先修订文档/计划，再进入编码阶段。
第七步：任务实施
现在终于可以开始写代码了。AI 会按照任务依赖顺序逐个实施。
任务按用户故事分阶段执行，每个用户故事完成后会有一个检查点，方便你确认成果后再继续。
对于我们的案例：
- 用户故事 1（核心追溯能力）：10 个任务
- 用户故事 2（合规数据计算）：7 个任务
- 用户故事 3（逻辑统一）：6 个任务
- 用户故事 4（接口升级）：5 个任务
AI 生成代码后，需要审核：
- 代码逻辑是否正确
- 是否符合项目宪章规范
- 注释是否完整
审核通过后告诉 AI 继续执行下一个任务。
实施阶段遇到问题的处理方式：
| 问题类型 | 处理方法 |
|---|---|
| 规格或设计遗漏信息 | 告知 AI 正确的业务逻辑，让其先回写更新规格、设计及任务，确认后再重新生成代码 |
| 设计缺失或未考虑现有逻辑 | 告知 AI 正确的设计思路，让其先回写更新设计文档及任务，确认后再重新生成代码 |
| 实现与设计不一致 | 提醒 AI 严格按照设计生成代码 |
第八步：代码提交与分支合并
任务实施完成后，将生成的代码提交到本地特性分支，然后合并到版本分支。
git add .
git commit -m "feat: implement data tracing feature"
git checkout develop
git merge feature/data-tracing
完整工作流总览
graph TD
A[SpecKit Skill 完成本次需求完整工作流] --> B[1. 项目宪章<br/>constitution<br/>一次性设置，团队共用]
B --> C[2. 需求规格<br/>specify]
C --> D{3. 需求澄清<br/>clarify<br/>可选，按需执行}
D --> E[4. 技术计划<br/>plan<br/>Phase 0 + Phase 1<br/>plan → research + design docs]
E --> E2[4. 技术计划<br/>plan<br/>Phase 0 + Phase 1<br/>plan → research + design docs]
E2 --> F[5. 任务拆分<br/>tasks]
F --> G[6. 一致性分析<br/>analyze]
G --> H{7. 问题修复 +<br/>二次一致性验证<br/>循环直到质量达标}
H --> I[8. 任务实施 + 代码生成<br/>implement<br/>按用户故事分阶段执行<br/>每个任务：生成代码 → 审核 → 确认<br/>循环直到所有任务完成]
I --> J[9. 代码提交 + 分支合并]
style A fill:#e1f5fe,stroke:#000,color:#fff
style B fill:#ff8c00,stroke:#000,color:#fff
style C fill:#87ceeb,stroke:#000,color:#fff
style D fill:#f9a825,stroke:#000,color:#fff
style E fill:#4ecdc4,stroke:#000,color:#fff
style E2 fill:#4ecdc4,stroke:#000,color:#fff
style F fill:#00b894,stroke:#000,color:#fff
style G fill:#e94560,stroke:#000,color:#fff
style H fill:#f44336,stroke:#000,color:#fff
style I fill:#a855f7,stroke:#000,color:#fff
style J fill:#2ecc71,stroke:#000,color:#fff
各阶段产出物
| 阶段 | 命令 | 产出文件 | 说明 |
|---|---|---|---|
| 项目宪章 | speckit.constitution | constitution.md | 项目工程原则 |
| 需求规格 | speckit.specify | spec.md | 需求规格说明 |
| 需求澄清 | speckit.clarify | spec.md（更新）、requirements.md | 澄清后的规格、检查清单 |
| 技术计划 | speckit.plan | plan.md、research.md、data-model.md、contracts/*.md、quickstart.md | 设计文档集 |
| 任务拆分 | speckit.tasks | tasks.md | 任务清单 |
| 一致性分析 | speckit.analyze | 分析报告（控制台输出） | 问题清单和建议 |
| 任务实施 | speckit.implement | 源代码文件 | 业务代码 |
效果评估
让我用数据说话。
时间对比
传统分步提示词模式：
- 需求理解和澄清：2 天
- 设计文档：1 天
- 编码和调试：5 天
- 测试和修复：2 天
- 总计：10 天
使用 SpecKit：
- 需求规格生成：0.5 天
- 需求澄清：0.5 天
- 技术计划生成：0.5 天
- 一致性分析和问题修复：0.5 天
- 编码和审核：3 天
- 测试：1 天
- 总计：6 天
时间节省了 40%，但这还不是最重要的。
质量提升
文档质量：AI 生成的文档结构清晰、内容完整，远超大多数工程师手工编写的水平。
一致性保证：一致性分析自动发现规格、计划、任务之间的不一致，这在传统流程中往往要到测试阶段才能发现。
知识沉淀：整个过程产生了一套完整的文档集合，包括需求规格、设计文档、测试计划等，这些都是宝贵的知识资产。
可复用性：项目宪章、常用的需求澄清模式都可以在后续项目中复用，效率会越来越高。
进阶技巧与经验分享
使用 SpecKit 一段时间后，我总结了一些经验：
Q：项目宪章需要每次需求都重新生成吗？
不需要。项目宪章首次生成后，只有在项目原则需要升级时才更新（如新增异常处理统一要求）。
Q：规格阶段如何更有效地向 AI 描述需求？
简单需求使用清晰的自然语言描述即可。复杂需求建议结构化包含以下内容：
- 需求描述
- 核心要求
- 需求范围
- 业务规则详细说明
- 外部接口依赖（如有）
- 历史逻辑说明（迭代类需求提供）
Q：需求规格生成后发现有遗漏怎么办？
执行需求澄清进行需求澄清。AI 会针对模糊点提出问题，你回答后 AI 会自动更新 spec.md。
Q：spec.md 生成后必须做什么？
务必严格校对并确认 spec.md 逻辑完全正确后再进入下一阶段。关键检查点：
- 业务逻辑是否准确无歧义
- 边界条件和异常场景是否覆盖
- 技术术语和概念是否统一
规格文档是后续设计与实现的唯一依据。如果规格文档本身存在歧义或错误，后续的所有设计和代码生成都将沦为无用功。
Q：设计阶段或任务实施阶段 AI 给出多个方案，不知道选哪个怎么办？
让 AI 展开详细说明每个方案的优缺点，或者直接让它给出推荐方案并说明理由。
Q：一致性分析发现问题后如何处理？
按照分析报告的修复建议逐一处理。AI 能自动解决的问题会直接修复，需要人工确认的会列出修改清单。修复后重新执行一致性分析，直到质量达标。
Q：什么时候需要提供现有代码上下文？
新功能/新系统：如果是独立功能，生成规格时无需提供额外代码，仅在设计阶段关注架构即可。
迭代/修改功能（建议提供）：虽然 AI 具备代码搜索能力，会根据需求关键字读取代码，但主动提供上下文能大幅减少 AI 幻觉，提升准确率和响应速度。
Q：如何处理复杂的业务需求？
面对复杂业务流时，避免一次性生成所有规格。推荐策略：
- 将大需求按业务模块或流程节点拆解为若干个小的子任务（Sub-spec）
- 分步生成和验证，每个子规格通过后再进行下一个
- 粒度控制能显著提高 AI 的掌控力和输出质量
Q：使用 SpecKit 开发模式的核心要点是什么？
核心理念："只关注需求规格本身，无需关心提示词工程"
-
项目宪章要完善：详细定义代码风格、注释规范、异常处理等，核心判断原则：对每一行问自己 "删除这行会导致 AI 犯错吗？"，如果不会就删掉。文件过长反而会导致 AI 忽略真正重要的规则。
-
需求描述要清晰：输入的需求描述要清晰准确，包含业务规则、边界条件、异常处理等，质量决定最终成败
-
关注需求规格：生成规格文档的准确性直接影响后续所有环节的效率和质量
-
及时反馈问题：发现问题立即告诉 AI，它会学习并改进
-
思维模式转变：从传统的"边做边想"转向"前置思考"
文档管理建议
每次需求完成后生成的规格文件不应被丢弃。建议实践：
- 将验证通过的 spec.md 归档管理，作为项目知识库沉淀
- 按时间线或功能模块组织，方便追溯业务逻辑演变
- 未来 AI 理解项目上下文时可作为高质量的输入参考
- 规格文档也是团队协作和新人培训的重要资料
一些思考
SpecKit 不是银弹。它不会让一个糟糕的工程师突然变成高手。但它能把优秀的工程师从繁琐的文档工作中解放出来，让他们专注于真正有价值的思考。
更重要的是，它建立了一套标准化的需求开发流程。这套流程强调"先把事情说清楚，再开始写代码"的理念。这种理念在任何团队、任何项目中都是适用的，只不过 SpecKit 把它变成了可执行的具体步骤。
我认为，AI 辅助开发的未来不是"AI 替代工程师"，而是"AI 帮助工程师更好地思考"。SpecKit 的成功之处在于，它找到了 AI 能真正发挥价值的地方——在动代码之前，帮助我们把问题想清楚。
补充说明
除了 SpecKit 之外，我也了解并尝试过另外一些开发模式，比如 superpowers 等。这些工具各有特色和优势，选择哪种方式取决于具体的使用场景和团队习惯。
如果你也在尝试用 AI 改进开发流程，我建议试试 SpecKit。也许你会发现，它带来的不仅仅是效率的提升，更是思维方式的变化。
