当前位置：首页 > news >正文

第6节：CLAUDE.md、Skills 与工程规范

news 2026/5/12 3:24:32

AI编程企业级实战

上一节：第5节：部署架构、性能预判与数据设计

本节：第6节：CLAUDE.md、Skills 与工程规范

下一节：待更新

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

它是什么？一个放在项目根目录下的Markdown文件。Claude Code每次启动新会话时自动读取，你不需要手动喂。它就是你和Claude Code之间的“合作协议”——项目是什么、代码怎么组织、有哪些规矩。

它的生效范围？项目根目录的CLAUDE.md对整个项目生效。你也可以在子目录下放CLAUDE.md，它只对那个目录下的代码生效，比如hify-web/下放一份前端专属的规范，hify-chat/下放一份对话引擎的特殊约定。子目录的规范会和根目录的叠加，不会覆盖。

它的结构怎么组织？前三讲我们已经实践了从宏观到微观的五层：

项目上下文：这是什么项目，做什么不做什么（第03讲）
架构规范：模块划分、依赖关系、外部调用处理（第04讲）
代码组织规范：分层结构、Controller/Service/Mapper 职责（第04讲）
部署与数据库规范：部署架构、索引规则、分页规范、pgvector（第05讲）
接口规范与行为指令：这一讲补完

接口规范

## 接口规范 ### 路径 RESTful 风格：/api/v1/{资源复数名} GET /api/v1/providers # 列表（分页） POST /api/v1/providers # 创建 GET /api/v1/providers/{id} # 详情 PUT /api/v1/providers/{id} # 更新 DELETE /api/v1/providers/{id} # 删除 POST /api/v1/providers/{id}/test-connection # 非 CRUD 操作用动词 ### 统一响应所有接口返回 Result<T>： { "code": 200, "message": "success", "data": {...} } ### 分页请求：page（从 1 开始）、pageSize（默认 20，最大 100）响应：Result<PageResult<T>>，PageResult 包含 list、total、page、pageSize ### 空值 - 列表字段空时返回 []，不返回 null - 字符串字段空时返回 ""，不返回 null - 对象不存在时返回 null ### 错误码四位数字，按模块分段： 1000-1999 通用 | 2000-2999 Provider | 3000-3999 Agent 4000-4999 Chat | 5000-5999 MCP | 6000-6999 Workflow | 7000-7999 Knowledge

行为指令

行为指令是CLAUDE.md里最容易被忽略但最有用的部分。它不是约束代码风格，是约束Claude Code的“行为模式”——遇到不同情况该怎么行事。

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

“改代码时”这三条是从实际踩坑中来的。第02讲提过，Claude Code改一个模块时会顺手改别的模块，破坏已有接口。写了这三条之后，它在修改代码前会先说“我理解这个模块的设计意图是……我打算改动……不会影响……”，给你确认的机会。

“不确定时”也很重要。不写这条，Claude Code遇到规范没覆盖的情况会自己编一套规矩，每次编的还不一样。写了之后，它会主动问你，而不是自作主张。

到这里，CLAUDE.md的五层全部补完了。

接口契约：模块级的蓝图

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

用Provider模块举个例子：

# Provider 模块接口契约GET /api/v1/providers 描述：分页查询提供商列表参数：page, pageSize, name(可选，模糊搜索) 响应：Result<PageResult<ProviderListResp>>POST /api/v1/providers 描述：创建提供商请求体：ProviderCreateReq { name, type, apiKey, baseUrl } 响应：Result<Long>DELETE /api/v1/providers/{id} 描述：删除提供商（需检查是否有 Agent 在使用）响应：Result<Void>POST /api/v1/providers/{id}/test-connection 描述：测试连通性响应：Result<ConnectionTestResp> { success, latencyMs, errorCode, errorMessage }

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

在这一步我希望你学到的，不是Hify的接口怎么定义。而是比如你现在已有一个项目，你要添加功能，你怎么快速让Claude Code帮你提出当前的规范，并沉淀为CLAUDE.md，从而让接下来的开发顺起来。或者你全新开发一个项目，怎么快速有你的规范。

Skills：可复用的规范片段

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

Skills 是什么？一个放在 .claude/skills/ 目录下的Markdown文件，描述一类任务的标准做法。Claude Code 在执行任务时会自动匹配相关的 Skill。

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

举个例子。后面每个模块开发前都要写接口契约，我把这个过程标准化成一个Skill：

# 接口契约设计 Skill ## 触发条件当需要为一个新模块设计接口契约时使用。 ## 步骤 1. 列出这个模块的核心业务操作（创建、查询、更新、删除、特殊操作） 2. 每个操作定义：HTTP 方法 + 路径 + 入参 + 出参 3. 路径遵循 /api/v1/{资源复数名} 格式 4. 所有接口返回 Result<T> 5. 列表接口支持分页（page, pageSize） 6. 删除接口标注是否需要关联检查 7. 非 CRUD 操作用动词路径（如 /test-connection）

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

用业界规范喂 Claude Code

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

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

比如Java编码规范。阿里巴巴Java开发手册、Google Java Style Guide都是业界公认的标准。你不需要自己读完几十页再手写，让Claude Code消化后帮你提炼：

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

Claude Code会生成一份精简版——不是把整本手册塞进去（那太长了，稀释重点），而是提炼出对AI写代码最关键的条目。你review一遍，删掉不适用的、调整措辞，就能直接用。

同样的思路适用于数据库规范：

基于业界MySQL设计规范（阿里巴巴MySQL规范、互联网公司常见的MySQL最佳实践），帮我补充Hify项目的数据库规范。

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

当然，现在业界发展出了很多开发框架，会内置这些规范，但是我希望你知道最底层是什么，而不是直接用别人封装好的。

背后的思维方式

前面都是具体技巧，这一节聊一个更本质的问题：怎么判断一条规范该不该写进 CLAUDE.md？

格式不难，难的是你要知道该写什么。

从架构决策推导规范。选了模块化单体，目的是以后能拆分微服务。从这个决策推导出“跨模块走Service接口，不直接引用其他模块的Mapper”。这条规范不是凭空想出来的，是架构决策的必然要求。你写CLAUDE.md时，每条规范都应该能追溯到一个架构决策或一个具体问题。追溯不到，就没必要写。
规范颗粒度跟着问题走。Claude Code反复跑偏的地方写细，不跑偏的地方不写。“文件编码用UTF-8”，它基本不会搞错，不值得占篇幅。“Controller不写业务逻辑”，它经常犯，必须写。你的注意力放在它真正容易犯错的地方。
规范是长出来的，不是设计出来的。Hify的CLAUDE.md从半页纸到现在的完整版，没有一条是提前想出来的，全部是在实际开发中遇到问题后补上去的。SDD闭环就是这个过程，每次AI跑偏，问自己是不是规范没覆盖到，然后补上。接受规范是渐进式完善的，不要追求一次写完。

总结就是：让业界标准规范为基准，逐步补充满足项目自身特点的规范。