我第一次认真把 Claude Code 接进日常开发是在一个维护了三年多的 Python 服务上。功能改到一半它突然开始重写模块里的异常处理——不知道团队约定用自定义异常而不是裸 raise不知道测试命令要指定 service 目录更不知道 build/ 是生成产物、永远不该手动碰。那一刻我意识到问题不在模型能力而在我的项目里从来没有一份 AI 需要遵守的书面约定。Claude Code 这类跑在终端里的 AI 编程助手核心价值在于能直接读代码库、跑命令、改文件。但它默认不认识你项目的特殊规则。templates 解决的就是这个信息差把项目背景、代码规范、常用操作、角色分工写成结构化的 Markdown 文件让 Claude 在每次会话开始时就读进去。相当于给 AI 同事准备一份入职手册而且是入职第一天就能背下来的那种。这篇文章就围绕 claude-code-templates 展开。我会先讲清楚模板到底在解决什么再拆解一个模板仓库里常见的文件类型和职责接着给出一套可以直接抄的目录结构和编写方法最后聊聊我实际用下来踩过的坑以及模板体系怎么跟着项目一起成长。适合正在用 Claude Code 但总觉得它差一点意思的开发者也适合想在团队里统一 AI 协作规范的工程负责人。1. 没有模板的 Claude Code问题到底出在哪1.1 每次会话都是一张白纸很多人第一次用 Claude Code 的感觉是惊艳又失控。惊艳在于它能自己读代码、跑测试、改 bug失控在于它经常按自己的想法来和你项目里的实际情况对不上号。原因其实很简单每个新会话都是一张白纸它不会记住你上一个会话里交代过什么约定。我举一个最典型的例子。我的项目测试命令是poetry run pytest tests/service/第一次使用 Claude Code 时我口头告诉它测试用这条命令。这一个会话里它确实照做了。但第二天开新会话它又开始用pytest直接跑结果因为依赖环境不对测试一片红。这不是它笨是我没有把约定变成跨会话、跨项目的稳定输入。后来我把这类信息写进 CLAUDE.md问题就消失了。Claude 每次进入项目都会自动加载这个文件相当于每句话都在重复一遍测试请用这条命令。一次写入每次生效这才是模板和口头交代的本质区别。1.2 口头交代只活在一个回合里口头交代还有一个更隐蔽的问题它只对当前回合有效。你可以在对话中说接下来所有数据库操作都走 repository 层模型大概率会在这个会话里照做但过几个小时后它可能就忘了又开始在 service 里直接写 SQLAlchemy 查询。原因在于模型遵循的是最近上下文你的那句叮嘱被大量代码内容冲刷得越来越弱。而写入模板文件的规则不一样。它位于每条对话消息之前等效于每一轮 Claude 在回答前都会先看到数据库操作必须走 repository 层这条约束优先级被显著抬高。从信息论的角度看模板文件里的内容等于在有限上下文窗口里做了固定席位预留比一闪而过的口头指令要稳固得多。另一个现实场景是多人协作。同一个仓库三个开发者各自用 Claude Code各说各的话产出的代码风格天差地别。有人要求用单引号有人不管格式有人要求提交前必须跑全量测试。最后 git log 一团糟。模板仓库的价值就是把这些口头约定收敛成一份团队共同维护的书面规范。1.3 模板真正规范的三件事指令、记忆、角色我在整理模板的过程中发现不管什么项目需要规范的东西归根结底就三类。第一类是指令。测试怎么跑、lint 怎么执行、部署命令是什么、编译产物放哪这类操作型知识。Claude Code 自己不会魔法般地猜出你的工程用什么包管理工具更不知道编译参数里那些历史坑。指令类模板的价值是把怎么做变成可复用的标准动作。第二类是记忆。项目是干什么的、模块怎么划分、哪些目录是生成产物、哪段代码是大家公认的雷区。这类静态知识充当项目的长期背景让 Claude 在分析问题时不至于提出重写整个模块这种离谱方案。第三类是角色。让 Claude 以什么身份、用什么视角工作。是让它在代码评审时扮演一个挑剔的资深工程师还是让它在调试时扮演一个关注边界条件的测试人员不同的角色设定直接影响输出质量。这三点分别对应模板仓库里的三类核心文件CLAUDE.md、自定义斜杠命令和角色模板。下面详细拆开看。2. 拆开模板仓库每类文件都在干什么2.1 CLAUDE.md项目的入职手册CLAUDE.md 是 Claude Code 体系里最基础也最重要的模板文件。项目根目录下的CLAUDE.md会在每次会话启动时自动加载用户主目录下的~/.claude/CLAUDE.md则对所有项目生效。两者的关系类似于公司规章制度和个人工作习惯——全局的管底线项目的管具体。一份合格的 CLAUDE.md 内容应该包括项目一句话介绍和核心目标让 AI 快速进入语境架构速览包括各模块职责和依赖方向常用命令的完整写法比如启动、测试、lint、构建编码约定包括命名规范、错误处理习惯、日志方式不准动清单比如生成目录、锁定文件、某些历史悠久的兼容层常见的坑和已知注意事项我自己的经验是写了 CLAUDE.md 之后Claude 犯低级错误的频率至少下降一半。尤其是架构速览这一节价值远超想象。之前它经常在改一个路由函数时顺手重构了整个 service 层因为根本不了解模块边界。写清楚app/api/ 只做参数校验业务逻辑必须放 app/services/之后这种行为基本绝迹。2.2 自定义命令把高频操作变成一条斜杠指令CLAUDE.md 管知道什么自定义命令管做什么。在.claude/commands/或~/.claude/commands/目录下你可以放一些 Markdown 文件它们会变成终端里的斜杠指令。每个命令文件用一个 YAML frontmatter 做元信息常用的字段包括description描述命令作用这个会显示在斜杠命令的提示列表里argument-hint告诉使用者可以传什么参数allowed-tools限定这条命令执行时 Claude 能使用哪些工具命令正文就是一段结构化指令Claude 执行斜杠命令时会完整读取正文并按照正文里的步骤去执行。比如我写了一个/review命令专用于代码评审--- description: 对当前改动做一次完整代码评审 argument-hint: [可选] 指定文件路径 allowed-tools: Read, Bash --- 1. 如果没有指定参数先用 git diff HEAD 查看最近改动 2. 按以下顺序检查 - 正确性逻辑是否与既有行为一致 - 边界条件空输入、异常输入、并发场景 - 错误处理是否统一走 AppError有没有裸 raise - 日志是否有足够的关键日志是否误用 print - 命名是否与项目现有风格一致 3. 每个问题标注严重程度阻塞 / 建议 / 可选 4. 只在确实存在问题时给出修改建议不要擅自重写代码这套形式相当于把一次高质量评审的完整流程固化下来。没有命令模板时每次我都得在对话里重新描述一遍评审要求有了命令之后输入/review就得到一份格式统一的评审结果。而且allowed-tools限定了它只能用读和命令执行类工具有效防止 Claude 评审到一半突然开始改代码。2.3 角色模板让 AI 以固定身份切入如果说 CLAUDE.md 是给 AI 看的手册角色模板就是给 AI化妆上岗。在.claude/agents/目录下可以定义专门的子代理agent每个代理有独立的提示词、工具权限承担特定任务。我常用的一个角色模板是 code-reviewer--- name: code-reviewer description: 资深代码评审专家专注找问题不写代码 allowed-tools: Read, Bash --- 你是一名有十年经验的资深代码评审专家。你的职责是严格审查代码并输出结构化评审意见。 你不需要修改代码不要给出完整代码示例只需要明确指出问题和改进建议。 评审时重点关注 - 潜在的业务逻辑漏洞和边界条件缺失 - 错误处理是否完备有没有吞异常的情况 - 是否引入不必要的复杂度 - 测试覆盖是否充分 输出格式 - [阻塞] 必须修复的问题 - [建议] 建议改进的点 - [可选] 可忽略的细节这种角色模板的好处是隔离复杂度。评审任务不需要关心技术栈细节也不需要写代码把工具权限限定为只读和高频命令类后它的行为模式非常稳定。相比在同一个会话里让 Claude 既写代码又自审拆出专门角色评审质量会明显更高。2.4 hooks 与 settings容易被忽略的规矩文件模板不只是 Markdown 提示词。.claude/settings.json里的钩子配置和权限配置同样是模板体系的重要组成部分。钩子可以在工具执行前或执行后介入比如拦截某些危险命令或者在做完测试后自动把结果写回上下文。举个例子我服务里的build/目录是生成产物我不希望 Claude 手动修改它。光在 CLAUDE.md 里写禁止修改 build/其实不够模型在长篇对话里偶尔会忘记。处理办法是在 settings 里加一条 PreToolUse 钩子检查 Bash 工具的参数里是否包含对 build/ 的写操作一旦命中就阻止执行并提示。这种规则写在提示词里、强制落在钩子里的双保险模式我后面会再详细展开。3. 从零搭一套能落地执行的模板仓库3.1 仓库结构先想清楚怎么组织一个 claude-code-templates 仓库最重要的是结构清晰。我自己用的是基础模板 项目覆盖层的两级组织方式claude-code-templates/ ├── README.md ├── install.sh ├── base/ │ ├── CLAUDE.md │ ├── commands/ │ │ ├── review.md │ │ ├── test.md │ │ ├── fix.md │ │ └── commit.md │ └── agents/ │ ├── code-reviewer.md │ └── debugger.md └── projects/ ├── python-service/ │ └── CLAUDE.md ├── web-frontend/ │ └── CLAUDE.md └──># Python Service 项目约定 ## 项目一句话 订单履约服务的后端FastAPI PostgreSQL Redis。 ## 常用命令 - 启动本地服务: uv run uvicorn app.main:app --reload - 跑测试: uv run pytest tests/ -q - 代码检查: uv run ruff check app/ tests/ ## 架构速览 - app/api/ 路由层只做参数校验和响应组装 - app/services/ 业务逻辑层禁止直接操作数据库 - app/repos/ 数据访问层所有 SQLAlchemy 操作集中在这里 - migrations/ 数据库迁移由 alembic 生成不要手动改 ## 硬性约定 - 异常统一抛 AppError禁止裸 raise Exception - 日志使用 logging.getLogger(__name__)禁止 print - build/ 和 .venv/ 是生成目录永远不要修改 - 新增依赖必须更新 pyproject.toml 并在 PR 里说明原因 ## 已知的坑 - 本地 Redis 是弱依赖测试里不要依赖真实 Redis - app/utils/ 里的代码是历史遗留新增逻辑不要放这里这份模板每一条都是可以验证的具体规则没有任何废话。写 CLAUDE.md 的核心原则就一条每条内容都要能直接变成 Claude 的行动依据。比如禁止裸 raise Exception这种规则Claude 完全可以照做而注意代码质量这种表述则毫无价值AI 无法把它量化成具体行为。3.3 命令模板这么写才不浪费上下文命令模板的编写方法和 CLAUDE.md 类似但更强调可执行性。优质命令的特点是步骤明确、检查顺序固定、输出格式统一。我以/test命令为例来说明设计思路。如果直接对 Claude 说跑一下测试它会问你要跑哪些、用什么命令、不过怎么办来回浪费好几轮。封装成命令后--- description: 运行项目测试并生成问题摘要 argument-hint: [可选] 指定测试文件或目录 allowed-tools: Bash, Read --- 1. 如果有参数直接运行 uv run pytest 参数 -q 如果没有参数运行 uv run pytest tests/ -q 2. 根据测试输出判断失败原因是断言失败还是代码异常 3. 如果失败进一步读取对应测试文件和被测代码 4. 输出总结通过数 / 失败数 / 失败原因 / 建议修复方向注意这里我把失败后要读取对应代码也写进了命令流程里。不写的话很多情况下 Claude 只会把失败信息贴给你不会主动去分析根因。一条命令就是一个完整的操作工作流这是它和普通聊天最大的区别。argument-hint字段也别忽略。当用户输入/test app/api/order.py时参数会传给命令正文Claude 就知道让它测指定文件。参数设计得越清晰命令的适用范围就越广。3.4 一键安装与多项目同步模板仓库建好后最烦人的问题是怎么分发到各个项目里。我一开始是手动拷贝很快发现改模板时要同步好几个项目非常容易漏。后来写了一个安装脚本核心逻辑就是用软链接把仓库里的文件映射到对应位置#!/usr/bin/env bash # 同步 base 模板到用户级 ~/.claude 目录 set -euo pipefail REPO_DIR$(cd $(dirname $0) pwd) for f in $REPO_DIR/base/CLAUDE.md \ $REPO_DIR/base/commands/*.md \ $REPO_DIR/base/agents/*.md; do dest$HOME/.claude/$(basename $(dirname $f))/$(basename $f) mkdir -p $(dirname $dest) ln -sf $f $dest done echo 模板已同步到 ~/.claude项目级的同步稍微有讲究。如果这个项目是你个人在维护用软链接指回模板仓库就好如果是多人协作仓库我建议直接把.claude/目录提交进项目仓库让所有人都用同一套配置。软链接的优点是一处修改处处生效缺点是脱离模板仓库就没法工作提交进仓库则恰好相反。两种方式按团队协作模式取舍没有绝对的对错。4. 实测跑通后的四个坑每个都值得记一笔4.1 模板越长后面的对话越容易失忆这是我踩过最深的一个坑。一开始我以为模板越详细越好于是把团队 wiki、接口文档、部署手册全摘要进 CLAUDE.md写到四百多行。用了一周发现效果反而变差——会话刚开始时 Claude 表现很好但对话进行到中途它开始出现前后矛盾的行为比如忘记禁用 print 的约定甚至开始建议我修改 build/ 目录下的文件。后来我理解了原因CLAUDE.md 的内容会驻留在整个会话的上下文里占用的是宝贵的上下文窗口。模板越长留给代码和对话内容的空间就越小当上下文接近上限时模型会倾向于优先保留最近的信息早期的模板内容就被挤出了有效注意力范围。解决方法很简单CLAUDE.md 只保留最高优先级的规则详细的技术文档和背景资料让 Claude 按需读取而不是常驻内存。比如数据库操作必须走 repos/ 层这种高频约束放 CLAUDE.md某个接口的完整字段说明放在项目 docs 目录下需要时命令里指定Read docs/xx.md就好。核心模板瘦身之后会话稳定性明显恢复。4.2 命令撞名与优先级自定义命令多了以后另一个问题是撞名。Claude Code 自带一批内置命令如果你自定义的命令和内置命令重名或者用户级命令和项目级命令重名实际生效的可能是你不期望的那个。我有一阵子项目里突然不能用/init排查了很久才发现是模板仓库里放了一个同名命令文件把它盖住了。团队场景这个问题更隐蔽。假设你分发了一套模板给团队某个人自己又装了一套带review.md的命令模板那么同一台机器上这个人的行为就和别人不一样出现问题时很难复现。我现在的做法是给自定义命令加业务前缀比如ci-test、code-review、make-commit尽量避免使用test、review这种过于通用的名字。同时在模板仓库的 README 里维护一张命令注册表写明每条命令放在哪个作用域让使用者一眼看出哪些是内置、哪些是自定义。4.3 必须不等于会执行模板里写着永远不允许修改 build/ 目录但实际对话中 Claude 仍然可能在特定场景下动它。原因在于模型本质上是依据概率选择回复的它遵循的是最近上下文的整体语境。用户说了帮我清理一下项目空间它就可能把 build/ 当成可清理对象。这不是模型不听话而是提示词天然的局限性。模板是约定不是纪律。对于真正不能出错的约束需要用机制来保证。我在 settings 里加了钩子当 Claude 试图通过 bash 命令修改受保护目录时钩子直接拦截。另外自建了权限配置把危险操作设为需要人工确认。把安全关键约束从提示词层下沉到机制层这才是可靠的方案。4.4 模板更新后旧项目还在用老规矩模板是活的东西会跟着实践迭代。但如果你用拷贝方式分发模板那么每次更新后所有旧项目里的模板都是过期版本。我之前更新了代码评审命令的检查清单结果发现只有最近新建的两个项目在用新清单老项目依然执行旧流程。解决方法是软链接分发或者给模板文件加一个版本标记。我在 base/CLAUDE.md 的末尾加了一行template-version: 2.3.0安装脚本里可以对比版本号版本不一致就提示重新同步。另外注意一点CLAUDE.md 的修改只对新开始的会话生效已经在跑的会话不会热加载。改完模板后记得新开会话再验证。5. 进阶让模板体系跟着项目一起长大5.1 基础模板 项目覆盖层的组合模式前文提到了base/和projects/的两级结构实际使用中我还会在两者之间加一层团队覆盖层。基础模板管的是个人通用能力团队覆盖层放的是团队特有的约定比如提交信息规范、PR 描述模板、代码评审必须检查的清单项目覆盖层再放具体技术栈的信息。分层的好处是让模板适配不同粒度。你不会希望所有项目都背一份提交信息必须包含 issue 编号的规则但如果团队统一要求放到团队层就很合适。项目覆盖层只需要关心这个项目独有的架构和命令内容更短加载更快。三个层次叠加时注意优先级最具体的项目层优先避免冲突时规则打架。5.2 从个人沉淀走向团队规范当模板仓库从个人使用变成团队共享时重要的是区分硬规范和软建议。硬规范是团队必须执行且可以自动检查的比如测试必须通过、不允许使用明文密码、提交信息必须按格式软建议是高效但不强制的要求比如推荐在 service 层做参数组装。区分这两类的标准很简单违反硬规范会造成实际经济损失或事故违反软建议只是降低代码质量。把硬规范写进 CLAUDE.md 并在 hooks 层做强制拦截软建议留给角色模板和命令模板去引导。我见过一些团队把软建议当成硬规范写进模板导致模板越来越长Claude 的行为反而变得束手束脚——明明是一条建议模型却当成禁止连合理的变通都不敢做了。另外团队模板一定要有 owner。没有 owner 的模板仓库一周就会落伍因为没人负责检查旧规则是否还适用、新实践是否需要沉淀。这个角色不能是人人有责必须是具体某个人哪怕只是每两周花半小时维护。5.3 定期给模板减脂模板不是越写越多就好。前面说过上下文窗口有限每一条规则都有使用成本。我给自己定了一条规矩每两周回顾一次模板里的每一条规则凡是在实际对话记录中从未触发过价值的行为直接删掉或把详细版移到按需读取的文件里。有一个非常典型的例子。我最早在模板里写了一大段关于 Python 版本兼容性的说明后来发现当前项目根本没在 Py2 环境跑过这条规则一次都没用上反而每次会话都在占用上下文。删掉之后神清气爽。经过两三个月的迭代一个健康的模板通常会经历膨胀-收缩-稳定的过程一开始什么都想写后来发现真正高频生效的规则其实就那么二十来条模板最终会收敛到一个比较精简的状态。这很像我日常代码重构里的最简可维护集思想——留下的一定是经过实践检验、真正影响行为的东西。最后说一点我自己的感受。整理 claude-code-templates 这件事本质上不是在调教工具而是把团队里的隐性知识做了一次显性化。刚开始会有点痛苦因为你会发现在这之前很多约定从没有被写下来过。但一旦写下来AI 变得好用只是副产品最大的受益者其实是刚加入项目的人以及三个月后的自己。我的建议是别追求一次到位先放一条命令、一份项目说明用起来之后再慢慢加。模板是活的东西它不是配置文件的堆砌而是你和你的工具之间越来越默契的语言。
