低代码平台做着做着，大家通常都会有一个共同感受：日常大部分时间不是在写多难的技术，而是在反复做同一类搬砖动作——建表、写接口、画表单、配审批流。而拿到 JeecgBoot 这类平台时，搬砖效率虽然已经比从零开发快很多，但真正耗神的环节其实是从“业务描述”到“平台配置”的那段翻译过程。我最近把 Claude Code 引入到这套链路里，做了一套自然语言驱动的技能集，大体效果是：用一句话描述需求，代码、表单、流程相关的重复工作能自动生成，人工只需要做检查和微调。
这篇内容相当于把我在实际项目中验证过的做法整理出来，聚焦“JeecgBoot × Claude Code 技能集”的设计思路、目录结构、提示词写法、生成质量和失败排查这几个维度。适合已经在用 JeecgBoot、想引入 AI 提效但又不想只停留在“让 AI 写个 HelloWorld”阶段的开发者参考。没有太虚的概念，都是能直接落地的配置和套路。
1. 核心思路：为什么要做“技能集”而不是随手写提示词
1.1 低代码平台与 AI 辅助的真实交汇点
先把边界想清楚。JeecgBoot 本身不是让开发者在命令行里敲代码的平台，它提供的是在线表单、Online Coding、代码生成器、流程设计器这些可视化能力。直接让 AI 生成一整套 Spring Boot 工程并不符合实际使用习惯，因为在现有工程里，你真正缺的是业务实体、页面脚本、流程配置这些“零件”。所以 AI 的定位应该是“业务代码生成器”，而不是“整个系统的替代品”。
把 Claude Code 接进来以后，我最开始的做法很粗暴：直接在对话里说“帮我生成一个客户管理模块的代码”。结果确实能出东西，但问题也明显——每次都需要重复描述项目里的表结构约定、包名、权限注解格式，生成出来的代码风格一会儿一个样，再往平台里搬还得手动改半死。我意识到问题不在模型能力，而在于我没有任何“约束上下文”。于是开始把规范性的内容沉淀成技能集，让模型在进入任务前自动加载这些约束，相当于给一个技术很强但不懂你们项目规矩的新同事发了一本新人手册。
1.2 技能集到底解决什么问题
技能集（Skills）这个形式的核心价值，在我看来是三个：上下文复用、流程固化、输出可控。
上下文复用说的是，不需要每次在提示词里重复“我们项目的实体类放在 com.xxx.modules.customer.entity 下，请使用 Swagger 注解，Controller 要继承 JeecgController……”这些规则。你把它们写进技能目录里的指令文件，Claude Code 会在相关任务触发时自动读取。
流程固化则是指，一个完整的生成任务往往不是一步到位的。比如生成一个带审批的模块，需要先识别表结构，再生成实体、Mapper、Service、Controller，接着生成前端列表页和表单页，最后生成流程定义。如果每一步都用一句零散提示词去驱动，很容易在某个环节断掉。技能集可以把这一整条流水线拆成多个子任务，定义好先后顺序和输入输出。
输出可控是最实际的好处。通过模板约束，AI 生成的代码会尽量贴合平台约定，例如列表页查询条件区怎么排、字典字段用什么组件渲染、Controller 返回类型是不是统一用 Result。这些细节决定了生成结果能不能直接跑起来，而不是看上去很专业但一编译就报错。
1.3 整体链路设计
在动手写技能集的 YAML 和提示词之前，强烈建议先把整条链路画一遍。我在项目里实际跑通的流程如下：
自然语言需求描述 → Claude Code 调用技能集解析意图 → 生成中间配置（字段清单、页面配置 JSON、流程定义 DSL）→ 调用平台代码生成器或导入接口落库 → 人工检查与微调 → 编译验证。
这几个环节里有一个关键取舍：不要指望 AI 直接修改平台数据库里的表单定义。风险和回滚成本都很高。更稳的方式是让 AI 生成可导入的中间文件，然后通过平台自身的导入功能或者写好的脚本完成落地。这样即使生成结果有问题，删除导入记录重来一遍就行，不会把线上配置搞乱。
2. 环境准备与技能集结构设计
2.1 推荐环境与基本配置
先说我在实际验证时用的环境组合。JeecgBoot 用的 3.x 系列，前端 Vue3 + 后端 Spring Boot；Claude Code 使用当前稳定版本，通过 CLI 方式在项目目录内运行。操作系统 Windows / macOS / Linux 都可以，但在 Windows 上要注意路径分隔符问题，技能脚本里如果涉及文件写入，建议用相对路径而不是绝对路径。
项目结构上，我建议把技能集放在一个独立的目录里，比如 skills/ 或者 .claude/skills/，而不是散落在项目各处。这样有几个好处：技能本身可以跟着项目走，也能用 Git 单独管理版本；团队其他人拉下来就能直接用，不需要重新发明一套配置；出问题时也能整体回退。Claude Code 会默认读取 .claude/skills 目录，这算是最省事的位置。
2.2 技能目录结构与核心文件
一个标准的技能目录，我通常这样组织：
.claude/skills/ └── jeecg-codegen/ ├── SKILL.md ├── templates/ │ ├── entity_template.java │ ├── controller_template.java │ ├── service_template.java │ ├── vue_list_template.vue │ └── form_config_template.json ├── scripts/ │ ├── generate.sh │ └── validate.sh └── examples/ ├── customer_module.md └── leave_process.mdSKILL.md 是这个技能集的入口文件，里面包含两大部分：frontmatter 区域声明技能名称、触发条件和简要描述；正文区域写具体的执行逻辑、代码规范、输出格式要求。Claude Code 在对话中会根据描述自动判断是否加载这个技能。
frontmatter 我一般写成这样：
--- name: jeecg-codegen description: 当用户需要生成 JeecgBoot 的实体、接口、页面、表单或流程配置时使用。 when-to-use: 检测到“生成模块/建表/创建表单/配置流程”等意图时自动加载。 ---description 一定要写得具体，避免和其他技能冲突。我刚开始把所有生成任务都塞进一个技能，后来发现表单类任务和流程类任务的处理逻辑差异太大，就拆成了三个独立的技能：jeecg-crud、jeecg-form、jeecg-process。每个技能各司其职，触发更精准，也不会相互干扰。
2.3 项目约定的注入方式
技能集解决的是局部操作规范，但 Claude Code 整体上还需要了解你项目的全局约定。我强烈建议在项目根目录放一个 CLAUDE.md 文件，内容包含项目模块划分、包名规则、数据库命名规范、常见代码风格的示例片段、以及危险操作清单。
举几个我在 CLAUDE.md 里写的条目：
- 所有新表主键统一使用 String 类型的雪花ID，不要用自增ID。
- Controller 层统一继承平台 BaseController，返回结构为 Result。
- 前端页面放在对应模块的 views 目录下，文件名用模块名 + List / Form 结尾。
- 不允许修改平台底层配置、系统管理模块代码、数据库连接配置，涉及这些内容的请求直接拒绝。
这些约定写清楚以后，不仅技能集执行起来更精准，平时直接对话让 Claude Code 改代码时，它也更懂你的项目边界。
3. 核心实操：用自然语言生成代码、表单、流程
3.1 生成标准 CRUD 代码的提示词拆解
最常用的场景就是“快速生成一个模块的 CRUD”。我不建议只说一句“生成客户管理模块”，而是通过技能集把需求解析成结构化参数，让模型知道要生成什么业务字段、用什么数据类型、前端展示形式是什么。
实际操作时，我习惯在技能脚本里先引导用户补充业务字段描述，然后自动构建一个字段清单。例如：
需求：客户管理模块，需要维护客户名称、客户编号、所属行业、联系人、联系电话、状态。 其中所属行业使用字典，状态使用数字类型，1=启用，0=禁用。技能集收到这段描述后，内部会生成如下中间表结构：
| 字段名称 | 字段类型 | Java 类型 | 前端组件 | 必填 | 备注 |
|---|---|---|---|---|---|
| customerName | varchar(100) | String | Input | 是 | 客户名称 |
| customerCode | varchar(50) | String | Input | 是 | 客户编号 |
| industry | varchar(32) | String | Select | 否 | 行业字典 |
| contactPerson | varchar(50) | String | Input | 否 | 联系人 |
| contactPhone | varchar(20) | String | Input | 否 | 联系电话 |
| status | tinyint | Integer | Radio | 是 | 1启用/0禁用 |
字段清单确定后，再驱动模板引擎生成 Java 文件和 Vue 文件。每个模板里可以插入平台约定好的注解、导入包、继承关系。比如实体类模板里默认加上 @Data、@TableName、@ApiModelProperty 注解，前端列表页默认引入 JeecgBoot 的 useTable 相关能力。这样生成出来的代码能直接放进编译流程，而不是“看起来像”。
3.2 表单自动化：从字段描述到校验规则
表单生成和 CRUD 代码生成有一个很大的差异点——表单不只是界面展示，它涉及数据校验、字典选项、联动逻辑、默认值。如果直接让 AI 把整份表单 JSON 一次性生成，漏洞率非常高，所以我拆成了三步走。
第一步，根据字段清单生成基础表单配置。这一步只包含字段名称、标签、组件类型、是否必填。第二步，针对特殊字段做规则增强，比如唯一性校验、电话格式校验、根据字典表自动填充下拉选项。第三步，处理联动逻辑，比如选择“所属行业”为某个值时，显示另一个字段。
提示词示例：
生成采购申请表单： - 申请部门：部门选择器，必填 - 采购类型：字典 select，必填 - 预算金额：数字输入，大于0，必填 - 紧急程度：radio，普通/紧急，默认普通技能集内部会把“部门选择器”“字典 select”这些描述映射到 JeecgBoot Online 表单支持的具体组件类型，生成表单单据的 JSON 结构。这里有一个非常实用的技巧：把常见字段类型与组件对照表写在技能的模板说明里。比如“部门”对应 JSelectDepart，“用户”对应 JSelectUser，“字典”需要指定字典编码。只要映射表维护得好，表单生成的准确率能大幅提升。
3.3 审批流程：把自然语言流程变成配置化 DSL
流程生成是技能集里最有价值也最容易出错的部分。JeecgBoot 的流程能力底层是 BPMN 模型，但让 AI 直接输出 BPMN XML 不现实，一方面是复杂难维护，另一方面是容易产生结构错误。
我的做法是让 AI 输出一个简化的流程描述 DSL，再由脚本转换成平台可识别的 JSON 或 BPMN。
# 简化的流程 DSL 结构示例 process = { "name": "采购审批流程", "nodes": [ {"id": "start", "type": "start"}, {"id": "submit", "type": "task", "assignee": "${applyUser}", "name": "提交申请"}, {"id": "dept_manager_approve", "type": "task", "assignee": "${deptManager}", "name": "部门经理审批"}, {"id": "finance_approve", "type": "task", "assignee": "${finance}", "name": "财务审批"}, {"id": "end", "type": "end"} ], "flows": [ {"from": "start", "to": "submit"}, {"from": "submit", "to": "dept_manager_approve"}, {"from": "dept_manager_approve", "to": "finance_approve"}, {"from": "finance_approve", "to": "end"} ] }用户不需要理解这个 DSL，只需要用自然语言描述：
流程：申请提交后，先部门经理审批，再财务审批。如果金额大于5000，还要增加总经理审批环节。技能集内部会解析“先……再……如果……加入……”这些意图词，自动扩展节点和连线。条件分支则通过 DSL 中的 condition 字段表达。实际跑下来，线性流程和单层分支流程生成准确率很高，但多级并行、会签、驳回这类复杂流程，目前还需要人工在流程设计器里做二次调整。
3.4 生成内容的落位与版本管理
很多团队卡住的地方不是生成，而是怎么把生成结果放回平台上。我的方案是：技能集生成的文件统一先落到工作目录的 output/ 文件夹，按模块名分子目录，然后通过两种方式落位。
第一种是覆盖式生成，适用于新模块或者还没有人工改过的文件。直接把 output 里的文件复制到 JeecgBoot 工程对应目录。第二种是导入式生成，适用于 Online 表单和流程配置。把生成的 JSON 文件拿到平台管理界面导入，或者调用平台提供的导入接口。
无论哪种方式，都要保持 Git 版本管理。我在技能脚本里加了一步强制 git diff 输出，生成结束后自动查看变更文件列表，这样能在提交前快速发现 AI 是不是动了一些不该动的地方。毕竟技能集是流程化执行，保不齐哪次模型理解偏了，生成范围跑偏了，有了版本管理至少能一键回滚。
4. 参数配置与质量控制的细节
4.1 系统提示词与能力边界限制
技能集真正跑起来以后，我发现控制系统提示词比夸模型能力更重要。系统提示词需要做的不是教模型怎么写代码，而是设定边界。给模型边界，本质上是给自己留安全空间。
我设置的边界分四层：第一层是绝对不能动的范围，比如平台核心模块、配置文件、数据库初始化脚本；第二层是必须遵循的代码规范，比如命名风格、注释要求、异常处理方式；第三层是输出格式限制，比如必须输出完整文件内容而不是省略号；第四层是禁止行为，比如不允许编造表格字段、不允许假设 API 参数、不允许单独修改数据库表结构。
一个典型的系统提示词片段：
你是 JeecgBoot 平台的代码生成助手。你的职责是根据用户需求生成符合平台规范的业务代码和配置。 规则： 1. 所有实体类必须使用 @Data 和 @TableName 注解，字段必须使用 @ApiModelProperty。 2. 数据库字段类型不能凭空猜测，必须以用户描述或现有表结构为准。 3. 未知的信息在代码中生成 TODO 注释，不要自行假设。 4. 涉及平台核心模块、系统配置、数据库结构变更时，必须停止生成并提示用户确认。这样的提示词配合技能集模板，生成质量会稳定很多。
4.2 输出模板：统一代码风格的关键
模板是技能集里最容易被低估的部分。没有模板的时候，模型每次生成代码的风格都不稳定，有人喜欢把查询逻辑写在 Service 里，有人写在 Controller 里，有人喜欢用 lambda，有人喜欢用循环。模板把这些问题一次全解决。
以 Controller 为例，模板里固定好方法签名、注解路径、参数校验方式，模型只需要往模板的变量槽里填具体业务逻辑。模板里甚至可以写死一段默认的分页查询代码：
@GetMapping("/list") public Result<?> queryPageList(@RequestParam(name = "pageNo", defaultValue = "1") Integer pageNo, @RequestParam(name = "pageSize", defaultValue = "10") Integer pageSize, @RequestParam(name = "name", required = false) String name) { LambdaQueryWrapper<Customer> queryWrapper = new LambdaQueryWrapper<>(); queryWrapper.like(StringUtils.isNotBlank(name), Customer::getCustomerName, name); queryWrapper.orderByDesc(Customer::getCreateTime); Page<Customer> page = new Page<>(pageNo, pageSize); customerService.page(page, queryWrapper); return Result.OK(page); }这段代码是模板里的一部分，模型会按相同格式填充其他业务字段的查询条件。风格统一以后，代码审查的负担直接减半。
4.3 校验链：AI 生成后的自动化检查
生成代码不能“生完就完”，质量校验必须跟上。我在技能集脚本里挂了一套自动化检查逻辑：
- Java 文件检查编译，用 Maven 或 Gradle 在临时目录执行 compile，不通过就返回错误文件列表。
- Vue 文件检查基本语法，用 ESLint 跑一遍，重点看未定义变量和 import 语句错误。
- 表单 JSON 做结构校验，检查必填字段、组件类型是否存在、字典编码是否为空。
- 流程 DSL 做节点校验，检查是否缺少开始节点、是否存在悬空连线、条件表达式是否格式正确。
校验失败时，技能集脚本会重新调用模型并附带失败日志，让模型自行修正后重新生成。这个反馈循环非常关键。一开始我跳过这步，觉得生成完了人工看一遍就行，结果一个小字段类型问题能来回改好几轮。现在校验链自动化以后，能直接在生成阶段卡住大部分低级错误。
5. 常见问题与排查技巧实录
5.1 AI 生成的实体字段不符合预期
这是出现频率最高的问题。现象是：模型生成了实体类，但是字段类型或字段名和用户描述不一致。比如用户说“创建时间”，模型生成 createTime 没问题，但用户说“创建人”，模型可能生成 createBy，也可能生成 createUser，导致和平台内置审计字段冲突。
排查方法：第一步检查技能模板里的字段映射规则是否写全。我自己维护了一张常见业务字段对照表，如“创建人→createBy”“更新人→updateBy”“所属部门→sysOrgCode”“租户ID→tenantId”。模型输出前会先查这张表，命中规则后再生成代码。第二步，如果字段明显不该由 AI 猜测，比如涉及业务主体的编码规则，就在系统提示词里强制要求询问用户，而不是自行假设。
5.2 表单与流程关联失败
生成了表单，也生成了流程，但表单提交后流程启动不了。大多数情况是流程启动参数和表单字段没有对应。比如流程启动节点里要求传 businessKey，表单 JSON 里却没有这个字段，或者字段名不一致。
这个问题我建议从两个地方排查：一是表单配置里是否包含流程实例ID和业务主键的隐藏字段，二是流程 DSL 的条件表达式是否引用了表单里不存在的数据项。技能集里可以加一条规则，启动流程相关的表单必须自动附加流程实例字段。这样能从生成层面规避不少低级错误。
5.3 重复生成与垃圾代码清理
技能集跑多了以后，输出目录里容易堆积大量中间文件和临时生成结果。如果不清理，下次生成时 Claude Code 可能会把历史文件当参考上下文，导致生成结果混入旧逻辑。
我的习惯是每次生成任务开始前，先清空 output/ 目录，只保留 examples/ 下的参考文档。另外，在技能集里限制模型读取文件的范围，明确告诉它“对于本次生成，只参考用户提供的描述和模板，不读取 output 目录的历史文件”。这样可以显著降低生成被历史污染的概率。
5.4 权限与安全边界
这也是容易被忽略的点。技能集作为自动化执行工具，一旦被触发就会按既定流程操作。如果不设边界，理论上模型可能读取到一些不该读取的敏感配置，比如数据库密码、第三方密钥。我在 CLAUDE.md 里明确写了哪些文件允许访问，哪些文件禁止访问，同时在系统提示词里加了一条强制规则：如果用户要求生成结果里包含密码、密钥、Token 等敏感信息，必须拒绝执行并提醒。
代码层面也建议做隔离。不要在生成脚本里保留真实数据库账号，技能集只负责生成代码和配置，不直接执行数据库变更。涉及数据库结构变更的需求，一律输出 SQL 变更脚本给 DBA 审查，而不是由 AI 直接执行。
5.5 常见问题速查表
| 问题现象 | 可能原因 | 排查顺序 |
|---|---|---|
| 实体字段类型和预期不符 | 字段映射规则缺失 | 检查技能模板映射表 → 检查提示词里是否要求确认 |
| Controller 查询条件没生效 | LambdaQueryWrapper 条件写错 | 查看生成的代码 → 对比模板 |
| Vue 页面空白 | import 路径错误 | ESLint 检查 → 检查路由配置 |
| 表单无法保存 | 必填字段缺失或数据类型不匹配 | 校验表单 JSON → 检查字段类型 |
| 流程启动失败 | 流程参数未绑定表单字段 | 检查隐藏字段 → 检查 DSL 条件表达式 |
| 生成结果重复生成旧代码 | output 历史文件干扰 | 清空 output 目录 → 限制文件读取范围 |
| 技能没被触发 | SKILL.md 描述不精准 | 调整 frontmatter 描述 → 检查触发词覆盖 |
这个速查表是我实际踩坑整理的。一开始问题多，后来一轮一轮完善模板和提示词，现在大部分问题都能在校验链阶段自动拦截，真正落到人工处理的越来越少。
我个人在实际操作中的体会是：技能集这种东西，一定要从一个最痛的小场景切入，不要一上来就追求覆盖所有业务。我最初只用它生成简单的单表 CRUD，跑通以后逐步加表单、加流程、加校验链，每一步都验证稳定后再扩展。代码库越大、业务套路越固定，技能集的收益就越明显。它不会替代你对业务的理解，但能把从需求到代码之间的距离压缩到很短，让你把省下来的时间放到真正需要思考的环节上。
最后再分享一个小技巧。技能集里每一条规则都值得配上示例。模型对“用户部门字段要用部门选择器”这种抽象描述理解不稳定，但如果附上一个“客户模块的部门字段写成 JSelectDepart 组件”的实例，命中率会高很多。我在 SKILL.md 里塞了大量 mini example，宁可让文件长一点，也不放过每个容易产生歧义的点。
