背景

初次尝试 AI Code + SpecKit，过程中被其能力所震撼。本文将总结一些实践经验，与大家共同学习探讨。

当前 vibe coding 正如火如荼，尤其适用于单兵作战时对新场景的快速验证与实现。然而，在成熟的存量应用开发中，直接套用这种方式往往会遇到不少挑战——前后端分离架构下的协作效率、多人分模块开发的一致性、以及长期可维护性，始终是绕不开的核心问题。

随着 规格驱动开发（Spec-Driven Development, SDD） 理念逐步落地，这些问题似乎有了新的解法。本次我们首次引入 SpecKit 作为规范管理工具，在一个成熟的 Java 应用中，按照标准化的研发流程进行实践。

SpecKit 遵循 SDD（规格驱动开发）与 TDD（测试驱动开发） 的设计思想，核心理念是：

通过一套结构化的规范，将开发过程拆解为“定义原则 → 明确需求 → 制定计划 → 拆解任务 → 执行实现”的有序步骤，逐步推进。在此过程中，沉淀出应用级的开发原则与关键决策，从而实现风格统一、可追溯、可持续的 AI 辅助编码（AI Coding）。

Speckit 官网链接：https://github.com/github/spec-kit

选型

从当前AI Coding的结构上来看大致分为了3层：

• 模型层各有优劣且推陈出新 -> 有的善于深度分析，有的善于快速实现，按场景和安全要求进行选择；
• 编码工具层有CLI & 智能编码IDE两大阵营；
• CLI 模式 - 在不改变现有编码习惯下能比较好兼容，但是实操过程发现对java语言有点不友好，缺少代码上下文的信息，如jar包无法解析到；
  
  
• IDE 模式 - cursor、qoder、lingma 借助于vscode的底层能力自建信息索引同时人机交互会更好，但是需要改变当前的习惯，重新适应新IDE框架；
• 安全层面考虑到代码上传的风险；
  
  
• 当前国外工具 -> 只能跑 C2 级代码；
• 当前最普世组合 cursor + claude 4.5 深度思考 -》代码质量较好，缺点是需要2个request；
• 当前最新组合 cursor + composer1 -》 cursor 自推的新模型，速度较快且质量较好，需要1个request；
• 当前安全组合 -> 支持 C3 级代码；
• idea + qwen code cli + qwen3 coder plus -》 基本能力满足，但是较cursor、Qoder来看缺失了自建代码索引部分，有部分信息缺失；
• 未来可期组合 Qoder + qwen3 coder plus；

之前技术组件包代码优化升级采用了 cursor + claude 整体体验较好。

本次是业务需求需保障C3级别代码安全，采用 idea + qwen code cli + qwen3 coder plus 。

环境准备

安装 qwen code：

https://github.com/QwenLM/qwen-code

sudo npm install -g @qwen-code/qwen-code@latest

qwen --version

安装 speckit：

https://github.com/github/spec-kit/releases

按对应的ai工具下载后解压，放到应用根目录：

一个是相关模型和ai工具的spec命令适配器（prompt的封装），一个是speckit主体（全局原则，命令工具，模板）。

在项目跟目录进入ai code 工具后可以看到spec命令。

speckit 分为主要步骤命令和过程命令（用于澄清，检查分析）。

主要步骤需按顺序执行 - 详见 git speckit

Step1：Use the /speckit.constitution command to create your project's governing principles and development guidelines that will guide all subsequent development.

/speckit.constitution Create principles focused on code quality, testing standards, user experience consistency, and performance requirements

Step2：Use the /speckit.specify command to describe what you want to build. Focus on the what and why, not the tech stack.

/speckit.specify Build an application that can help me organize my photos in separate photo albums. Albums are grouped by date and can be re-organized by dragging and dropping on the main page. Albums are never in other nested albums. Within each album, photos are previewed in a tile-like interface.

Step3：Use the /speckit.plan command to provide your tech stack and architecture choices.

/speckit.plan The application uses Vite with minimal number of libraries. Use vanilla HTML, CSS, and JavaScript as much as possible. Images are not uploaded anywhere and metadata is stored in a local SQLite database.

Step4：Use /speckit.tasks to create an actionable task list from your implementation plan.

/speckit.tasks

Step5：Use /speckit.implement to execute all tasks and build your feature according to the plan.

/speckit.implement

执行实例

取部分需求作为例子 ： 提供给运维同学工具，解析excel 生成用于报备的图片zip包。

注意点 - spec模式下需要步步执行，步步确认。与人开发逻辑一致，在后置步骤发现需求or设计偏差，会产生较大返工成本。

Step1：明确原则

构建应用的开发原则

本次执行中由于初始输入较少，导致过程需要不停地进行调优校正。

/speckit.constitution 遵循模块化设计原则，采用COLA架构，遵循阿里巴巴开发规范，代码遵循最小依赖原则，代码规范和样式统一，speckit相关文件尽量用中文表述

生成了全局原则 - 记忆在specify

需求结束后，可以往上归纳总结升级 。

Step2：规格化需求和要求

/speckit.specify 需要对 com.alicom.message.supervise.service.register 包下的报备材料功能进行升级，新增加来自供应链反馈的固定材料管理能力，提供给供应链和服务团队的运维人员对固定材料的管理服务，对应的git分支为 feature/20251029_27086783_mt_1

相关需求说明文件为 Req 文件夹下的 批量生成报备用图片.md

• 生成spec分支；
• 生成 requirements.md；
• 生成 spec.md -> 规范化的需求文档，和产品侧、相关方进行二次确认，进行了部分微调；
• 生成api.md -> 提供给前端对齐，但是pop怎么搞是个问题；
• 生成data-model.md -> 用于生成后续对象和sql；

需要多多检查&细节调整

可以二次对话微调，比如改个输出格式：

api.md 改为 java rpc 规范生成

Step3：明确技术实现方案

在这个阶段输入技术栈要求，我给了一个参考例子，实际执行情况没有达到预期。

当前为一个bad case，缺失了很多内容，后面不得不猛猛修正（参考后面的实现和总结环节 ）。

/speckit.plan 先分析 RegisterMaterialsManageServiceI 的实现结构，先生成主体代码结构，包含rpc实现 domainservice gateway mapper convetor，组件生成到com.alicom.message.supervise.service.register.file.compoments ，预留 excel解析、图片处理、zip压缩的逻辑实现

• 生成框架代码、需要多次调整和给予案例
• 生成 ARCHITECTURE.md

Step4：分析执行任务

/speckit.tasks

• 生成 tasks.md

ai自己分析应该怎么去实现的步骤List

Step5：执行代码实现

/speckit.implement

• 生成 IMPLEMENTATION_SUMMARY.md

Qwen code 分为2步来实现

1. 先生成结构代码 - 把所有主要类生成，具体逻辑抽了方法，用伪代码列了 TODO 计划 （很详细），在完成后可以对代码进行骨架检查和逻辑检查；

生成的伪代码like

2. 在代码结构基本搞对后，将TODO & 伪代码 补充逻辑明细。

结构生成阶段

对结构检查发现很多问题并进行反复纠错。

在此阶段进行了多轮返工，自动重新跑specify，plan，task动作。

1. constitution 定义有漏；

2. plan的输入不够，没有讲清楚结构，代码要求，ai没有按范例的解析不够深入，没有到gateway层；

有好多问题 - mapper 写的不对，类转换没有用mapstruct ，gateway实现标准、DO/DTO/DomainModel使用混乱等等......

经过多次执行澄清明命令 & 自然语言对焦，qwen code 会把结论记录到 - adr 决策记录中，在后续执行中会自动应用决策并对技术方案和执行task进行调整。

决策结合给予了标准范例作为参考，生成出的代码质量大大提升。

例如：

ZipPackagingService 逻辑合并到 ZipPackagingComponent，ImageGenerationService 逻辑合并到 ImageGenerationComponent ，domain 包下的com.alicom.message.supervise.service.register.file.compoments 
 是放业务组件和单体功能的地方，com.alicom.message.supervise.service.register.file.service整体合并到com.alicom.message.supervise.service.register.file.compoments

com.alicom.message.supervise.service.register.file.FileBatchProcessDomainService#getBatchTaskResult 逻辑放到app层，domainservice只需要一个读BatchTask的方案，上层封装成为BatchTaskResult

ps. 这时处理上下文太多应该触发某些限速机制，导致异常缓慢1个会话要跑半小时以上，只能重启qwen code -> 导致会话记录丢失和上下文丢失，花了不少时间重新校准。

实现细节阶段

这个阶段由于已经比较聚焦，AI写的快且准重新调优了一次就基本成型，收尾再稍微进行了打磨和检测就具备了交付条件。

第一次生成：生成了所有的细节逻辑，但是发现有部分实现逻辑没有使用应用中通用工具；

FileBatchProcessDomainService startBatchTaskProcess 实现 异步处理逻辑 在处理完成或者抛异常后，需要把处理结果回写到 BatchTask，更新任务状态和成功失败数据、结果文件、异常文件

第二次调整：要求按统一工具类调整

参考 com.alicom.message.supervise.service.auth.util.ExcelUtil 的使用情况，分析各使用代码，对 com.alicom.message.supervise.service.register.file.compoments.ExcelParsingComponent#parseExcelFile 逻辑进行实现 & 调优

Oss 操作会使用 OssClientUtil 扫描一下应用内代码使用情况，对当前需求代码做调整，输入的excelFileKey，输出的zipFileKey，failureFileKey 都是oss文件key
本期默认都生成一个空的 .jpg 文件

当遇到不会使用工具api，会主动访问git查api

Step6：收尾的反向总结

个人增加的一步，执行结果可以再让AI 归纳成为应用知识资产。

原则整理到 constitution.md，说明和最优实践需要整理归纳到 App-Desc（应用级的归纳说明）。

过程命令使用情况

/speckit.analyze

在task后 implement前

对 spec 文件夹下的内容和代码进行对齐校准，看看有没有不一致的地方进行确认。

/speckit.clarify

澄清命令 补充你的要求或者让ai进行总结，在发现偏差问题后使用。

/speckit.checklist

生成自定义质量检查表，以验证需求的完整性，本期暂未用上。

新增的git文件

全局的应用知识 -> 在代码结构生成比较规范后，尝试用ai总结了一下，还是得进一步优化。

以当前specs内容为参考，com.alicom.message.supervise.service.register.file.api.FileBatchProcessServiceI com.alicom.message.supervise.service.register.materials.api.RegisterMaterialsManageServiceI │
│ 的代码实现结构为案例，用中文归纳总结 到 App-Desc 下 关键md文件 应用结构说明.md 最优代码实现说明.md 通用工具组件说明.md 单测结构说明.md 等

App-Desc

应用的说明书：为每个应用都需要维护的md -> 应交由架构师和应用负责人做好管理。

过程记录

specs - 多分支记录：当前分支生产过程的规格化说明，蕴含过程的纠偏、反馈信息，可用于下次新需求。

优点

1. 有记忆能力，纠正后能保持；

2. 每一步动作执行后都可以进行细节沟通；

3. 给于范例后，代码格式风格还原度很高，整体结构质量不错；

问题

1. 前置步骤没检测内容就执行后续动作，等到了 task implement 再调整返工 123 步骤，花了不少时间重检查重新生成，同时增加了上下文噪音导致后面越来越慢不得不重开qwen code。

2. 不指定案例的情况下，会随机找个几个类学习联想，在没有确认的情况下就开始执行，生成效果与预期有较大偏差。

3. qwen 偶发抽风 T_T 导致需要重开窗口或者 /quit -> cursor好像没有出现此类问题。

• 返工量大导致越来越慢 ，感觉由于上下文太大触发了限速墙。
• 长时间不操作命令行后的再次请求突然变慢。

4. qwen code 相较 cursor 读文件速度不是很快。

5. specify or plan 阶段 需要生成对外 api 说明，当前没有平台能适配自动上传获取，需要人工传递。

思考&总结

1. 研发效率提升 ：在进行过一次实施后，第二次实施可以充分复用上一次的经验和全局沉淀，一个小需求在熟练后很快可搞完，整体落地速度变快。

2. AI 并不是魔法，和人一样也会逻辑混乱甚至遗忘部分信息：在未明确阶段内容急着往下推进往往需要返工，导致大量推倒调整成本。做到一定程度可以让AI做个整体分析和汇总汇报，针对汇总信息进行问题反馈并记录到adr决策反馈能有效提升后续效率，确认对焦清楚后可缩减上下文从而提升模型速度。

3. 程序员打双线甚至多线操作在未来是基本操作：两个屏幕甚至多个屏幕，一个显示器跑ai agent 时不时遇到需要反馈/确认的时候进行操作，一个显示器干其他事情。

4. AI 在促进规范化标准化：

• 每个应用需要给若干个说明文档，下次在constitution & plan阶段 输入即可，应由架构师为应用知识和团队知识负责，对每个应用标准知识的初始化，大致需要如下内容：
• 应用结构说明.md
• 单测结构说明.md
• 最优代码实践说明.md -> 团队cola代码规范 & 以实际应用中的代码举例
• 最优单测实现说明.md
• 通用工具组件说明.md
• 打包集成说明.md
• API 定义需要能被发布 & 获取
• 团队技术标准应该需要说明文档，可以远程获取，public权限。
• 产品文档应该有个标准结构，获取方式要支持远程获取，授权 - 目前已经通过mcp解决。
• 需要配合AI的生产流程优化现有开发流程，加强概要设计和AI过程产物的检查。

5. 需要增加全局知识检索能力：让ai能按场景获取对应知识而不是一遍遍人工输入校准，业界也在推荐AI主动智能检索的方案而不是RAG。

来源  |  阿里云开发者公众号

作者  |  悟壳