1. 从裸奔到模板化我为什么给 Claude Code 配了一套工作台先说一段真实经历。第一次用 Claude Code 的时候我直接在终端敲了个claude丢给它一个 GitHub 仓库地址让它帮我看看这个项目。它确实能跑起来会读代码、会改文件、会执行命令但总有一种在跟一个聪明但完全不了解我的新人合作的感觉。每次都要重新解释项目背景、技术栈取舍、哪些目录不能动、测试命令是什么哪怕刚解释完换个会话它又忘了。后来我才意识到问题不在模型能力而在于我从来没给 Claude Code 提供过稳定的工作上下文。就像你招了个经验丰富的新同事却不给他看部门规范、不告诉他构建命令、不给他交接文档那他再聪明也只能靠猜。这就是claude-code-templates要解决的问题。这套模板并不是什么花哨的代码生成器而是一整套针对 Claude Code 工作流的配置文件集合包括 CLAUDE.md 上下文模板、自定义斜杠命令模板、Hooks 钩子模板以及配套的目录组织规范。把它配好之后Claude Code 从一个偶尔聪明、经常失忆的临时工变成了一个懂项目规矩、能自动执行检查、按团队风格干活的稳定成员。这篇文章适合两类人一类是刚接触 Claude Code、还在用最原始方式跑命令的初学者另一类是已经在深度使用、但觉得每次会话上下文不一致、想把它纳入团队正规工作流的开发者。我会把模板的每一块拆开讲附带可以直接复制的配置代码以及我在实际踩坑后总结的设计原则。2. 上下文分层设计用户级、项目级、目录级 CLAUDE.md 各管什么2.1 三层上下文的作用域与加载机制CLAUDE.md 是 Claude Code 的入职手册它的加载规则很多人会用错。系统会按作用域自动读取多个 CLAUDE.md 文件大致分三层层级存放位置适用场景加载时机用户级~/.claude/CLAUDE.md个人编码习惯、全局禁用项每次会话自动加载项目级./CLAUDE.md项目架构、命令、规范在项目目录启动时自动加载目录级子目录中的CLAUDE.md模块专属约定操作涉及该目录时加载我没有一开始就理解这个机制结果走了一段弯路。我以为只要写一个长长的全局 CLAUDE.md 就够了结果发现它会污染所有项目的上下文——我在 A 项目写的构建命令跑到 B 项目里变成了噪音反而干扰 Claude Code 的判断。正确做法是全局文件只写通用于你所有工作的东西比如修改代码前先跑现有测试禁止使用 rm -rf 删除未跟踪文件所有新增依赖必须说明理由。而项目级文件才写这个项目的独有信息包括目录结构、技术栈、测试方式、常见的坑。2.2 我常用的项目级 CLAUDE.md 模板下面这份模板是我在多个实际项目中迭代出来的直接复制到项目的CLAUDE.md就能用。重点是五个板块项目一句话定位、技术栈与命令、目录地图、编码约定、雷区清单。# 项目概述 这是一个基于 FastAPI React 的轻量级工单系统核心是提供 REST API 前端使用 Vite 构建。项目目标用户是内部运维团队日均请求量预计在千级。 # 技术栈与关键命令 - 后端Python 3.11, FastAPI, SQLAlchemy 2.0, PostgreSQL 15 - 前端React 18, TypeScript, Vite, TailwindCSS - 启动后端uvicorn app.main:app --reload --port 8000 - 启动前端npm run dev - 跑全部测试pytest tests/ -v - 跑单个测试文件pytest tests/unit/test_tickets.py -v - 代码检查ruff check . ruff format --check . # 目录地图 - app/main.py —— FastAPI 入口注册路由和中间件 - app/api/ —— 路由层只做参数校验和响应封装 - app/services/ —— 业务逻辑层核心规则都在这 - app/models/ —— SQLAlchemy ORM 模型 - app/schemas/ —— Pydantic 序列化模型 - frontend/src/ —— React 组件与页面 # 编码约定 - API 响应统一使用 { code: 0, data: ..., message: ok } 结构 - 业务规则写在 services 层禁止在路由层写业务判断 - 数据库迁移文件命名{version}_{描述}.py - 所有时间字段统一用 UTC 存储返回给前端前转东八区 - 新增依赖必须同步更新 requirements.txt 和 pyproject.toml # 雷区清单 - 不要直接修改 app/models/ 下已迁移的表结构必须新建迁移文件 - auth 相关的中间件在 app/middleware/auth.py改鉴权逻辑前先读它 - 前端代码风格使用 ESLint 配置不要用 prettier 覆盖 - tests/ 下有 conftest.py 定义了测试数据库夹具别绕过它直接连库这个模板的关键是雷区清单。我发现 Claude Code 出问题最多的场景不是它不会写代码而是它会用一种看起来很合理但其实违反项目约定的方式去改代码。把雷区明确写清楚能减少大量返工。2.3 目录级 CLAUDE.md 的实用案例项目级文件管全局但有些子目录里的规矩跟其他地方不一样。比如我们项目的app/services/payment/目录里所有涉及金额的操作必须走事务并记录流水frontend/src/components/ui/目录里组件必须支持受控和非受控两种模式。这些局部规则写进目录级 CLAUDE.md 最合适。# 目录级规则app/services/payment/CLAUDE.md 本目录所有函数涉及资金变动时 1. 必须在同一个数据库事务内完成余额变更和流水写入 2. 流水表 payment_logs 只能追加不允许 UPDATE 和 DELETE 3. 金额单位统一为分int禁止使用 float 存金额 4. 对外抛出的异常必须先转换成 PaymentError 类型Claude Code 在处理这个目录下的任务时会自动读取该文件相当于进入了支付模块工作模式。这个机制特别适合大仓库里某些模块有强约束的场景比把所有规则堆在根目录 CLAUDE.md 里清晰得多。3. 自定义斜杠命令模板把高频操作封装成可复用的技能3.1 命令文件的存放规则与格式光有 CLAUDE.md 只是让 Claude Code 懂规矩真正提升效率的是自定义斜杠命令。它让你在终端输入/的时候能调出项目专属的技能菜单。命令文件本质上是 Markdown 文件带一个可选的 YAML frontmatter放在.claude/commands/目录下项目级或~/.claude/commands/用户级。命令文件的核心格式长这样--- description: 对当前改动进行代码审查输出结构化问题清单 allowed-tools: Read, Grep, Glob model: sonnet --- 请你作为资深代码审查者审查当前工作区的未提交改动。 审查流程 1. 先运行 git diff HEAD 查看全部变更文件 2. 按文件逐个审查重点关注 - 潜在的异常/资源泄漏 - 并发安全问题 - 与项目编码约定的冲突 3. 输出格式按严重问题 / 建议改进 / 可选优化三档列出 4. 每个问题必须标明文件路径和行号并解释原因这里有个关键细节allowed-tools字段可以限制命令执行时允许使用的工具。比如审查类命令只需要读文件就不必给它执行任意 shell 的能力降低误操作风险。3.2 五个我认为最值得内置的命令模板我自己的模板仓库经历过几轮减法下面这几个是真正每天在用的每个都有明确的场景。/commit——规范提交信息没有它之前Claude Code 生成的 commit message 经常是 fix: update some stuff 这种废话。现在这个命令会先跑git diff和git status再结合项目的 Conventional Commits 约定生成信息并且支持$ARGUMENTS传入自定义说明。--- description: 根据当前改动生成符合 Conventional Commits 规范的提交信息 --- 请根据 git diff 的内容生成一条提交信息。 规则 1. 先执行 git status 和 git diff --stat 了解改动范围 2. 再执行 git diff HEAD 查看具体内容 3. 提交信息格式type(scope): subject type 取值feat / fix / refactor / docs / test / chore 4. 如果用户提供了额外说明$ARGUMENTS把它合并进 subject 5. 只输出提交信息本身不要输出解释/test——给当前改动补测试--- description: 针对当前改动自动生成单元测试 --- 请针对当前工作区的改动生成单元测试。 要求 1. 先通过 git diff HEAD 识别改动了哪些函数或模块 2. 只针对改动涉及的代码路径写测试不要扩大范围 3. 测试风格遵循项目现有惯例先读一个现有测试文件确认写法 4. 测试文件放在 tests/ 对应目录下命名 test_{目标模块}.py 5. 写完测试后执行 pytest 验证失败的话迭代修复/docs——更新文档--- description: 根据代码改动同步更新相关文档 --- 请检查当前改动是否影响 README.md、docs/ 目录或 API 文档。 操作流程 1. git diff HEAD 查看改动 2. 对比文档中的相关描述标记出已过时的内容 3. 同步更新文档保持与代码行为一致 4. 如果改动涉及对外 API额外检查是否需要更新示例代码/refactor——小步重构--- description: 对指定模块进行安全重构不做行为变更 --- 对 $ARGUMENTS 指向的文件/模块进行重构。 铁律 1. 不允许改变任何对外行为只调整内部结构 2. 重构前先确认相关测试存在且可通过 3. 每完成一个子步骤就暂停让用户确认后再继续 4. 重构完成后跑全量测试输出前后对比说明/debug——日志式排查--- description: 根据报错信息定位问题根因 --- 请帮忙排查 $ARGUMENTS 描述的报错。 排查步骤 1. 先复现报错明确报错信息、触发条件和相关日志 2. 检查代码中对应的调用链画出执行路径 3. 列出可能的根因假设按概率排序逐一验证 4. 找到根因后给出最小改动修复方案 5. 禁止用建议添加 try-except这种治标不治本的做法3.3 $ARGUMENTS 和条件逻辑的进阶用法斜杠命令支持$ARGUMENTS变量它会把用户在命令后输入的参数原样带进系统提示词。比如用户输入/refactor app/services/ticket.py那么$ARGUMENTS的值就是app/services/ticket.py命令文件里引用它即可。更进阶的玩法是用命令打开或关闭某些行为。比如我有个/focus mode命令它的作用是在会话中临时追加只允许修改 tests/ 目录下文件的约束--- description: 切换为测试开发模式只允许修改测试文件 --- 从现在开始进入测试模式 1. 你只允许修改 tests/ 目录下的文件 2. 产品代码一律不允许改动哪怕是修复明显的 bug 3. 如果要修改产品代码才能完成测试请明确告知用户具体位置和原因等待确认 4. 本约束在本次会话内持续有效这个命令在写测试用例的时候特别好用——它会彻底阻止 Claude Code顺手去改产品代码来迎合测试的行为。实际用下来误改率直接下降了一个量级。4. Hooks 钩子模板在工具调用的关键节点装上自动化护栏4.1 四个钩子事件分别管什么如果说 CLAUDE.md 是让 Claude Code知道规矩斜杠命令是让它有技能可用那 Hooks 就是让它在干活的过程中自动被校验。Hooks 是事件驱动的脚本配置在.claude/settings.json里在特定事件发生时由 Claude Code 自动调用。我常用的有四类钩子事件触发时机典型用途PreToolUse工具被调用前拦截危险命令、白名单校验PostToolUse工具执行完成后自动格式化、检查生成结果Notification需要通知用户时发出桌面通知或播报语音Stop一次完整响应结束时自动跑测试、记录会话摘要Hooks 脚本可以用 shell、Python、Node 等任意可执行方式编写Claude Code 会按事件传入 JSON 格式的工具调用信息。这个机制是最容易被忽略、但收益最直接的部分。4.2 PostToolUse 自动格式化的钩子示例最常见的需求Claude Code 修改完代码后自动执行格式化工具。比如前端项目里我们让它在每次Write或Edit工具执行完以后自动跑 Prettier{ hooks: { PostToolUse: [ { matcher: Write|Edit, hooks: [ { type: command, command: cd $CLAUDE_PROJECT_DIR npx prettier --write \$CLAUDE_FILE_PATTERN\ 2/dev/null || true } ] } ] } }这里有几个细节matcher用来匹配工具名支持正则环境变量$CLAUDE_PROJECT_DIR、$CLAUDE_FILE_PATTERN是 Claude Code 注入的2/dev/null || true是为了避免格式化报错打断主流程。加上这个钩子之后Claude Code 生成的代码格式就跟你团队 CI 里的要求完全一致了再也不用回头统一格式。4.3 PreToolUse 危险命令拦截示例更硬核的用法是 PreToolUse 拦截。我们有个后端项目生产数据库信息在.env.production里绝不允许 Claude Code 在会话中去读它或执行生产环境命令。钩子这样写{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: bash ~/.claude/hooks/check-dangerous-command.sh, timeout: 5 } ] } ] } }配套的脚本check-dangerous-command.sh#!/usr/bin/env bash # 从 JSON 输入中提取即将执行的命令 INPUT_JSON$(cat) COMMAND$(echo $INPUT_JSON | python3 -c import json, sys data json.load(sys.stdin) tool_input data.get(tool_input, {}) print(tool_input.get(command, )) ) # 定义危险模式 if [[ $COMMAND *.env.production* ]] || [[ $COMMAND *prod* ]] [[ $COMMAND *psql* ]]; then echo {hookSpecificOutput: {hookEventName: PreToolUse, decision: block, message: 禁止在会话中访问生产环境配置或执行生产数据库命令}} exit 2 fi # 放行 echo {hookSpecificOutput: {hookEventName: PreToolUse, decision: approve}} exit 0这个钩子不能 100% 杜绝所有危险操作但它把生产环境命令和日常开发命令之间加了一道默认关闭的门。对于团队协作场景这比口头约定可靠得多——毕竟 AI 不会记得你上周在群里说的别碰生产库。4.4 钩子脚本的调试技巧钩子调试是我踩坑最多的地方。问题的难点在于钩子脚本运行在独立进程里stdout 不会直接显示在对话中。我的调试方法是分三步第一手动模拟输入。把 Claude Code 传给钩子的 JSON 结构打印出来用真实数据测一次脚本逻辑。第二把脚本里的中间变量写到临时日志文件比如/tmp/hook-debug.log然后观察日志确认分支走对了。第三注意exit退出码的语义exit 0放行、exit 2拦截并给出提示。很多新手写钩子时把拦截逻辑写在exit 1结果行为跟预期不符。另一个重要经验钩子脚本必须保持快。PreToolUse是在用户等待的工具调用响应之前执行的如果脚本慢了整个交互都卡顿。所以不要在钩子里跑重量级分析超过 100ms 的都应该考虑换成异步方式或只在 Stop 事件里做。5. 模板仓库落地实践目录结构、版本管理与协作踩坑记录5.1 一套可以直接照搬的目录结构下面是我当前在用的模板仓库目录结构。核心思路是区分个人偏好和项目基建个人偏好放用户级项目基建跟着仓库走。claude-code-templates/ ├── user/ │ ├── CLAUDE.md # 用户级上下文 │ └── commands/ │ ├── commit.md # 全局可用的提交命令 │ ├── review.md # 代码审查命令 │ └── focus-mode.md # 测试模式开关 ├── project/ │ ├── CLAUDE.md # 项目级上下文模板 │ ├── commands/ │ │ ├── test.md # 补测试 │ │ ├── docs.md # 同步文档 │ │ └── refactor.md # 安全重构 │ └── hooks/ │ ├── settings.json # 项目钩子配置 │ ├── check-dangerous-command.sh │ └── auto-format.sh └── README.md # 模板使用说明与设计要求用户级命令和项目级命令我刻意做了区分像/commit、/review这种在任何项目都通用的放进 user 目录像/test里先读现有测试文件确认写法这种强依赖项目风格的放进 project 目录。5.2 模板的版本管理与演进策略Claude Code 本身迭代很快模板也必须跟着演进。我把模板仓库当成普通代码仓库管理每次改动都走 MR 和 review有几个原则是实践后沉淀下来的模板文件一律要标注适用版本。CLAUDE.md 和 hooks 的行为会随 Claude Code 版本变化不标注版本半年后自己都看不懂为什么当初要这么写。每次新增命令先回答一个问题这个操作是不是每周至少发生一次如果只是偶发需求不值得固化成命令——它反而会污染命令菜单让 AI 在选工具时多一个干扰项。每月做一次冗余清理。我统计过实际使用中大约有三成命令是刚写的时候很兴奋、之后再也没用过的。季末清理一次保持命令菜单精简。5.3 我踩过的三个坑及最终解法第一个坑是上下文过载。一开始我把什么规则都往 CLAUDE.md 里塞结果文件超过 500 行Claude Code 反而开始忽略一些关键指令——上下文太长了注意力和优先级全被稀释。解法是给规则分优先级只保留 P0 级别的硬约束和 P1 级别的常用约定其他内容挪到 docs/ 里按需引用。第二个坑是钩子与命令之间的循环调用。我曾写了一个 PostToolUse 钩子它在代码格式化后自动执行测试而测试命令里又包含格式检查导致 Claude Code 在工具调用链里反复触发。最终表现是会话卡死。解法是明确区分职责格式统一由 PostToolUse 负责测试只放在/test命令和 Stop 事件里绝不交叉。第三个坑是团队共享模板时的个人习惯冲突。有人喜欢命令输出详细解释有人只想要最终结果有人习惯中文提示词有人坚持英文。最开始的方案是把所有人的偏好都写进共享模板结果命令文件变得臃肿且互相矛盾。后来的方案是共享模板只保留团队约定和项目规范个人表达习惯一律放用户级目录双方互不干扰。6. 从模板到工作流我的实际收益与使用建议配置完这套模板之后最直观的变化是会话的启动成本低了很多。以前每次开新会话光是把项目背景和注意事项说清楚就要花三五分钟现在 Claude Code 启动即读 CLAUDE.md配合斜杠命令几乎不用重复解释。我实际统计过同样一个修改工单状态流转逻辑的任务模板化之前平均要对话 12 轮左右模板化之后缩短到 5 轮以内。不过我也想给个降温建议不要第一天就追求把 CLAUDE.md、命令、钩子全部配齐。正确节奏是先配一份精简的项目级 CLAUDE.md跑上一周然后把重复了三次以上的操作逐步固化成斜杠命令等命令稳定了再考虑用钩子做自动化和拦截。一次到位往往意味着频繁改动反而增加了维护成本。最后分享一个我在实际操作中觉得最值的小技巧把模板仓库本身做成一个可安装的脚手架——用一个小脚本把 project 目录里的模板按需复制到新项目里几秒钟就能生成一个新项目的基础配置。这样新项目从第一天起就带着相同的上下文规范和技能集团队里每个人的 Claude Code 行为都保持一致评审代码的时候也少了很多风格不统一的争论。