这节课我们会从最基础的AGENT.md说起里面放一些基础的规范。然后在后续中融入skill让我们体会到各个维度工具的优势AGENT.md你和AI的合作协议它是一个放在根目录下的md文件AI编辑器每次启动新绘画时就会自动读取你不需要手动喂给他它是你与AI编辑器合作的协议项目是什么代码怎么组织有哪些规矩它的生效范围项目跟目录中的AGENT.md对整个项目生效。你也可以在子目录下放AGENT.md他只对那个目录下的代码生效。子目录的规范和根目录的规范会叠加不会覆盖。它的组织结构是什么项目上下文这是什么目录做什么不做什么架构规范模块划分依赖关系外部调用处理代码组织规范分层结构ControllerServiceMapper职责部署与数据库规范部署架构索引规则分页规范接口规范与行为指南Gdify是SpringBootPostgresRedisVue的Ai Agent平台帮我设计他的接口规范要有接口入径统一响应分页、空值、错误码这节课我们会从最基础的AGENT.md说起里面放一些基础的规范。然后在后续中融入skill让我们体会到各个维度工具的优势AGENT.md你和AI的合作协议它是一个放在根目录下的md文件AI编辑器每次启动新绘画时就会自动读取你不需要手动喂给他它是你与AI编辑器合作的协议项目是什么代码怎么组织有哪些规矩它的生效范围项目跟目录中的AGENT.md对整个项目生效。你也可以在子目录下放AGENT.md他只对那个目录下的代码生效。子目录的规范和根目录的规范会叠加不会覆盖。它的组织结构是什么项目上下文这是什么目录做什么不做什么架构规范模块划分依赖关系外部调用处理代码组织规范分层结构ControllerServiceMapper职责部署与数据库规范部署架构索引规则分页规范接口规范与行为指南Gdify是SpringBootPostgresRedisVue的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 示例 - 53001Agent 不存在 - 53002Agent 已停用 - 54001会话不存在 - 54002会话已关闭 - 55001文档解析失败 - 55002切片失败 - 56001工作流节点配置非法 - 57001MCP 工具未注册 ### 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 示例 - 53001Agent 不存在 - 53002Agent 已停用 - 54001会话不存在 - 54002会话已关闭 - 55001文档解析失败 - 55002切片失败 - 56001工作流节点配置非法 - 57001MCP 工具未注册 ### 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让它生成适合你项目的版本。思维方式比具体技巧更重要。每条规范追溯到一个架构决策颗粒度跟着问题走接受规范是渐进完善的。
AGENT.md，Skill与工程规范
发布时间：2026/5/30 23:29:20
这节课我们会从最基础的AGENT.md说起里面放一些基础的规范。然后在后续中融入skill让我们体会到各个维度工具的优势AGENT.md你和AI的合作协议它是一个放在根目录下的md文件AI编辑器每次启动新绘画时就会自动读取你不需要手动喂给他它是你与AI编辑器合作的协议项目是什么代码怎么组织有哪些规矩它的生效范围项目跟目录中的AGENT.md对整个项目生效。你也可以在子目录下放AGENT.md他只对那个目录下的代码生效。子目录的规范和根目录的规范会叠加不会覆盖。它的组织结构是什么项目上下文这是什么目录做什么不做什么架构规范模块划分依赖关系外部调用处理代码组织规范分层结构ControllerServiceMapper职责部署与数据库规范部署架构索引规则分页规范接口规范与行为指南Gdify是SpringBootPostgresRedisVue的Ai Agent平台帮我设计他的接口规范要有接口入径统一响应分页、空值、错误码这节课我们会从最基础的AGENT.md说起里面放一些基础的规范。然后在后续中融入skill让我们体会到各个维度工具的优势AGENT.md你和AI的合作协议它是一个放在根目录下的md文件AI编辑器每次启动新绘画时就会自动读取你不需要手动喂给他它是你与AI编辑器合作的协议项目是什么代码怎么组织有哪些规矩它的生效范围项目跟目录中的AGENT.md对整个项目生效。你也可以在子目录下放AGENT.md他只对那个目录下的代码生效。子目录的规范和根目录的规范会叠加不会覆盖。它的组织结构是什么项目上下文这是什么目录做什么不做什么架构规范模块划分依赖关系外部调用处理代码组织规范分层结构ControllerServiceMapper职责部署与数据库规范部署架构索引规则分页规范接口规范与行为指南Gdify是SpringBootPostgresRedisVue的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 示例 - 53001Agent 不存在 - 53002Agent 已停用 - 54001会话不存在 - 54002会话已关闭 - 55001文档解析失败 - 55002切片失败 - 56001工作流节点配置非法 - 57001MCP 工具未注册 ### 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 示例 - 53001Agent 不存在 - 53002Agent 已停用 - 54001会话不存在 - 54002会话已关闭 - 55001文档解析失败 - 55002切片失败 - 56001工作流节点配置非法 - 57001MCP 工具未注册 ### 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让它生成适合你项目的版本。思维方式比具体技巧更重要。每条规范追溯到一个架构决策颗粒度跟着问题走接受规范是渐进完善的。
