用华为云码道 CodeArts 治理一个 13 模块医院集成平台：架构、开发过程与 16 个自定义 Skill 的设计得失

本文记录我们用一个医院/企业级集成平台（代号 integration-platform）的真实开发过程，沉淀出 16 个项目级 Skill 与 14 条 Rule，并把它交给华为云码道 CodeArts 代码智能体执行的全过程。文中所有 Skill/Rule 示例均摘自项目 .codeartsdoer/ 目录下的真实文件，非示意伪代码。重点讲这套 Skill/Rule 体系设计得怎么样、有什么优缺点，给同样想在存量项目里落地 CodeArts 的团队一个参考。

一、项目架构

integration-platform 是一个面向医院/大型企业的集成平台，工作区下挂两个独立 Git 仓库：后端 platform-java 与前端 platform-ui，各自带自己的 AGENTS.md/CLAUDE.md。

1.1 后端架构

后端基于 PigX 架构二次开发，技术栈与版本（摘自 .codeartsdoer/rules/java-backend.md）：

组件	版本
Java	17
Spring Boot	3.5.9
Spring Cloud	2025.0.1
Spring Cloud Alibaba	2023.0.3.3（Nacos/Sentinel/Seata）
MyBatis-Plus	3.5.x
LangChain4j / Spring AI	1.6.0 / 1.0.2（RAG、向量存储）
Servlet 容器	Undertow

后端拆成 20+ 个 Maven 模块。核心几条线：

基础设施线 ：platform-boot（单体启动器）、platform-gateway（网关）、platform-register（Nacos）、platform-auth（认证）、platform-upms（用户权限）、platform-flow（审批流）
数据线 ：platform-data-etl / data-governance / data-integration / data-quality / data-service------数据集成、治理、质量、服务一条龙
HRP 线 （医院资源规划）：platform-hrp 下 13 个子模块------资产、预算、合同、成本、财务、人事、物资、绩效、招采、招聘、报销、专项
业务线 ：platform-drug（药品）、platform-finance（财务）、platform-order（订单）
AI 线 ：platform-knowledge（AI 知识库，RAG 核心，支持 Qdrant/Milvus/Chroma/PGVector/Neo4j 向量存储）

1.2 前端架构

前端 platform-ui 技术栈（摘自 .codeartsdoer/rules/vue3-frontend.md）：Vue 3 Composition API + <script setup lang="ts"> + Vite + Element Plus + Pinia + Tailwind CSS + DaisyUI + qiankun 微前端，后端控制路由，路径别名 /@ → src/。

前端按 HRP 子模块切了十几个构建环境（.env.production.hrp-asset / hrp-budget / hrp-contract / hrp-cost / hrp-finance / hrp-hr / hrp-material / hrp-performance / hrp-procurement / hrp-recruit / hrp-reimburse / hrp-special），每个子模块可独立出包。

1.3 架构总览

#mermaid-svg-PwlGkkNDZcsA0x8x{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-PwlGkkNDZcsA0x8x .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-PwlGkkNDZcsA0x8x .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-PwlGkkNDZcsA0x8x .error-icon{fill:#552222;}#mermaid-svg-PwlGkkNDZcsA0x8x .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-PwlGkkNDZcsA0x8x .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-PwlGkkNDZcsA0x8x .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-PwlGkkNDZcsA0x8x .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-PwlGkkNDZcsA0x8x .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-PwlGkkNDZcsA0x8x .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-PwlGkkNDZcsA0x8x .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-PwlGkkNDZcsA0x8x .marker{fill:#333333;stroke:#333333;}#mermaid-svg-PwlGkkNDZcsA0x8x .marker.cross{stroke:#333333;}#mermaid-svg-PwlGkkNDZcsA0x8x svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-PwlGkkNDZcsA0x8x p{margin:0;}#mermaid-svg-PwlGkkNDZcsA0x8x .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-PwlGkkNDZcsA0x8x .cluster-label text{fill:#333;}#mermaid-svg-PwlGkkNDZcsA0x8x .cluster-label span{color:#333;}#mermaid-svg-PwlGkkNDZcsA0x8x .cluster-label span p{background-color:transparent;}#mermaid-svg-PwlGkkNDZcsA0x8x .label text,#mermaid-svg-PwlGkkNDZcsA0x8x span{fill:#333;color:#333;}#mermaid-svg-PwlGkkNDZcsA0x8x .node rect,#mermaid-svg-PwlGkkNDZcsA0x8x .node circle,#mermaid-svg-PwlGkkNDZcsA0x8x .node ellipse,#mermaid-svg-PwlGkkNDZcsA0x8x .node polygon,#mermaid-svg-PwlGkkNDZcsA0x8x .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-PwlGkkNDZcsA0x8x .rough-node .label text,#mermaid-svg-PwlGkkNDZcsA0x8x .node .label text,#mermaid-svg-PwlGkkNDZcsA0x8x .image-shape .label,#mermaid-svg-PwlGkkNDZcsA0x8x .icon-shape .label{text-anchor:middle;}#mermaid-svg-PwlGkkNDZcsA0x8x .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-PwlGkkNDZcsA0x8x .rough-node .label,#mermaid-svg-PwlGkkNDZcsA0x8x .node .label,#mermaid-svg-PwlGkkNDZcsA0x8x .image-shape .label,#mermaid-svg-PwlGkkNDZcsA0x8x .icon-shape .label{text-align:center;}#mermaid-svg-PwlGkkNDZcsA0x8x .node.clickable{cursor:pointer;}#mermaid-svg-PwlGkkNDZcsA0x8x .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-PwlGkkNDZcsA0x8x .arrowheadPath{fill:#333333;}#mermaid-svg-PwlGkkNDZcsA0x8x .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-PwlGkkNDZcsA0x8x .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-PwlGkkNDZcsA0x8x .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-PwlGkkNDZcsA0x8x .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-PwlGkkNDZcsA0x8x .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-PwlGkkNDZcsA0x8x .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-PwlGkkNDZcsA0x8x .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-PwlGkkNDZcsA0x8x .cluster text{fill:#333;}#mermaid-svg-PwlGkkNDZcsA0x8x .cluster span{color:#333;}#mermaid-svg-PwlGkkNDZcsA0x8x div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-PwlGkkNDZcsA0x8x .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-PwlGkkNDZcsA0x8x rect.text{fill:none;stroke-width:0;}#mermaid-svg-PwlGkkNDZcsA0x8x .icon-shape,#mermaid-svg-PwlGkkNDZcsA0x8x .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-PwlGkkNDZcsA0x8x .icon-shape p,#mermaid-svg-PwlGkkNDZcsA0x8x .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-PwlGkkNDZcsA0x8x .icon-shape .label rect,#mermaid-svg-PwlGkkNDZcsA0x8x .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-PwlGkkNDZcsA0x8x .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-PwlGkkNDZcsA0x8x .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-PwlGkkNDZcsA0x8x :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 后端模块线
integration-platform 工作区
HTTP
platform-java

Spring Cloud Alibaba

20+ Maven 模块
platform-ui

Vue3 + Vite + TS

qiankun 微前端
基础设施

boot/gateway/register/

auth/upms/flow
数据线

etl/governance/

integration/quality/service
HRP 线

13 子模块

asset...procurement...special
业务线

drug/finance/order
AI 线

platform-knowledge

RAG + 5 种向量库

1.4 严格 MVC 分层

后端最核心的架构约束是严格 MVC 分层 ，这条被写进 java-backend.md Rule 并钉成 P0 阻断级。分层职责矩阵（摘自该 Rule 第 3.1 节）：

层	职责	禁止做的事
Controller	接收请求、调用 Service、返回 `R<T>`	写业务逻辑、直接调 Mapper、try-catch 吞异常
Service	业务逻辑、事务管理、返回业务数据	返回 `R` 对象、处理 HTTP 语义、操作 HttpRequest/Response
Mapper	数据访问（MyBatis-Plus）	写业务逻辑、调 Service、`${}` 拼接 SQL
Entity	数据库映射对象	写业务方法、含 HTTP/响应逻辑

依赖方向严格单向：Controller → Service → Mapper → Entity，反向依赖一律 P0。

二、开发过程：CodeArts + Skill 的工作流

2.1 为什么不裸用 CodeArts

CodeArts 的通用能力（问答、补全、解释）对"写一段新代码"很擅长，但对"按一套企业规范去审查/生成代码"会跑偏------它不知道我们要求 Service 层禁止返回 R<T>、不知道前端列表页必须以 hisYfExpertInfo/index.vue 为模板、不知道审批表必须带 6 个核心审批字段。

裸用智能体写代码，质量取决于 prompt 写得多好，且每次都要重复约束。我们的做法是把团队的工程规范沉淀成 Skill + Rule，让 CodeArts 每次干活都按同一套规矩来，规范从"事后 review"前移到"生成时自带"。

2.2 Skill + Rule 的分工

Rule （14 条，.codeartsdoer/rules/*.md）：静态规范，描述"代码应该长什么样"。Controller 不写业务逻辑、Service 不返回 R、审批表带 6 字段、前端列表页用指定模板......Rule 是"约束"。
Skill （16 个，.codeartsdoer/skills/*/SKILL.md）：动态工序，描述"按什么步骤干活"。审查一个模块、开发一个全栈功能、跑一遍 CI 门禁......Skill 是"流程"。
settings.json ：硬约束，PreToolUse hooks 与 permissions 白名单，机器层面拦截，不依赖智能体自觉。

三者关系：
#mermaid-svg-GRGDALMpqovGhy2l{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-GRGDALMpqovGhy2l .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-GRGDALMpqovGhy2l .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-GRGDALMpqovGhy2l .error-icon{fill:#552222;}#mermaid-svg-GRGDALMpqovGhy2l .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-GRGDALMpqovGhy2l .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-GRGDALMpqovGhy2l .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-GRGDALMpqovGhy2l .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-GRGDALMpqovGhy2l .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-GRGDALMpqovGhy2l .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-GRGDALMpqovGhy2l .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-GRGDALMpqovGhy2l .marker{fill:#333333;stroke:#333333;}#mermaid-svg-GRGDALMpqovGhy2l .marker.cross{stroke:#333333;}#mermaid-svg-GRGDALMpqovGhy2l svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-GRGDALMpqovGhy2l p{margin:0;}#mermaid-svg-GRGDALMpqovGhy2l .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-GRGDALMpqovGhy2l .cluster-label text{fill:#333;}#mermaid-svg-GRGDALMpqovGhy2l .cluster-label span{color:#333;}#mermaid-svg-GRGDALMpqovGhy2l .cluster-label span p{background-color:transparent;}#mermaid-svg-GRGDALMpqovGhy2l .label text,#mermaid-svg-GRGDALMpqovGhy2l span{fill:#333;color:#333;}#mermaid-svg-GRGDALMpqovGhy2l .node rect,#mermaid-svg-GRGDALMpqovGhy2l .node circle,#mermaid-svg-GRGDALMpqovGhy2l .node ellipse,#mermaid-svg-GRGDALMpqovGhy2l .node polygon,#mermaid-svg-GRGDALMpqovGhy2l .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-GRGDALMpqovGhy2l .rough-node .label text,#mermaid-svg-GRGDALMpqovGhy2l .node .label text,#mermaid-svg-GRGDALMpqovGhy2l .image-shape .label,#mermaid-svg-GRGDALMpqovGhy2l .icon-shape .label{text-anchor:middle;}#mermaid-svg-GRGDALMpqovGhy2l .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-GRGDALMpqovGhy2l .rough-node .label,#mermaid-svg-GRGDALMpqovGhy2l .node .label,#mermaid-svg-GRGDALMpqovGhy2l .image-shape .label,#mermaid-svg-GRGDALMpqovGhy2l .icon-shape .label{text-align:center;}#mermaid-svg-GRGDALMpqovGhy2l .node.clickable{cursor:pointer;}#mermaid-svg-GRGDALMpqovGhy2l .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-GRGDALMpqovGhy2l .arrowheadPath{fill:#333333;}#mermaid-svg-GRGDALMpqovGhy2l .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-GRGDALMpqovGhy2l .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-GRGDALMpqovGhy2l .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-GRGDALMpqovGhy2l .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-GRGDALMpqovGhy2l .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-GRGDALMpqovGhy2l .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-GRGDALMpqovGhy2l .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-GRGDALMpqovGhy2l .cluster text{fill:#333;}#mermaid-svg-GRGDALMpqovGhy2l .cluster span{color:#333;}#mermaid-svg-GRGDALMpqovGhy2l div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-GRGDALMpqovGhy2l .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-GRGDALMpqovGhy2l rect.text{fill:none;stroke-width:0;}#mermaid-svg-GRGDALMpqovGhy2l .icon-shape,#mermaid-svg-GRGDALMpqovGhy2l .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-GRGDALMpqovGhy2l .icon-shape p,#mermaid-svg-GRGDALMpqovGhy2l .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-GRGDALMpqovGhy2l .icon-shape .label rect,#mermaid-svg-GRGDALMpqovGhy2l .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-GRGDALMpqovGhy2l .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-GRGDALMpqovGhy2l .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-GRGDALMpqovGhy2l :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 按 Skill 工序

守 Rule 规范

受 settings 约束
14 条 Rule

静态规范

java-backend/database/

vue3-frontend/api-design...
16 个 Skill

动态工序

architecture-governance/

fullstack-feature/cicd-closedloop...
settings.json

硬约束

hooks 拦截 + permissions 白名单
CodeArts 智能体
项目代码
代码变更 + 审查报告 + 契约对齐报告

2.3 一个全栈功能的开发闭环

以新增一个 HRP 业务功能为例，调用 fullstack-feature Skill 后，CodeArts 按 9 个阶段顺序执行（摘自该 Skill 的 Phase 1-9）：
#mermaid-svg-30SXk7sHGPoK5ZAn{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-30SXk7sHGPoK5ZAn .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-30SXk7sHGPoK5ZAn .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-30SXk7sHGPoK5ZAn .error-icon{fill:#552222;}#mermaid-svg-30SXk7sHGPoK5ZAn .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-30SXk7sHGPoK5ZAn .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-30SXk7sHGPoK5ZAn .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-30SXk7sHGPoK5ZAn .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-30SXk7sHGPoK5ZAn .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-30SXk7sHGPoK5ZAn .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-30SXk7sHGPoK5ZAn .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-30SXk7sHGPoK5ZAn .marker{fill:#333333;stroke:#333333;}#mermaid-svg-30SXk7sHGPoK5ZAn .marker.cross{stroke:#333333;}#mermaid-svg-30SXk7sHGPoK5ZAn svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-30SXk7sHGPoK5ZAn p{margin:0;}#mermaid-svg-30SXk7sHGPoK5ZAn .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-30SXk7sHGPoK5ZAn .cluster-label text{fill:#333;}#mermaid-svg-30SXk7sHGPoK5ZAn .cluster-label span{color:#333;}#mermaid-svg-30SXk7sHGPoK5ZAn .cluster-label span p{background-color:transparent;}#mermaid-svg-30SXk7sHGPoK5ZAn .label text,#mermaid-svg-30SXk7sHGPoK5ZAn span{fill:#333;color:#333;}#mermaid-svg-30SXk7sHGPoK5ZAn .node rect,#mermaid-svg-30SXk7sHGPoK5ZAn .node circle,#mermaid-svg-30SXk7sHGPoK5ZAn .node ellipse,#mermaid-svg-30SXk7sHGPoK5ZAn .node polygon,#mermaid-svg-30SXk7sHGPoK5ZAn .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-30SXk7sHGPoK5ZAn .rough-node .label text,#mermaid-svg-30SXk7sHGPoK5ZAn .node .label text,#mermaid-svg-30SXk7sHGPoK5ZAn .image-shape .label,#mermaid-svg-30SXk7sHGPoK5ZAn .icon-shape .label{text-anchor:middle;}#mermaid-svg-30SXk7sHGPoK5ZAn .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-30SXk7sHGPoK5ZAn .rough-node .label,#mermaid-svg-30SXk7sHGPoK5ZAn .node .label,#mermaid-svg-30SXk7sHGPoK5ZAn .image-shape .label,#mermaid-svg-30SXk7sHGPoK5ZAn .icon-shape .label{text-align:center;}#mermaid-svg-30SXk7sHGPoK5ZAn .node.clickable{cursor:pointer;}#mermaid-svg-30SXk7sHGPoK5ZAn .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-30SXk7sHGPoK5ZAn .arrowheadPath{fill:#333333;}#mermaid-svg-30SXk7sHGPoK5ZAn .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-30SXk7sHGPoK5ZAn .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-30SXk7sHGPoK5ZAn .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-30SXk7sHGPoK5ZAn .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-30SXk7sHGPoK5ZAn .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-30SXk7sHGPoK5ZAn .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-30SXk7sHGPoK5ZAn .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-30SXk7sHGPoK5ZAn .cluster text{fill:#333;}#mermaid-svg-30SXk7sHGPoK5ZAn .cluster span{color:#333;}#mermaid-svg-30SXk7sHGPoK5ZAn div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-30SXk7sHGPoK5ZAn .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-30SXk7sHGPoK5ZAn rect.text{fill:none;stroke-width:0;}#mermaid-svg-30SXk7sHGPoK5ZAn .icon-shape,#mermaid-svg-30SXk7sHGPoK5ZAn .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-30SXk7sHGPoK5ZAn .icon-shape p,#mermaid-svg-30SXk7sHGPoK5ZAn .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-30SXk7sHGPoK5ZAn .icon-shape .label rect,#mermaid-svg-30SXk7sHGPoK5ZAn .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-30SXk7sHGPoK5ZAn .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-30SXk7sHGPoK5ZAn .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-30SXk7sHGPoK5ZAn :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} Phase 1

需求分析
Phase 2

数据库设计

up/down 脚本
Phase 3

后端接口

Entity→Mapper→Service→Controller
Phase 4

前端页面

API→类型→页面→权限
Phase 5

后端闭环验证

单测/覆盖率/编译/格式/构建
Phase 6

前端闭环验证

vue-tsc/ESLint/构建
Phase 7

契约对齐

路径/字段/权限码/字典
Phase 8

代码审查

code_review 工具
Phase 9

提交

Conventional Commits

关键在 Phase 7（契约对齐）和 Phase 8（代码审查）：这两步把"前后端字段对不对齐、权限码一不一致、分层有没有越权"从事后人 review 前移到生成时自检。这是 Skill 相比裸用智能体最大的增量价值。

三、16 个自定义 Skill 的设计

3.1 Skill 全览

类别	Skill	职责	触发方式
架构治理	`architecture-governance`	评估模块边界/依赖/分层/技术债，输出 P0-P3 清单	`/architecture-governance scope=module target=...`
全栈开发	`fullstack-feature`	9 阶段端到端开发闭环	`/fullstack-feature name=... module=...`
后端	`backend-integration`	Feign/OAuth2/网关/审批/AI-RAG 集成	`/backend-integration task=approval module=...`
前端	`frontend-dev`	Vue3 页面开发，以指定模板为准	`/frontend-dev ...`
前后端对齐	`frontend-field-alignment`	前端表单字段与后端 Entity 对齐，识别占位	`/frontend-field-alignment module=... entity=...`
代码审查	`code-reviewer`	按 P0-P3 审查 diff，对接 code_review 工具	`/code-reviewer` 或 pre-commit 自动
API 文档	`api-documenter`	生成/校验 API 文档与契约	---
CI/CD	`cicd-closedloop`	CI 门禁→CD 部署→回滚完整闭环	`/cicd-closedloop stage=ci project=fullstack`
DevOps	`devops-deploy`	部署与回滚	---
Maven	`maven-build`	多模块构建优化	---
迁移	`migration-helper`	版本/依赖迁移	---
Mock	`mock-data-generator`	生成业务 Mock 数据	---
性能	`performance-opt`	性能定位与优化	---
安全	`security-audit`	安全审计	---
测试	`test-writer`	单测生成（Service 层覆盖率 ≥80%）	---
排障	`troubleshoot`	故障定位	---

3.2 代表性 Skill 示例

示例 1：architecture-governance（审查类）

摘自 .codeartsdoer/skills/architecture-governance/SKILL.md：

参数

参数必填说明

scope 是评估范围：module / dependency / quality / tech-debt

target 否目标模块或文件路径

输出

问题清单（按优先级：P0 阻断 / P1 高优 / P2 中优 / P3 低优）

改进建议和重构方案

修复优先级排序

禁止自动格式化：不得使用 Prettier、ESLint --fix、Google Java Format 等工具自动格式化代码，保持原有格式

参数	必填	说明
scope	是	评估范围：module / dependency / quality / tech-debt
target	否	目标模块或文件路径

设计要点：输出被钉死成"分级清单"而不是"散文"。清单才能派发成任务、才能排期验收。如果让智能体自由发挥写一段总结，没法落地。

示例 2：fullstack-feature（开发类）的 MVC 自检清单

摘自 .codeartsdoer/skills/fullstack-feature/SKILL.md Phase 3 的自检清单：

Controller 无业务逻辑（无循环校验、无数据转换、无业务判断）

Controller 未直接调 Mapper（通过 Service 访问数据层）

Controller 无 try-catch 吞异常（异常由全局处理器统一处理）

Service 未返回 R<T>（返回业务数据：Entity/DTO/String/Boolean 等）

Service 未处理 HTTP 语义（未设置状态码、未操作 HttpServletResponse）

Mapper SQL 用 #{} 参数绑定，未用 ${} 拼接用户输入

依赖方向单向：Controller→Service→Mapper→Entity，无反向依赖

设计要点：生成代码后强制自检，把"分层越权、返回 R、SQL 注入"这些事后才该发现的坑在生成时就拦掉。

示例 3：cicd-closedloop（CI/CD 类）的契约对齐门禁

摘自 .codeartsdoer/skills/cicd-closedloop/SKILL.md 的契约对齐门禁，用 diff 比对后端 @RequestMapping 与前端 url、后端 @pms.hasPermission 与前端 v-auth、前端 useDict 与后端 dict_type：

bash 复制代码

# API 路径对齐
diff <(grep -rn "@RequestMapping\|@GetMapping\|@PostMapping" platform-java/*/src/main/java/ --include="*.java" | ...) \
     <(grep -rn "url:" platform-ui/src/api/ --include="*.ts" | ...)

# 权限码对齐
diff <(grep -rn "@pms.hasPermission" platform-java/*/src/main/java/ --include="*.java" | ...) \
     <(grep -rn "v-auth=" platform-ui/src/views/ --include="*.vue" | ...)

设计要点：契约对齐用 grep + diff 做硬比对，不靠智能体"理解"，机器比对零误判。

示例 4：code-reviewer（审查类）的 P0-P3 分级

摘自 .codeartsdoer/skills/code-reviewer/SKILL.md：

优先级类别处理方式

P0 阻断性问题（编译错误、安全漏洞、数据丢失风险、租户隔离绕过）必须修复后才能提交

P1 高优问题（逻辑错误、边界遗漏、异常处理缺失、SQL 注入风险）必须修复

P2 中优问题（命名不规范、注释缺失、性能隐患、类型不完整）建议修复

P3 低优问题（代码风格、可读性优化）可选修复

优先级	类别	处理方式
P0	阻断性问题（编译错误、安全漏洞、数据丢失风险、租户隔离绕过）	必须修复后才能提交
P1	高优问题（逻辑错误、边界遗漏、异常处理缺失、SQL 注入风险）	必须修复
P2	中优问题（命名不规范、注释缺失、性能隐患、类型不完整）	建议修复
P3	低优问题（代码风格、可读性优化）	可选修复

且明确要求必须调用 code_review 工具执行自动化审查，"而不是仅凭人工经验审查"。P0/P1 未修复则阻断提交。

四、14 条 Rule 的设计

4.1 Rule 全览

.codeartsdoer/rules/ 下 14 条 Rule：

Rule	约束范围
`java-backend.md`	Java 后端：技术栈、模块组织、MVC 分层、命名、AI/RAG 集成、格式化、检查清单
`vue3-frontend.md`	Vue3 前端：目录结构、页面模板、Hooks、弹窗、路由、Prettier/ESLint
`api-design.md`	API 设计：统一返回 `R<T>`、分页协议、鉴权、参数校验、异常处理、Swagger
`database.md`	数据库：脚本管理、字段变更、逻辑删除、审批字段、HR 人员关联、字典
`contract-alignment.md`	前后端契约对齐
`security.md`	安全规范
`performance.md`	性能规范
`testing.md`	测试规范
`nacos-config.md`	Nacos 配置管理
`cicd-gate.md`	CI/CD 门禁
`deploy-rollback.md`	部署与回滚
`dev-test-loop.md`	开发测试循环
`scheduled-task.md`	定时任务
`api-request.md`	API 请求规范

4.2 代表性 Rule 示例

示例 1：database.md 的审批字段规范

摘自 .codeartsdoer/rules/database.md 第 4 节，所有需审批的业务表必须包含 6 个核心审批字段：

sql 复制代码

`process_instance_id` VARCHAR(50) DEFAULT NULL COMMENT '流程实例ID',
`status` INT NOT NULL DEFAULT 0 COMMENT '流程实例状态（0-进行中，1-已完成，2-已拒绝，3-已取消）',
`finish_reason` VARCHAR(50) DEFAULT NULL COMMENT '流程结束原因',
`task_id` VARCHAR(50) DEFAULT NULL COMMENT '当前/历史任务ID',
`approve_desc` VARCHAR(100) DEFAULT NULL COMMENT '审批人拒绝原因',
`end_time` DATETIME DEFAULT NULL COMMENT '流程在业务系统结束时间',

这条 Rule 让 CodeArts 生成任何审批业务表时自动带齐这 6 个字段，不用每次提醒。HR 模块还有一条额外约束：业务表必须用 person_id 关联 hrp_hr_person 人员表。

示例 2：vue3-frontend.md 的页面模板规范

摘自 .codeartsdoer/rules/vue3-frontend.md 第 3 节，生成 CRUD 列表页必须以 src/views/yf/drug/hisYfExpertInfo/index.vue 为模板，模板结构顺序固定为 7 段：

外层 layout-padding 容器

顶部查询表单区域

操作按钮区域

右侧工具栏

数据表格

分页组件

子弹窗组件

且脚本 <script setup lang="ts"> 的代码分区顺序也固定为 9 段（导入声明→显隐控制→异步组件→字典→ref→响应式数据→表格状态→Hook→方法）。列宽也有量化规则：4 个中文字的列 min-width 设 120px，5 个字 150px，6 个字 180px。

这条 Rule 让 13 个 HRP 子模块的前端列表页长得一模一样，不会每个开发者各写一套 UI。

示例 3：settings.json 的硬约束

摘自 .codeartsdoer/settings.json，这是机器层面拦截，不依赖智能体自觉：

json 复制代码

{
  "hooks": {
    "PreToolUse": {
      ".env*": "block",
      "pnpm-lock.yaml": "block",
      "yarn.lock": "block",
      "platform-java/db/*.sql": "block",
      "platform-java/**/application-prod.yml": "block"
    }
  },
  "permissions": {
    "allow": [
      "Edit", "Write",
      "Bash(pnpm test:*)", "Bash(pnpm lint:*)", "Bash(pnpm build:*)",
      "Bash(mvn compile:*)", "Bash(mvn test:*)", "Bash(mvn clean install:*)",
      "Bash(mvn spring-javaformat:*)", "Bash(mvn jacoco:*)"
    ]
  }
}

PreToolUse hooks 直接拦截 .env、lock 文件、生产配置、db SQL 的编辑------智能体想改也改不了。permissions 白名单只放行构建/测试/格式相关命令，其他 bash 命令需人工授权。

五、Skill 与 Rule 的优点

5.1 规范从"事后 review"前移到"生成时自带"

这是最大收益。以前架构师逐行盯代码，现在 16 个 Skill + 14 条 Rule 把"该怎么写"显性化、可执行化。新人用 CodeArts + 这套 Skill，写出来的代码天然符合规范。

5.2 输出可量化、可派发

审查类 Skill 输出 P0-P3 分级清单，不是"模块有点问题"这种空话。每个断点带编号、级别、必须完善的功能、工作量估算，可以排期、派发、验收。

5.3 契约对齐机器化

cicd-closedloop 的契约对齐门禁用 grep + diff 硬比对前后端 API 路径、权限码、字典项。不靠智能体"理解"，零误判。前后端权限码不一致（差一个 hrp_ 前缀）这种坑，人 review 容易漏，机器比对一抓一个准。

5.4 硬约束兜底

settings.json 的 PreToolUse hooks 在机器层面拦截敏感文件编辑，不依赖智能体自觉。即使智能体"想"改 .env 或生产配置，也被 block。

5.5 一次沉淀，线性复用

16 个 Skill + 14 条 Rule 一次沉淀，后续 13 个 HRP 子模块、数据线、订单线全部复用。项目规模越大，这笔投入的 ROI 越高。

六、Skill 与 Rule 的缺点与局限（重点）

这套体系不是银弹，落地过程中暴露出若干问题，逐一记录。

6.1 Skill 不能自动发现新场景，全靠人工沉淀

16 个 Skill 是我们遇到问题后逐个写的------出了"前端别名占位骗过 review"才写 frontend-field-alignment，出了"前后端权限码不一致"才在 cicd-closedloop 加契约对齐门禁。Skill 永远滞后于问题，没法预判未知的违规模式。新场景出现时，先裸用智能体试，踩坑了再沉淀成 Skill，存在一段"裸奔期"。

6.2 Rule 的正反例维护成本高，容易过时

java-backend.md 里写了大量正反例代码片段（正确：Controller 只做编排；错误：Controller 写业务逻辑）。这些片段绑定具体 API（R<T>、@RequestExcel、PigxException），框架升级时正反例要同步改。Spring Boot 从 3.x 升到 4.x、PigX 改统一返回类，Rule 里的示例就过时了，但不改也不会报错------直到智能体按过时示例生成代码，才在线上炸。Rule 的"腐化"是静默的。

6.3 禁自动格式化是一把双刃剑

每个 Skill/Rule 末尾都钉了"禁止 Prettier/ESLint --fix/Google Java Format 自动格式化，保持原有格式"。初衷是避免 diff 污染（智能体一格式化，改 3 行的 PR 膨胀到 2000 行）。但副作用是：项目里历史遗留的不规范格式永远不会被自动修正 ，代码风格漂移长期存在。我们目前靠定期人工跑一次 mvn spring-javaformat:apply 全量格式化，但这又和"禁自动格式化"矛盾------实际上禁的是"智能体生成时顺手格式化"，不是禁项目级全量格式化。这条 Rule 的表述有歧义，容易误读成"永远不准格式化"。

6.4 契约对齐门禁的 grep 方案对动态路由/动态权限失效

cicd-closedloop 用 grep + diff 比对前后端契约，对静态声明的路由和权限码有效。但项目里有动态路由（后端路由由 API 控制，前端从接口拉）、动态权限（租户隔离的权限码运行时生成），这些 grep 抓不到。门禁通过不代表契约真的对齐，只代表"静态声明的部分对齐"。动态部分仍需运行时验证，但 Skill 里没覆盖。

6.5 Skill 之间有职责重叠

code-reviewer 和 architecture-governance 都做审查，都输出 P0-P3 清单，审查维度有交集（分层违规、SQL 注入两者都查）。fullstack-feature 的 Phase 8 代码审查又会调 code-reviewer。重叠导致结果不一致------两个 Skill 对同一段代码可能给出不同级别判定，没有仲裁机制。用户不知道该信哪个。

6.6 全中文规范，对英文母语/海外协作不友好

14 条 Rule 全用简体中文写，正反例注释也是中文。对国内团队友好，但项目里有英文母语的海外协作方时，他们读 Rule 困难，CodeArts 按中文 Rule 生成代码时，代码注释/异常信息也倾向中文，和英文项目冲突。没有 i18n 方案。

6.7 permissions 白名单粒度粗

settings.json 的 permissions 用 Bash(mvn test:*) 这种通配符白名单。mvn test:* 意味着任何 mvn test 开头的命令都放行，包括 mvn test -Dtest=SomeTest -DfailIfNoTests=false 这种无害的，但也包括拼接了危险参数的。通配符白名单无法区分参数语义。更细的粒度需要写正则或自定义 hook，成本高。

6.8 Skill 依赖 code_review 工具，工具不可用时降级

code-reviewer 明确要求"必须调用 code_review 工具执行自动化审查，而不是仅凭人工经验审查"。但 code_review 工具本身依赖沙箱环境执行。沙箱不可用时（例如我们遇到的 CLI 发行包缺 darwin-x64 toolset zip），Skill 降级成纯文本审查，P0/P1 拦截能力大幅下降。Skill 的有效性依赖底层工具链可用，工具链断了 Skill 就瘸了。

6.9 Skill 的"9 阶段闭环"对小改动过重

fullstack-feature 的 9 阶段闭环（需求→DB→后端→前端→后端验证→前端验证→契约对齐→代码审查→提交）对一个完整新功能很合适，但对"改一个字段名""加一个接口"这种小改动过重------走完 9 阶段比直接改还慢。目前没有"轻量模式"，要么全走，要么裸改（裸改就绕过了所有自检）。缺一个按改动规模自动选择工序的机制。

七、效果与经验

7.1 实测数据

指标	裸用智能体	CodeArts + Skill/Rule
生成代码一次过审率	~60%（分层/返回值/权限码各种小错）	90%+（自检清单生成时拦掉）
前后端契约不一致发现时机	线上 403 时才发现	CI 门禁 grep diff 拦截
敏感文件误改	偶发（智能体改过 `.env`）	0（PreToolUse hook 拦截）
新人产出符合规范	需架构师逐行 review	Skill 自检兜底，review 负担下降
Skill/Rule 维护	---	16+14 个文件，框架升级时需同步

7.2 三条核心经验

Skill 要输出清单，不要输出散文 。architecture-governance 输出 P0-P3 断点清单，能派发能验收；如果输出一段读不懂的总结，等于没输出。
生成类 Skill 必须带自检清单 。fullstack-feature 的 10 条 MVC 自检 + 5 条契约对齐自检，是它区别于"自由问答"的关键。没有自检的 Skill 就是套了壳的补全。
硬约束用 settings.json，软约束用 Rule，流程用 Skill。三层各司其职：settings.json 拦得住的（敏感文件、危险命令）绝不交给 Rule；Rule 描述"应该怎样"；Skill 描述"怎么做到"。别把所有约束都塞进 Skill，Skill 太长智能体会忽略后半段。

7.3 后续改进方向

针对第六节列的缺点，我们计划：① 给 Skill 加"轻量模式"按改动规模选工序；② 契约对齐门禁补充运行时动态路由验证；③ Rule 正反例绑定框架版本，升级时 CI 检查示例可编译；④ 探索 Skill 间审查结果的仲裁机制；⑤ Rule 增加英文版做 i18n。

八、写在最后

这次落地最深的感受：CodeArts + Skill/Rule 的价值不是"写代码快一点"，而是"让工程规范能被机器执行"。16 个 Skill + 14 条 Rule 本质上是把架构师脑子里"该怎么写"的隐性知识显性化、可执行化。

但它不是银弹。Skill 滞后于问题、Rule 会静默腐化、契约门禁对动态场景失效、Skill 间有重叠无仲裁、沙箱断了 Skill 就瘸------这些缺点都是真实的。写出来不是劝退，是给同样想落地的团队一个预期：Skill/Rule 体系需要持续维护，它是一笔随项目演进不断投入的资产，不是一次沉淀一劳永逸的工具。

如果你也在存量项目里挣扎于"规范说不听、review 抓不全"，这套思路值得试。