AGENT.md，Skill与工程规范

这节课我们会从最基础的AGENT.md说起，里面放一些基础的规范。然后在后续中融入skill，让我们体会到各个维度工具的优势

AGENT.md：你和AI的合作协议

它是一个放在根目录下的md文件，AI编辑器每次启动新绘画时就会自动读取，你不需要手动喂给他，它是你与AI编辑器合作的协议，项目是什么？代码怎么组织，有哪些规矩？

它的生效范围？项目跟目录中的AGENT.md对整个项目生效。你也可以在子目录下放AGENT.md，他只对那个目录下的代码生效。子目录的规范和根目录的规范会叠加，不会覆盖。

它的组织结构是什么？

• 项目上下文：这是什么目录，做什么不做什么

• 架构规范：模块划分，依赖关系，外部调用处理

• 代码组织规范：分层结构，Controller，Service，Mapper职责

• 部署与数据库规范：部署架构，索引规则，分页规范

• 接口规范与行为指南

  
  Gdify是SpringBoot+Postgres+Redis+Vue的Ai Agent平台，帮我设计他的接口规范，要有接口入径，统一响应，分页、空值、错误码

这节课我们会从最基础的AGENT.md说起，里面放一些基础的规范。然后在后续中融入skill，让我们体会到各个维度工具的优势

AGENT.md：你和AI的合作协议

它是一个放在根目录下的md文件，AI编辑器每次启动新绘画时就会自动读取，你不需要手动喂给他，它是你与AI编辑器合作的协议，项目是什么？代码怎么组织，有哪些规矩？

它的生效范围？项目跟目录中的AGENT.md对整个项目生效。你也可以在子目录下放AGENT.md，他只对那个目录下的代码生效。子目录的规范和根目录的规范会叠加，不会覆盖。

它的组织结构是什么？

• 项目上下文：这是什么目录，做什么不做什么

• 架构规范：模块划分，依赖关系，外部调用处理

• 代码组织规范：分层结构，Controller，Service，Mapper职责

• 部署与数据库规范：部署架构，索引规则，分页规范

• 接口规范与行为指南

  
  Gdify是SpringBoot+Postgres+Redis+Vue的Ai Agent平台，帮我设计他的接口规范，要有接口入径，统一响应，分页、空值、错误码

  
  # Gdify API 接口规范
  ​
  适用范围：
  - Spring Boot 后端
  - Vue 管理端与聊天端
  - Postgres / Redis 支撑的业务接口
  - SSE 流式对话接口
  ​
  目标：
  - 接口入径统一
  - 返回结构统一
  - 分页结构统一
  - 空值语义统一
  - 错误码统一
  ​
  ---
  ​
  ## 1. 接口入径
  ​
  ### 1.1 统一前缀
  ​
  统一使用：
  ​
  ```text
  /api/v1
  ```
  ​
  ### 1.2 路径分组
  ​
  - `/admin`：管理端接口
  - `/chat`：聊天端接口
  - `/internal`：内部调用接口
  ​
  ### 1.3 命名规则
  ​
  - 全部使用小写
  - 统一使用复数名词
  - 多单词使用 `-` 分隔
  - 路径只表达资源，不表达动作
  - 动作类接口只在状态流转时出现，例如 `publish`、`disable`、`retry`
  ​
  ### 1.4 路径示例
  ​
  ```text
  GET    /api/v1/admin/agents
  POST   /api/v1/admin/agents
  GET    /api/v1/admin/agents/{id}
  PUT    /api/v1/admin/agents/{id}
  DELETE /api/v1/admin/agents/{id}
  ​
  GET    /api/v1/chat/conversations
  POST   /api/v1/chat/conversations
  POST   /api/v1/chat/conversations/{conversationId}/messages
  POST   /api/v1/chat/conversations/{conversationId}/messages/stream
  ​
  GET    /api/v1/admin/knowledge-bases
  POST   /api/v1/admin/documents
  POST   /api/v1/admin/workflows/{id}/publish
  POST   /api/v1/admin/mcp-servers/{id}/enable
  ```
  ​
  ### 1.5 资源建议映射
  ​
  | 模块 | 典型路径 |
  |---|---|
  | 认证与用户 | `/api/v1/admin/auth/*`、`/api/v1/admin/users/*` |
  | 模型提供商 | `/api/v1/admin/providers/*` |
  | Agent | `/api/v1/admin/agents/*` |
  | 会话与消息 | `/api/v1/chat/conversations/*` |
  | RAG | `/api/v1/admin/knowledge-bases/*`、`/api/v1/admin/documents/*` |
  | Workflow | `/api/v1/admin/workflows/*` |
  | MCP | `/api/v1/admin/mcp-servers/*`、`/api/v1/admin/tools/*` |
  ​
  ---
  ​
  ## 2. 请求约定
  ​
  ### 2.1 HTTP 方法
  ​
  - `GET`：查询列表、详情
  - `POST`：创建、动作触发、流式发送
  - `PUT`：整体更新
  - `PATCH`：局部更新
  - `DELETE`：删除
  ​
  ### 2.2 常用请求头
  ​
  - `Authorization: Bearer <accessToken>`
  - `Content-Type: application/json`
  - `Accept: application/json`
  - `X-Trace-Id: <traceId>`：可选，未传则服务端生成
  - `Idempotency-Key: <uuid>`：建议用于可能重试的 `POST`
  ​
  ### 2.3 时间与 ID
  ​
  - 时间字段统一使用 ISO 8601
  - 返回时间建议带时区
  - 对外 `id` 字段建议统一返回字符串，避免前端精度丢失
  ​
  ---
  ​
  ## 3. 统一响应
  ​
  ### 3.1 基本结构
  ​
  ```json
  {
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {},
    "errors": [],
    "traceId": "a1b2c3d4e5",
    "timestamp": 1716540000000
  }
  ```
  ​
  ### 3.2 字段说明
  ​
  | 字段 | 类型 | 说明 |
  |---|---|---|
  | `success` | boolean | 是否成功，等价于 `code == 0` |
  | `code` | int | 业务错误码，`0` 表示成功 |
  | `message` | string | 给前端展示的简短消息 |
  | `data` | object / array / string / number / null | 业务数据 |
  | `errors` | array | 字段级错误，通常用于参数校验失败 |
  | `traceId` | string | 链路追踪 ID |
  | `timestamp` | number | 服务端返回时间戳，毫秒 |
  ​
  ### 3.3 成功示例
  ​
  ```json
  {
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
      "id": "1024",
      "name": "Demo Agent"
    },
    "traceId": "a1b2c3d4e5",
    "timestamp": 1716540000000
  }
  ```
  ​
  ### 3.4 失败示例
  ​
  ```json
  {
    "success": false,
    "code": 53001,
    "message": "Agent 不存在",
    "data": null,
    "errors": [],
    "traceId": "a1b2c3d4e5",
    "timestamp": 1716540000000
  }
  ```
  ​
  ### 3.5 返回原则
  ​
  - 成功返回 `2xx`
  - 参数或校验失败返回 `4xx`
  - 系统或依赖错误返回 `5xx`
  - 所有业务错误都要落到统一响应体
  - `traceId` 必须可回传、可检索、可定位日志
  ​
  ---
  ​
  ## 4. 分页
  ​
  ### 4.1 请求参数
  ​
  | 参数 | 默认值 | 说明 |
  |---|---|---|
  | `pageNo` | `1` | 页码，从 1 开始 |
  | `pageSize` | `20` | 每页条数 |
  | `sortBy` | 可选 | 排序字段 |
  | `sortOrder` | `desc` | `asc` 或 `desc` |
  ​
  约束：
  - `pageSize` 最大建议 `100`
  - 列表页无数据时返回空数组，不返回 `null`
  ​
  ### 4.2 分页响应
  ​
  ```json
  {
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
      "list": [],
      "pageNo": 1,
      "pageSize": 20,
      "total": 0,
      "pages": 0
    },
    "traceId": "a1b2c3d4e5",
    "timestamp": 1716540000000
  }
  ```
  ​
  ### 4.3 分页规则
  ​
  - `list` 永远不返回 `null`
  - `total = 0` 时，`pages = 0`
  - `pageNo` 超出范围时，建议返回空列表而不是报错
  ​
  ---
  ​
  ## 5. 空值
  ​
  ### 5.1 统一原则
  ​
  - 列表字段返回 `[]`
  - 对象字段在“确实不存在”时可返回 `null`
  - 字符串字段在“需要展示空文本”时返回 `""`
  - 数值字段不要用 `0` 伪装“缺失”
  - 布尔字段不要用 `null` 代替业务含义，默认用 `false`
  ​
  ### 5.2 推荐语义
  ​
  | 类型 | 推荐值 |
  |---|---|
  | `string` | `""` 或 `null`，取决于语义是否为空 |
  | `list` | `[]` |
  | `object` | `null` 或 `{}` |
  | `number` | `null` |
  | `boolean` | `false` |
  | `datetime` | ISO 8601 字符串或 `null` |
  ​
  ### 5.3 约束
  ​
  - 不要全局把 `null` 强行转成空字符串
  - 不要把 `0`、`false` 当成“未填写”
  - 前端不应依赖字段顺序，只依赖字段名
  ​
  ---
  ​
  ## 6. 错误码
  ​
  ### 6.1 设计原则
  ​
  - `0` 表示成功
  - 错误码必须唯一
  - 前端用 `code` 判断业务结果
  - HTTP 状态码用于表达协议层结果
  - `message` 只返回可读提示，不返回堆栈
  ​
  ### 6.2 公共错误码
  ​
  | 错误码 | 含义 | HTTP |
  |---|---|---|
  | `0` | 成功 | `200` |
  | `40000` | 请求参数非法 | `400` |
  | `40001` | 参数校验失败 | `400` |
  | `40002` | 请求体解析失败 | `400` |
  | `40100` | 未登录或 token 无效 | `401` |
  | `40101` | token 过期 | `401` |
  | `40300` | 无权限 | `403` |
  | `40400` | 资源不存在 | `404` |
  | `40900` | 资源冲突或重复 | `409` |
  | `42200` | 业务规则不满足 | `422` |
  | `42900` | 请求过于频繁 | `429` |
  | `50000` | 系统内部错误 | `500` |
  | `50001` | 数据库错误 | `500` |
  | `50002` | Redis 错误 | `500` |
  | `50200` | 上游服务异常 | `502` |
  | `50300` | 上游服务不可用 | `503` |
  ​
  ### 6.3 业务错误码分段
  ​
  | 范围 | 模块 |
  |---|---|
  | `51000-51999` | 用户与认证 |
  | `52000-52999` | 模型提供商 |
  | `53000-53999` | Agent |
  | `54000-54999` | 会话与消息 |
  | `55000-55999` | RAG |
  | `56000-56999` | Workflow |
  | `57000-57999` | MCP |
  ​
  ### 6.4 示例
  ​
  - `53001`：Agent 不存在
  - `53002`：Agent 已停用
  - `54001`：会话不存在
  - `54002`：会话已关闭
  - `55001`：文档解析失败
  - `55002`：切片失败
  - `56001`：工作流节点配置非法
  - `57001`：MCP 工具未注册
  ​
  ### 6.5 校验错误建议
  ​
  字段校验失败时，建议补充 `errors`：
  ​
  ```json
  {
    "success": false,
    "code": 40001,
    "message": "参数校验失败",
    "errors": [
      {
        "field": "name",
        "message": "不能为空"
      }
    ],
    "traceId": "a1b2c3d4e5",
    "timestamp": 1716540000000
  }
  ```
  ​
  ---
  ​
  ## 7. SSE 流式接口
  ​
  ### 7.1 适用场景
  ​
  - Agent 对话
  - 大模型流式输出
  - 工具调用过程回传
  ​
  ### 7.2 接口约定
  ​
  - 请求路径建议使用 `/stream` 后缀
  - 响应 `Content-Type` 为 `text/event-stream`
  - SSE 接口不使用标准 JSON 包装
  ​
  ### 7.3 事件类型
  ​
  - `meta`：开始信息
  - `delta`：增量文本
  - `tool_call`：工具调用
  - `done`：结束信息
  - `error`：错误信息
  ​
  ### 7.4 示例
  ​
  ```text
  event: meta
  data: {"conversationId":"c_1001","requestId":"r_9001"}
  ​
  event: delta
  data: {"content":"你好"}
  ​
  event: done
  data: {"finishReason":"stop","usage":{"promptTokens":12,"completionTokens":8}}
  ```
  ​
  ---
  ​
  ## 8. 兼容性规则
  ​
  - 同一版本只允许新增字段，不允许随意删字段或改字段名
  - 破坏性变更必须升级主版本号
  - 旧接口下线前必须保留一段过渡期
  - 新增枚举值必须保证前端可降级处理
  ​

行为规范我就直接贴到这了，你也可以跟AI编辑器去交流

  
  ## 行为指令
  ​
  ### 写代码时
  - 每个功能用最简单直接的方式实现
  - 不引入不必要的设计模式，除非我明确要求
  - 不做过度抽象
  - 不引入技术栈以外的依赖，需要时先问我
  - 所有外部调用必须有超时设置
  - 配置项外化到 application.yml，不硬编码
  ​
  ### 改代码时
  - 先理解相关模块的设计意图
  - 不要为了新功能破坏已有接口契约
  - 改完确保已有测试通过
  ​
  ### 不确定时
  - 架构选择给我 2-3 个方案对比，我来拍板
  - 规范没覆盖的情况，先问我，不要自己编规矩

在改动代码时的三条建议是从实际开发过程中踩坑而来。在AI编辑器改动一个模块时，会顺手改动别的模块，破坏已有接口，写了这三条之后，他修改代码前会说我理解这个模块的设计意图是XXX。我打算改动它XXX，不会影响XXX，给你确认机会

不确定时也很重要，AI编辑器遇到规范没有覆盖的情况，会自己编一套规矩。每次编辑还不一样，写了之后他会主动问你，而不是善作主张

接口契约：模块级的蓝图

AGENT.md的接口规范是通用规矩（路径格式、响应结构、错误码分段）。但每个模块开始开发前，还需要一份具体蓝图------这个模块有哪些接口、每个接口的入参出参是什么。这就是接口契约。

你不需要在项目开始时就把所有模块的接口契约都写完。每个模块开发前写那个模块的就行， 给AI编辑器这份蓝图，它生成的Controller和DTO会精确匹配你的设计，不需要大面积返工。

Skills：可复用的规范片段

AGENT.md是项目级的全局规范，覆盖整个项目。但有些规范是针对某一类具体任务的，比如怎么写单元测试，怎么做接口契约，怎么做代码review。这些写进AGENT.md太细了，不写每次又要重复描述。Skills解决这个问题。

什么时候该创建一个Skill？当你发现自己给AI编辑器的指令有重复模式时。比如每次写新模块的接口契约，你都要说"RESTful 风格、Result 返回、分页用 PageResult......"。这些就可以沉淀成一个Skill。

创建了这个Skill之后，下次你说"帮我设计Agent模块的接口契约"，AI编辑器会自动按这个标准流程走，不需要你每次重复描述格式要求。

一期不需要创建太多Skills。随着开发推进，你会自然发现哪些指令在重复，那就是该创建Skill的信号。

用业界规范喂 AI编辑器

前面几讲AGENT.md 里的规范都是我们自己定的，但很多规范不需要从零发明，业界已经有成熟的标准，直接用就行。

技巧是：把业界规范喂给 AI编辑器 ，让它基于这些规范生成适合你项目的版本

比如Java编码规范。阿里巴巴Java开发手册、Google Java Style Guide都是业界公认的标准。

我在做一个Spring Boot项目，请基于阿里巴巴Java开发手册，帮我提炼出最关键的20条编码规范，写成AGENT.md 可以直接用的格式。重点覆盖命名、异常处理、日志、并发这几个方面。不要照搬原文，要精简到 AI 能直接执行。

这个技巧的本质是：你不需要是每个领域的专家，但你可以让 AI编辑器 帮你把专家的经验转化成你项目的规范。 Java规范、MySQL规范、安全规范、API设计规范，任何一个领域都可以用这个方法。喂入业界标准 + 你的项目上下文，让AI编辑器 生成适配版本，你review定稿。

让 AI编辑器帮你生成完整 AGENT.md

  
  我在做一个叫Gdify的项目，以下是前期做的所有决策：放到AGENT.md中了，另外请基于阿里巴巴Java开发手册，补充编码规范部分。请帮我合并生成一份完整的CLAUDE.md。要求：结构清晰，从项目概述到行为指令，规范要具体到AI能直接执行。

总结

AGENT.md 是你和 AI 的合作协议 。五层结构从宏观到微观，项目上下文→架构→代码组织→数据库→接口+行为指令。根目录放全局规范，子目录放模块规范，两者叠加生效。

Skills是可复用的规范片段。发现指令在重复，就该创建Skill。

业界规范喂入，是写AGENT.md的加速器。不需要自己从零写每条规范，把阿里巴巴Java规范、MySQL最佳实践喂给Claude Code，让它生成适合你项目的版本。

思维方式比具体技巧更重要。每条规范追溯到一个架构决策，颗粒度跟着问题走，接受规范是渐进完善的。

  
  # Gdify API 接口规范
  ​
  适用范围：
  - Spring Boot 后端
  - Vue 管理端与聊天端
  - Postgres / Redis 支撑的业务接口
  - SSE 流式对话接口
  ​
  目标：
  - 接口入径统一
  - 返回结构统一
  - 分页结构统一
  - 空值语义统一
  - 错误码统一
  ​
  ---
  ​
  ## 1. 接口入径
  ​
  ### 1.1 统一前缀
  ​
  统一使用：
  ​
  ```text
  /api/v1
  ```
  ​
  ### 1.2 路径分组
  ​
  - `/admin`：管理端接口
  - `/chat`：聊天端接口
  - `/internal`：内部调用接口
  ​
  ### 1.3 命名规则
  ​
  - 全部使用小写
  - 统一使用复数名词
  - 多单词使用 `-` 分隔
  - 路径只表达资源，不表达动作
  - 动作类接口只在状态流转时出现，例如 `publish`、`disable`、`retry`
  ​
  ### 1.4 路径示例
  ​
  ```text
  GET    /api/v1/admin/agents
  POST   /api/v1/admin/agents
  GET    /api/v1/admin/agents/{id}
  PUT    /api/v1/admin/agents/{id}
  DELETE /api/v1/admin/agents/{id}
  ​
  GET    /api/v1/chat/conversations
  POST   /api/v1/chat/conversations
  POST   /api/v1/chat/conversations/{conversationId}/messages
  POST   /api/v1/chat/conversations/{conversationId}/messages/stream
  ​
  GET    /api/v1/admin/knowledge-bases
  POST   /api/v1/admin/documents
  POST   /api/v1/admin/workflows/{id}/publish
  POST   /api/v1/admin/mcp-servers/{id}/enable
  ```
  ​
  ### 1.5 资源建议映射
  ​
  | 模块 | 典型路径 |
  |---|---|
  | 认证与用户 | `/api/v1/admin/auth/*`、`/api/v1/admin/users/*` |
  | 模型提供商 | `/api/v1/admin/providers/*` |
  | Agent | `/api/v1/admin/agents/*` |
  | 会话与消息 | `/api/v1/chat/conversations/*` |
  | RAG | `/api/v1/admin/knowledge-bases/*`、`/api/v1/admin/documents/*` |
  | Workflow | `/api/v1/admin/workflows/*` |
  | MCP | `/api/v1/admin/mcp-servers/*`、`/api/v1/admin/tools/*` |
  ​
  ---
  ​
  ## 2. 请求约定
  ​
  ### 2.1 HTTP 方法
  ​
  - `GET`：查询列表、详情
  - `POST`：创建、动作触发、流式发送
  - `PUT`：整体更新
  - `PATCH`：局部更新
  - `DELETE`：删除
  ​
  ### 2.2 常用请求头
  ​
  - `Authorization: Bearer <accessToken>`
  - `Content-Type: application/json`
  - `Accept: application/json`
  - `X-Trace-Id: <traceId>`：可选，未传则服务端生成
  - `Idempotency-Key: <uuid>`：建议用于可能重试的 `POST`
  ​
  ### 2.3 时间与 ID
  ​
  - 时间字段统一使用 ISO 8601
  - 返回时间建议带时区
  - 对外 `id` 字段建议统一返回字符串，避免前端精度丢失
  ​
  ---
  ​
  ## 3. 统一响应
  ​
  ### 3.1 基本结构
  ​
  ```json
  {
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {},
    "errors": [],
    "traceId": "a1b2c3d4e5",
    "timestamp": 1716540000000
  }
  ```
  ​
  ### 3.2 字段说明
  ​
  | 字段 | 类型 | 说明 |
  |---|---|---|
  | `success` | boolean | 是否成功，等价于 `code == 0` |
  | `code` | int | 业务错误码，`0` 表示成功 |
  | `message` | string | 给前端展示的简短消息 |
  | `data` | object / array / string / number / null | 业务数据 |
  | `errors` | array | 字段级错误，通常用于参数校验失败 |
  | `traceId` | string | 链路追踪 ID |
  | `timestamp` | number | 服务端返回时间戳，毫秒 |
  ​
  ### 3.3 成功示例
  ​
  ```json
  {
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
      "id": "1024",
      "name": "Demo Agent"
    },
    "traceId": "a1b2c3d4e5",
    "timestamp": 1716540000000
  }
  ```
  ​
  ### 3.4 失败示例
  ​
  ```json
  {
    "success": false,
    "code": 53001,
    "message": "Agent 不存在",
    "data": null,
    "errors": [],
    "traceId": "a1b2c3d4e5",
    "timestamp": 1716540000000
  }
  ```
  ​
  ### 3.5 返回原则
  ​
  - 成功返回 `2xx`
  - 参数或校验失败返回 `4xx`
  - 系统或依赖错误返回 `5xx`
  - 所有业务错误都要落到统一响应体
  - `traceId` 必须可回传、可检索、可定位日志
  ​
  ---
  ​
  ## 4. 分页
  ​
  ### 4.1 请求参数
  ​
  | 参数 | 默认值 | 说明 |
  |---|---|---|
  | `pageNo` | `1` | 页码，从 1 开始 |
  | `pageSize` | `20` | 每页条数 |
  | `sortBy` | 可选 | 排序字段 |
  | `sortOrder` | `desc` | `asc` 或 `desc` |
  ​
  约束：
  - `pageSize` 最大建议 `100`
  - 列表页无数据时返回空数组，不返回 `null`
  ​
  ### 4.2 分页响应
  ​
  ```json
  {
    "success": true,
    "code": 0,
    "message": "OK",
    "data": {
      "list": [],
      "pageNo": 1,
      "pageSize": 20,
      "total": 0,
      "pages": 0
    },
    "traceId": "a1b2c3d4e5",
    "timestamp": 1716540000000
  }
  ```
  ​
  ### 4.3 分页规则
  ​
  - `list` 永远不返回 `null`
  - `total = 0` 时，`pages = 0`
  - `pageNo` 超出范围时，建议返回空列表而不是报错
  ​
  ---
  ​
  ## 5. 空值
  ​
  ### 5.1 统一原则
  ​
  - 列表字段返回 `[]`
  - 对象字段在“确实不存在”时可返回 `null`
  - 字符串字段在“需要展示空文本”时返回 `""`
  - 数值字段不要用 `0` 伪装“缺失”
  - 布尔字段不要用 `null` 代替业务含义，默认用 `false`
  ​
  ### 5.2 推荐语义
  ​
  | 类型 | 推荐值 |
  |---|---|
  | `string` | `""` 或 `null`，取决于语义是否为空 |
  | `list` | `[]` |
  | `object` | `null` 或 `{}` |
  | `number` | `null` |
  | `boolean` | `false` |
  | `datetime` | ISO 8601 字符串或 `null` |
  ​
  ### 5.3 约束
  ​
  - 不要全局把 `null` 强行转成空字符串
  - 不要把 `0`、`false` 当成“未填写”
  - 前端不应依赖字段顺序，只依赖字段名
  ​
  ---
  ​
  ## 6. 错误码
  ​
  ### 6.1 设计原则
  ​
  - `0` 表示成功
  - 错误码必须唯一
  - 前端用 `code` 判断业务结果
  - HTTP 状态码用于表达协议层结果
  - `message` 只返回可读提示，不返回堆栈
  ​
  ### 6.2 公共错误码
  ​
  | 错误码 | 含义 | HTTP |
  |---|---|---|
  | `0` | 成功 | `200` |
  | `40000` | 请求参数非法 | `400` |
  | `40001` | 参数校验失败 | `400` |
  | `40002` | 请求体解析失败 | `400` |
  | `40100` | 未登录或 token 无效 | `401` |
  | `40101` | token 过期 | `401` |
  | `40300` | 无权限 | `403` |
  | `40400` | 资源不存在 | `404` |
  | `40900` | 资源冲突或重复 | `409` |
  | `42200` | 业务规则不满足 | `422` |
  | `42900` | 请求过于频繁 | `429` |
  | `50000` | 系统内部错误 | `500` |
  | `50001` | 数据库错误 | `500` |
  | `50002` | Redis 错误 | `500` |
  | `50200` | 上游服务异常 | `502` |
  | `50300` | 上游服务不可用 | `503` |
  ​
  ### 6.3 业务错误码分段
  ​
  | 范围 | 模块 |
  |---|---|
  | `51000-51999` | 用户与认证 |
  | `52000-52999` | 模型提供商 |
  | `53000-53999` | Agent |
  | `54000-54999` | 会话与消息 |
  | `55000-55999` | RAG |
  | `56000-56999` | Workflow |
  | `57000-57999` | MCP |
  ​
  ### 6.4 示例
  ​
  - `53001`：Agent 不存在
  - `53002`：Agent 已停用
  - `54001`：会话不存在
  - `54002`：会话已关闭
  - `55001`：文档解析失败
  - `55002`：切片失败
  - `56001`：工作流节点配置非法
  - `57001`：MCP 工具未注册
  ​
  ### 6.5 校验错误建议
  ​
  字段校验失败时，建议补充 `errors`：
  ​
  ```json
  {
    "success": false,
    "code": 40001,
    "message": "参数校验失败",
    "errors": [
      {
        "field": "name",
        "message": "不能为空"
      }
    ],
    "traceId": "a1b2c3d4e5",
    "timestamp": 1716540000000
  }
  ```
  ​
  ---
  ​
  ## 7. SSE 流式接口
  ​
  ### 7.1 适用场景
  ​
  - Agent 对话
  - 大模型流式输出
  - 工具调用过程回传
  ​
  ### 7.2 接口约定
  ​
  - 请求路径建议使用 `/stream` 后缀
  - 响应 `Content-Type` 为 `text/event-stream`
  - SSE 接口不使用标准 JSON 包装
  ​
  ### 7.3 事件类型
  ​
  - `meta`：开始信息
  - `delta`：增量文本
  - `tool_call`：工具调用
  - `done`：结束信息
  - `error`：错误信息
  ​
  ### 7.4 示例
  ​
  ```text
  event: meta
  data: {"conversationId":"c_1001","requestId":"r_9001"}
  ​
  event: delta
  data: {"content":"你好"}
  ​
  event: done
  data: {"finishReason":"stop","usage":{"promptTokens":12,"completionTokens":8}}
  ```
  ​
  ---
  ​
  ## 8. 兼容性规则
  ​
  - 同一版本只允许新增字段，不允许随意删字段或改字段名
  - 破坏性变更必须升级主版本号
  - 旧接口下线前必须保留一段过渡期
  - 新增枚举值必须保证前端可降级处理
  ​

行为规范我就直接贴到这了，你也可以跟AI编辑器去交流

  
  ## 行为指令
  ​
  ### 写代码时
  - 每个功能用最简单直接的方式实现
  - 不引入不必要的设计模式，除非我明确要求
  - 不做过度抽象
  - 不引入技术栈以外的依赖，需要时先问我
  - 所有外部调用必须有超时设置
  - 配置项外化到 application.yml，不硬编码
  ​
  ### 改代码时
  - 先理解相关模块的设计意图
  - 不要为了新功能破坏已有接口契约
  - 改完确保已有测试通过
  ​
  ### 不确定时
  - 架构选择给我 2-3 个方案对比，我来拍板
  - 规范没覆盖的情况，先问我，不要自己编规矩

在改动代码时的三条建议是从实际开发过程中踩坑而来。在AI编辑器改动一个模块时，会顺手改动别的模块，破坏已有接口，写了这三条之后，他修改代码前会说我理解这个模块的设计意图是XXX。我打算改动它XXX，不会影响XXX，给你确认机会

不确定时也很重要，AI编辑器遇到规范没有覆盖的情况，会自己编一套规矩。每次编辑还不一样，写了之后他会主动问你，而不是善作主张

接口契约：模块级的蓝图

AGENT.md的接口规范是通用规矩（路径格式、响应结构、错误码分段）。但每个模块开始开发前，还需要一份具体蓝图------这个模块有哪些接口、每个接口的入参出参是什么。这就是接口契约。

你不需要在项目开始时就把所有模块的接口契约都写完。每个模块开发前写那个模块的就行， 给AI编辑器这份蓝图，它生成的Controller和DTO会精确匹配你的设计，不需要大面积返工。

Skills：可复用的规范片段

AGENT.md是项目级的全局规范，覆盖整个项目。但有些规范是针对某一类具体任务的，比如怎么写单元测试，怎么做接口契约，怎么做代码review。这些写进AGENT.md太细了，不写每次又要重复描述。Skills解决这个问题。

什么时候该创建一个Skill？当你发现自己给AI编辑器的指令有重复模式时。比如每次写新模块的接口契约，你都要说"RESTful 风格、Result 返回、分页用 PageResult......"。这些就可以沉淀成一个Skill。

创建了这个Skill之后，下次你说"帮我设计Agent模块的接口契约"，AI编辑器会自动按这个标准流程走，不需要你每次重复描述格式要求。

一期不需要创建太多Skills。随着开发推进，你会自然发现哪些指令在重复，那就是该创建Skill的信号。

用业界规范喂 AI编辑器

前面几讲AGENT.md 里的规范都是我们自己定的，但很多规范不需要从零发明，业界已经有成熟的标准，直接用就行。

技巧是：把业界规范喂给 AI编辑器 ，让它基于这些规范生成适合你项目的版本

比如Java编码规范。阿里巴巴Java开发手册、Google Java Style Guide都是业界公认的标准。

我在做一个Spring Boot项目，请基于阿里巴巴Java开发手册，帮我提炼出最关键的20条编码规范，写成AGENT.md 可以直接用的格式。重点覆盖命名、异常处理、日志、并发这几个方面。不要照搬原文，要精简到 AI 能直接执行。

这个技巧的本质是：你不需要是每个领域的专家，但你可以让 AI编辑器 帮你把专家的经验转化成你项目的规范。 Java规范、MySQL规范、安全规范、API设计规范，任何一个领域都可以用这个方法。喂入业界标准 + 你的项目上下文，让AI编辑器 生成适配版本，你review定稿。

让 AI编辑器帮你生成完整 AGENT.md

  
  我在做一个叫Gdify的项目，以下是前期做的所有决策：放到AGENT.md中了，另外请基于阿里巴巴Java开发手册，补充编码规范部分。请帮我合并生成一份完整的CLAUDE.md。要求：结构清晰，从项目概述到行为指令，规范要具体到AI能直接执行。

总结

AGENT.md 是你和 AI 的合作协议 。五层结构从宏观到微观，项目上下文→架构→代码组织→数据库→接口+行为指令。根目录放全局规范，子目录放模块规范，两者叠加生效。

Skills是可复用的规范片段。发现指令在重复，就该创建Skill。

业界规范喂入，是写AGENT.md的加速器。不需要自己从零写每条规范，把阿里巴巴Java规范、MySQL最佳实践喂给Claude Code，让它生成适合你项目的版本。

思维方式比具体技巧更重要。每条规范追溯到一个架构决策，颗粒度跟着问题走，接受规范是渐进完善的。