如果你在项目里用过一段时间 Claude Code应该很快会撞到同一个问题同一个模型、同一个仓库今天它对需求的理解和上周完全不一样换个项目更是像换了个人。问题多半不是出在模型身上而是你根本没有给它一套稳定的“工作规则”。我整理这套 claude-code-templates就是把散落在多个项目里的规则文件、提示词、命令脚本、hook 配置全部沉淀成一套可以直接复用的模板集。它解决的是三件事让 AI 按照统一规范工作、把高频操作固化成命令、让多个人和多个项目共享同一套行为约束。适合已经装好 Claude Code 但还没系统配置过规则文件的开发者也适合想给团队统一 AI 协作方式的人。1. 这套模板到底解决什么问题1.1 从“每次从头写提示词”到“一套配置跑多个项目”Claude Code 这类 AI 编程助手最典型的用法是你在终端里扔一句“帮我实现登录功能”它就开始读代码、猜需求、动手改。前面几次确实快但用久了就会发现这个“快”是拿后续的返工时间换的。模型对项目的上下文一无所知它不知道你团队用不用 TypeScript不知道你的测试框架是哪一家更不知道“改完代码必须跑一遍 lint”是你的红线。于是你开始复制粘贴一大段项目说明到对话里今天粘一份明天粘一份稍微换个人协作又得重新粘。这就是最原始的“模板需求”——把重复的指令内容沉淀成文件让 Claude Code 每次启动时自动加载。我在早期尝试时就走过这个弯路把一大堆要求写在系统提示词里每次开会话都要带进去token 费了一堆效果还不稳定。后来才意识到真正的解法是把规则放到项目目录里让 AI 自己读取。这就是 CLAUDE.md 文件存在的意义它相当于一份“给 AI 看的 README”既说明项目背景也规定行为方式。模板的核心价值就是把这层配置做成一套开箱即用的骨架而不是让每个项目从零开始重写。1.2 模板不是提示词收藏夹而是一套工程化配置很多人以为 Claude Code 模板就是“提示词合集”这是误解。提示词收藏夹只解决单次对话质量而真正的模板集要解决的是工程协作问题。一个合格的模板集至少包含四层内容规则层CLAUDE.md、AGENTS.md 这类记忆文件定义角色、流程、红线命令层自定义斜杠命令比如 /test、/review、/commit把高频操作变成一键触发钩子层hooks 脚本在 AI 执行工具的某些节点自动检查质量、拦截错误脚本层辅助脚本用于格式化代码、收集测试反馈、提交前检查等。为什么一定要分这么多层因为职责单一原则同样适用于 AI 配置。如果所有约束都堆在一个 CLAUDE.md 里文件会越来越长模型读到后面就忘了前面而且规则之间互相干扰。命令层和钩子层的存在能让 AI 在正确的时机调用正确的逻辑而不是靠“记忆”去承载所有行为。我可以负责任地说一个项目只要跑顺过这套分层模板再让它去处理一个新的类似项目效率提升是肉眼可见的。因为模型不只是在“理解代码”它还在“理解这个项目的协作方式”而协作方式恰恰是它以前最欠缺的信息。2. 规则层模板设计CLAUDE.md 与 AGENTS.md 到底怎么写2.1 CLAUDE.md 主规则角色、流程、红线CLAUDE.md 是模板里最核心的文件它决定了 AI 对整个项目的基本认知。我写这个文件的时候坚持一个原则只写模型必须知道且需要长期遵守的内容不写临时指令。一份好的 CLAUDE.md 通常包含以下结构# CLAUDE.md ## 角色定位你是谁 你是本仓库的一名资深全栈工程师负责在 project-name 中实现需求。 你的目标不是“写最快”而是“写最少的问题”优先保证可维护性。 ## 工作流程先怎么做后怎么做 1. 接到新需求先读 README 和相关模块结构明确改动范围。 2. 任何超过 50 行的改动先向用户输出实现方案确认后再编码。 3. 代码改动之后执行 npm test确认无回归再结束任务。 4. 提交信息遵循 Conventional Commits 规范。 ## 代码风格硬性要求 - TypeScript 优先禁止使用 any。 - 组件函数使用大写驼峰命名事件处理函数统一以 handle 开头。 - 单元测试使用 Vitest测试文件放 __tests__ 目录不允许跳过测试。 ## 红线绝对禁止 - 不得修改 package-lock.json除非用户明确要求。 - 不得绕过 ESLint 规则更不允许在代码里加 eslint-disable 注释。 - 不跨越包与包之间的边界自由 import 内部模块必须通过对外导出。这个文件写完之后最关键的一点是把它交给模型“读取”而不是“描述”。Claude Code 在启动时和代码变更时会自动加载项目根目录下的 CLAUDE.md所以你不必在每次对话里重复这些内容。实际操作中我踩过的一个坑是把 CLAUDE.md 写得像项目百科连数据库连接地址、第三方服务密钥都写进去了。这完全没必要。模型需要的是“行为约定”不是机密信息。而且这类敏感信息写进去一旦文件被同步到仓库泄露风险很大。CLAUDE.md 应当像一份团队新成员入职手册而不是运维手册。2.2 AGENTS.md 子代理分工什么时候需要一份“规定动作”AGENTS.md 是比 CLAUDE.md 更细粒度的规则文件它主要针对多代理协同的场景。如果你只是单人在单仓库里用 Claude Code一个 CLAUDE.md 通常够用。但一旦项目变大或者你想让 AI 在特定领域比如文档、数据库迁移、代码评审保持不同的行为方式AGENTS.md 就很有用了。我通常把 AGENTS.md 放在子目录里形成分层规则。比如在 docs/ 目录下放一份 AGENTS.md里面写# AGENTS.md for docs/ 执行本目录下的任务时你是一名技术文档工程师。 - 文档命名必须与 API 名称对应比如 user-api.md。 - 每个文档必须包含功能说明、参数表、示例、错误码。 - 不要直接在文档中嵌入内网 IP 或真实令牌一律用占位符。这样做的逻辑很简单规则离代码越近越容易被模型注意到。当 AI 处理 docs/ 目录下的文件时它会优先读取这个子目录里的 AGENTS.md而不是翻到仓库根目录去找主规则。我实测下来这种“就近原则”比把所有内容塞进一个 CLAUDE.md 要可靠得多也不容易产生规则覆盖的混乱。2.3 变量与占位符模板怎么适配不同项目模板最大的特点是可以复制但直接复制往往不能用因为每个项目的角色定位、包管理工具、测试框架都不一样。所以我在模板里做了一个很关键的约定用占位符代替硬编码。比如上面的 CLAUDE.md 里project-name、npm test、Vitest 这些内容在模板里都写成可替换的变量。初始化模板时我会先运行一个初始化脚本把占位符替换成实际值。这一步看似简单却避免了一个常见问题AI 宁可相信模板里的“默认值”也不愿花时间去读真实的 package.json。你给它一份写着“使用 Mocha 测试”的模板它就真的往项目里装 Mocha哪怕你项目里用的是 Jest。所以变量替换这一步绝对不能省。一个靠谱的模板集必须配套一个初始化脚本把占位符、项目名、测试命令、代码规范这些内容一次性替换到位。不要低估这一步的价值我在一个客户项目里见过 AI 连续三次按照模板里的旧框架生成代码就是因为模板没有完成替换。3. 命令层模板把高频操作变成斜杠命令3.1 自定义 slash commands 怎么注册Claude Code 的斜杠命令本质上就是存在 .claude/commands/ 目录下的 Markdown 文件文件名就是命令名。你输入 /test它就读取 test.md 并执行里面的指令。这个机制的妙处在于它把“上下文 行为”绑定成了一个稳定入口。一个命令文件长这样--- description: 运行测试并反馈结果 argument-hint: [可选] 测试名称过滤 --- 运行测试并给出结果总结 - 执行 npm run test:unit -- filters - 若测试失败列出前 3 个失败用例及对应堆栈 - 分析失败原因是断言逻辑问题还是业务代码问题 - 针对失败原因给出修复建议但不要直接修改代码除非用户明确同意。为什么要把这些内容写成文件而不是每次手打因为命令文件里包含了两层价值一是操作流程的标准答案二是行为边界的预设。比如上面最后一条“不要直接修改代码”就是防止 AI 在前置任务还没确认时就越权乱改。注册命令之后团队里任何人敲 /test 都能得到一致的流程不会因为某个人少说一句话导致结果不同。3.2 /review、/commit 三个模板拆解除了测试命令我最常用的三个命令是 /review、/commit 和 /fix。它们的模板在设计上各有侧重。/review 命令的核心是“独立评审视角”避免 AI 陷入“自己写自己评”的怪圈。模板里我会强调--- description: 审查当前未提交的改动 --- 审查当前 git diff 内容重点检查 1. 是否有明显逻辑错误或边界遗漏 2. 是否遵守项目 CLAUDE.md 中定义的代码风格 3. 是否遗漏错误处理路径 4. 是否引入安全风险如拼装 SQL、硬编码密钥。 输出格式按严重程度分为 P0/P1/P2 列出问题每条附上对应代码位置。/commit 命令则相反它要求 AI 先总结 diff再生成符合规范的提交信息--- description: 生成提交信息 --- 把当前暂存区的改动整理成 Conventional Commits 格式的提交信息。 先输出改动摘要再按 type(scope): subject 格式生成提交标题。 如果存在破坏性变更必须在正文中注明 BREAKING CHANGE 及其影响。这两个命令放在同一个项目里正好形成一收一放/review 是收紧环节/commit 是收尾环节。两者都写成模板最大的好处是 AI 不会因为“用户没要求”就跳过质量检查。3.3 hooks 脚本在关键节点自动卡质量命令是主动触发的而 hooks 是被动触发的。Claude Code 支持在工具调用的前后执行脚本这个能力非常值得在模板里用起来。最常见的做法是配置 PreToolUse 和 PostToolUse 钩子。举一个实测的配置例子。我想确保 AI 不会绕过测试目录的命名规范于是在 .claude/settings.json 里加了这样的 hook{ hooks: { PreToolUse: [ { matcher: Write, hooks: [ { type: command, command: .claude/hooks/check-test-path.sh \$CLAUDE_TOOL_INPUT\ } ] } ] } }对应脚本 .claude/hooks/check-test-path.sh 的核心逻辑是如果本次 Write 的目标路径是测试文件就校验路径是否以tests开头不满足则输出错误并以非零码退出从而阻止 AI 把测试文件写到乱糟糟的位置。hook 配置最值得注意的地方是它的退出码。脚本输出到 stderr 的信息会被 Claude Code 捕捉退出码非零会中断当前操作。所以写 hook 脚本时要区分“警告”和“阻断”两种力度。大部分场景用警告就够了频繁阻断反而会让 AI 的任务执行变得碎片化影响整体效率。4. 实操过程从零初始化一套项目模板4.1 五步初始化复制、替换、注册、验证现在我把这套模板落到一个新项目里整个过程分五步复制模板骨架把 .claude/ 目录和根目录的 CLAUDE.md、AGENTS.md 复制到目标项目。执行变量替换运行初始化脚本把占位符替换为真实项目名、包管理工具、测试命令。这一步一定要显式执行不能靠 AI 自己推断。注册命令脚本确认 .claude/commands/ 下的 .md 文件权限和路径无误命令行输入 / 查看命令列表是否出现自定义命令。配置 hooks将 .claude/settings.json 里的 hook 路径改为项目内实际脚本路径并给脚本加可执行权限chmod x。验证规则加载新开一个 Claude Code 会话随便问一句“这个项目的代码风格是什么”看它能否正确回答出 CLAUDE.md 里定义的规范。这一步能快速暴露配置是否生效。我遇到过的最典型的初始化错误是在 Windows 环境克隆了仓库脚本权限丢失导致 pre-commit 直接钩子什么都不干。所以在配置 hooks 这步我会专门检查脚本的 shebang 行和可执行权限。复制模板后如果发现命令没有出现在斜杠菜单里多半是文件后缀写成了 .markdown而系统只认 .md 后缀。4.2 第一次全流程验证让它从头写一个功能配置完成后我通常会拿一个小需求做一次全流程验证比如“给订单模块加一个导出 CSV 的接口”。看 AI 的表现重点不是功能是否实现而是它有没有遵守规则有没有先输出实现方案再动手编码测试文件是否放到了tests目录有没有用 TypeScript 而不是 any 泛滥命令行为是否符合 CLAUDE.md 的定义。这套验证流程不是多余的因为模板配置错误往往不会直接报错只会表现为“AI 行为奇怪”。比如它写文件到了错误路径、不写测试、或者提交信息不符合规范。如果第一次验证就发现问题八成是 CLAUDE.md 里的规则描述太模糊或者优先级冲突。此时我会先精简规则条目再试一次。我在给一个团队配置模板时发现 AI 总是忽略测试要求排查半天才意识到CLAUDE.md 里写着“必须写测试”但同一个项目根目录下的 AGENTS.md 里又有“优先实现功能测试可后续补充”这句话。两条规则冲突时模型选择了后者。这个案例给我们的教训是模板里的规则必须互相补位而不是互相打架冲突规则比没有规则更糟。4.3 多仓库复用与团队同步模板的最后一层价值是团队复用。把整个 .claude/ 目录提交到仓库后团队成员拉取代码就自动获得了同一套命令和规则不需要每个人手动配置。这一点对团队协作帮助很大同一套 /review 规则不会有张三一个版本、李四一个版本的问题。团推同步时需要注意版本控制。模板会随项目演进不断调整如果 A 成员改了 CLAUDE.mdB 成员的本地内容还是旧版就会出现规则不一致。我的习惯是把 CLAUDE.md 和 .claude/ 目录纳入 Code Review 范围任何修改都要像改业务代码一样过评审。这听起来有点重但对于一个依赖 AI 协作的仓库来说规则文件的稳定性直接影响产出质量值得投入。5. 常见问题与排查技巧实录5.1 规则文件改了AI 却不按新规则执行这是反馈最多的问题。大多数人会以为是规则写得不到位但实际上多半是上下文没有刷新。Claude Code 会在新会话开启时读取规则文件但同一个会话里已经产生的上下文不会立刻失效。也就是说你改了 CLAUDE.md老会话里的 AI 可能还在按旧规则干活。解决方法是改完规则后新开一个会话或者用 /clear 清空当前上下文。另外还有一种情况项目根目录的 CLAUDE.md 和子目录的 AGENTS.md 规则叠在一起后读取的规则把前面的覆盖了。排查这类问题时我会让 AI 输出“你当前遵循的规则摘要”直接看它心里到底装了什么。这个方法比反复改文件快得多。5.2 上下文被无关输出喂饱规则被稀释AI 的上下文窗口是有限的如果 hook 脚本或者命令要求它输出大量原始日志真正有用的规则反而会被顶出上下文。我见过一个项目AI 执行测试命令时把整段十几万字符的测试输出原样贴回上下文结果后续任务质量急剧下降。模板里的测试命令必须强制要求 AI只总结结果不粘贴原始日志。比如命令模板里明确写“输出前 10 行关键错误摘要”而不是“输出全部日志”。另外如果你的模板经常需要读取日志数据最好配合 grep 或者 tail 这类 shell 命令做预过滤让 AI 只拿到关键片段。这一步对于上下文预算紧张的场景是很实用的保命技巧。5.3 hooks 无声失败与路径坑hook 脚本最容易踩的坑是“无声失败”。脚本明明写错了但因为输出格式不对、退出码被忽略Claude Code 照样继续干活看起来什么都没发生。第一次排查这类问题时我花了整整一下午最后发现是脚本里用了相对路径而 hook 的工作目录并非项目根目录。所以我的模板里统一规定hook 脚本内所有路径引用都用绝对路径并在脚本开头做环境检查。比如#!/usr/bin/env bash # 检查必要参数是否存在 if [ -z $CLAUDE_TOOL_INPUT ]; then echo 缺少工具输入参数 2 exit 1 fi跨平台执行也要注意。同一个脚本在 Linux 上跑得好好的到了 macOS 上 sed 命令语法就报错。模板集里所有 shell 脚本我都会标注清楚适用平台或者写成兼容写法。hooks 排查技巧总结下来就一句话先看退出码再看 stderr 输出最后才怀疑业务逻辑。6. 最后再分享一点个人经验这套模板我用到现在最大的感触是它不像一个“加速工具”更像是一个“约束工具”。AI 编程的体验不取决于模型有多强而取决于边界画得多清楚。规则写得太松AI 会放飞自我写得太死AI 又束手束脚。模板的价值就是让这两者之间找到平衡。在实际操作中我最后总是提醒自己模板是起点不是终点。每个项目都有它自己的特殊性模板只能提供一个共同底座。真正好用的规则文件是在项目的实际迭代中一点点长出来的——你发现 AI 总在某个环节犯错就去补一条规则你发现某条规则总是引发误判就删掉重写。保持 CLAUDE.md 精简控制在一个文件能读完全部要点以内的长度效果远好于写一份巨细无遗的“宪法”。另外如果你打算把模板分享给其他人记得在初始化的脚本里加入自检命令。这会让第一次使用的人少走很多弯路也会减少你收到“模板不好用”反馈的概率。我就是这样做的现在团队里的新项目一律先跑一遍模板初始化再谈具体开发省下的沟通成本完全超出我的预期。
