LLM - 用 SpecKit 和 AICode 改造遗留系统 完整实践指南

小小工匠2025-12-25 13:23

文章目录

概述

用 SpecKit 和 AICode 改造存量 Java Web 系统，可以把"拍脑袋写代码"的 vibe coding，升级成一套可复用、可协作、可审计的规范驱动开发流程，尤其适合中大型 Spring Boot 项目。

引言：从 vibe coding 到规范驱动

近两年 AI 编程工具极大提升了个人开发效率，但在成熟存量系统中直接"对着大模型聊天写代码"，很容易引入风格不统一、边界不清晰、测试缺失等问题。

SpecKit 提出的规格驱动开发（Spec-Driven Development, SDD），通过一套从需求到代码的可执行规范，把 AI 从"写代码助手"升级为"按规格交付的工程承包商"。

将 SpecKit 与 AICode 类工具结合，可以在 Spring Boot 等 Java 后端项目中形成标准化的五步流程：对齐原则 → 规格化需求 → 技术方案与模型设计 → 任务分解 → 自动实现与回归，显著提升协作效率与可维护性。

背景：存量业务系统中的典型痛点

在一个运行多年的存量系统中，引入 AI 编码通常会遇到以下问题。

  • 需求模糊且多口径

    • 产品、运营、后端、前端对同一需求的理解存在偏差，口头澄清成本高。
    • 需求文档缺失或分散，AI 无法稳定理解上下文，产出的代码质量波动大。

  • 代码风格与架构分裂

    • 老代码使用传统三层架构，新代码夹杂 DDD、事件驱动、各种工具封装，风格不一致。
    • AI 生成代码如果没有"宪法级"规范约束，很容易引入新的架构分支和隐性技术债。

  • 测试与质量不可控

    • 存量系统往往测试覆盖不高，AI 生成代码缺乏统一测试约束，业务回归风险大。
    • 代码评审成本上升，因为人要花大量时间读 AI 产出的代码并补测试。

  • 团队协作困难

    • 不同开发者各自和 AI"聊天"，上下文不共享、规范不一致，协作成本反而上升。
    • 变更记录难以追踪：哪个功能是人写的、哪个是 AI 写的、基于哪份需求讨论，缺乏可追溯性。

SpecKit 核心理念与五步流程

SpecKit 做的到底是什么

  • SpecKit 将"项目规则 + 需求 + 技术方案 + 任务清单"全部变成结构化、可执行的规范文件，包括 constitution、requirements、spec、api、data-model、architecture、tasks 等。
  • 在这些规范之上，AI 才开始"实现代码"：通过实现命令按任务清单逐项生成具体代码，并在过程中持续对照规范做质量检查。

五步流程总览

以一个"订单批量补发报备图片"的存量需求为例，典型的 SpecKit + AICode 流程可抽象为五步。

  1. 对齐原则：Constitution（项目宪法）
    • 明确代码风格、分层规范、异常处理、日志规范、测试要求、性能指标等，生成 constitution.md。
  2. 需求规格化：Requirements & Spec
    • 将零散的需求描述整理为结构化的需求 requirements.md，再产出更技术化的 spec.md 供研发对齐。
  3. 技术方案与模型设计：API / Data Model / Architecture
    • 由 AI 在 SpecKit 约束下生成 api.md、data-model.md、ARCHITECTURE.md 等，统一接口与数据模型。
  4. 任务分解：Tasks
    • 使用任务命令生成 tasks.md，形成可执行的任务列表（控制器、服务、仓储、测试、配置等）。
  5. 代码实现与迭代：Implement
    • AICode 在任务清单和规范文件的约束下完成具体代码生成，多轮迭代微调与评审，并结合 CI/CD 做自动化校验与回归。

从零到一：在项目中落地 SpecKit

这一节以"订单批量生成报备图片"功能为贯穿示例，假设你有一个使用 Spring Boot 3.x + Java 17/21 的微服务项目，需要在不破坏现有架构的前提下引入 AI 辅助开发。

Step 1：定义项目宪法 constitution.md

目标是给 AI 一份"项目级的开发宪法"，避免它乱改架构与风格。

建议在仓库根目录下新增 speckit/constitution.md，内容可包括：

  • 工程与架构约束

    • 后端统一使用 Spring Boot 3.x + Spring MVC，遵循典型 Controller → Service → Repository 分层。
    • 业务逻辑不得写在 Controller 中，必须封装到 Service 层。
    • 统一使用统一的异常基类和全局异常处理器，错误码规则写清楚。

  • 代码风格与命名规范

    • Java 使用驼峰命名，类名使用业务含义，禁止缩写。
    • DTO、VO、Entity、Repository、Service 的命名后缀统一。

  • 测试与质量标准

    • 所有新增业务逻辑必须附带单元测试，使用 JUnit 5 + Mock 框架，覆盖核心 Happy Path 与关键边界。
    • 对外接口变更需要补充接口级回归测试（可通过 Spring MVC 测试或集成测试）。

  • 性能与安全要求

    • 对批量处理操作需保证单次请求的处理时间和并发策略，避免影响核心链路。
    • 涉及用户隐私或敏感数据的字段需要按照既有安全规范处理。

该文件会在 SpecKit 初始化和任务执行时反复作为"裁判规则"，约束 AI 的代码产出。

Step 2：需求规格化 requirements.md & spec.md

接下来要把"零散的产品需求"变成 AI 能读懂且可追踪的规范文件。

  • 在 SpecKit 中可以通过需求命令生成 requirements.md 草稿，再由人工补充和修订。
  • requirements.md 中推荐结构：
    • 背景与业务目标
    • 用户角色与典型场景
    • 功能性需求（按用例列出）
    • 非功能性需求（性能、稳定性、审计、权限等）
    • 业务规则与限制

示例片段（简化）：

markdown 复制代码 
# 背景

为满足监管要求，需要为历史订单生成并补发报备图片，支撑后续抽检和审计。

# 核心场景

- 运营同学在控制台选择时间范围与订单类型，触发批量生成报备图片任务。
- 系统异步执行任务，支持分页、断点续跑与失败重试。
  • 在此基础上，通过规范命令生成 spec.md，由 AI 将偏业务的描述翻译成面向开发的规格，包括接口粒度、交互流程、错误处理策略等。
  • 人工需要再次审阅 spec.md，确认与产品侧理解完全一致，再将其作为后续技术设计和编码的唯一依据。

Step 3：生成 API 与数据模型规范

在需求达成共识后，用 SpecKit 生成 API 规范与数据模型规范，作为前后端协作与数据库变更的基础。

  • api.md：约定对外暴露的 REST 接口

    • 路径、方法（GET/POST）、请求体与响应体字段、状态码与错误码、鉴权与权限说明。
    • 例如：
      • POST /api/admin/report-image-tasks：创建批量生成任务。
      • GET /api/admin/report-image-tasks/{taskId}：查看任务进度与结果。

  • data-model.md：实体模型与表结构

    • 新增的任务表、任务明细表、状态字段、索引设计等。
    • 明确与现有订单表之间的关联方式（外键、业务主键）。

  • ARCHITECTURE.md：架构视图

    • 描述该功能在现有微服务中的边界与依赖，明确是否需要新服务、还是在某个既有服务中扩展。

这些规范随后会用于指导 AICode 两个方向的产出：一是具体 Java 类和接口定义，二是数据库脚本和映射层代码。

Step 4：任务分解 tasks.md

有了规范之后，使用 SpecKit 的任务功能让 AI 为你列出完整的开发任务清单。

典型任务列表会包含：

  • 领域与数据层

    • 定义 ReportImageTask 实体与映射。
    • 扩展或新增 Repository 接口与实现。

  • 应用与接口层

    • 新增 ReportImageTaskController 与对应的请求/响应 DTO。
    • 在 Service 层实现任务创建、状态查询、批处理执行逻辑。

  • 基础设施与集成

    • 集成批处理调度（如 Spring Batch、定时任务）。
    • 新增外部服务或存储（如对象存储客户端）。

  • 测试与验证

    • 单元测试、集成测试、接口回归用例。
    • 上线前联调与回归范围说明。

这个 tasks.md 既是 AI 的"施工清单"，也可以直接纳入项目管理工具（Jira、禅道等）作为任务拆分基础。

Step 5：AICode 驱动的实现与迭代

在上述规范与任务之上，AICode（如 IDE 插件或专用 AI 编码工具）开始发挥作用。

  • 将 spec.md、api.md、data-model.md、constitution.md 等上下文注入 AICode，使其在生成代码时受到统一约束。
  • 按 tasks.md 的粒度逐项请求 AI 实现：
    • 先生成接口与 DTO。
    • 再生成 Service 骨架与 Repository。
    • 最后补齐单元测试与必要的配置。

人工职责变成：

  • 评审 AI 产出的代码是否符合宪法与规范。
  • 纠正业务细节偏差，并将修正同步回 spec.md 或补充到 requirements.md 中。
  • 通过 CI/CD 管道跑完 lint、测试、静态分析，确保整体质量。

代码层面的实践要点

这一节给出一些更贴近代码的操作建议（示例为简化版伪代码风格，便于在你的项目中调整应用）。

约束 AICode 的输入上下文

在让 AI 生成代码前，尽量提供以下信息：

  • 相关规范文件的摘要：
    • constitution.md 中与当前任务高度相关的片段。
    • api.md 中该接口的请求、响应定义。
  • 项目已有代码示例：
    • 一个典型的 Controller + Service + Repository 组合，用作"风格样板"。
  • 具体任务描述：
    • 从 tasks.md 挑出当前任务的条目，让 AI 以此作为执行目标。

这样可以让 AI 产出的代码更符合既有工程风格和抽象层级，减少后期重构成本。

示例：Service 层任务描述（伪代码）

任务描述示例（给 AI）：

text 复制代码 
在现有的 Spring Boot 项目中，基于以下规范：

- constitution.md 中的分层和异常处理约定
- api.md 中的 "创建报备图片批量任务" 接口定义
- data-model.md 中的 ReportImageTask / ReportImageTaskItem 实体

请实现 ReportImageTaskService：
- 创建批量任务：校验参数，生成任务和任务明细，异步触发任务执行
- 查询任务进度：统计已完成/失败/进行中的明细数量
需要同时生成对应的单元测试，覆盖正常流程和参数校验失败场景。

AI 生成的 Service 类与测试类再由你进行审阅与微调，期间涉及的业务规则变更可以回写到 spec.md 与 requirements.md，保持文档与实现同步演进。

与传统开发模式的核心差异

下面表格总结传统"人工驱动开发"与"SpecKit + AICode 规范驱动开发"在几个维度上的典型差异。

维度 传统模式（无 SpecKit / AICode） 规范驱动 AI 模式（SpecKit + AICode）
需求管理 需求多在 IM 群聊、零散文档中，口径不一致，易误解。 统一沉淀到 requirements.md / spec.md，版本可追踪，研发以同一规格为准。
架构与风格 依赖资深同学"口头规约"和 Code Review，落地不均衡。 有 constitution.md 和 ARCHITECTURE.md 作为架构宪法，AI 生成代码也必须遵守。
任务拆分 由人拍脑袋拆分，粒度不一，跨人协作难度大。 通过 tasks.md 由 AI 结合规范统一拆分任务，便于分工与追踪。
编码效率 人工手写，复杂逻辑和样板代码耗时长。 AICode 在规范约束下快速生成样板与逻辑，人更多投入在业务与抽象质量上。
代码质量 质量高度依赖个人能力，测试缺失常见。 宪法中明确测试和性能要求，AI 自动生成基础测试，人负责关键路径与边界补充。
文档与实现一致性 文档常年滞后或失真，很难作为真源头。 规范文件是"真源头"，实现依赖规范，变更要先更规范再更代码。
团队协作 每人各写各的，风格与抽象差异大，协同成本高。 编码风格、接口设计、模型命名由规范统一，AI 成为"统一执行器"。
可维护性与知识沉淀 依赖口碑与个人记忆，新人上手慢。 需求、架构、任务、代码一体化沉淀，新人只需阅读规范与关键代码即可上手。

团队协作与规范落地实践

在团队层面，SpecKit + AICode 的引入不只是安装几个工具，而是一次轻量的研发流程升级。

角色分工与协作模式

  • 架构师 / 资深工程师

    • 负责制定与维护 constitution.md、ARCHITECTURE.md，定义可允许的技术栈与边界。
    • 负责对关键规范变更进行评审（如新增跨服务调用、数据库结构变更）。

  • 模块负责人 / 后端开发

    • 主导 requirements.md 与 spec.md 的编写和修订，与产品侧对齐。
    • 主导 api.md、data-model.md 的生成与确认，保证对外接口稳定性。

  • 团队成员与 AI 使用者

    • 基于 tasks.md 承接任务，使用 AICode 生成与改写代码。
    • 遵守宪法与规范，发现规范缺失或矛盾时提出修订。

代码评审（Code Review）流程优化

引入 SpecKit 之后，Code Review 的关注点会发生转移。

  • 从"检查代码细节"转向"检查是否符合规范与业务意图"：
    • 是否遵守了 constitution.md 的分层与异常处理规则。
    • 实现是否准确满足 spec.md 里的业务规则和边界场景。
  • 将规范文件作为 Review 清单的一部分：
    • PR 模板中增加检查项：
      • 是否有对应的 requirements/spec/api/data-model 变更链接。
      • 是否有足够的测试覆盖。
  • 对 AI 自动生成的样板代码采用"抽查 + 重点检查"的策略，把精力集中在复杂逻辑和边界处理上。

与 CI/CD 的集成

要让 AI 生成的代码"安全落地"，必须依赖一条严密的 CI/CD 流水线。

  • CI 阶段

    • 静态检查：Checkstyle、SpotBugs、SonarQube 等工具，强制执行基本风格和质量标准。
    • 单元测试：强制要求新增模块单元测试通过，覆盖率不下降。
    • 合约测试（如有）：确保对外 API 行为未破坏既有调用方。

  • CD 阶段

    • 蓝绿发布或灰度发布，降低 AI 引入变更导致的线上事故风险。
    • 自动化回滚策略，配合监控指标（错误率、延迟、QPS）进行异常检测。

这些机制与 SpecKit 并不冲突，反而相互增强：规范定义"应该是什么"，CI/CD 负责保证"实际就是这样"。

在存量项目中渐进式落地的建议

对于已经运行多年的 Spring Boot 系统，不建议一次性"大重构"，而应该采用渐进式策略。

  • 从新需求或低风险模块开始
    • 优先选取业务相对独立、改动边界清晰的模块（如批处理、报表、内部工具）试点 SpecKit + AICode。
  • 逐步补齐旧模块的规范
    • 对于老模块，先抽取"显性规范"到 constitution.md 和 ARCHITECTURE.md，再在新需求迭代中逐步清理遗留问题。
  • 将规范与知识库结合
    • 将 requirements/spec/api/data-model 等文件纳入内部知识平台或文档系统，便于搜索和交叉引用。

最终目标是让"写规范 → AI 按规范实现 → 人做业务与质量把关"成为默认工作方式，而不是"实验项目中的新鲜玩具"。

扩展阅读

AI + Java 工程实践

SpecKit 与 AI 编码实践

🔗 https://developer.aliyun.com/article/1691457
探索在成熟 Java 项目中利用 AI Code + SpecKit 实现规范化、可追溯的编码实践

技术深度解析类（含开源项目 / 生态）

AI 代码助手 - 开源项目：ai-code-helper（Liyupi）

🔗 https://github.com/liyupi/ai-code-helper
GitHub：AI 代码辅助工具仓库

AI 母体项目 - yu-ai-code-mother（Liyupi）

🔗 https://github.com/liyupi/yu-ai-code-mother

社区技术文章 / 深度解析

xmsumi 技术社区文章

🔗 https://xmsumi.com/detail/1725

CSDN: AI 编码 / 实践相关文章

🔗 https://blog.csdn.net/qq_35766758/article/details/148209616

腾讯云开发者社区

🔗 https://cloud.tencent.com/developer/article/2539833

视频 & 多媒体学习资源

YouTube 技术讲解视频（AI/Spring/编码）

🔗 https://www.youtube.com/watch?v=YVFbc06cV_w

相关推荐
LYFlied3 天前
规范驱动开发（SDD）主流工具与框架深度解析
驱动开发·ai编程·sdd
小小工匠15 天前
Vibe Coding - Fission-AI OpenSpec 面向 AI 编程助手的规范驱动开发
spec·openspec·fission ai
小小工匠2 个月前
Vibe Coding - 深度解读规范驱动开发（SDD）：对 Kiro、spec-kit、Tessl 三大工具的剖析与实践
kiro·spec-kit·sdd·规范驱动开发·tessl
许泽宇的技术分享6 个月前
终端里的AI黑魔法：OpenCode深度体验与架构揭秘
人工智能·aicode
爱勤海之旅2 年前
iOS 搭建组件化私有库
ios·cocoapods·spec·本地私有库
热门推荐
01GitHub 镜像站点023D 圣诞树网页代码03从快手“12·22”直播攻击事件看：一次教科书式的业务层饱和攻击04UV安装并设置国内源05Gemini3 生成的基于手势控制3D粒子圣诞树06在VSCode配置Java开发环境的保姆级教程（适配各类AI编程IDE）07Linux下V2Ray安装配置指南08解决 WSL Ubuntu 中 /etc/resolv.conf 自动重置问题09Labelme从安装到标注：零基础完整指南10GLM-4.7 vs MiniMax-M2.1：代码工程理解