用华为云码道 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）：

后端拆成 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 架构总览

1.4 严格 MVC 分层

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

依赖方向严格单向：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 白名单，机器层面拦截，不依赖智能体自觉。

三者关系：

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

以新增一个 HRP 业务功能为例，调用 fullstack-feature Skill 后，CodeArts 按 9 个阶段顺序执行（摘自该 Skill 的 Phase 1-9）：

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

三、16 个自定义 Skill 的设计

3.1 Skill 全览

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 等工具自动格式化代码，保持原有格式

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

示例 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：

# 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	低优问题（代码风格、可读性优化）	可选修复

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

四、14 条 Rule 的设计

4.1 Rule 全览

.codeartsdoer/rules/ 下 14 条 Rule：

4.2 代表性 Rule 示例

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

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

`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 段：

1. 外层 layout-padding 容器
2. 顶部查询表单区域
3. 操作按钮区域
4. 右侧工具栏
5. 数据表格
6. 分页组件
7. 子弹窗组件

且脚本 <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，这是机器层面拦截，不依赖智能体自觉：

{
  "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 实测数据

7.2 三条核心经验

1. Skill 要输出清单，不要输出散文。architecture-governance 输出 P0-P3 断点清单，能派发能验收；如果输出一段读不懂的总结，等于没输出。
2. 生成类 Skill 必须带自检清单。fullstack-feature 的 10 条 MVC 自检 + 5 条契约对齐自检，是它区别于"自由问答"的关键。没有自检的 Skill 就是套了壳的补全。
3. 硬约束用 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 抓不全"，这套思路值得试。