Qoder 从入门到精通
大规模工程 Harness 实践

技能沉淀——将最佳实践封装为可复用 Skill ​

从"一次写对"到"每次都写对" ​

在 Growth 产品线的日常开发中，我们经常需要重复做某些标准化的工程操作：

  • 新建一个 C# 模块（项目 + 接口层 + 实现层 + DI 注册）
  • 执行代码审查（Checklist + 逐文件检查 + 生成报告）
  • 运行全量测试（构建 → 测试 → 报告）

每次手动做一遍既慢又不一致。Skill 的核心价值就是把"这次做对了"变成"每次都做对了"。

案例：create-csharp-module 技能包 ​

这是 Growth 中最常用的 Skill 之一。它把一个标准化流程封装成了可执行的步骤：

yaml
name: create-csharp-module
description: 按 Growth 标准结构创建 C# 模块

steps:
  - 创建项目目录结构（src/、interfaces/、tests/）
  - 生成 .csproj 文件（引用公共包）
  - 创建接口层（I{Module}Service）
  - 创建实现层（{Module}Service）
  - 在 DI 模块中注册服务
  - 创建单元测试模板

使用前：每次新建模块需要 15-20 分钟，且不同人建的模块结构不一致。

使用后：AI 按 Skill 执行，3 分钟完成，结构完全统一。

案例：账务系统的"记账规则"Skill ​

Skill 不仅适用于工程操作，也适用于业务逻辑。随着系统越做越大，你会发现某些业务规则反复出现，每次都要手动处理，而且一旦记错就出问题。

例如在一个交易平台中，经过多次迭代后沉淀了一套账务系统，涉及多种账户类型（现金、奖金、红包、押金等），每种账户都有固定的记账规则：

  • 什么场景记借、什么场景记贷
  • 哪些账户需要同时记账（复式记账）
  • 对账不平怎么处理
  • 冲正/退款时的反向记账规则

这些规则业务人员用文档写，但开发每次都得重新理解一遍。封装成 Skill 后：

yaml
name: apply-accounting-rules
description: 按账务系统规则处理记账请求

required_context:
  - 交易类型（充值/消费/退款/提现）
  - 账户类型（现金/奖金/红包）
  - 金额

steps:
  - 根据交易类型确定记账方向（借/贷）
  - 确定涉及的账户（主账户 + 关联账户）
  - 执行复式记账（确保借贷平衡）
  - 写交易流水
  - 如果是对账场景，执行对账逻辑

使用前：每次新业务接入账务系统，开发都要对着文档翻半天记账规则，经常漏记或记反。

使用后：AI 按 Skill 执行记账逻辑，规则统一、不出错。

这个案例说明：业务知识同样可以封装为 Skill。Skill 不只是技术流程的自动化，更是业务经验的固化。

延伸：账务排错——把"查账"也变成 Skill ​

账务系统不像普通功能，出了问题你没法"重启试试"。余额对不上、流水缺失、冻结金额异常……每次查账都像破案：翻数据库、拼 SQL、手动对比数据，搞半天还不一定找到根因。

查账虽然每次场景不同，但查账的方法论是固定的。我们可以把查账流程封装成 Skill，让 AI 根据具体场景自动编写 Python 脚本去排查：

yaml
name: audit-accounting
description: 排查账务异常，自动编写 Python 脚本连接数据库进行数据对账

required_context:
  - 异常现象描述（如"用户余额对不上"、"冻结金额异常"）
  - 涉及的用户 ID 或时间范围
  - 数据库连接信息（只读库地址、库名、账号）

steps:
  - 分析异常现象，确定需要查询哪些数据表
  - 编写 Python 脚本，连接只读数据库
  - 读取相关表数据（交易主表、交易流水、各账户表）
  - 执行数据对比逻辑（余额 vs 流水汇总、冻结 vs 解冻）
  - 输出对比结果，标注差异
  - 生成排查报告，定位异常根因

实际使用时，你只需要说一句话：

"审计一下用户 1534 的账户余额，看看跟交易流水对不对得上。"

Skill 里已经预置好了 Python 审计脚本（数据库连接、SQL 查询、对比逻辑都是写好的），AI 只需要把用户 ID 和时间范围填进去执行：

  1. 连接只读数据库，从 mi_cash_account 读取该用户当前余额
  2. 从 mi_trans + mi_trans_flow 汇总该用户的全部交易流水
  3. 执行余额等式校验：余额 = 充值 - 消费 - 提现 + 退款？
  4. 如果对不上，逐笔定位差异，输出排查报告

这些步骤不是 AI 现场编的，Skill 里已经写好了——换个用户 ID 就能再跑一次。

更关键的是：如果发现新的异常类型，直接把排查方式追加到 Skill 里。下次遇到同样的问题，AI 直接就有现成的排查路径。Skill 越用越"聪明"。

有了这个 Skill 之后，你再也不用担心账务系统出问题——查账变成了发号施令，而不是翻数据库。

什么场景适合封装 Skill ​

不是所有操作都值得封装成 Skill。判断标准：

适合封装不适合封装
多步骤流程（3 步以上）一句话能说清的操作
有明确的输入/输出依赖大量手动判断
执行步骤顺序固定每次执行方式都不一样
在项目中反复出现一年做不超过 3 次

编写 Skill 的标准结构 ​

name: 简洁的动词短语（如 create-module）
description: 一句话说明什么场景下触发

# 上下文要求（可选）
required_context:
  - 目标模块名称
  - 所属产品线

# 执行步骤
steps:
  - step 1: 描述做什么
  - step 2: 描述做什么
  ...

# 输出产物（可选）
output:
  - 生成的文件夹路径
  - 创建的接口文件

最常用的 Skill 模式：Java CRUD 全家桶 ​

在 Java 后端开发中，80% 的工作是 CRUD。给一张新表，要创建一堆文件：domain 实体、Mapper 接口、Mapper XML、Service 接口、ServiceImpl、Controller……每一层的目录结构、命名规则、代码风格都得一致。

这就是 Skill 最擅长的事。以下是两个最常用的 Java Skill：

create-mybatis：从表结构到持久层 ​

根据数据库表结构，自动生成 domain 实体类和 Mapper 层。说白了就是把"表名 → 类名、字段 → 属性、CRUD SQL 模板"这套映射规则固定下来。

yaml
name: create-mybatis
description: 根据数据库表结构创建 Mapper 层全套代码

required_context:
  - 表名
  - 模块名
  - 表字段列表（字段名、类型、注释）

steps:
  - 创建 domain 包，按表名生成实体类（驼峰命名、@TableName 注解）
  - 创建 mapper 包，生成 Mapper 接口（继承 BaseMapper 或手写）
  - 在 resources/mapper 下创建 Mapper XML（基础 CRUD + 自定义查询）
  - 如果使用 MyBatis-Plus，按项目规范选择性启用分页、逻辑删除
  - 生成的代码包含统一字段：id、create_by、create_time、update_by、update_time

create-api：从 domain 到完整接口 ​

拿到 domain 后，生成一整套 Controller / Service 代码，包括增删改查、分页、导出等标准接口。本质是把每张表的接口结构"框架化"。

yaml
name: create-api
description: 为一张表创建 Controller → Service → ServiceImpl 全套 CRUD 接口

required_context:
  - domain 类名
  - 模块路由前缀
  - 主键类型

steps:
  - 创建 Service 接口（I{Entity}Service），定义 CRUD 方法签名
  - 创建 ServiceImpl，实现基础 CRUD + 分页查询
  - 创建 Controller，统一加 @RestController 和 @RequestMapping
  - 标准接口：分页列表、详情、新增、修改、删除
  - 集成 Swagger 注解（@Api、@ApiOperation）
  - 统一返回格式包装（ResponseWrapper）

使用效果：

手工做用 Skill
一张新表的完整 CRUD30-60 分钟5-10 分钟
目录/命名一致性靠 Code Review 保证一次定好，永不跑偏
新人上手先看一遍现有代码模仿AI 按 Skill 直接出，学 Skill 即可

如何生成 Skill：让 AI 帮你总结 ​

你不需要从零手写 Skill 文件。最简单的方式就是告诉 AI：

帮我分析当前项目的 MyBatis 目录结构，分析新建一张表需要生成哪些文件，然后生成一个 Skill，名字叫 create-mybatis。

AI 会扫描你项目的已有代码，自动总结出：

  • 目录放哪（domain / mapper / service / controller 分别在哪个包下）
  • 命名规则（表名转类名的规则、字段转属性的规则）
  • 代码模板（Mapper XML 的命名空间、resultMap 的写法）
  • 框架依赖（用了 MyBatis-Plus 还是手写 Mapper、有没有统一基类）

你把 AI 生成的 Skill 文件存到 .qoder/skills/ 目录下，以后每次新建表时，直接说"用 create-mybatis 生成用户表"就行。这就是从代码中总结规范，再让 AI 按规范执行的闭环。