最近我系统整理了一个叫claude-code-templates的项目。它不是什么复杂框架就是一套围绕 claude-code 的模板集合项目级 CLAUDE.md 模板、斜杠命令模板、钩子模板、各种提示词片段全都能拷进仓库直接改。用它的目的是省掉每次新项目重复写上下文的时间和踩坑成本让终端里的编码代理从“散养状态”变成“有章可循”。不管是刚开始用 claude-code 的新手还是已经把它焊进工作流的重度用户我觉得这套东西都值得你参考或者直接抄走。写这个项目的起因很简单claude-code 这类工具的能力上限取决于上下文质量。你不给它好的规则和场景化提示它就只会用通用套路回你碰到特定技术栈、特定工程规范、特定审查标准时经常翻车。把这些东西沉淀成模板本质上是把“怎么用 Claude 干活”变成一种可复用、可维护的工程资产。1. claude-code-templates 的核心设计思路1.1 模板到底在解决什么问题先说结论模板解决的是上下文混乱和重复劳动。很多人在终端里用 claude-code 的时候习惯直接丢一段需求描述就开始干活但这样模型只拥有当前对话窗口里的信息一旦遇到项目结构复杂、过往决策没记录、团队规范靠口口相传的情况它就会开始“自由发挥”。我见过典型的翻车现场让 claude-code 帮忙重构一个模块它改了接口定义却没同步更新所有调用方原因是上下文里根本没写“项目里哪些目录是内部实现、哪些是公开 API改动时需要联动修改哪些文件”。这种问题靠模型能力变强是解决不了的必须靠项目上下文模板来兜底。claude-code-templates的核心思路就是把两类东西做成标准件静态规则项目语言、架构分层、编码风格、测试要求、禁止事项。这些写进 CLAUDE.md每次启动对话时自动加载等于给 agent 发了一张“项目身份证”。动态流程代码评审、重构、补测试、写文档、排查线上问题。这些做成命令和提示词模板让 agent 在特定场景下按固定步骤执行而不是每次重新即兴发挥。这两类模板一组合claude-code 就不只是“能改代码的聊天工具”而是一个拥有项目记忆、工作流约束和安全边界的协作角色。1.2 为什么值得抽象成模板而不是现写现写提示词不是不行但维护成本很高。我统计过自己之前的使用习惯每个项目在 CLAUDE.md 里写的内容至少有 40% 是重复的同类语言的项目规范相似同类任务的审查标准相似。把这些内容抽象到模板里收益是实打实的第一一致性。团队三五个人都在用 claude-code如果每个人各写各的 CLAUDE.md两个人得到的代码风格可能完全不同。模板统一之后至少基础规范是一致的agent 输出的差异只来自任务本身的多样性而不来自上下文写得好坏。第二可测试。提示词不是写出来就完事的你需要验证“换个项目描述模板还能不能稳定输出符合预期的结果”。把提示词沉淀到模板仓库配合一套简单的测试用例就能在改动后快速回归。这一点后面我会细说。第三可演进。模板和软件代码一样需要迭代。你在这个项目里踩了坑把对应规则补进模板下次其他项目就自动避开了。如果每次都是现场写提示踩过的坑大概率会在另一个项目里再踩一遍。2. 模板库的四大组成CLAUDE.md、命令、提示片段和钩子2.1 CLAUDE.md给 claude-code 的项目记忆CLAUDE.md 是 claude-code 的核心上下文文件相当于给 agent 的一份项目操作手册。我在claude-code-templates里给不同技术栈各维护了一套基础版以 Python 模板为例大致结构是这样的# CLAUDE.md ## 项目概述 - 项目类型后端服务 / 数据处理 / CLI 工具 - 主要语言版本Python 3.11 - 依赖管理uv不要直接用 pip install - 入口文件src/app.py ## 架构约定 - 分层接口层 - 服务层 - 数据访问层禁止跨层调用 - 新增模块必须放在 src/module_name/ 下不能堆在根目录 - 数据模型变更必须附带 migration 脚本 ## 代码风格 - 类型标注所有公共函数必须带完整类型标注 - 日志使用 logging 模块统一格式 %(asctime)s %(levelname)s %(name)s: %(message)s - 异常禁止裸 except必须捕获具体异常类型 ## 测试要求 - 新功能必须配套 pytest 测试覆盖率不低于 80% - 集成测试放在 tests/integration/单元测试放在 tests/unit/ - 所有对外接口的测试必须使用真实请求方式不能 mock 掉网络层 ## 禁止事项 - 不要修改 migrations/ 目录下的历史迁移文件 - 不要在生产配置里写入任何密钥 - 不要使用全局变量保存状态写这份文档的关键不是“把所有东西都塞进去”而是“只写 agent 不知道就无法正确工作的信息”。比如 Python 项目大家都知道要用类型标注这条可以不写但是“用 uv 而不用 pip”“禁止跨层调用”这种非常规约定必须写。我见过有人把 CLAUDE.md 写成几千字的编程教程那是错误的方向agent 会被大量废话干扰反而忽略真正重要的项目约束。2.2 斜杠命令模板把高频任务变成快捷指令命令模板是claude-code-templates里最实用也最容易见效的部分。在 claude-code 里你可以自定义斜杠命令把一套完整的提示词封装成一个/cmd比如/review、/refactor、/test。我维护了一个通用代码审查命令模板核心内容如下--- description: 执行一次严谨的代码审查输出结构化报告 argument-hint: [可选] 指定文件或目录默认检查最近改动 --- 你是一位资深的代码审查者。请对当前分支的改动执行以下流程 1. 先用 Git 获取本次改动的文件列表和 diff确认改动范围 2. 对每个改动文件依次检查 - 是否有逻辑错误或边界条件遗漏 - 错误处理是否到位会不会吞掉异常 - 是否有安全隐患SQL 注入、路径穿越、敏感信息泄露 - 是否破坏了现有接口的兼容性 - 测试是否覆盖了改动路径 3. 按严重程度输出问题列表 - [P0] 必须修复阻塞上线 - [P1] 建议修复存在明显隐患 - [P2] 可以优化代码风格或结构问题 4. 最后给出总结标注当前分支是否可以合并 注意 - 不要修改任何代码本次任务只做审查 - 如果 diff 中有您不确定的部分请明确说明不要猜测 - 所有评价必须基于实际代码不能使用空泛的形容词这种命令模板的威力在于把“怎么做代码审查”的隐性经验固化了。没有命令时你得在对话里解释审查范围、输出格式、关注重点有了命令之后一次敲入/review就得到统一格式的结果。而且输出结构标准化之后团队可以约定 P0 级别的问题必须在合并前解决这直接变成了工程流程的一部分。2.3 提示片段与子代理模板复用高价值的角色设定除了 CLAUDE.md 和命令我还维护了一批提示片段对应的是那些“需要长篇上下文才能干好”的任务。典型例子是安全审查和迁移重构。安全审查任务我做成了一段很长的系统提示包含常见的漏洞清单、审查顺序、报告模板。把它单独放在prompts/security-audit.md里需要的时候通过命令引用它。这样做的好处是主 CLAUDE.md 保持精简只有执行安全审查时 agent 才加载完整的漏洞知识库。这就好比你不会让一个常驻员工每天背诵安全手册全文而是让他需要检查时再查阅。类似地我做了“API 兼容性分析”“数据库迁移影响分析”“性能问题初诊”这些角色的提示片段。它们的特点是流程复杂、需要多步推理、需要引用项目特定的信息。以数据库迁移为例提示词会要求 agent 先读取所有 schema 文件再分析新旧版本的字段变更再列出所有涉及该表的 SQL 查询最后输出影响清单。没有这个模板时它往往会拍脑袋回答“这个字段改名影响不大”。2.4 钩子模板控制工具使用的边界钩子是 claude-code 的自动化机制能在工具调用前后介入。比如PreToolUse可以在允许 agent 执行危险命令前拦截并二次确认PostToolUse可以在工具输出后注入额外的检查和提示。我在claude-code-templates里维护了一套最少但必要的钩子模板命令拦截钩子检测 agent 是否试图执行rm -rf、git push --force、直接修改生产配置等高风险操作命中后立即中断并提示用户确认。测试触发钩子当 agent 修改了某个源代码文件并结束调用时自动在后置钩子里发起一次“受影响模块的测试建议”检查。密钥泄露检查钩子在写入文件前扫描内容如果发现形如AKIA、sk-、password 的高风险字段直接阻止写入。钩子的价值是给 agent 套上安全边界。Claude 这类编码代理输出质量再高也不能保证每次工具调用都是安全的特别是涉及破坏性命令时。靠钩子把风险动作挡在用户确认之前和“让 agent 自觉”相比是两条完全不同的可靠性路径。我强烈建议生产环境至少配置一条PreToolUse钩子来拦截危险操作。3. 仓库的目录结构与模板语法设计3.1 一个可以照抄的目录布局claude-code-templates的仓库布局我调整过好几轮现在这个版本用起来最顺手claude-code-templates/ ├── templates/ │ ├── python/ # Python 项目 CLAUDE.md 模板 │ ├── typescript/ # TypeScript/Node 项目 CLAUDE.md 模板 │ ├── go/ # Go 项目 CLAUDE.md 模板 │ └── generic/ # 通用项目 CLAUDE.md 模板 ├── commands/ # 斜杠命令模板 │ ├── review.md │ ├── refactor.md │ ├── test.md │ └── doc.md ├── prompts/ # 长上下文提示片段 │ ├── security-audit.md │ └── migration-impact.md ├── hooks/ # 钩子脚本模板 │ ├── pre-tool-use.js │ └── post-tool-use.js ├── scripts/ # 工具脚本 │ ├── init_project.sh │ └── validate_templates.py └── README.md这个结构的设计原则是“按场景划分而不是按文件类型堆砌”。CLAUDE.md模板和技术栈强相关所以按语言分目录命令模板按任务类型划分可以跨语言复用提示片段是长文本角色设定单独放一块方便维护。如果你的团队已经有自己的项目模板仓库完全可以把这套东西当子目录集成进去。在工程基建里引入 ai 工作流模板和引入代码规范、ci 配置一样都是项目初始化的一部分。3.2 模板里用变量占位符而不是硬编码复用模板最大的敌人是“硬编码项目名”。每次新项目都要复制一份模板再去全局替换名字既容易漏也很蠢。我在模板里统一使用{{ }}语法做占位符示例片段## 项目概述 - 项目名称{{ project.name }} - 项目类型{{ project.type }} - 主要语言版本{{ project.language_version }} - 依赖管理{{ project.package_manager }} - 入口文件{{ project.entry_file }}配套一个init_project.sh脚本接受项目参数自动完成模板复制和占位符替换# init_project.sh #!/usr/bin/env bash set -euo pipefail PROJECT_NAME${1:?project name required} TECH_STACK${2:?tech stack required: python|typescript|go|generic} template_dirtemplates/$TECH_STACK target_dir. if [ ! -d $template_dir ]; then echo 未知模板: $TECH_STACK 2 exit 1 fi # 把 CLAUDE.md 模板复制到目标项目并替换占位符 sed -e s/{{ project.name }}/$PROJECT_NAME/g \ -e s/{{ project.type }}/$PROJECT_TYPE/g \ $template_dir/CLAUDE.md $target_dir/CLAUDE.md echo 已生成 CLAUDE.md请检查后使用用脚本生成而不是手动复制最大的好处是后续模板更新时你可以重新执行生成命令来同步而不是在一堆复制品里手工改。当然这只适用于模板是“项目初始默认值”的情况项目进行中积累了专有规范后需要和模板做区分这时我建议在 CLAUDE.md 顶部写一段“自动生成模板项目自定义内容以下方为准”的字样。3.3 按技术栈拆分而不是“一份模板走天下”我见过有人试图维护一个“万能 CLAUDE.md 模板”里面同时写了 Python、Java、前端、数据库的所有规范。这种东西实际用起来就是灾难因为 claude-code 每次都会把整个模板读进上下文而大部分内容和当前项目毫无关系白白占掉上下文窗口还容易让 agent 产生错误联想。所以我坚持按技术栈拆分同时保留一份generic模板处理不常见的场景。拆分的粒度不是越细越好而是以“一个模板能覆盖同类项目的公共约束”为准。比如 Python 后端模板和 Python 数据处理脚本模板就有明显差异后端模板强调分层和 API 设计脚本模板强调可重复运行和幂等性。差异足够大就拆否则就合成一个。4. 从模板到实际项目完整交付路径4.1 初始化一个带 claude-code 配置的新项目如果你是在新项目里使用这套模板完整流程其实很顺。假设我要创建一个名为 “blog-api” 的 Python 后端项目复制模板执行bash scripts/init_project.sh blog-api python编辑生成的 CLAUDE.md填写项目的真实细节比如入口文件、数据模型位置、认证方式等将commands/下的命令模板复制到项目的.claude/commands/目录将hooks/下的钩子脚本复制到.claude/目录并检查钩子配置在项目根目录启动 claude-code输入/config或在项目设置中确认 hooks 生效实际执行时第 2 步最花时间。模板生成的只是骨架项目专有信息必须手动补充比如“用户认证使用 JWTtoken 密钥从环境变量读取”“订单状态流转有 5 个状态禁止跳过中间态”。这些信息在模板里只能留空位填充后 claude-code 的准确率会有质的提升。4.2 一个实际例子用命令模板驱动代码重构我拿一个真实的场景演示命令模板的效果。假设有个 TypeScript 项目遗留代码里有个utils/format.ts文件函数又长又臭需要重构。如果没有命令模板我大概率会这样输入请重构一下 utils/format.ts拆分成更清晰的函数保持行为不变这种描述的问题在于 undefined 太多拆成几个函数函数命名风格是什么要不要补测试可不可以改动导出接口agent 大概率会按通用惯例执行结果可能不符合项目的具体约定。用了我模板库里的/refactor命令之后我会这么输入/refactor utils/format.ts命令模板里包含的内容是--- description: 执行安全重构拆分函数并保持外部行为不变 argument-hint: [目标文件路径] --- 重构任务{{ 用户输入 }} 执行要求 1. 先阅读目标文件拆解出所有公开函数的签名和用途 2. 梳理内部依赖找出可以拆分的纯函数和需要访问外部状态的逻辑 3. 保持对外导出的 API 签名不变如果必须修改需要额外输出调用方影响分析 4. 重构过程中对每个拆分出来的新函数补充类型标注和 JSDoc 5. 执行 TypeScript 类型检查确认无编译错误 6. 运行目标文件相关的单元测试确保行为不变 7. 以 diff 的形式输出改动摘要 禁止事项 - 不要在重构过程中顺手优化业务逻辑 - 不要修改与本次拆分无关的代码 - 不要移动文件位置对比结束后结果差异非常明显。后者输出的重构方案会先给一份函数依赖分析再按拆分点逐个重构最后附上测试结果。这个命令模板消耗的 token 不比重新描述多多少但输出的规范性完全不是一回事。模板真正的价值就是替你在每次交流里“默认补齐”了那些环境上下文。4.3 模板变更的安全网自动验证脚本模板也是代码改成模板库后最怕的就是“改坏了但没发现”。我为claude-code-templates写了一个简单的验证脚本核心作用是检查每个模板里的占位符是否成对闭合没有落单的{{检查命令模板是否包含必需的 frontmatter 字段description等检查 CLAUDE.md 模板是否包含必需章节项目概述、架构约定、禁止事项验证脚本不复杂但能挡住 80% 的复制粘贴失误。团队把模板当共享资产维护时这个验证流程可以挂进 CI每次合并模板改动前自动跑一遍。5. 踩坑记录与排查速查5.1 CLAUDE.md 越写越长上下文越来越臃肿这是我在实际使用中踩得最深的坑。最开始我很贪心把项目的所有知识都往 CLAUDE.md 里塞导致 claude-code 每次启动都加载很长的系统提示。结果是 agent 看起来记住了很多东西但真正干活时反而抓不住重点经常把无关紧要的规则也带进推理。后来我把模板拆成两层一是常驻的 CLAUDE.md只保留“不放进去就会出错”的信息二是按需加载的提示片段用命令触发时才读入。比如完整的数据库设计文档放在项目 docs 目录CLAUDE.md 里只写“数据库 schema 以 docs/schema.md 为准修改前必须阅读”。这样常驻上下文轻需要时 agent 自己会去读取。5.2 命令模板里的指令互相冲突单个命令模板没问题但当你同时加载多个命令比如/review要求“不要修改代码”而/test要求“自动修复失败的测试”agent 偶尔会把两者的边界搞混。最好的办法是在每个命令模板的description里明确它的作用范围并在常见冲突点写清“本次会话中只执行该命令定义的任务”。我还在模板库里加了一条通用原则不同命令之间不互相调用避免职责纠缠。5.3 钩子误伤正常操作钩子最烦人的问题是拦截规则写太死导致正常操作也频繁弹确认框。比如我最初把git push直接禁止结果 agent 每次推代码都卡住最后用户只能手动推钩子反而成了效率黑洞。优化后的策略是分级处理破坏性极高的命令比如rm -rf直接拦截并要求人工确认高风险但可逆的操作比如git push只记录日志并追加一段提示不打断流程。钩子应该做“安全网”而不是“管家婆”。如果你发现钩子经常触发先检查是不是拦截阈值设置得不合理。5.4 常见故障速查表现象可能原因排查方法claude-code 完全不理 CLAUDE.md文件命名或位置不对确认文件在当前工作目录且名称为CLAUDE.md不要加版本号后缀命令输入后无效命令文件没放在.claude/commands/下检查目录位置确认文件是.md格式并包含descriptionfrontmatter钩子脚本未执行钩子配置路径错误检查.claude/settings.json中的执行路径使用绝对路径调试模板中占位符没被替换初始化脚本的 sed 语法不兼容手动检查模板中是否漏了闭合的}}agent 经常忽略测试要求CLAUDE.md 中测试规范太靠后把测试要求提前到项目概述之后并写清“每次改动后执行”同一项目反复出现同样的错误错误没有沉淀回模板把本次排错结论补进 CLAUDE.md 或命令模板跑一遍验证脚本5.5 关于模板维护的几个习惯模板库不是建好就完事的。我自己的节奏是每次在某个项目里发现问题都会随手把规则补进对应模板每周抽半天统一梳理一次删掉那些已经过时或者被新规则覆盖的条目。因为模板一旦和实际操作脱节agent 输出质量会明显下降这一点和代码债是一个道理。我在实际维护中还发现一个细节命令模板的输出格式最好也模板化。比如审查命令的输出固定为“问题编号 文件:行号 问题描述 建议方案”这样接 CI 或者后续让别的 agent 处理报告时效率最高。格式统一是模板资产产生复利的前提。这个思路同样适用所有任务型命令值得你从第一天就规范起来。如果你准备动手做自己的 claude-code 模板我的建议是先别追求大而全。挑一个你最高频的任务比如代码审查或者测试生成先把这个命令模板做扎实用两个项目验证没问题再继续扩展。模板这东西只有经过真实项目打磨过才靠得住纸上设计得再漂亮也替代不了实战。