![image.png](https://developer.qcloudimg.com/http-save/yehe-9261324/a95adafc096beb1319dfa2d91fcb7473.png)


>工欲善其事，必先利其器。——《论语·卫灵公》


## 一、冷汗直冒的下午

![image.png](https://developer.qcloudimg.com/http-save/yehe-9261324/c2746a51ed4a8fa9d4292359248350f7.png)

老李，10年架构师，手上带着三个项目组，加一起二十多号工程师。

那天下午 Code Review，他打开小王提交的 PR，一个"用户登录"接口，Claude Code 十分钟生成，三百行。

Controller 里查数据库。`UserBo` 直接放进了响应 `Res`。

`OrderStatusEnum` 堂而皇之挂在 `LoginReq` 的字段上。

`App` 里嵌了四层私有方法，进去就出不来。

老李叹了口气。代码没有错——逻辑是通的，功能是好的。

**但这不是他们团队的代码。**

更让他心沉的不是小王这一个人。是另外两个项目组，同样在用 Claude Code，同样在以各自不同的"随机风格"生成代码。

**AI 的速度，在放大每个人的不同习惯，把团队风格炸得七零八落。**

这不是工具问题。这是**经验没有被固化**的问题。


----

## 二、为什么有规范还是没用？


>善弈者谋势，不善弈者谋子。——《弈理》


老李在职场做了这么多年，见过太多这样的循环：

**第一步**：老李写了一份 Wiki 规范文档，洋洋洒洒八千字。
**第二步**：新人入职，导师 发链接，"这是我们的规范，请阅读"。
**第三步**：新人读了，觉得明白了，然后写出来的代码还是老样子。
**第四步**：Code Review 打回，新人改，老李解释，来回三轮。
**第五步**：两周后，老李发现另一个老员工也没遵守规范。
**第六步**：规范文档更新了，但没人知道更新了。

**Wiki 传递不了判断力，只传递文字。** 

而 AI IDE 时代，这个问题被放大了十倍——AI 不读 Wiki，AI 只看它能访问的上下文。

**你不给 AI 规范，AI 就按"互联网平均水平"生成代码。** 

而互联网平均水平，就是你最不想要的那种代码。

企业软件系统三大痛点，AI 时代一条都没解决，反而加速了：


|痛点|AI时代的放大效应|
|:-:|:-:|
|Controller 变垃圾桶|AI 默认把所有逻辑堆在最上层，一次生成，全员复制|
|入参出参边界模糊|AI 不知道 BO 不能出现在 Res，直接透传|
|业务流程不可读|AI 没有"两层限制"概念，嵌套到第五层毫不手软|


----

## 三、分层规范全景图


>不谋全局者，不足谋一域。——《寤言二迁都建藩议》


老李把团队多年沉淀的规范，整理成了一张清晰的架构图（见上图），核心要点如下：

**接口触发层同级**：`controller`（HTTP接口）、`job`（定时任务）、`listener`（MQ/Redis消息）三者平级，都是"触发入口"，不是谁管谁的关系。

**para 的边界**：


- `XReq` / `XRes`：**只能**在接口触发层使用，禁止出现在 App 层及以下

- `XBo` / `XEnum`：可以在应用层和业务层流转，**禁止**暴露到接口层


**service 可以调用 manager**：

`service` 是本模块的业务能力，`manager` 是跨模块的复用能力，

service 可以调用 manager，但 manager 不依赖具体 service。


----

## 四、金字塔模型：App 层的灵魂


>治大国，若烹小鲜。——《道德经》


这是老李最看重的规范，也是最被 AI 破坏的规范。

业界最佳实践（Clean Architecture + DDD Application Layer）对应用层的共识是：**一个 Use Case = 一个 Application Service，对外只暴露一个执行入口，内部用语义化私有方法描述业务步骤。**

老李把它具体化成"金字塔双层"：

**以电商"用户下单"为例：**

```java
OrderApp.exe(PlaceOrderReq req)
│
├─ 第一层（业务流程，一眼看懂做了什么）
│   ├─ validateStock(req)          校验库存
│   ├─ calculatePrice(req, items)  计算价格（含优惠券）
│   ├─ createOrder(req, price)     创建订单
│   ├─ deductStock(items)          扣减库存
│   └─ sendOrderNotice(order)      发送通知
│
└─ 第二层（每个步骤的细节实现）
    ├─ validateStock 内部：查缓存→查DB→比较库存数
    ├─ calculatePrice 内部：查商品价→应用优惠规则→汇总
    └─ ...（每个方法独立实现，不再有第三层调用链）
```

**为什么这么设计？**

读 `exe()` 就像读一份业务说明书：
校验库存 → 算价格 → 建订单 → 扣库存 → 发通知。
不用进每个方法，业务全程一览无余。

这不只是为了人阅读——**这也是 AI 最喜欢的结构**。

扁平、语义化、两层到头，AI 生成后续代码时不会迷失在调用链里。


----

## 五、把规范变成 Skill的步骤


>授人以鱼，不如授人以渔。——《淮南子》


老李做了一件事，把规范"装"进了 AI 的大脑——写成了 `SKILL.md`。

**Skill 是什么？** 一个带有 YAML 元数据头的 Markdown 文件，放在 AI IDE 能自动发现的位置。AI 在接到相关任务时，自动加载并遵循其中的规范。

这不是 prompt，是**持久化的规范记忆**。

### 步骤一：创建 SKILL.md


```
java-layered-arch/
├── SKILL.md          ← 核心规范文件
└── references/
    └── examples.md   ← 可选：代码示例（避免 SKILL.md 过长）
```
`SKILL.md` 结构（基于官方规范）：

```
---
name: java-layered-arch
description: >
  Java企业分层架构代码生成规范。当用户要求生成Java接口、
  Controller/App/Service/Mapper代码时触发。
  触发词：生成Java代码、写接口、按分层规范、写Controller、
  写Service、写Mapper、接口入参出参、BO对象、枚举定义。
---

# Java 分层规范
[规范内容...]
```
>**关键**：`description` 字段最多200字，必须包含触发词，AI 靠它决定何时加载此 Skill。


### 步骤二：在 Claude Code 中安装

![image.png](https://developer.qcloudimg.com/http-save/yehe-9261324/412524c9d46331d16c82feee5a69321e.png)

```shell
# ① 项目级安装（推荐，随Git版本管理）
cd your-project-root
mkdir -p .claude/skills/java-layered-arch
# 将 SKILL.md 放入该目录
cp /path/to/java-layered-arch/SKILL.md .claude/skills/java-layered-arch/

# ② 提交到 Git（团队所有成员克隆后自动生效）
git add .claude/skills/
git commit -m "feat: add java-layered-arch skill for AI code generation"
git push

# ③ 启动 Claude Code
claude  # 在项目目录下启动

# ④ 验证 Skill 已加载
# 在 Claude Code 会话中输入：
/skills
# 应看到 java-layered-arch 出现在列表中

# ⑤ 使用（自动触发 或 显式调用）
# 自动触发：直接描述需求
# "按分层规范，生成用户登录接口的完整代码，模块名 user，表名 t_user"

# 显式调用：
# $java-layered-arch 生成订单创建接口
```

>注意：Skill 文件的实时变更检测已支持，编辑 SKILL.md 后无需重启 Claude Code 即可生效。


### 步骤三：在 Codex 中安装使用


Codex 从 `.agents/skills` 目录（从当前工作目录向上扫描到仓库根）加载 Skill，同时支持全局个人 Skill：

```shell 
# ① 项目级（团队共享，推荐）
mkdir -p .agents/skills/java-layered-arch
cp SKILL.md .agents/skills/java-layered-arch/
git add .agents/ && git commit -m "add codex skill"

# ② 个人全局级（跨项目）
mkdir -p $HOME/.agents/skills/java-layered-arch
cp SKILL.md $HOME/.agents/skills/java-layered-arch/

# ③ 补充 AGENTS.md（项目级规范文件，Codex 自动读取）
cat >> AGENTS.md << 'EOF'
## 代码规范
遵循 java-layered-arch Skill 的分层规范。
生成 Java 代码时，必须按 controller/app/service/mapper 分层。
EOF

# ④ 启动 Codex 并验证
codex
# 会话中输入：
/skills  # 确认列表中有 java-layered-arch

# ⑤ 使用
# 自动触发（描述任务）或显式调用：
# $java-layered-arch 生成商品查询接口
```

>Codex 的 personal skills 存储在 `$HOME/.agents/skills`，团队共享 skills 可以检入 `.agents/skills` 仓库目录，特别有助于新成员 onboarding。


### 步骤四：团队提示词模板（可直接用）


配合 Skill 使用的**标准任务描述模板**：

```
按 java-layered-arch 规范，生成以下功能的完整分层代码：

功能：[如：用户下单]
模块：[如：order]
数据表：[如：t_order，字段：id, user_id, total_amount, status, created_at]
业务规则：
  - [规则1，如：校验商品库存，不足则抛出业务异常]
  - [规则2，如：优惠券抵扣后计算实付金额]

需要生成的文件：
- para/request/PlaceOrderReq.java
- para/response/PlaceOrderRes.java
- para/bo/OrderBo.java
- controller/OrderController.java
- app/PlaceOrderApp.java
- service/OrderService.java
- service/StockService.java
- mapper/OrderMapper.java
- model/OrderModel.java
```
### Skill 步骤小结


|步骤|操作|验证方式|
|:-:|:-:|:-:|
|写 SKILL.md|规范内容 + 触发词描述|检查 description ≤200字，name唯一|
|Claude Code 安装|放入 `.claude/skills/` 目录|`/skills` 列表中可见|
|Codex 安装|放入 `.agents/skills/` 目录|`/skills` 列表中可见|
|Git 共享|`git commit` 推送|新成员克隆即可用|
|验证效果|生成一个接口，对照检查清单|无层级违规即成功|


----

## 六、三条洞见：从 AI 工具使用者到 AI 超级个体


>君子不器。——《论语·为政》


这是老李想得最深的部分。

**洞见一：规范即资产，沉淀即复利**

传统职场，你的经验只能靠"一对一传授"线性扩散。老李带一个新人，花两周，带十个人，花二十周。Skill 把这件事变成指数扩散：一次把规范写进 SKILL.md，注入 AI，所有人所有项目同时继承。**你的经验，第一次可以并行复用。**

**洞见二：金字塔双层是 AI 时代的"可读代码"最低标准**
![image.png](https://developer.qcloudimg.com/http-save/yehe-9261324/420674765fb3f287942cf401163e726c.png)
以前代码只给人读，靠注释凑合。现在代码也给 AI 读，AI 要理解上下文才能生成正确的后续代码。三层以上的嵌套，AI 无法判断下一步方法属于哪层，生成结果随机落层。金字塔双层是**人类可读性和 AI 可理解性的最大公约数**。

**洞见三：AI 超级个体的本质，是把隐性经验显性化的能力**

每一个职场人都有自己的"隐性经验"——那些没写下来但确实影响判断的东西。

**AI 时代最大的职业分化，不是会不会用 AI，而是能不能把自己的隐性经验显性化，装进 AI 的大脑。**
![image.png](https://developer.qcloudimg.com/http-save/yehe-9261324/229ccdc551fbba703767b13b8abb14cc.png)

Lv.1 的人用 AI，每次 prompt 不同，结果随机。

Lv.4 的人有 Skill，AI 永久携带他的经验标准，每次生成都是他审查过的质量。

**这才是 AI 超级个体的真正含义：你的经验，第一次可以不依赖你在场就发挥作用。**


----

## 七、号召：你的职业经验值得被更好地传承


>不积跬步，无以至千里。——《荀子·劝学》


老李做了这件事之后，项目组发生了三个变化：

新人入职第一天，克隆代码，Skill 自动加载，第一个 PR 的分层就是对的。Code Review 的时间从"讲规范"变成了"讲业务"。

老李自己，终于可以把时间花在真正的架构决策上，而不是反复解释"BO 不能放进 Res"。

**现在轮到你了。**

你职业生涯里积累的那些判断——哪些操作是对的，哪些坑绝对不能踩——

它们现在只活在你的脑子里。每次换项目、换团队、来新同事，就要重新传授一遍。

**把它们写进 SKILL.md。一次，永久。**


----

### 行动方法论：30 分钟开始你的第一个 Skill


|时间|行动|
|:-:|:-:|
|前 10 分钟|写下你团队最重要的一条规范，哪怕只有 20 行|
|第 11-20 分钟|创建 `.claude/skills/your-skill/SKILL.md`，填入内容|
|第 21-30 分钟|用 Claude Code 生成一个接口，对照检查，修正 SKILL.md|
|本周内|提交 Git，发给团队，让一个同事跑一遍|
|本月内|迭代 3 次，Skill 趋于稳定，成为团队资产|

>**AI 不是让你失业的工具，是让你的经验第一次摆脱了时间和空间的限制。**


那天下午 Code Review，他打开小王提交的 PR，一个"用户登录"接口，Claude Code 十分钟生成，三百行。

把自己的经验装进 AI 的大脑:自定义skill和团队skill沉淀实战

自定义skill是让你的经验第一次摆脱了时间和空间的限制。

架构师

人工智能

架构设计

职业发展

AI时代如何规范团队代码风格？资深架构师分享分层架构规范实践，通过SKILL.md文件固化经验，实现代码风格统一。从接口触发层到业务层，详解金字塔双层模型设计，让AI生成的代码符合团队标准。掌握将隐性经验显性化的方法，提升团队协作效率，打造AI超级个体。

数据库

Redis

Java

2026采购季 | AI焕新·智启新局

tencentdb-catalog

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

把自己的经验装进 AI 的大脑:自定义skill和团队skill沉淀实战-腾讯云开发者社区-腾讯云

把自己的经验装进 AI 的大脑:自定义skill和团队skill沉淀实战

把自己的经验装进 AI 的大脑:自定义skill和团队skill沉淀实战

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐