打造 Claude Code 模板：让 AI 助手记住你的项目规范与工程约定

如果你已经开始用 Claude Code 写代码，大概率会和我经历同样的阶段——刚装上觉得是真香，用上一周就开始嫌弃。明明项目里早就写好的代码风格、目录结构、测试要求，每次新开一个会话它都忘得干干净净；同一个坑反复踩，同样的规范翻来覆去地讲，讲到后面我都怀疑自己在跟一个失忆的实习生配合。直到我把这些经验和约束整理成一套 claude-code-templates，这个问题才算真正从根上解决。

这篇文章想把我整理 Claude Code 模板的完整思路一次讲清楚：为什么模板能解决“AI 记不住项目约定”这个核心痛点，一套完整的模板体系应该包含哪些层次，以及一份能直接抄走的生产级 CLAUDE.md 和斜杠命令应该怎么设计。适合正在用 Claude Code 提效但又觉得它“不够懂你”的开发者，也适合准备给团队统一引入 Claude Code 的工程负责人。不管你是刚接触 CLI 编程助手的新手，还是已经折腾过一阵子的老手，这篇文章里都应该有一两段能让你拍大腿的东西。

1. 为什么需要模板，模板到底解决了什么问题

1.1 没有模板时，AI 为什么总在重复犯错

先说一个很现实的现象：Claude Code 每次启动新会话时，它对项目的了解程度约等于一个刚被拉到群里的新人。它能读你的代码仓，能看你的 README，也能执行命令，但它默认不知道你心里那套“约定俗成”的东西。

我举个例子你就有体感了。之前我给一个支付服务接新渠道，项目里明确要求金额计算必须用Decimal禁止float，Claude Code 在同一个会话里写得规规矩矩，可一旦把上下文清掉重新开对话，它又开始用float算金额。我最初的做法是在每次对话开头手动把这条规则粘进上下文，后来规则越来越多，一段话从三行涨到三十行，最后我比它还先崩溃。

这就是没有模板时的核心问题：规则存在于人脑里，而不在任何 AI 每次启动都能读取的地方。你可能会说，不是有记忆功能吗？但记忆是碎片化、口语化的，而且更像是个人偏好，不是项目级的工程约束。另外一个容易忽略的点是：README 这种文档通常讲“项目是什么”“怎么跑起来”，很少把“不许这么写代码”“新文件必须放在哪个目录”这类规范性动作写进去。AI 读了 README，依然不知道你的红线在哪。

1.2 模板的本质：把“约定”从人脑搬进仓库

我自己后来琢磨明白了一件事：模板的本质，是给 AI 写一本入职手册。新人入职第一天，你给他什么，他学什么；你只给他代码仓库，他就只能顺着仓库里的惯性写代码。但如果你把工作流、代码风格、目录规则、红线约束都写成一本书让他先读，他的产出就会从一开始就贴着项目标准走。

具体到 Claude Code，这套“入职手册”通常由三层组成：CLAUDE.md（项目级规则）、斜杠命令（可复用工作流）、技能与代理（能力包和角色）。第一层解决“AI 知道规矩”，第二层解决“AI 按流程干活”，第三层解决“AI 具备领域能力”。这三层合在一起，就是我理解的 claude-code-templates 全景。

我踩过的坑是：早期我只写了一个 CLAUDE.md，就以为万事大吉，结果发现规则确实记住了，但每次让它干一个稍复杂的事，比如“给一个新模块生成四层代码并补测试”，它还是我行我素，顺序乱走。后来我把这套流程做成了斜杠命令，它才开始稳定地按步骤执行。这就是为什么模板不能只写一份文档，而是要搭一个体系。

2. 模板体系设计：把 CLAUDE.md、斜杠命令、技能组织成完整链路

2.1 CLAUDE.md：项目级“工作手册”

CLAUDE.md 是整个模板体系的地基，它是一份 Markdown 文件，Claude Code 每次启动会话时都会自动读取并把它作为背景知识加载。按我习惯的放法，项目根目录放一份CLAUDE.md管整个项目，如果有必要还可以在复杂的子目录里放局部版本，用户主目录下放一份全局的~/.claude/CLAUDE.md管个人偏好。加载优先级我是按“局部覆盖全局”来理解的：子目录的最优先，然后是项目根目录，最后才是用户全局目录。

关于 CLAUDE.md 的内容，我的建议是只写“结论性规范”，不要写背景故事。它的结构可以按这几个区块组织：项目背景、技术栈、目录结构与新文件落位规则、代码风格、测试要求、常用命令、开发红线。每一句话都应该是“AI 可以照着执行”的动作，而不是“这个项目创建于 2023 年”这类陈述。比如“禁止在路由层直接处理业务逻辑”就是有效的规则，“请尽量写出优雅的代码”就是没用的废话。

我自己会刻意控制 CLAUDE.md 的长度，项目级文件一般压在一百到一百五十行以内。写太长有两个问题：一是占了大量上下文窗口，影响对话质量；二是太长的规范本身就是噪音，AI 反而抓不住重点。如果规则很多，我会把详细操作步骤拆到斜杠命令里，CLAUDE.md 只保留高频复用和最硬的红线。

2.2 斜杠命令：把高频工作流变成可复用按钮

如果说 CLAUDE.md 是手册，斜杠命令就是宏。Claude Code 支持自定义斜杠命令，我们团队一般把它们放在项目的.claude/commands/目录下，每个命令是一个带元信息的 Markdown 文件。它的妙处在于：命令只有在被调用的时候才会加载，所以哪怕里面写了几十行详细步骤，也不会常驻占上下文。这一点对长会话非常友好。

一个完整的命令文件长这样：

--- name: api-module description: 新增一个 API 模块，按四层结构生成代码并补测试 --- 你是一个资深后端工程师，请按以下步骤完成新 API 模块“$ARGUMENTS”的开发： 1. 先阅读项目根目录 CLAUDE.md，确认目录结构与代码约定。 2. 按“路由-服务-模型-测试”四层结构创建代码。 3. 模型层字段要加注释，包含 created_at 和 updated_at。 4. 服务层必须写结构化日志，返回值用 Pydantic schema 封装。 5. 写完代码后立即运行 ruff check 和 pytest，直到全部通过。 6. 最后输出本次新增/修改文件的清单，供我 review。

文件头部那个 YAML 块里的name就是斜杠命令名，description是 AI 判断何时使用该命令的依据，正文里的$ARGUMENTS是用户在斜杠命令后输入的内容占位符。这种设计特别适合“固定流程+变化参数”的场景，比如“生成新模块”“修一个 bug 并写测试”“给某接口做安全审计”。

2.3 技能与代理：模板的进阶打开方式

在同一套模板体系里，比斜杠命令更进一层的是技能和代理。技能我更愿意把它理解成“能力包”，它把某类任务的高频知识、样例、判断标准打包起来，让 AI 遇到相关场景时能主动调取；代理则是“角色”，相当于一个预先设定好人设和职责范围的专属助手，比如“代码审查员”“测试负责人”“数据库迁移专员”。

在实际项目中，技能适合沉淀领域知识。比如我做过一个金融类项目，把“支付金额计算规范”“敏感数据脱敏规则”“SQL 审计要求”做成了一个技能包，Claude Code 在处理相关代码时就能自动按这套知识去判断。代理则适合固定岗位，我会让一个子代理专门负责代码评审，它的系统提示里写清楚了审查标准和输出格式，评审结果从头到尾是同一个风格，不会因为当天上下文不同而变化。

我的体会是：斜杠命令管“动作”，技能管“知识”，代理管“角色”。如果你的使用场景只是个人提效，斜杠命令和 CLAUDE.md 基本够用；如果是团队用，技能和代理带来的收益会明显更大，因为它们解决了个体差异的问题。

3. 实操：手写一套可落地的项目模板

3.1 写模板之前，先盘一遍项目现状

很多人拿到模板方案第一反应是埋头开写，我劝你先花半小时盘一下项目现状。直接写最容易出现两种后果：要么模板内容过于理想化，AI 照着执行反而破坏了现有多样性；要么漏掉最关键的约束，写完之后该犯的错照样犯。

我会按下面这个清单收集素材：

• 项目目录结构长什么样，新代码默认放哪，有没有已经约定俗成的落位规则。
• 技术栈清单，包括语言版本、框架、ORM、数据库、队列、部署方式。
• 常用命令集，比如启动开发环境、跑测试、跑 lint、生成迁移文件、格式化代码。
• 代码风格门槛，比如类型注解规范、错误处理统一方式、日志格式要求。
• 不变量和红线，比如金额不能用浮点、不能直接改表结构、禁止在路由里裸抛异常。
• 团队协作习惯，比如分支命名、commit 规范、review 需要什么信息。

这个盘点的输出不用很长，每个类别抓住真正重要的三到五条即可。宁缺毋滥。我见过最失败的 CLAUDE.md 是把整个 README 复制了一遍，AI 是记住了，但真正该记住的部署红线一条都没进去，等于浪费上下文。

3.2 一份能直接用的 CLAUDE.md 示例：Python FastAPI 支付服务

盘完现状之后，我拿一个真实的 Python FastAPI 支付类服务举例，给你看一份能直接抄走的 CLAUDE.md。为了让你直接对号入座，我用了一个虚构的payment-gateway项目。

# 项目手册：payment-gateway ## 项目背景 支付网关服务，对内提供统一支付接口，对接微信支付、支付宝、模拟网关。 当前阶段重点：新增钱包余额功能，同时保证存量接口兼容。 ## 技术栈约定 - Python 3.11 + FastAPI + SQLAlchemy 2.0 + Alembic - 数据库：PostgreSQL 15，schema 名为 payment - 异步：asyncpg + SQLAlchemy async session - 队列：Celery + Redis；定时任务使用 celery beat - 部署：Docker Compose，编排配置见 docker-compose.yml ## 目录结构与新文件的落位规则 - app/api/v1/：路由层，只做参数校验与响应组装 - app/services/：业务逻辑层，按业务模块拆分 - app/models/：SQLAlchemy 模型，不含业务逻辑 - app/schemas/：Pydantic 请求与响应模型 - tests/：单元测试与接口测试，命名与模块对应，如 test_services_payment.py 新功能必须按“路由-服务-模型-测试”四层结构落位。 ## 代码风格与约定 - 使用 from __future__ import annotations，所有类型注解必须写全 - 错误处理统一走 app/exceptions.py 自定义异常，禁止在路由里裸抛 HTTPException - 日志统一使用 structlog，字段格式：event、level、request_id、user_id - SQLAlchemy 查询统一使用 select() 写法，不使用方法链式查询 ## 测试要求 - 新功能必须补测试，核心服务单测覆盖率不低于 85% - 测试命令：pytest -x -q tests/ - 冒烟测试：pytest -m smoke tests/ - 运行测试前需确保 test DB 已启动：docker compose up -d postgres-test ## 常用命令 - 启动开发环境：docker compose up -d && uvicorn app.main:app --reload --port 8000 - 数据库迁移：alembic upgrade head - 跑 lint：ruff check app tests - 格式化：black app tests ## 开发红线 - 修改数据库结构必须生成 Alembic 迁移文件，禁止直接改表 - 涉及支付金额的计算一律使用 Decimal，禁止使用 float - 外部 API 调用超时不得低于 3 秒，所有请求必须注入 trace_id - 禁止把密钥、token、第三方凭证写入代码或日志

这份 CLAUDE.md 的思路就是“每一段对应 AI 做决策的一个维度”。当它新建文件时，查“目录结构”；当它写函数时，查“代码风格”；当它动数据库时，查“开发红线”。段落之间没有废话，也没有任何需要 AI 去猜的形容词。你要做的就是把它改成自己项目对应的内容，半小时就能完成。

3.3 把“新增一个 API 模块”做成斜杠命令

CLAUDE.md 解决的是“知道规矩”，但规矩再多，AI 执行复杂任务时的步骤还是容易乱。我习惯的做法是把高频任务拆成一个完整的斜杠命令。下面是一个命令文件，我会把它放在.claude/commands/api-module.md：

--- name: api-module description: 新增一个 API 模块，按四层结构生成代码并补测试 --- 基于项目 CLAUDE.md 中的目录结构和代码约定，为“$ARGUMENTS”新增一个完整 API 模块： 1. 先阅读 CLAUDE.md，确认技术栈与代码风格。 2. 创建以下四个文件： - app/api/v1/<module>.py：路由层，只做参数校验和响应组装 - app/services/<module>.py：业务逻辑层 - app/models/<module>.py：SQLAlchemy 模型 - tests/test_services_<module>.py：服务层单元测试 3. 模型层统一包含 manager、status、created_at、updated_at 字段并加注释。 4. 服务层调用任何外部依赖前先打印结构化日志，包括入参和 trace_id。 5. 所有返回数据必须用 Pydantic schema 封装后再交给路由层。 6. 完成后依次运行 ruff check 和 pytest -x -q tests/test_services_<module>.py。 7. 如果测试失败，修复后重新运行，直到全部通过再汇报。 8. 最终输出新增或修改的文件清单，标注每个文件的职责。

实际使用时，我只需要敲/api-module user-wallet，Claude Code 就会按这套流程生成user-wallet模块，从建文件、写代码到跑测试整体走一遍。相比每次都要手动输入一长串要求，这种命令既省时间又稳定，而且因为整段流程只在调用时加载，平时根本不占用上下文空间。

3.4 用全局模板统一个人风格

项目级模板解决的是“这个项目怎么开发”，全局模板解决的是“我这个人喜欢怎么写代码”。我在~/.claude/CLAUDE.md里会放一些跨项目通用的偏好，比如注释要写中文、commit message 用 Conventional Commits 规范、不要随意删除未确认的代码、生成代码时优先复用项目中已有的工具函数而不是新造轮子。

这些偏好单看每条都不重，但累积起来效果很明显。特别是跨多个项目时，如果没有全局模板，我每进入一个新项目都要重新把自己的习惯交代一遍。现在这些个人偏好会自动带进每一个会话，我只需要靠项目级 CLAUDE.md 来区分不同项目的特殊规则。

有一点要注意：全局模板别写得像个人日记。我见过有人在全局文件里写了一堆“我很喜欢 cleartype 字体”之类的私人偏好，反而干扰了 AI 对代码的判断。全局文件同样要遵守“只说可执行规范”的原则。

4. 常见问题与排查技巧实录

4.1 CLAUDE.md 修改了但没生效

这个问题我印象最深，因为它藏得最深。CLAUDE.md 是在会话启动时被加载进上下文的，如果你正在一个会话里修改了它，当前会话并不会重新加载，你继续对话时会发现 AI 好像看不见新规则，这不是你写错了，而是它压根没来得及读。

所以遇到 CLAUDE.md 改了没效果，第一步就是开一个新会话再试。如果新会话还是没效果，再检查几件事：文件是不是真的命名为CLAUDE.md，是不是放在了正确的位置，以及文件有没有被你用什么工具链误打进了 gitignore 或对应的 ignore 列表。我实际踩过的坑是把文件名写成了CLAUDE.md.txt，Windows 用户尤其容易犯这种错，记事本一存就帮你把扩展名改了。

如果你想确认 AI 到底加载了哪些内容，可以直接在对话里要求它列出当前生效的项目规范，它通常会把加载到的规则摘要展示出来。看到摘要那一刻，你就能立刻发现哪条规则写错了地方，或者根本没被加载。

4.2 模板越写越长，上下文空间不够用

CLAUDE.md 默认常驻上下文，所以它每多一行，你的对话空间就少一行。当模板变得越来越详细，你会发现 AI 回答变慢了、开始忘记你刚说过的要求，这是因为可用上下文被规则占掉了。

我的经验是把模板内容按“常驻”和“按需”分开。CLAUDE.md 只保留每个会话几乎都会用到的核心规范，控制在 15KB 以内比较合适；那些只有特定任务才会用到的详细步骤，全部挪到斜杠命令或技能包里。例如“发布流程”这种不是每次写代码都用得上的内容，我会把它做成/release命令，而不是写进 CLAUDE.md。这样上下文空间被释放出来，AI 的短期记忆质量明显提高。

如果你确实有大量规则要维护，可以考虑定期清理 CLAUDE.md 里已经融入代码库惯性的规则。比如当整个代码库已经自然采用了某个命名规范，就没必要再写了，AI 能自己从上下文里学到。

4.3 斜杠命令撞车与加载优先级

斜杠命令多起来之后，你可能会遇到“AI 选了错误的命令”或者“命令直接被覆盖”的情况。项目级.claude/commands/和用户级~/.claude/commands/如果存在同名文件，项目级会优先；同目录下出现同名文件则是后加载的覆盖先加载的，但这个顺序在不同版本里表现不一定一致，所以最稳妥的办法就是用命名空间前缀避免冲突。

我给团队建议的命名方式是按领域加前缀：api-开头是接口相关，>