有一段时间我对 Claude Code 又爱又恨。爱的是它写代码确实快恨的是每开一个新项目它都得重新“磨合”不认识项目结构调整方向、不知道测试框架放哪、不清楚我要什么风格的提交信息。项目一多大量时间都耗在重复交代背景、重复贴规则、反复纠正输出上。后来我干脆花几个晚上整理出一套claude-code-templates把项目上下文、常用指令、子代理角色和权限策略全部固化成模板。现在新项目几分钟就能接入团队协作方式也跟着统一了。这篇就聊聊这套模板到底做了什么、为什么这么设计以及你自己建模板时容易踩哪些坑。这套做法适合所有在终端里使用 Claude Code 的人。无论你是个人开发者、三五人小组还是多团队协作模板本质就是 Markdown 加 JSON 的组合学起来没什么门槛。真正值钱的是里面那些“约束 AI 行为”的设计思路而不是文件本身。1. 为什么需要一套 Claude Code 模板体系先说一下我最开始的状态。Claude Code 默认情况下就是一张白纸它知道通用的编程知识但完全不了解你的项目不知道你用 PNPM 还是 Yarn不知道代码规范里禁不禁止any不知道测试是跑在 Vitest 还是 Jest 上。你问它问题它回答得冠冕堂皇但一到改代码就“差点意思”。没有模板约束时通常遇到三类问题重复解释。每次开对话都要把技术栈、目录作用、构建命令重新说一遍。对话一长前面的背景被上下文窗口冲淡它又开始犯基础错误。风格漂移。今天让它写组件它给你函数式明天让它加接口它给你写类。代码风格和团队规范完全是两套东西。安全隐患。它确实可能执行危险命令。如果没做权限限制一句“清理临时文件”可能给你跑出来rm -rf之类的东西人在终端前盯着都觉得心慌。模板体系解决的就是这三件事。它把项目相关的上下文固化成文档把常用操作固化成指令把权限和敏感操作固化成白名单和钩子。AI 每次启动都知道“在这个项目里该怎么做”而不是“按通用方式随便做”。这里面有个取舍要注意模板不是越厚越好。我见过有人把几十页团队规范全塞进去结果 AI 读文档就消耗了大量上下文真正写代码时反而变笨。模板的价值是“帮 AI 快速建立正确的行为基线”不是把所有可能性都穷举出来。信息过载和缺失一样糟糕。1.1 模板体系的四个核心模块我最终把整套模板拆成了四块各司其职模块文件位置作用项目说明CLAUDE.md给 AI 提供项目背景、技术栈、约定、常用命令自定义命令.claude/commands/*.md把常用操作固化成斜杠指令比如/review、/test子代理.claude/agents/*.md定义不同角色的 AI比如架构师、审查员、调试助手权限与钩子.claude/settings.json、hooks控制 AI 能做什么、不能做什么关键动作做二次确认这四块的职责边界非常清晰。项目说明解决“背景缺失”自定义命令解决“重复劳动”子代理解决“角色混乱”权限钩子解决“失控风险”。下面详细拆开讲。2. CLAUDE.md项目的“说明书”怎么写才有效CLAUDE.md是 Claude Code 在项目根目录读取的项目说明文件。它的地位很像项目 README但读者不是人而是 AI。AI 会在每次对话时持续参考这个文件来判断项目背景、输出风格、操作边界。有朋友问我写 CLAUDE.md 是不是就是把 README 抄一遍不是。README 面向人可以讲故事、讲背景、讲愿景CLAUDE.md面向 AI必须讲约束、讲路径、讲命令、讲避坑点。一个合格的 CLAUDE.md 应该可以在 AI 头脑里快速转成“操作手册”。2.1 推荐结构与字段我常用的一套结构是七个板块顺序也有讲究# 项目名称 ## 一句话概述 xxx 服务负责 xxx核心目标是 xxx。 ## 技术栈 - 前端: React 18 TypeScript Vite - 后端: Node.js 20 Express - 数据库: PostgreSQL 15 Prisma - 测试: Vitest Testing Library - 包管理器: pnpm ## 常用命令 - 安装依赖: pnpm install - 启动开发: pnpm dev - 构建: pnpm build - 单测: pnpm test - 代码检查: pnpm lint - 提交规范: pnpm commit ## 目录结构 - src/components —— 通用组件禁止放业务逻辑 - src/pages —— 页面组件一个路由对应一个目录 - src/api —— 所有接口调用统一收敛在这里禁止在组件内直接写 fetch - src/store —— 全局状态优先使用 zustand - src/utils —— 纯函数工具集禁止出现 DOM 操作 ## 代码约定 - 组件一律函数式写法禁止 class 组件 - props 使用 TypeScript 定义禁止 any - 样式使用 CSS Modules不引入全局样式污染 - 文件命名组件用 PascalCase工具函数用 camelCase - 注释只写为什么不写是什么 ## 测试约定 - 每个工具函数必须要有单测 - 组件测试主要覆盖交互行为和关键渲染 - 禁止对私有实现细节做断言 ## 避坑清单 - 禁止直接改数据库表结构必须走 migration - 生产环境日志禁止输出用户手机号等敏感信息 - 不要删除 src/api 下的兼容层下游服务还在依赖 - 依赖升级前必须跑一遍全量回归各部分顺序不是随便排的。概述放最前是让 AI 在最短时间内建立项目心智模型技术栈和命令紧跟其后是让它知道“这个项目里我该用什么工具”目录结构讲清边界让它改动时有明确落点代码约定和测试约定是输出质量的规格说明避坑清单是全篇最值钱的部分里面写的是你在这条路上踩过的雷AI 接管后可以少犯一遍。2.2 三层文档体系从全局到模块如果一个仓库里有多个独立应用根目录一份 CLAUDE.md 就不够用了。这时候可以用三层结构用户级~/.claude/CLAUDE.md写所有项目的通用规则比如“禁止修改保险相关配置”“代码评审必须检查安全点”这类不区分项目的底线。仓库级项目根目录/CLAUDE.md写技术栈、全局约定、共用模块说明。目录级src/modules/order/CLAUDE.md写这个业务模块的内部约定比如订单状态机怎么流转、哪些状态不允许跳转。Claude Code 会按优先级从高到低合并这些上下文。这样设计的好处是每个层级的文档都保持精简AI 在进入不同目录时自然加载对应说明不需要把全仓库的规则一次性塞进上下文。我见过把 1000 行说明堆在一个文件里的项目AI 每次回答问题前光读文档就会浪费大量 context结果反而更笨。2.3 会“打架”的规则怎么办写文档时不可避免遇到规则冲突比如用户级说“所有命令要二次确认”目录级说“这个目录下的命令直接跑”。这种情况不要寄希望于 AI 自行判断规则就是规则它会选择离上下文更近的那条。所以你在写低层级的规则之前最好先想想这条规则是不是真的应该凌驾于全局规则之上。如果只是这条命令确实安全那就在目录级写明原因“此命令只影响临时文件无破坏性”。另外CLAUDE.md不是写完就不动的。它应该像代码一样被 review。每季度过一遍把过时的目录说明删掉把新的坑补进去。我见过团队里 CLAUDE.md 写了之后半年没人动里面还写着已经废弃的技术栈AI 照着旧约定改代码那就不叫提效叫回退。3. 自定义命令与子代理的实现细节如果说CLAUDE.md是给 AI 的“背景设定”自定义命令就是给 AI 的“快捷指令”。你没给它定义命令时每次让它做 code review都要敲一大段要求定义好之后一个/review就能触发一整套标准评审流程。3.1 自定义命令的文件结构与示例命令文件放在项目根目录的.claude/commands/下文件名就是命令名。文件是 Markdown 格式头部用 YAML 定义元信息正文是提示词内容。一个简单的代码评审命令长这样--- description: 对指定文件做标准代码评审 argument-hint: [文件路径默认当前文件] --- 请对 input 文件做一次标准代码评审按以下维度逐项检查并输出 ## 检查维度 1. 安全性是否存在注入、敏感信息泄露、越权风险 2. 性能是否存在不必要的重复计算、明显的 N1 查询 3. 健壮性异常处理是否完整、边界条件是否覆盖 4. 可维护性命名是否清晰、职责是否单一、是否存在重复代码 ## 输出格式 | 等级 | 问题描述 | 具体位置 | 修改建议 | |------|----------|----------|----------| | P0 | 高优先级问题 | src/api/user.ts: 42 | 必须修复 | | P1 | 中优先级问题 | src/utils/date.ts: 18 | 建议修复 | | P2 | 一般建议 | src/pages/order.tsx: 77 | 可选 | 最后给出总体评价是否可以直接合并还是需要先处理 P0 再合并。这个命令的价值在于标准化评审维度。团队里每个人手动 review 时关注点可能不一样有人偏样式有人只盯逻辑。但通过/review触发时AI 至少保证每轮都会从安全、性能、健壮性、可维护性四个维度去看一个团队的标准就拉齐了。类似地我还会配置/test、/refactor、/commit、/docs这类高频指令。每个命令的核心思路都一样把你在提示词里反复敲的那段“标准需求”沉淀成模板让 AI 每次按同一套标准执行。3.2 子代理让 AI 切换角色子代理和自定义命令的区别是命令是“让 AI 做一件事”代理是“让 AI 成为某种角色”。子代理文件放在.claude/agents/每个文件对应一个角色AI 可以在主对话中按需唤起。一个架构师角色可以这样定义--- name: 架构师 description: 负责需求拆解、方案设计、技术选型输出可执行的开发计划 tools: Read, Grep, Glob, WebSearch mode: subagent --- 你是一位资深软件架构师。当接到一个功能需求时严格按以下流程处理 1. 先理解需求目标如果需求描述含糊列出需要澄清的问题 2. 输出技术方案包含 - 涉及的核心模块与改动范围 - 关键技术选型与选择理由 - 数据模型或接口设计的建议 3. 拆解任务列表每个任务标注依赖关系和验收标准 4. 列出风险点与回滚方案 注意 - 方案必须基于本仓库的现有技术栈不要引入未经确认的外部依赖 - 输出要简洁不要“贴代码式”地连篇累牍 - 如果发现需求与现有架构冲突要明确指出而不是硬扛定义子代理时有一条核心经验角色的边界要清晰但不要把所有细节都封装在黑盒里。tools字段决定它能使用哪些工具mode: subagent表示它以子任务方式运行主对话不会被它的中间思考过程污染只接收最终结果。这个机制特别适合做“并行思考”你有几十个文件要看让一个审查 Agent 去扫安全让一个架构 Agent 去评审设计主线程还能继续别的工作。3.3 写提示词模板的三个原则自定义命令和子代理的本质都是提示词模板。写提示词模板跟写普通提示词不一样有三个原则必须记住第一给定输入格式不如给定输出格式。你让 AI“分析这段代码”它给你写一篇散文你说“按表格输出四列分别是等级、位置、问题、建议”它至少不会跑题。模板里优先定义输出结构。第二约束比指导更可靠。不要写“注意代码质量”这种空话要写“禁止any”“组件禁止 class 写法”“函数超过 60 行必须拆分”。AI 对否定性约束的遵守程度明显好于对模糊概念的领悟程度。第三上下文变量要显式声明。命令里的input、argument是运行时注入的模板里必须把这些占位符写明确否则 AI 容易把占位符当成字面内容处理明明你要它读文件它却把“input”理解成字符串。4. 权限白名单与钩子配置安全落地的关键很多初用 Claude Code 的人不配置权限AI 说什么就是什么命令行里面跑什么全凭自觉。这对个人玩具项目问题不大但在真实项目里风险很高。权限配置是模板体系里最容易被忽略、也是最容易出事的部分。4.1 权限白名单怎么配权限配置写在.claude/settings.json核心是控制 AI 能执行哪些命令。一个典型的配置{ permissions: { defaultMode: plan, allow: [ Bash(pnpm run dev), Bash(pnpm run build), Bash(pnpm test), Bash(pnpm lint), Read, Write, Edit ], deny: [ Bash(rm -rf *), Bash(sudo *), Bash(git push --force), Bash(pnpm add *) ] } }这里的逻辑是“默认拒绝白名单放行”。defaultMode: plan意味着 AI 默认只做规划不直接动文件白名单里明确写清楚哪些命令可以跑哪些命令绝对禁止。新增依赖pnpm add不在白名单内AI 就没法自作主张给你装包必须回到主线程由你手动执行这一步能拦下不少“AI 自嗨式开发”的问题。配白名单时有两个细节容易踩坑。第一命令匹配要写完整前缀不能只写Bash(pnpm)否则pnpm add、pnpm run build、pnpm install全都会被同时放行白名单形同虚设。第二不要一上来就把所有常用命令都塞进白名单可以先让它跑一步、你确认一步观察两三天后再逐步扩大范围。权限管理宁可一开始紧一点也不要后面被吓一跳。4.2 钩子最后一道闸门权限解决的是“能不能跑”钩子解决的是“跑了之后符不符合要求”。钩子可以在工具调用前后触发自定义检测脚本典型场景包括在PostToolUse阶段检查输出内容不符合规范直接拦截在PreToolUse阶段检查将要执行的命令发现危险命令就拒绝在Stop阶段检查最终交付内容举一个简单的前置检查钩子脚本判断即将执行的命令里有没有危险模式#!/usr/bin/env bash # scripts/prompt-guard.sh # 检查传给 Bash 工具的命令中是否包含危险模式 INPUT_FILE$1 # 危险模式列表 PATTERNS( rm -rf / sudo rm -rf git push --force DROP TABLE TRUNCATE TABLE ) for pattern in ${PATTERNS[]}; do if grep -q $pattern $INPUT_FILE; then echo 拦截命令包含敏感模式: $pattern exit 130 fi done exit 0在settings.json里挂上这个脚本{ hooks: { PreToolUse: [ { matcher: Bash(rm *)|Bash(sudo *), hooks: [ { type: command, command: bash scripts/prompt-guard.sh } ] } ] } }钩子脚本的退出码决定后续行为0放行130拦截。如果你在脚本里看到exit 130那孩子这意味着“在此处必须停下”。把这个理解透你就可以写出极其强硬的保护网——比任何口头警告都可靠。需要注意钩子不能代替权限白名单。权限是前置判断钩子是后置兜底。两者同时存在才能把“大禹治水”的围堵策略落实到位。4.3 模板的安装与版本管理模板最终要能方便地复制到新项目里。我维护了一套目录结构并用一个安装脚本来自动化部署#!/usr/bin/env bash # install.sh —— 把模板安装到目标项目 # 用法: bash install.sh 目标项目目录 TARGET${1:-.} if [ ! -d $TARGET/.claude ]; then mkdir -p $TARGET/.claude/commands $TARGET/.claude/agents fi cp -r templates/commands/* $TARGET/.claude/commands/ cp -r templates/agents/* $TARGET/.claude/agents/ cp templates/settings.json $TARGET/.claude/settings.json echo 模板已安装到 $TARGET/.claude echo 请手动检查 settings.json 中的白名单模板仓库本身放在 Git 里管理版本更新后只要git pull再跑一遍安装脚本即可。这里有一条非常重要的经验不要把模板直接软链到项目里因为各项目可以根据自身情况微调配置直接软链会导致全局改动波及所有项目反而是隐患。复制一份到项目里各项目自由演进模板仓库只负责维护通用基线这是比较稳的玩法。5. 常见问题与避坑心得跑了一段时间模板我把实际中遇到的典型问题整理成了一张速查表方便你对照排查。问题表现可能原因解决办法AI 不按 CLAUDE.md 里的规则执行文档太啰嗦AI 没抓住重点压缩到两三百行重点前置规则用否定句自定义命令在斜杠列表里不显示文件后缀或头部 YAML 格式错误检查文件是否为.mdYAML 里description是否齐全白名单命令总是被拒权限规则匹配太严格或默认模式是 plan确认命令前缀与白名单一致必要时切到 acceptEdits 模式钩子脚本误杀合法命令危险模式 grep 匹配太宽收紧模式加上下文条件比如只匹配rm -rf /不匹配rm -rf ./dist模板在某项目里被改得面目全非没有版本管理边改边丢模板仓库和项目副本分开模板作为基线项目改动通过 PR 回流上下文过长导致 AI 变笨CLAUDE.md 和命令模板塞了太多信息把文档拆层级用目录级 CLAUDE.md 按需加载这些坑里最让我印象深刻的是“AI 变笨”这件事。刚开始我迷信‘规则越全越安全’写了一整本手册级的 CLAUDE.md结果 AI 每轮对话都先读一千多字的说明读取完还剩多少空间思考你的需求效果反而比没有文档时更差。后来我学会做减法只留技术栈、目录边界、命令、避坑清单四类信息规则条目务求“少而狠”。另一个心得是模板不是一次性的而是一个活的产物。我见过有同学建好模板后就不管了三个月后再看里面还在约束已经废弃的旧目录规范。正确姿势是每次项目发生结构性变化时顺手更新一下 CLAUDE.md就像维护 README 一样自然。也可以定期做一次“模板 review”拿一个真实需求去跑一遍新旧对比看看是变快了还是变慢了用结果反推模板改不改。最后分享一个我后来加进去的命令模板个人觉得这是整套模板里 ROI 最高的一个。它叫/handoff用途是生成交接文档。当你需要休假或把一个模块交给同事时执行这个命令AI 会读取近期改动记录、未完成任务、已知坑点和下一步建议汇总成一份交接说明。以前写交接文档要花一两个小时现在几分钟就能拿到初稿再补细节。这种“把团队协作中反复做的事固化成模板”的思路远比单纯堆配置文件更有价值。你的模板库不必追求大而全找到自己团队最高频的那个痛点把它做成命令已经赢了一半。
