1. 为什么 Spring Boot 老项目需要一份 CodeBuddy Skill接手一个跑了三年的 Spring Boot 单体项目最耗时的从来不是写新接口而是搞清楚「这个项目到底怎么写的」。统一返回体是ResultT还是RT异常是抛BizException还是返回错误码订单状态枚举里 3 到底是「已支付」还是「已发货」这些信息散落在几十个 Controller、上百张表和一堆// 注意注释里新人翻两天也未必理得清。CodeBuddy 的 Skill 机制正好能解决这个问题。Skill 是一个模块化、自包含的能力包把通用 AI 变成「懂你这个项目」的专属开发助手。它遵循官方定义的渐进式披露原则SKILL.md作为常驻上下文的轻量入口只放元数据和核心指令详细文档全部拆到references/目录按需加载。这样既不会把上下文撑爆又能让 AI 在需要时精准取用项目知识。这篇要做的就是用一段可复制的扫描 Prompt让 CodeBuddy 自动读完你的 Spring Boot 项目产出符合官方规范的SKILL.md加一整套references知识库。适合谁正在维护中大型 Spring Boot 项目的后端、需要给团队沉淀项目规范的技术负责人、以及想让 AI 写代码时天然遵守项目约定的开发者。整个过程实测下来 5 分钟左右能拿到可加载的成果下面把目录骨架、模板、拆分规则和校验动作一步步拆开讲。2. 前置准备目录规范与 Skill 分层动手前先把两个概念分清楚否则文件放错位置 AI 根本加载不到。CodeBuddy 的 Skill 分两个层级。项目级 Skill 放在项目根目录的.codebuddy/skills/下随 Git 提交团队共享优先级高于用户级。用户级 Skill 放在本机全局目录所有项目生效适合放个人通用规范。我们这次生成的是项目专属知识库所以统一落在项目级路径。这里有个高频踩坑点Claude Code 用的是.claude/skillsCodeBuddy 固定用.codebuddy/skills两者不能混。我见过有人把文件丢进.claude目录然后纳闷为什么斜杠命令唤不出来就是路径写错了。标准目录骨架长这样.codebuddy/ └── skills/ └── my-project/ ├── SKILL.md └── references/ ├── project-overview.md ├── code-templates.md ├── api-contracts.md ├── database-schema.md ├── business-flows.md └── pitfalls.mdSKILL.md是核心入口头部必须带 YAML frontmatter正文控制在 400 行以内只写触发场景、核心工作流和规则速查表。references/下的文件是详细资料按需加载不占用常驻上下文。官方对资源目录还有更细的划分references放业务文档和架构说明给 AI 阅读scripts放可执行脚本assets放模板和静态资源。我们这个场景只需要references。环境要求很简单任意规模的 Java / Spring Boot 项目Maven 或 Gradle 都行IDEA 里装好 CodeBuddy 插件并确保插件有读取项目源码的权限。装插件直接在 IDEA 插件市场搜 CodeBuddy 即可。3. 可复制配置扫描 Prompt 与 SKILL.md 模板3.1 扫描生成 Prompt把下面这段完整粘进 CodeBuddy 对话框执行。它强制约束了目录规范、渐进式披露原则和产出物结构是整套流程的核心。请全面扫描当前 Spring Boot 项目源码生成一套符合 CodeBuddy 官方规范的完整项目知识库 Skill 能力包。 严格遵循 CodeBuddy Skill 规范 1. Skill 根目录my-project 2. 必须包含带 YAML frontmatter 的 SKILL.md核心入口 3. 详细文档统一放入 references/禁止大量内容堆砌在 SKILL.md 4. 遵循渐进式披露原则SKILL.md 精简详细资料作为按需加载资源 ## 第一部分项目知识梳理优先输出 结构化整理以下项目特有信息仅保留项目自定义逻辑剔除 SpringBoot、MyBatis 通用基础知识点 ### 1. 项目概览 - 项目名称、业务定位 - 精准技术栈清单框架版本、数据库、中间件、核心依赖 - 项目分层架构、模块依赖关系 ### 2. 核心业务模块清单 - 全部业务模块order/user/payment 等 - 各模块职责、模块间调用关系 ### 3. 核心数据表清单 - 核心业务表用途 - 表关联关系外键、关联字段 - 关键字段、状态枚举、类型枚举释义 ### 4. Controller 接口清单 - 所有 Controller 基础路径 - 接口请求方式、URL、入参、返回体 - 标记权限接口、幂等接口、限流、异步接口 ### 5. Service 核心业务逻辑 - 核心 Service 职责 - 复杂逻辑标记事务、状态机、分布式锁、消息队列、重试逻辑 - 关键业务流程 ### 6. 项目代码规范从源码提取 - 统一返回实体 ResultT 结构、错误码体系 - 全局异常处理规则 - 类、方法、URL、数据库字段命名规范 - 日志埋点、参数校验规则 - 自定义异常码清单 ### 7. 项目特殊逻辑 历史坑点 提取代码内隐性规则 分布式锁 Key 规范、缓存更新策略、分布式事务方案、幂等处理、异步消息场景、分库分表 所有注释 注意/TODO/FIXME 存在特殊分支判断的业务规则。 ## 第二部分生成标准化 Skill 文件 ### SKILL.md 要求 1. 文件头部必须携带标准 YAML frontmattername、description 必填 2. 正文控制在 400 行以内 3. 写明 Skill 触发场景、核心工作流、项目规则速查表 4. 长文档全部引用 references/ 下文件禁止大段文本 ### references/ 需要产出文件清单 - project-overview.md第一部分全部项目梳理内容 - code-templates.md项目通用代码模板 - api-contracts.md接口完整文档 - database-schema.md数据表、字段、枚举说明 - business-flows.md业务流程 - pitfalls.md项目避坑清单 ## 输出格式硬性要求 1. 先输出【项目知识梳理】再输出【Skill 全套文件】 2. 使用 文件名 分割每个独立文件 3. 所有代码、文档使用 markdown / java 代码块包裹 ## 重要约束 - 不输出通用 Java/Spring 教程只保留当前项目独有业务与规范 - 全面扫描核心接口、事务逻辑、特殊分支不要遗漏关键业务规则 - 结构清晰方便后续人工维护迭代3.2 SKILL.md 模板样板AI 生成后SKILL.md的头部结构应该长这样可以拿这个模板对照检查--- name: springboot-project-rules description: 当需要为当前 SpringBoot 项目编写接口、Service、数据库代码、修复 bug、评审代码时启用强制遵循项目统一返回格式、业务约束、历史避坑规则。 allowed-tools: [] disable: false --- # Spring Boot 项目开发规范 ## 触发场景 - 编写或修改 Controller / Service / Mapper - 新增数据库表或字段 - 修复业务 bug、评审代码 ## 核心工作流 1. 确认接口返回统一使用 ResultT 2. 业务异常统一抛 BizException由全局异常处理器兜底 3. 涉及订单状态变更时先查 references/business-flows.md 4. 编码前扫一遍 references/pitfalls.md 的历史坑点 ## 项目规则速查表 | 规则项 | 约定 | | --- | --- | | 返回体 | ResultTcode/message/data | | 异常 | BizException 全局处理器 | | 命名 | 类 UpperCamel方法 lowerCamel表 snake_case | | 日志 | 关键分支打 info异常打 error 带 traceId | 详细文档见 references/ 目录按需加载。name字段对应斜杠调用命令比如上面这个就是/springboot-project-rules。description决定 AI 自动触发的匹配逻辑写得越贴合实际使用场景自动加载越准。4. 落地文件与验证请求4.1 创建目录并落地文件先建官方标准目录mkdir -p .codebuddy/skills/my-project/ mkdir -p .codebuddy/skills/my-project/references/AI 输出时会用 文件名 分割每个文件按下面的映射表保存即可AI 输出文件名项目存放路径SKILL.md.codebuddy/skills/my-project/SKILL.mdproject-overview.md.codebuddy/skills/my-project/references/project-overview.mdcode-templates.md.codebuddy/skills/my-project/references/code-templates.mdapi-contracts.md.codebuddy/skills/my-project/references/api-contracts.mddatabase-schema.md.codebuddy/skills/my-project/references/database-schema.mdbusiness-flows.md.codebuddy/skills/my-project/references/business-flows.mdpitfalls.md.codebuddy/skills/my-project/references/pitfalls.md4.2 加载与验证CodeBuddy 支持两种调用方式。自动触发是日常用法AI 根据SKILL.md里的description识别场景自动加载不用手动操作。手动强制启用适合测试两种方式任选对话框输入/唤起 Skill 选择菜单选中my-project或者直接敲斜杠命令/my-project。验证是否生效发一条测试指令根据项目规范帮我生成一个查询订单列表的接口生效的判断标准很直观AI 自动用了项目自定义的ResultT返回体、遵守内部命名规范、复用项目真实表结构、并且规避了pitfalls.md里记录的历史问题。如果它还在用ResponseEntity或者自己造返回结构说明 Skill 没加载上回去检查路径和 frontmatter。管理入口在 CodeBuddy 设置面板的 Skills 项能看到全部项目级和用户级 Skill支持导入导出。5. 本篇常见错排查斜杠命令唤不出 Skill。九成是路径问题。确认文件在.codebuddy/skills/my-project/下不是.claude也不是多套了一层目录。SKILL.md必须直接位于my-project根下不能藏在子文件夹里。AI 不自动触发每次都要手动敲命令。检查description是不是写得太泛比如只写了「项目规范」。要写清楚触发条件像「当需要编写接口、Service、数据库代码、修复 bug 时启用」这种带具体动作的描述匹配才准。生成内容里全是 Spring Boot 通用教程。说明 Prompt 里的约束没生效或者项目里通用代码占比太高。可以在 Prompt 末尾追加一句「只保留当前项目独有业务与规范通用框架用法一律不输出」再重新扫描。上下文溢出、生成到一半断了。大项目常见。用拆分扫描法第一步只让它输出项目概览和业务模块清单第二步输出数据表清单和 Controller 接口清单第三步再生成完整 Skill 文件。分三次喂每次上下文压力小很多。扫描时把数据库密码也读进去了。扫描前先屏蔽敏感配置或者追加指令「跳过 application 配置文件中的密钥、账号等敏感内容」。生成后也顺手检查一遍references里有没有残留的密钥。SKILL.md 超过 400 行。说明详细内容没拆干净。把大段接口文档、表结构说明全部挪到references/对应文件SKILL.md只留速查表和引用链接。官方原则是SKILL.md当指令手册、references当百科文档两边严禁重复。团队拉代码后 Skill 不生效。确认.codebuddy/skills/已经纳入 Git 版本管理别被.gitignore忽略了。成员拉取后 CodeBuddy 会自动识别项目级 Skill不需要额外配置。6. 让 Skill 长期可用迭代与团队共享生成只是起点真正省时间的是后续迭代。当发现 AI 反复犯同一类错误直接追加指令更新文档比如你在生成订单取消逻辑时缺少【待支付状态校验】规则 请将这条约束补充到 references/pitfalls.md 同时同步更新 SKILL.md 核心规则速查表。这样知识库会随着项目演进持续沉淀而不是生成一次就烂在那。业务流程图想更直观可以在主 Prompt 里追加「在 business-flows.md 中使用 Mermaid 语法绘制核心业务流程图」评审时一眼就能看懂状态流转。团队共享方面把.codebuddy/skills/提交进 Git所有成员拉取后自动生效新人上手直接问 AI 就行不用再追着老员工问「这个字段啥意思」。如果你在接入过程中需要管理 API Key、查看调用额度可以走 TaoToken API Keys 配置想先验证模型对项目规范的理解效果用 模型对话 快速试跑如果是长期做编码和 Agent 场景Coding Plan 更合适。接入细节和参数说明都在 接入文档 里遇到报错先翻文档再排查能省不少时间。
5分钟让 CodeBuddy 自动扫描 Spring Boot 项目：适配官方 Skill 规范，一键生成 SKILL.md 与 references 知识库
1. 为什么 Spring Boot 老项目需要一份 CodeBuddy Skill接手一个跑了三年的 Spring Boot 单体项目最耗时的从来不是写新接口而是搞清楚「这个项目到底怎么写的」。统一返回体是ResultT还是RT异常是抛BizException还是返回错误码订单状态枚举里 3 到底是「已支付」还是「已发货」这些信息散落在几十个 Controller、上百张表和一堆// 注意注释里新人翻两天也未必理得清。CodeBuddy 的 Skill 机制正好能解决这个问题。Skill 是一个模块化、自包含的能力包把通用 AI 变成「懂你这个项目」的专属开发助手。它遵循官方定义的渐进式披露原则SKILL.md作为常驻上下文的轻量入口只放元数据和核心指令详细文档全部拆到references/目录按需加载。这样既不会把上下文撑爆又能让 AI 在需要时精准取用项目知识。这篇要做的就是用一段可复制的扫描 Prompt让 CodeBuddy 自动读完你的 Spring Boot 项目产出符合官方规范的SKILL.md加一整套references知识库。适合谁正在维护中大型 Spring Boot 项目的后端、需要给团队沉淀项目规范的技术负责人、以及想让 AI 写代码时天然遵守项目约定的开发者。整个过程实测下来 5 分钟左右能拿到可加载的成果下面把目录骨架、模板、拆分规则和校验动作一步步拆开讲。2. 前置准备目录规范与 Skill 分层动手前先把两个概念分清楚否则文件放错位置 AI 根本加载不到。CodeBuddy 的 Skill 分两个层级。项目级 Skill 放在项目根目录的.codebuddy/skills/下随 Git 提交团队共享优先级高于用户级。用户级 Skill 放在本机全局目录所有项目生效适合放个人通用规范。我们这次生成的是项目专属知识库所以统一落在项目级路径。这里有个高频踩坑点Claude Code 用的是.claude/skillsCodeBuddy 固定用.codebuddy/skills两者不能混。我见过有人把文件丢进.claude目录然后纳闷为什么斜杠命令唤不出来就是路径写错了。标准目录骨架长这样.codebuddy/ └── skills/ └── my-project/ ├── SKILL.md └── references/ ├── project-overview.md ├── code-templates.md ├── api-contracts.md ├── database-schema.md ├── business-flows.md └── pitfalls.mdSKILL.md是核心入口头部必须带 YAML frontmatter正文控制在 400 行以内只写触发场景、核心工作流和规则速查表。references/下的文件是详细资料按需加载不占用常驻上下文。官方对资源目录还有更细的划分references放业务文档和架构说明给 AI 阅读scripts放可执行脚本assets放模板和静态资源。我们这个场景只需要references。环境要求很简单任意规模的 Java / Spring Boot 项目Maven 或 Gradle 都行IDEA 里装好 CodeBuddy 插件并确保插件有读取项目源码的权限。装插件直接在 IDEA 插件市场搜 CodeBuddy 即可。3. 可复制配置扫描 Prompt 与 SKILL.md 模板3.1 扫描生成 Prompt把下面这段完整粘进 CodeBuddy 对话框执行。它强制约束了目录规范、渐进式披露原则和产出物结构是整套流程的核心。请全面扫描当前 Spring Boot 项目源码生成一套符合 CodeBuddy 官方规范的完整项目知识库 Skill 能力包。 严格遵循 CodeBuddy Skill 规范 1. Skill 根目录my-project 2. 必须包含带 YAML frontmatter 的 SKILL.md核心入口 3. 详细文档统一放入 references/禁止大量内容堆砌在 SKILL.md 4. 遵循渐进式披露原则SKILL.md 精简详细资料作为按需加载资源 ## 第一部分项目知识梳理优先输出 结构化整理以下项目特有信息仅保留项目自定义逻辑剔除 SpringBoot、MyBatis 通用基础知识点 ### 1. 项目概览 - 项目名称、业务定位 - 精准技术栈清单框架版本、数据库、中间件、核心依赖 - 项目分层架构、模块依赖关系 ### 2. 核心业务模块清单 - 全部业务模块order/user/payment 等 - 各模块职责、模块间调用关系 ### 3. 核心数据表清单 - 核心业务表用途 - 表关联关系外键、关联字段 - 关键字段、状态枚举、类型枚举释义 ### 4. Controller 接口清单 - 所有 Controller 基础路径 - 接口请求方式、URL、入参、返回体 - 标记权限接口、幂等接口、限流、异步接口 ### 5. Service 核心业务逻辑 - 核心 Service 职责 - 复杂逻辑标记事务、状态机、分布式锁、消息队列、重试逻辑 - 关键业务流程 ### 6. 项目代码规范从源码提取 - 统一返回实体 ResultT 结构、错误码体系 - 全局异常处理规则 - 类、方法、URL、数据库字段命名规范 - 日志埋点、参数校验规则 - 自定义异常码清单 ### 7. 项目特殊逻辑 历史坑点 提取代码内隐性规则 分布式锁 Key 规范、缓存更新策略、分布式事务方案、幂等处理、异步消息场景、分库分表 所有注释 注意/TODO/FIXME 存在特殊分支判断的业务规则。 ## 第二部分生成标准化 Skill 文件 ### SKILL.md 要求 1. 文件头部必须携带标准 YAML frontmattername、description 必填 2. 正文控制在 400 行以内 3. 写明 Skill 触发场景、核心工作流、项目规则速查表 4. 长文档全部引用 references/ 下文件禁止大段文本 ### references/ 需要产出文件清单 - project-overview.md第一部分全部项目梳理内容 - code-templates.md项目通用代码模板 - api-contracts.md接口完整文档 - database-schema.md数据表、字段、枚举说明 - business-flows.md业务流程 - pitfalls.md项目避坑清单 ## 输出格式硬性要求 1. 先输出【项目知识梳理】再输出【Skill 全套文件】 2. 使用 文件名 分割每个独立文件 3. 所有代码、文档使用 markdown / java 代码块包裹 ## 重要约束 - 不输出通用 Java/Spring 教程只保留当前项目独有业务与规范 - 全面扫描核心接口、事务逻辑、特殊分支不要遗漏关键业务规则 - 结构清晰方便后续人工维护迭代3.2 SKILL.md 模板样板AI 生成后SKILL.md的头部结构应该长这样可以拿这个模板对照检查--- name: springboot-project-rules description: 当需要为当前 SpringBoot 项目编写接口、Service、数据库代码、修复 bug、评审代码时启用强制遵循项目统一返回格式、业务约束、历史避坑规则。 allowed-tools: [] disable: false --- # Spring Boot 项目开发规范 ## 触发场景 - 编写或修改 Controller / Service / Mapper - 新增数据库表或字段 - 修复业务 bug、评审代码 ## 核心工作流 1. 确认接口返回统一使用 ResultT 2. 业务异常统一抛 BizException由全局异常处理器兜底 3. 涉及订单状态变更时先查 references/business-flows.md 4. 编码前扫一遍 references/pitfalls.md 的历史坑点 ## 项目规则速查表 | 规则项 | 约定 | | --- | --- | | 返回体 | ResultTcode/message/data | | 异常 | BizException 全局处理器 | | 命名 | 类 UpperCamel方法 lowerCamel表 snake_case | | 日志 | 关键分支打 info异常打 error 带 traceId | 详细文档见 references/ 目录按需加载。name字段对应斜杠调用命令比如上面这个就是/springboot-project-rules。description决定 AI 自动触发的匹配逻辑写得越贴合实际使用场景自动加载越准。4. 落地文件与验证请求4.1 创建目录并落地文件先建官方标准目录mkdir -p .codebuddy/skills/my-project/ mkdir -p .codebuddy/skills/my-project/references/AI 输出时会用 文件名 分割每个文件按下面的映射表保存即可AI 输出文件名项目存放路径SKILL.md.codebuddy/skills/my-project/SKILL.mdproject-overview.md.codebuddy/skills/my-project/references/project-overview.mdcode-templates.md.codebuddy/skills/my-project/references/code-templates.mdapi-contracts.md.codebuddy/skills/my-project/references/api-contracts.mddatabase-schema.md.codebuddy/skills/my-project/references/database-schema.mdbusiness-flows.md.codebuddy/skills/my-project/references/business-flows.mdpitfalls.md.codebuddy/skills/my-project/references/pitfalls.md4.2 加载与验证CodeBuddy 支持两种调用方式。自动触发是日常用法AI 根据SKILL.md里的description识别场景自动加载不用手动操作。手动强制启用适合测试两种方式任选对话框输入/唤起 Skill 选择菜单选中my-project或者直接敲斜杠命令/my-project。验证是否生效发一条测试指令根据项目规范帮我生成一个查询订单列表的接口生效的判断标准很直观AI 自动用了项目自定义的ResultT返回体、遵守内部命名规范、复用项目真实表结构、并且规避了pitfalls.md里记录的历史问题。如果它还在用ResponseEntity或者自己造返回结构说明 Skill 没加载上回去检查路径和 frontmatter。管理入口在 CodeBuddy 设置面板的 Skills 项能看到全部项目级和用户级 Skill支持导入导出。5. 本篇常见错排查斜杠命令唤不出 Skill。九成是路径问题。确认文件在.codebuddy/skills/my-project/下不是.claude也不是多套了一层目录。SKILL.md必须直接位于my-project根下不能藏在子文件夹里。AI 不自动触发每次都要手动敲命令。检查description是不是写得太泛比如只写了「项目规范」。要写清楚触发条件像「当需要编写接口、Service、数据库代码、修复 bug 时启用」这种带具体动作的描述匹配才准。生成内容里全是 Spring Boot 通用教程。说明 Prompt 里的约束没生效或者项目里通用代码占比太高。可以在 Prompt 末尾追加一句「只保留当前项目独有业务与规范通用框架用法一律不输出」再重新扫描。上下文溢出、生成到一半断了。大项目常见。用拆分扫描法第一步只让它输出项目概览和业务模块清单第二步输出数据表清单和 Controller 接口清单第三步再生成完整 Skill 文件。分三次喂每次上下文压力小很多。扫描时把数据库密码也读进去了。扫描前先屏蔽敏感配置或者追加指令「跳过 application 配置文件中的密钥、账号等敏感内容」。生成后也顺手检查一遍references里有没有残留的密钥。SKILL.md 超过 400 行。说明详细内容没拆干净。把大段接口文档、表结构说明全部挪到references/对应文件SKILL.md只留速查表和引用链接。官方原则是SKILL.md当指令手册、references当百科文档两边严禁重复。团队拉代码后 Skill 不生效。确认.codebuddy/skills/已经纳入 Git 版本管理别被.gitignore忽略了。成员拉取后 CodeBuddy 会自动识别项目级 Skill不需要额外配置。6. 让 Skill 长期可用迭代与团队共享生成只是起点真正省时间的是后续迭代。当发现 AI 反复犯同一类错误直接追加指令更新文档比如你在生成订单取消逻辑时缺少【待支付状态校验】规则 请将这条约束补充到 references/pitfalls.md 同时同步更新 SKILL.md 核心规则速查表。这样知识库会随着项目演进持续沉淀而不是生成一次就烂在那。业务流程图想更直观可以在主 Prompt 里追加「在 business-flows.md 中使用 Mermaid 语法绘制核心业务流程图」评审时一眼就能看懂状态流转。团队共享方面把.codebuddy/skills/提交进 Git所有成员拉取后自动生效新人上手直接问 AI 就行不用再追着老员工问「这个字段啥意思」。如果你在接入过程中需要管理 API Key、查看调用额度可以走 TaoToken API Keys 配置想先验证模型对项目规范的理解效果用 模型对话 快速试跑如果是长期做编码和 Agent 场景Coding Plan 更合适。接入细节和参数说明都在 接入文档 里遇到报错先翻文档再排查能省不少时间。
