Claude Code工作流模板：CLAUDE.md、斜杠命令与Hooks配置实战

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.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 自动调用。我常用的有四类：

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 行为都保持一致，评审代码的时候也少了很多"风格不统一"的争论。