AI编程实践：规则 + 技能 + 子代理 + 钩子，拆解Trae AI 开发规范的完整落地范式

实践得真知哇

这篇文章是基于我们训练营内部项目总结实践出来的，思考供大家学习参考。

最近有粉丝去面试，被问到如何进行AI编程的，回答的太浅了。

这篇文章看完之后，相信你对AI编程会有一个新的理解。

因为我们训练营内部，绝大多数同学都是基于trae开发的，所以用trae来举例子。

如果你们使用claude、codex开发，需要把这些文件放到.claude中，另外需要做下兼容。

你可以直接和AI提要求，比如：

我要在claude中复用trae的AI编程规范，你帮我出方案和落地，先和我明确方案，我确认之后，你再操作。

想了解更多，欢迎链接我，微信：wangzhongyang1993

正文开始

阅读本文档后，你肯定理解项目规范的运作方式，并知道在什么场景下用什么工具。

一、为什么要做这套规范

痛点

在 AI 辅助开发中，常见以下问题：

分层混乱：AI 不了解项目分层约束，生成的代码经常跨层调用（Handler 直接操作数据库、Service 引入 HTTP 框架）
质量不可控：AI 产出的代码缺乏测试、注释不规范、错误处理缺失，每次都需要人工反复纠正
计划与执行脱节：AI 直接写代码，没有计划评审环节，导致方向性错误发现太晚
上下文污染：大量检索和分析任务在主对话中执行，挤占上下文窗口，降低 AI 对核心任务的注意力
团队规范不统一：不同开发者用 AI 产出的代码风格不一致，难以维护

解决思路

通过 .trae/ 目录下的四类配置，将团队规范固化为 AI 可执行的约束：

配置类型	目录	作用	触发方式
规则文件（Rules）	`.trae/rules/`	编码规范、分层约束	每次对话自动注入 context
技能（Skills）	`.trae/skills/`	标准化流程（生成计划、分层校验）	开发者手动调用 `/命令`
子代理（Subagents）	`.trae/agents/`	独立上下文的质量门禁（计划审核、测试合规）	SOLO Agent 自动匹配调用
钩子（Hooks）	`.trae/hooks.json`	提交前规范提醒	用户发送消息时自动触发

核心原则：让 AI 在正确的时机自动执行正确的流程，而不是依赖人每次提醒。

二、目录结构

shell 复制代码

    .trae/
    ├── README.md                          # 本文档（综合规范介绍）
    ├── hooks.json                         # 钩子配置（提交前提醒）
    │
    ├── rules/                             # 规则文件（每次对话自动加载）
    │   ├── project_rules.md               #   项目总则（技术栈、编码规则、文档约定）
    │   ├── handler.md                     #   Handler 层规则（api/handler/）
    │   ├── service.md                     #   Service 层规则（internal/service/）
    │   ├── repository.md                  #   Repository 层规则（internal/repository/）
    │   ├── domain.md                      #   Domain 层规则（internal/ragplatform/domain/）
    │   ├── milvus.md                      #   Milvus 检索核心规则（internal/milvus/）
    │   ├── rag.md                         #   RAG 编排层规则（internal/rag/）
    │   └── frontend.md                    #   前端规则（admin/src/）
    │
    ├── skills/                            # 技能（开发者手动调用）
    │   ├── gen-plan/                      #   生成标准化开发计划
    │   │   ├── SKILL.md                   #     技能定义和执行流程
    │   │   ├── template.md                #     计划文档模板
    │   │   └── examples/
    │   │       └── example-feature.md     #     完整示例
    │   └── layer-check/                   #   分层依赖校验
    │       ├── SKILL.md                   #     技能定义和执行流程
    │       └── layer_rules.json           #     分层规则配置（层级映射、允许/禁止依赖）
    │
    └── agents/                            # 子代理（SOLO Agent 自动调用）
        ├── plan-review.md                 #   文档计划审核子代理
        └── test-compliance.md             #   测试及合规检测子代理

三、规则文件（Rules）

3.1 作用机制

.trae/rules/ 下的所有 Markdown 文件是 always-applied 的------每次 AI 对话开始时自动加载到 context，全程生效。AI 在编辑代码时会自动遵守对应层的规则。

3.2 规则文件一览

文件	管辖范围	核心约束
project_rules.md	全项目	技术栈、提交规范、文档约定、分层总则、禁止操作
handler.md	`api/handler/`	不碰 DB/Model/Milvus/Config，请求响应隔离，DTO 隔离
service.md	`internal/service/`、`internal/ragplatform/application/`	不碰 HTTP，构造函数注入，事务边界，error wrap
repository.md	`internal/repository/`、`internal/ragplatform/repository/`	不返回 *gorm.DB，不依赖上层
domain.md	`internal/ragplatform/domain/`	零依赖（现阶段宽松，DDD 改造后强制）
milvus.md	`internal/milvus/`	不依赖 API/Service/Repository，策略可插拔
rag.md	`internal/rag/`	编排层，不感知 Web，与 milvus 层区分
frontend.md	`admin/src/`	页面/组件/服务/类型/配置五层分离，禁止组件直接调 fetch

3.3 分层依赖方向

shell 复制代码

                        ┌──────────┐
                        │   cmd    │  程序入口（装配点，可依赖所有内部包）
                        └────┬─────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
        ┌──────────┐  ┌───────────┐  ┌───────────┐
        │ router   │  │ ragrouter │  │  handler  │  HTTP 路由层
        └────┬─────┘  └─────┬─────┘  └─────┬─────┘
              │              │              │
              │              │         ┌────┴─────┐
              │              │         ▼          ▼
              │              │    ┌────────┐ ┌─────────┐
              │              │    │response│ │middleware│
              │              │    └────────┘ └────┬────┘
              │              │                    │
              │              │              ┌─────┴─────┐
              │              │              │   auth    │
              │              │              └─────┬─────┘
              │              │                    │
              │              ▼                    │
              │         ┌──────────┐              │
              └────────►│ service  │◄─────────────┘
                        └────┬─────┘
                             │
              ┌──────────────┼──────────────┐
              ▼              ▼              ▼
        ┌──────────┐  ┌───────────┐  ┌───────────┐
        │repository│  │   model   │  │   rag     │  业务/数据层
        └────┬─────┘  └───────────┘  └─────┬─────┘
             │                             │
             ▼                             ▼
        ┌──────────┐                 ┌───────────┐
        │  model   │                 │  milvus   │  核心/基础层
        └──────────┘                 └───────────┘

核心 BLOCK 规则（违反会被 layer-check 拦截）：

源层	禁止依赖	原因
handler	repository, model, milvus	Handler 不碰 DB，用 DTO 隔离
service	handler, response, milvus	Service 不感知 HTTP，检索通过接口解耦
repository	service, handler, milvus	数据层不反向依赖业务
milvus	handler, service, repository, model	检索核心隔离，不碰 DB

四、技能（Skills）

4.1 作用机制

Skill 是开发者 手动调用 的标准化流程。通过在 AI 对话输入框输入 /技能名 触发。Skill 会按预定义的步骤逐步执行，确保流程不遗漏。

4.2 gen-plan：生成开发计划

属性	值
调用方式	`/gen-plan`
触发时机	开发者口述需求后手动调用
输入	业务需求描述
输出	标准化开发计划文档（保存到 `Docs/`）

执行流程：

理解需求 → 2. 读取项目规范 → 3. 确定分层落点 → 4. 设计接口契约 → 5. 制定测试要求 → 6. 编写验收清单 → 7. 输出文档 → 8. 提示审核

产出计划后，SOLO Agent 会自动提示调用 plan-review subagent 进行审核。

4.3 layer-check：分层依赖校验

属性	值
调用方式	`/layer-check`
触发时机	代码编写完成后手动调用
输入	当前 diff（自动获取）或指定文件
输出	分层校验报告（BLOCK / needs-review / 通过）

校验逻辑：

读取 layer_rules.json → 2. 获取 diff 文件 → 3. 提取 import → 4. 映射到层级 → 5. 检查依赖方向 → 6. 输出报告

判定规则：

import 目标在源层 allowed 列表中 → 通过
import 目标在源层 forbidden_cross 列表中 → BLOCK（必须修复）
import 目标不在两个列表中 → needs-review（需人工判断）

4.4 layer_rules.json 配置说明

json 复制代码

{
  "layers": { ... },        // 文件路径 → 层级映射（29 个层）
  "allowed": { ... },       // 允许依赖（12 个核心层配置，其余走 needs-review）
  "forbidden_cross": { ... }, // 禁止依赖（4 条核心 BLOCK 规则）
  "ignore": [ ... ]         // 忽略的文件（测试文件、vendor 等）
}

设计原则：核心 DDD 分层（handler/service/repository/milvus）有精确的 allowed + forbidden_cross（硬门禁），基础设施层走 needs-review（软提醒）。 DDD 改造未完成前不过度约束。

五、子代理（Subagents）

5.1 作用机制

Subagent 是 SOLO Agent 自动调用 的专用智能体。SOLO Agent 根据用户意图与 subagent 的 description 字段自动匹配，决定是否委派任务。

Subagent 拥有 独立上下文窗口，中间推理和执行过程不污染主对话历史，适合需要大量检索、分析但最终只需返回结果的任务。

5.2 plan-review：文档计划审核

属性	值
文件	agents/plan-review.md
自动触发	gen-plan 产出计划后、开发者要求审核规划文档时
可用工具	Read
输出	审核报告（通过/有条件通过/不通过）

审核内容：

技术可行性：技术选型一致性、分层落点合规性、接口契约完整性、资源合理性
风险识别：架构风险、数据风险、安全风险、依赖风险（每项标注高/中/低）
测试方案补全：自动补全边界用例（空值/越界/并发/幂等）、异常用例（基础设施不可用/网络异常/权限异常）、性能测试建议

5.3 test-compliance：测试及合规检测

属性	值
文件	agents/test-compliance.md
自动触发	代码编写完成后、提交 MR 前、需要合规检测时
可用工具	Read, Terminal, Edit
输出	综合测试合规报告（通过/有条件通过/不通过）

检测内容：

编译检查 ：go build ./... / npm run build
执行测试 ：go test ./... / npx vitest run（记录覆盖率）
合规性检测：通用规范（中文注释、error 检查、无硬编码密钥）+ 分层规范（引用 rules/ 规则文件）+ 分层依赖校验
自动修复：注释缺失、error 未 wrap、命名不规范可直接修复；架构违规提供修复建议

六、钩子（Hooks）

6.1 作用机制

hooks.json 在用户发送消息时自动触发，向 AI 注入项目规范提醒。

6.2 当前配置

json 复制代码

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "项目使用 Go(Hertz) + Next.js 双栈。修改后端代码前确认遵守 .trae/rules/handler.md 等分层规则；修改前端前确认遵守 .trae/rules/frontend.md。新代码必须配套测试，注释用中文。"
          }
        ]
      }
    ]
  }
}

每次发送消息时，AI 会收到这条提醒，确保在处理任何任务前都意识到分层规则和测试要求。

七、完整工作流

以"新增一个告警查询接口"为例，完整流程如下：

shell 复制代码

    1. 开发者口述需求
       "实现知识库告警列表的分页查询接口，支持按状态、严重度筛选"

    2. 生成计划（skill）
       /gen-plan
       → AI 按模板生成开发计划，包含分层落点、接口契约、测试要求、验收清单
       → 文档保存到 Docs/

    3. 审核计划（subagent，自动触发）
       → SOLO Agent 自动调用 plan-review
       → 技术可行性分析、风险识别、测试方案补全
       → 输出审核报告

    4. 管理员评审
       → 人工确认审核报告，通过后进入开发

    5. 代码编写
       → AI 按 handler.md / service.md / repository.md 规则编写代码
       → rules/ 中的规则全程自动生效

    6. 分层校验（skill）
       /layer-check
       → 扫描 diff 文件的 import
       → 检查是否违反 forbidden_cross
       → BLOCK 违规必须修复

    7. 测试合规（subagent，自动触发）
       → SOLO Agent 自动调用 test-compliance
       → 编译检查 → 执行测试 → 合规检测 → 自动修复
       → 输出综合报告

    8. 提交 MR
       → 全部通过后提交代码

八、新人快速上手

8.1 第一次接触项目

阅读本文件了解规范体系
阅读 rules/project_rules.md 了解项目总则
根据你要修改的代码区域，阅读对应的层规则文件（如改 Handler 读 handler.md）

8.2 开始开发一个新功能

在 AI 对话中口述需求
输入 /gen-plan 生成开发计划
等待 plan-review subagent 自动审核
管理员评审通过后开始编码
编码完成后输入 /layer-check 校验分层
等待 test-compliance subagent 自动检测
通过后提交 MR

8.3 修改分层规则

编辑 rules/ 下对应的 .md 文件（修改约束描述）
编辑 skills/layer-check/layer_rules.json（修改 allowed / forbidden_cross）
两者必须保持一致------md 描述的约束和 json 配置的校验规则不能矛盾

8.4 新增一个 Subagent

在 agents/ 下创建 <name>.md 文件
按 frontmatter 格式填写 name、description、tools
编写系统提示词（角色、工作流程、行为边界、输出格式）
description 要写得具体，避免误触发或漏触发

九、技术债标注

以下问题已识别并标注，在 DDD 改造过程中逐步修复：

问题	位置	严重度	说明
config 反向依赖 rag	`config/config.go`	中	import 了 `internal/rag/governance`，应内联配置结构体
middleware 依赖 repository	`middleware/auth.go`	中	应通过 auth 包封装用户查询
handler 依赖 model（存量）	部分 handler 文件	低	应逐步用 DTO 隔离
DDD 改造未完成	`internal/ragplatform/`	---	application 层为空壳，domain 层宽松约束

新代码不得延续以上违规模式。

了解更多

想了解更多，欢迎链接我，微信：wangzhongyang1993