实践得真知哇
这篇文章是基于我们训练营内部项目总结实践出来的，思考供大家学习参考。
最近有粉丝去面试，被问到如何进行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 在正确的时机自动执行正确的流程，而不是依赖人每次提醒。
二、目录结构
.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 分层依赖方向
┌──────────┐
│ 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 配置说明
{
"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 当前配置
{
"hooks": {
"UserPromptSubmit": [
{
"matcher": "*",
"hooks": [
{
"type": "prompt",
"prompt": "项目使用 Go(Hertz) + Next.js 双栈。修改后端代码前确认遵守 .trae/rules/handler.md 等分层规则；修改前端前确认遵守 .trae/rules/frontend.md。新代码必须配套测试，注释用中文。"
}
]
}
]
}
}
每次发送消息时，AI 会收到这条提醒，确保在处理任何任务前都意识到分层规则和测试要求。
七、完整工作流
以"新增一个告警查询接口"为例，完整流程如下：
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
