最近我把手上的 claude-code-templates 重新整理了一遍发现很多人不是不会用 Claude Code而是每次都从零开始“调教”模型。这个项目本质上不是一份给人看的文档而是一套可以直接塞进仓库的模板体系项目级的 CLAUDE.md、斜杠命令slash commands、子代理配置以及一把初始化脚本。用上之后我开新项目的速度明显变快模型对项目约定的理解也更稳不会再出现“同一个仓库昨天按 A 风格写、今天换成 B 风格”的情况。如果你经常在终端里用 Claude Code 写代码、做 Code Review或者同时维护多个技术栈的仓库这套模板可以整份抄走也可以拆开只挑需要的模块。1. 先搞明白Claude Code 里“模板”到底在管什么1.1 模板不是神秘黑盒就是几类“记忆文件”Claude Code 在项目里工作时并不会自动知道你的代码风格、测试命令和目录约定它依赖两类东西一是对话里的即时上下文二是项目里的长期记忆文件。长期记忆的核心就是CLAUDE.md它有点像给模型看的项目 README但比 README 更偏向“行为约定”。除了CLAUDE.md现在比较新版本的 Claude Code 还支持自定义命令放在.claude/commands/目录下。你只要在交互界面里敲一个/review、/test之类的斜杠命令模型就会自动加载对应的 Markdown 提示词文件按预定义的流程干活。这个机制的好处是把“如何做一件事”沉淀成文件不用每次都在对话框里重复交代。再往后走还有 subagents子代理的概念通常在.claude/agents/目录下配置。它相当于给模型同时开了几个“专用身份”比如一个负责写测试、一个负责审查代码、一个负责查文档每个子代理有自己独立的系统提示词和工具权限。模板项目要管的就是这些文件的结构、内容和调用方式。1.2 没有模板时我踩过的三个坑以前我新建一个仓库第一件事就是打开 Claude Code然后把项目背景、技术栈、目录结构、测试命令、代码风格全部用自然语言写一遍。刚开始还行但项目一多就暴露了问题。第一个坑是上下文浪费。每次重新描述项目约定两边都要花大量 token。如果项目里有个Makefile我明明可以直接告诉模型“所有通用操作都看 Makefile 里的 target”但没有模板的话模型可能要先读目录、再猜命令来回好几轮才能干正事。第二个坑是行为不一致。今天你心情好在对话里强调“不要动公共接口的文件”模型记住了明天换个 session这个约束就没了。尤其是团队协作时不同人用 Claude Code 的习惯不一样写出来的代码风格像三个人写的一样。模板的核心作用就是把这种“临时提醒”变成“项目默认规则”。第三个坑是上下文被无关信息挤占。很多人喜欢把所有规范都塞进粘贴的提示词里结果真正关键的约束反而被淹没。模板的另一个价值是帮你做裁剪什么信息进CLAUDE.md什么信息只留给子代理什么信息只在命令触发时加载这是有层次的。2. claude-code-templates 项目的整体设计与目录拆解2.1 仓库结构长什么样我整理后的目录大致如下你可以直接用这个骨架claude-code-templates/ ├── README.md ├── CLAUDE.md ├── templates/ │ ├── web-app/ │ │ ├── CLAUDE.md │ │ ├── commands/ │ │ │ └── review.md │ │ └── agents/ │ │ └── test-agent.md │ ├── python-lib/ │ │ ├── CLAUDE.md │ │ └── commands/ │ │ └── build-doc.md │ └── general/ │ ├── CLAUDE.md │ └── commands/ │ └── explain.md ├── commands/ │ ├── api-design.md │ ├── code-audit.md │ └── test-generate.md ├── scripts/ │ └── init-template.sh └── docs/ └── usage.md这里的templates/是给不同项目类型的“初始模板包”。比如web-app里放了一份偏前端项目的CLAUDE.md和对应的命令、代理配置python-lib则是给 Python 库用的general是通用兜底。commands/顶层那几份是跨项目通用的斜杠命令像 API 设计评审、代码审计不算绑定某个技术栈。顶层CLAUDE.md是给我自己这个模板仓库用的它会让 Claude Code 在维护模板时也遵循统一的规则。这个细节容易被忽略模板仓库本身也应该被模板管理。2.2 模板不是越多越好而是按“使用频率”和“出错代价”来选做模板最大的误区是贪多。我一开始给每个技术栈都写了七八个命令结果大部分从来没被调用过还要花精力维护。后来我给自己定了一个筛选标准只有同时满足下面几个条件的才值得写进模板判断维度具体问题值得做模板吗使用频率这个操作是不是每周都会做高频操作值得出错代价做错了会不会导致返工或线上事故高风险值得重复性每次做时逻辑是不是基本一样高度重复值得团队共享别人用了是否能保证体验一致多人协作值得比如“跑一遍所有测试然后总结失败原因”这属于高频、重复、多人协作都会用的场景非常适合做成/test-summary命令。而“用某个一次性脚本删数据库里的脏数据”虽然风险高但可能几个月才做一次而且涉及环境变量放进模板反而危险更适合每次临时说明。2.3 选模板时的落地原则我给模板分了三个层级你也可以照这个思路来组织第一层是项目级CLAUDE.md它控制所有会话的基础行为。内容必须短只放“必须遵守”的规则比如技术栈、目录职责、禁止修改的路径、测试命令。第二层是命令文件它只在主动触发时加载。内容可以稍微详细但仍然要聚焦在单一任务上。第三层是子代理配置适合需要长期角色分工的场景。这个最灵活但也最容易把系统提示词写得太长。这样的分层能解决一个很实际的问题CLAUDE.md太长模型每次都要读消耗大量上下文命令文件虽然长但只有你主动调用时才进入视野子代理更独立各自只关心自己的任务。三层配合既不丢失信息也不挤占主会话的上下文。3. 手把手做一套能直接用的核心模板3.1 项目级 CLAUDE.md 模板尽量短只留“必须听”下面这份是我常用的通用CLAUDE.md你复制到项目根目录后把方括号里的内容替换成自己的# 项目约定 ## 技术栈 - 语言/框架[例如 TypeScript Next.js] - 包管理器[例如 pnpm] - 测试框架[例如 Vitest Testing Library] ## 目录职责 - src/app/路由与页面只放 UI 层逻辑 - src/lib/纯函数与工具不得引入 React - src/server/后端接口与数据校验禁止直接访问 DOM ## 常用命令 - 启动开发服务pnpm dev - 全部测试pnpm test - 单测某个文件pnpm vitest run src/lib/xxx.test.ts - 类型检查pnpm typecheck ## 代码风格 - 组件使用函数组件 hooks不要用 class 组件 - 接口类型放到 src/types/ 下避免在组件文件里定义 - 所有对外 API 必须写 JSDoc 注释 ## 绝对禁忌 - 不要直接修改 db/migrations/ 下已提交的迁移文件 - 不要用 any 绕过类型检查 - 不要往 src/app/api/ 里写非路由相关逻辑这么短的文档模型一次就能读完而且每条都足够明确。特别注意“绝对禁忌”这一节我实测下来非常管用。Claude Code 在生成代码时有时会为了“跑通”而忽略潜在风险你明确写上“不要修改已提交的迁移文件”它就会在动手前先提醒你。在实践里我还会在CLAUDE.md里加一小节“读取这里之前先看一眼docs/architecture.md”。这样不会把所有架构细节都塞进主文件但模型需要时知道去哪里找。3.2 斜杠命令模板把一次高质量 Code Review 固化下来斜杠命令最好的例子就是 Code Review。我以前的对话式 review 经常只有一句“帮我看看这次的改动”然后模型自己发挥输出有时深有时浅。现在我把 review 做成了命令文件放在.claude/commands/review.md--- description: 对当前分支的改动做一次全面代码审查 argument-hint: 可选填写需要重点关注的路径或风险点 allowed-tools: Bash, Read, Grep, Glob --- 你是一位资深 Code Reviewer。请基于当前 git 分支与主分支的差异进行审查。 ## 执行步骤 1. 先运行 git diff --stat HEAD~1 或 git diff --stat origin/main...HEAD确认改动范围。 2. 读取变更文件清单优先审查 src/、api/、db/ 相关文件。 3. 对每个文件用 Grep 找出潜在问题比如错误处理缺失、魔法数字、重复逻辑。 4. 输出审查结果按严重程度分组 ## 输出格式 ### 阻断问题必须修改 ### 建议优化不影响上线 ### 疑问点需要作者确认 最后给一个总体结论是否可以直接合并是否需要二次 review。 ## 注意 - 不要修改任何代码只做审查和提问。 - 如果用户的 argument-hint 给了路径优先审查指定路径。 - 引用具体文件时带上行号方便定位。文件开头的frontmatter很重要它决定了命令的描述、是否允许传参以及这个命令能使用哪些工具。这里我把allowed-tools限制成Bash, Read, Grep, Glob不允许模型随便用Edit或Write从机制上保证它是一个“只读审查命令”。否则模型手一滑就可能改掉你的代码。调用的时候在 Claude Code 里输入/review或者/review src/lib后面的参数会作为argument-hint传给提示词模型就会把审查焦点放在指定路径上。3.3 子代理模板给模型一个“测试专项负责人”如果你的 Claude Code 版本支持 subagents可以试试在.claude/agents/test-agent.md里这样写--- name: test-agent description: 负责分析测试覆盖、生成单元测试、跑回归测试并输出报告 tools: Bash, Read, Grep, Edit, Write model: sonnet --- 你是这个项目的测试专项负责人。你的职责是保证核心逻辑有足够的单元测试覆盖并且测试代码风格统一。 ## 工作方式 - 先读取 CLAUDE.md 里的测试约定再动手。 - 新增测试时优先补充边界条件不要只测 happy path。 - 跑测试用 pnpm test不要绕过测试框架直接执行 node。 - 测试文件的命名必须与被测模块对应放在同目录的 __tests__/ 下。 ## 输出规范 完成测试后用表格列出 - 被测文件 - 新增用例数 - 覆盖的边界条件 - 剩余风险点子代理和普通命令最大的区别是它拥有自己的工具集和模型配置主会话可以随时把任务交给它而不打断主对话流的思路。适合做测试、文档生成、依赖分析这类“杂活”。但注意子代理的能力范围越大越可能做出越权操作。我的经验是工具权限尽可能收紧比如测试代理就只给它 Bash、Read、Grep 加上测试目录的 Edit 权限。3.4 初始化脚本把模板变成新项目的“一键注入”模板文件本身只是静态资源真正提升效率的是初始化脚本。我写了一个简单的 shell 脚本核心逻辑是把选好的模板复制到目标项目里并把占位符替换成真实项目名。#!/usr/bin/env bash set -euo pipefail PROJECT_DIR${1:?用法: init-template.sh 项目目录} TEMPLATE_TYPE${2:-general} TEMPLATE_ROOT$(cd $(dirname $0)/.. pwd)/templates if [ ! -f $TEMPLATE_ROOT/$TEMPLATE_TYPE/CLAUDE.md ]; then echo 没有找到模板: $TEMPLATE_TYPE exit 1 fi mkdir -p $PROJECT_DIR/.claude/commands mkdir -p $PROJECT_DIR/.claude/agents cp $TEMPLATE_ROOT/$TEMPLATE_TYPE/CLAUDE.md $PROJECT_DIR/CLAUDE.md cp -r $TEMPLATE_ROOT/$TEMPLATE_TYPE/commands/. $PROJECT_DIR/.claude/commands/ cp -r $TEMPLATE_ROOT/$TEMPLATE_TYPE/agents/. $PROJECT_DIR/.claude/agents/ if command -v sed /dev/null 21; then # 替换 {{project_name}} 占位符 sed -i.bak s/{{project_name}}/${PROJECT_DIR##*/}/g \ $PROJECT_DIR/CLAUDE.md \ $PROJECT_DIR/.claude/commands/*.md \ $PROJECT_DIR/.claude/agents/*.md 2/dev/null || true find $PROJECT_DIR -name *.bak -delete fi echo 模板已注入到 $PROJECT_DIR这个脚本没什么高深技巧主要是做了三件事建目录、复制文件、替换占位符。我在模板文件里习惯用{{project_name}}这类双花括号占位符方便脚本统一处理。如果你在 Windows 上用可以改成 PowerShell 版本逻辑一样。4. 把模板接入日常项目流一次完整的实操记录4.1 从零初始化一个前端项目再到跑一次 review拿一个实际项目举例。我新建了一个叫blog-platform的 Next.js 项目但没有先装一堆依赖而是直接执行./scripts/init-template.sh ~/work/blog-platform web-app脚本跑完之后项目里多了CLAUDE.md、.claude/commands/review.md和.claude/agents/test-agent.md。这时候我再打开 Claude Code它已经能准确说出“这个项目用 pnpm、测试用 Vitest、业务代码在src/app下”这些信息。我没有多打一个字它就知道不要碰迁移文件。后面我在一个分支上写了一堆改动想检查代码质量直接在 Claude Code 里输入/review src/lib。它会先看git diff --stat然后逐个文件读改动最后返回一份按“阻断问题、建议优化、疑问点”分组的报告。这个过程全程只读不会擅自改我的代码比我以前口头让它 review 要安全得多。写测试的时候我直接把对应文件丢给test-agent让它补充边界测试。因为子代理有自己的model配置可以用更快的小模型来处理这种结构化任务主会话暂时不会被测试细节占满。跑完后它会返回一张覆盖情况的表格我扫一眼就知道哪里还有风险。4.2 模板跟着项目一起演进用版本管理维护很多人的模板项目死在“写完就再也不改”。实际上模板是会过时的。比如项目从src/utils重构到了src/lib如果CLAUDE.md里的目录职责没同步模型就会给出过时的建议。我的经验是给模板仓库单独建一个 git 仓库每次从实际项目里碰到“模型理解错了约定”或“命令输出格式不够清晰”的情况就回模板仓库改一版然后提交一个简短的 commit。比如我原本的 review 命令只输出“阻断问题和建议”后来发现模型经常把“疑问点”混进建议里于是我在提示词里加了严格的分组定义。这就是一次模板迭代。再往后你还可以给不同命令打版本标签比如v1的 review 允许模型读全量 diffv2改成默认只读最近 50 个文件避免大改动时上下文爆炸。每次升级前先在旧项目上跑一次对比确认输出质量没有下降再推广。5. 常见问题与排查实录5.1 CLAUDE.md 没生效怎么办最常见的排查点有三个第一文件位置不对。Claude Code 读取的是当前工作目录下的CLAUDE.md我见过有人把文件放到了docs/CLAUDE.md自然不生效。如果用了 monorepo子项目里可以放自己的CLAUDE.md但要注意它会不会覆盖根目录的规则。第二内容格式问题。Claude Code 对 Markdown 的解析并不严格但如果你用了大量自定义 HTML 标签或者非标准语法模型可能理解不了。建议只用最基本的标题、列表、引用块。第三启动会话时机问题。如果你在一个已经打开的会话里新增了CLAUDE.md它可能不会被重新加载。最简单的方法是重启 Claude Code重新进入项目目录或者开一个新会话。5.2 斜杠命令找不到、参数被吞怎么办斜杠命令必须放在.claude/commands/目录下文件名就是触发名。比如test.md对应/test。如果你放在别的位置命令就不会出现在系统提示里。参数被吞掉的情况多半是 frontmatter 里少了argument-hint字段。只有声明了这个字段模型才会把/review src/lib里的src/lib当成用户输入传下去否则它可能只触发命令不理会后面的参数。还有一个容易忽略的点命令文件经过 gitignore 排除后在别的机器上不会同步。我在项目里通常把.claude/强制纳入版本管理除非里面存了密钥之类的敏感信息。5.3 模板越写越厚占上下文怎么办模板文件变长之后模型每次启动都要读一大段文字反而拖慢响应。我的处理方法是主CLAUDE.md只保留最重要的五条其他都拆到对应命令或文档里。例如“如何提交代码”我放在/commit命令中“数据库迁移规范”我放在docs/db.md并在CLAUDE.md里只写一行“涉及数据库改动时先读 docs/db.md”。另外可以用 agent 的方式隔离复杂任务。测试、文档生成这类工作不再占用主会话的上下文而是交给子代理完成。这样主会话始终轻量只保留核心约定和当前任务需要的临时信息。我在实际使用中还发现一个技巧每过一个月把项目里出现的CLAUDE.md打开看一眼凡是超过 100 行的基本都可以做一次瘦身。长期维护的模板始终应该保持“删掉一句都不影响核心行为”的克制感。毕竟模板是给你用的不是拿来展示的。
