让我们聊聊 SpecKit 在成熟 Java 项目中如何实现 AI 编码的那些事儿！

背景

最近我第一次试用了 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 的架构来看，大致可以分为三层：

• 各模型层各有特点和优势 -> 有些擅长深度分析，有些则是快速实现，选择上可以根据场景和安全需求来定；
• 编码工具层则分为CLI和智能编码IDE两种类型；

• CLI 模式 – 在不改变现有编码习惯的情况下可以较好兼容，但在实际操作中发现对 Java 语言支持不太友好，像 jar 包的信息解析上就有问题；
• IDE 模式 – cursor、qoder、lingma 利用 vscode 的底层能力自建信息索引，人机交互上更顺畅，不过需要适应新的 IDE 框架，改变一些现有的习惯；

• 在安全方面要考虑代码上传的风险；

• 目前国外工具 -> 只能处理 C2 级代码；

• 现在最常用的组合是 cursor + claude 4.5 深度思考 -> 代码质量还不错，但缺点是需要发送两个请求；
• 最新的组合是 cursor + composer1 -> 这是 cursor 自推的新模型，速度快，质量高，只需要一个请求；

• 目前的安全组合 -> 支持 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：

轻松上手AI工具的安装与使用

你可以通过这个链接找到相关的资源：https://github.com/github/spec-kit/releases

下载完对应的AI工具后，记得解压缩，然后把它们放到应用的根目录哦！

这款工具主要由两个部分组成，一个是用于适应特定模型和AI工具的spec命令适配器，另一个则是speckit的主体，涵盖了全球原则、命令工具和模板等内容。

进入项目的根目录后，打开AI代码工具，你就能看到spec命令了，简单吧？

轻松上手speckit的操作指南

speckit的使用分为主要步骤和过程命令，这些可以帮助你理清思路和检查分析。

主要步骤要按照顺序来，具体内容可以查看 git speckit 的文档。

第一步：使用 /speckit.constitution 命令来制定项目的治理原则和发展指南，这些将指引后续的开发步骤。

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

第二步：通过 /speckit.specify 命令来描述你想要构建的内容，着重于目标和原因，而不是具体的技术栈。

/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.

第三步：使用 /speckit.plan 命令来提供你的技术栈和架构选择。

/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.

第四步：用 /speckit.tasks 来从你的实施计划中创建可操作的任务清单。

/speckit.tasks

第五步：通过 /speckit.implement 来执行所有任务，按照计划构建你的功能。

/speckit.implement

实例演示

举个例子：我们需要为运维的同事提供一个工具，能够解析excel并生成用于报备的图片压缩包。

要注意的是，在spec模式下，得一步一步来，确认每一步的结果。如果后续发现需求或设计有偏差，可能会带来很大的返工成本。

第一步：明确原则

设定应用开发的原则

这次执行因为最开始输入的信息比较少，所以在过程中需要不断进行调整和优化。

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

最终生成了全局原则 – 具体内容请记得在specify中查阅。

需求分析与开发流程的友好指南

需求结束后，咱们可以整理一下，总结出一些升级的方向。

第二步：需求和要求的规范化

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


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

• 创建spec分支；
• 编写requirements.md；
• 撰写规范化的spec.md – 这份文档需要和产品团队、相关人员确认，并做一些调整；
• 编写api.md – 这用来帮助前端对接，但实现细节有待讨论；
• 生成data-model.md – 为后续对象和SQL脚本的创建提供基础；

要多加检查和细节调整

可以进行二次对话，微调输出格式：

api.md 改为 java rpc 规范生成

第三步：明确技术实现方案

这时，我们需要明确技术栈的要求。我给了一个参考例子，但实际的执行情况却没有达到预期。

现在这个案例可以说是个坏例子，缺了不少内容，后续不得不进行大量的修正（具体情况可以参考后面的实现和总结部分）。

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

• 生成框架代码，需要多次调整并提供示例
• 撰写ARCHITECTURE.md

第四步：分析执行任务

/speckit.tasks

• 编写tasks.md

AI会自动分析应该如何实现步骤列表

第五步：执行代码实现

/speckit.implement

• 生成IMPLEMENTATION_SUMMARY.md

Qwen code的实现分为两个步骤

1. 先生成结构代码 – 把主要类都写出来，具体的逻辑用伪代码表示，列出TODO计划（非常详细），完成后可以进行代码结构和逻辑的检查；

生成的伪代码示例

代码实现之旅：从构想到交付

第二步呢，就是在我们大致理清代码结构后，接着把TODO和伪代码里的逻辑细节补充完整。

结构生成阶段

在检查结构的时候，发现了很多问题，得一一纠正。

这一阶段我们做了好几轮的返工，自动重新跑了一遍specify、plan和task的动作。

1. constitution的定义有遗漏；

2. plan的输入不够详细，没把结构和代码要求讲明白，AI对范例的解析也不够深入，没有触及到gateway层；

问题一大堆，比如mapper写错了，类转换没用mapstruct，gateway实现也不标准，DO/DTO/DomainModel之间的使用混乱等等。

经过多次的澄清命令和自然语言的对焦，qwen code会把结论记录到adr决策记录中，而在后续执行中会自动应用这些决策，调整技术方案和执行任务。

结合这些决策，给出了标准范例作为参考，生成的代码质量确实提升了不少。

举个例子：

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

顺便说一下，这时候如果处理上下文太多，可能会触发一些限速机制，导致异常缓慢。有时一个会话会跑半小时以上，只能重启qwen code，这样一来会话记录和上下文都会丢失，重新校准也花了不少时间。

实现细节阶段

在这个阶段，大家已经更聚焦了，AI的写作速度和准确性都提高了，经过一次调优后基本就成型了，最后再稍微打磨一下，检查完就可以交付了。

第一次生成的时候，细节逻辑都写出来了，但发现有些实现没有用到通用工具；

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

第二次调整：要求按照统一工具类进行修改。

当你不知道怎么用工具的API时，别忘了可以去Git上查找相关的API信息哦。

第六步：总结反思

这一步是我自己加的，执行的结果可以让AI帮忙整理成一些知识资产，挺方便的。

记得把原则整理到 constitution.md 文件里，同时最优实践的说明也要归纳到 App-Desc 中，确保应用的文档清晰。

命令执行情况

在任务执行后、实施之前，要先对 spec 文件夹里的内容和代码进行对齐，检查有没有不一致的地方。

发现问题时，可以澄清命令，补充你的要求，或者请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. 如果前面的步骤没有检测内容，后面的动作就会直接执行，等到任务实施的时候再去调整123步骤，结果花了很多时间重新检查和生成，同时上下文噪音也增加，导致后面的处理越来越慢，最后不得不重启qwen code。

2. 在没有指定案例的情况下，它可能会随机找几个类进行学习联想，但如果未确认就开始执行，生成的效果和预期差距就会很大。

3. qwen有时候会突然卡住T_T，需要重新打开窗口，或者使用/quit -> 而cursor似乎并没有出现类似的问题。

一些思考与总结

• 最近返工的事情真是让人头疼，速度越来越慢，感觉是上下文太复杂导致触发了限速。
• 长时间不动命令行，重新请求的时候速度也突然变得很慢。

4. 相比于cursor，qwen code的文件读取速度就显得有些慢。

5. 在计划和指定阶段，我们得生成外部API的说明，但现在还没有平台可以自动上传获取，得靠手动来传递。

1. 提升研发效率：经过一次实施后，第二次可以把上次的经验充分利用，小需求熟练后能迅速完成，整体进展加快。

2. AI并不是万灵药，它和人一样，有时候会逻辑混乱，甚至忘记信息。急于推进未明确的阶段，往往会导致返工，从而增加成本。如果做到一定程度，可以让AI进行整体分析和汇总，再根据汇总信息反馈问题，记录到adr决策中，这样后续效率也能得到有效提升，确认好目标后还能减少上下文，提高模型速度。

3. 程序员打双线甚至多线操作将会成为常态：有可能会用两个甚至多个屏幕，一个显示器运行AI代理，遇到需要反馈的情况能及时操作，另一个显示器用来处理其他事务。

4. AI在推动规范化和标准化的进程中：

• 每个应用都需要准备多个说明文档，下次在计划阶段直接输入就行，架构师负责应用和团队的知识，初始化每个应用的标准知识，大致内容包括：

• 应用结构说明.md
• 单测结构说明.md
• 最佳代码实践说明.md – 团队cola代码规范和实际应用中的代码示例
• 最佳单测实现说明.md
• 通用工具组件说明.md
• 打包集成说明.md

• API定义需要能发布和获取
• 团队的技术标准需要有说明文档，能远程获取，并且要有公共权限。
• 产品文档应该有标准结构，获取方式要支持远程，授权问题已经通过mcp解决。
• 还需要配合AI优化现有的开发流程，加强概要设计和AI过程产物的检查。

5. 要增强全局知识检索能力：让AI能根据场景获取相关知识，而不是不断进行人工输入校准，业界也在推荐AI主动智能检索的方案，而不是RAG。

Qwen-Image，告别文字乱码的生图时代

针对AI绘画文字生成不准确的普遍问题，我们推出的方案搭载了业界领先的Qwen-Image系列模型，能提供精准的图文生成和图像编辑能力，帮助您轻松制作清晰美观的中英文海报、Logo和创意图。此外，这个方案还支持一键生成视频，为内容创作提供全方位的支持。

点击部署Qwen-Image精准生图-AI绘画模型-技术解决方案-阿里云了解更多详情。