近期，许多求职者在面试中被问及“如何进行AI编程”时，回答通常比较表面，仅仅列举了几款工具。面试官一句“你管这叫AI编程？”精准指出了众多团队在AI辅助开发中面临的现实困境——虽然使用了工具，但开发效率与代码质量并未得到实质性提升。

本文内容源于我们内部项目实践中的经验总结，旨在提供一个更系统化的视角。我们团队绝大多数项目都基于Trae进行开发，因此下文将以Trae为例展开说明。如果你使用的是Claude、Codex等类似工具，思路是相通的，只需将配置文件和规则调整到对应目录（如.claude目录），做一下适配即可。

你可以直接向AI提出需求，但核心不在于对话方式，而在于你如何为AI设定一套清晰的“行为准则”。

一、为何需要制定这套规范

在AI辅助开发过程中，团队常常会碰到以下几个令人困扰的问题：

分层混乱。 AI不理解你的项目架构，生成的代码经常出现跨层调用，例如Handler直接操作数据库，或者Service层引入HTTP框架。这种代码在人工审查时极为痛苦。

质量不可控。 AI产出的代码往往缺少测试、注释不规范、错误处理不到位。每次都需要人工反复纠正，反而增加了额外工作量。

计划与执行脱节。 AI习惯直接动手写代码，跳过了计划评审环节。这导致一些方向性错误通常在写完大量代码后才被发现，返工成本非常高昂。

上下文污染。 大量检索和分析任务在主对话中执行，严重挤占了AI宝贵的上下文窗口。结果就是AI对核心任务的注意力下降，输出质量大打折扣。

团队规范不统一。 不同开发者使用AI产出的代码风格差异明显，项目后期的维护成本自然水涨船高。

那么，如何解决这些问题？核心思路其实很清晰：将团队规范固化为AI可执行的约束。 通过.trae/目录下的四类配置文件，我们可以达成这个目标。

核心原则非常明确：让AI在恰当的时机自动执行正确的流程，而非依赖人工每次去提醒。 这才是实现工程化提效的关键。

二、目录结构

理解了要做的事，我们先搭好架子。整个规范体系的核心目录结构如下：

.trae/
├── README.md                     # 本文档（综合规范介绍）
├── hooks.json                    # 钩子配置（提交前提醒）
│
├── rules/                        # 规则文件（每次对话自动加载）
│   ├── project_rules.md          # 项目总则（技术栈、编码规则、文档约定）
│   ├── handler.md                # Handler 层规则
│   ├── service.md                # Service 层规则
│   ├── repository.md             # Repository 层规则
│   ├── domain.md                 # Domain 层规则
│   ├── milvus.md                 # Milvus 检索核心规则
│   ├── rag.md                    # RAG 编排层规则
│   └── frontend.md               # 前端规则
│
├── 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文件均为“始终生效”状态。每次AI对话开始时，它们会自动加载到上下文中并全程发挥作用。AI在编辑代码时，会自动遵守对应层的规则。

3.2 规则文件一览

这些规则文件基本覆盖了项目中的每一层，每层都有清晰的边界和约束条件：

3.3 分层依赖方向

下面这张图展示了项目各层之间的依赖方向，这是整个架构的基石：

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

这里有四条核心的“硬门禁”规则，任何违反行为都会在layer-check环节被直接拦截：

四、技能（Skills）

4.1 作用机制

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

4.2 gen-plan：生成开发计划

该技能用于生成标准化的开发计划，可以说是整个流程的起点。

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

计划产出后，SOLO Agent会自动提示调用plan-review子智能体进行审核，形成闭环。

4.3 layer-check：分层依赖校验

代码编写完成后，通过该技能校验依赖关系是否合规，非常实用。

校验逻辑同样清晰：
读取 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文件是分层校验的“法律依据”，它的设计遵循一项重要原则：核心DDD分层拥有精确的allowed和forbidden_cross硬门禁，而基础设施层则走needs-review软提醒。在DDD改造未完成前，不过度约束，避免“步子太大扯着蛋”。

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

五、子智能体（Subagents）

5.1 作用机制

Subagent是SOLO Agent自动调用的专用智能体。SOLO Agent会根据用户意图和subagent的description字段自动匹配，决定是否委派任务。最关键的是，Subagent拥有独立上下文窗口，其中的中间推理和执行过程不会污染主对话历史。这对于需要大量检索、分析但最终只需返回结果的任务来说，效果非常显著。

5.2 plan-review：文档计划审核

这个子智能体专门审核gen-plan产出的开发计划，相当于一个“计划质检员”。

它主要审核三方面内容：

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

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

该子智能体负责在开发完成后进行一次全面的“体检”，确保代码质量和合规性。

它的检测内容非常全面：

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

六、钩子（Hooks）

6.1 作用机制

hooks.json在用户发送消息时自动触发，向AI注入项目规范提醒。它就像是一个“背景音”，时刻提醒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. 生成计划（技能）：/gen-plan → AI按模板生成开发计划，包含分层落点、接口契约、测试要求、验收清单 → 文档保存到Docs/
3. 审核计划（子智能体，自动触发）：SOLO Agent自动调用plan-review → 技术可行性分析、风险识别、测试方案补全 → 输出审核报告
4. 管理员评审：人工确认审核报告，通过后进入开发
5. 代码编写：AI按handler.md / service.md / repository.md规则编写代码 → rules/中的规则全程自动生效
6. 分层校验（技能）：/layer-check → 扫描diff文件的import → 检查是否违反forbidden_cross → BLOCK违规必须修复
7. 测试合规（子智能体，自动触发）：SOLO Agent自动调用test-compliance → 编译检查 → 执行测试 → 合规检测 → 自动修复 → 输出综合报告
8. 提交MR：全部通过后提交代码

这个流程从需求到交付，每一步都有对应的工具和规则来保障质量与效率。

八、新人快速上手

这套体系对新人也很友好，可以快速上手。

8.1 第一次接触项目

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

8.2 开始开发一个新功能

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

8.3 修改分层规则

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

8.4 新增一个Subagent

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

九、技术债标注

没有完美的系统，任何项目都存在技术债。以下问题已识别并标注，将在DDD改造过程中逐步修复：

需要强调的是，新代码不得延续以上违规模式。这也正是这套规范体系的意义所在——它确保新开发的代码从一开始就走在正确的道路上。