如果你想系统化使用 Claude Code或者正在寻找一种方式把团队里的提示词工程经验沉淀下来那么claude-code-templates这类项目值得你花半小时研究一下。简单说它是一个围绕 Claude Code 的模板管理项目核心是把常用的 prompt、项目配置甚至整个目录骨架标准化让你不用每次在对话里重复解释背景、纪律和输出格式。它解决的是这样几个实际问题新成员加入项目时不需要靠口口相传了解规矩你写完一个高质量的代码审查 prompt 后不用再复制粘贴到聊天框里而是可以一键调用甚至整个项目的初始文件CLAUDE.md、自定义命令、配置规则都能用一套模板瞬间铺好。适合刚接触 Claude Code 的开发者也适合已经在团队里推广 AI 辅助编程、想要把用法沉淀成资产的人。这篇文章不打算讲假大空的概念我就直接以claude-code-templates为线索把我实际搭建模板库的过程、踩过的坑、以及最终沉淀下来的目录结构和配置原理一条条拆给你看。1. 这个项目到底在管什么从一次重复劳动说起先讲个场景。两个月前我在一个用 Python 写后端服务的仓库里每次让 Claude Code 帮忙改代码都要先花几百字描述项目结构、编码规范、单元测试要求。最痛苦的是每次对话结束下一轮又得重新交代一遍。后来我了解到 Claude Code 原生支持项目记忆文件CLAUDE.md和自定义斜杠命令而claude-code-templates正好就是把这些东西模板化的实践集合我才意识到之前的用法完全是折腾自己。1.1 核心需求拆解为什么不能只靠一段 prompt先说结论单条 prompt 解决不了上下文管理问题。你写一段“帮我重构这个函数并补充测试”Claude Code 确实能听懂但它不知道你的缩进风格是 4 空格还是 2 空格不知道你要求类型注解必须全量覆盖不知道测试框架用的是 pytest 还是 unittest。这些背景信息如果不沉淀每次对话你都变成复读机。claude-code-templates的核心思路是用一套可复制的文件结构把“背景知识”“操作指令”“输出规范”固化下来。它通常包含这几层CLAUDE.md项目根目录下的记忆文件每次对话自动加载。.claude/commands/自定义斜杠命令目录比如/review、/test。模板脚手架脚本用于生成上述文件的初始化模板。这套结构最大的价值是让 AI 的“行为”变得可版本化。你改一行规范所有使用该模板的项目都会跟着变你踩过一个坑可以把教训写成命令模板下次直接调用不用重新踩。1.2 方案选型模板目录结构为什么长这样我见过的claude-code-templates项目目录组织上大同小异核心是围绕 Claude Code 的加载机制来设计。Claude Code 在启动时会自动读取当前目录和~/.claude下的配置文件你放的每个文件都有明确的位置和加载优先级。文件/目录作用加载时机CLAUDE.md项目级记忆描述技术栈、代码风格、常用命令每次会话启动自动注入~/.claude/CLAUDE.md用户级记忆跨项目生效每次会话启动自动注入.claude/commands/*.md自定义斜杠命令比如/review输入斜杠命令时按需加载.claude/settings.json权限、环境变量、钩子配置会话启动时读取templates/或scripts/脚手架脚本或模板源文件手动执行生成我推荐把模板源文件和生成脚本分开不要直接把CLAUDE.md硬编码在脚手架里。原因是同一个模板往往有多种变体比如团队里有的人用 vim有的人用 VSCodeCLAUDE.md 里的编辑器指令就不该写死。把模板做成带变量的源文件比如使用简单的文本替换或者 Jinja2 语法生成时传入具体值就能一套模板多处复用。2. 核心细节解析CLAUDE.md 与自定义命令的配合这部分是整个模板库的灵魂。CLAUDE.md解决的是“AI 懂环境”的问题自定义命令解决的是“AI 干活动”的问题。两者缺一不可我一开始只写了CLAUDE.md后来发现没有命令模板很多高频操作还是要手动粘 prompt效率并没有本质提升。2.1 一份合格 CLAUDE.md 的写法很多人以为CLAUDE.md就是写“你是我的 AI 助手”这种废话完全不是。它是给模型看的项目说明书要具体到“如果让你改代码你需要注意什么”。我的一份典型模板长这样# 项目记忆 ## 技术栈 - 后端Python 3.11, FastAPI, SQLAlchemy 2.x - 测试pytest httpx - 数据库PostgreSQL 15, 使用 Alembic 做迁移 ## 代码风格 - 类型注解必须覆盖所有函数签名包括返回值。 - 导入一律使用绝对导入禁止 from .xxx import *。 - 字符串优先用双引号但 SQL 内嵌语句除外。 - 所有业务函数必须附带 docstring写清楚参数和副作用。 ## 构建与运行 - 本地开发docker compose up dev - 测试poetry run pytest - 迁移alembic upgrade head ## 约定 - 不修改数据库迁移脚本的历史版本。 - 接口返回结构统一为 {code, message, data}。 - 修改涉及数据库模型时需要同步生成迁移文件。看到关键点了吗这份文件没有一句“如何做事”的空话全是“本项目要求什么”。模型读取后相当于你在入职第一天把开发手册丢了它。注意别写太长我之前写过 300 行的CLAUDE.md结果模型反而抓不住重点。一般 30 到 80 行就够了超过 100 行建议拆成CLAUDE.md加CLAUDE.local.md或者把详细规则放进命令模板按需加载。2.2 自定义斜杠命令模板的正确姿势.claude/commands/目录下的每个.md文件就是一个斜杠命令。文件名不带.md后缀就是命令名文件内容就是 prompt 模板。比如我建了一个review.md内容如下请对当前目录下的代码变更执行代码审查。审查规则 1. 逐个文件检视只关注有变更的部分。 2. 优先检查以下问题 - 是否存在未处理的异常。 - 是否有 SQL 注入或 XSS 风险。 - 事务是否可能跨请求持有过长时间。 - 新代码是否遵守 CLAUDE.md 中定义的风格要求。 3. 输出格式 - 严重问题必须修改标注文件、行号、原因、建议。 - 建议改进可选只列关键项。 - 最后给出一段总结说明整体质量。使用时在 Claude Code 里输入/review它就会按这个框架执行。比手打 prompt 强在哪第一是稳定性不会再出现今天让它输出表格明天让它输出列表的情况第二是支持参数比如你写{{file}}调用时/review README.md就能把参数传进来实现针对单一文件的审查。命令模板里我建议也写清楚“输出风格”否则模型很容易放飞自我。比如我会加一句必须覆盖风险等级、位置、复现步骤、修复建议四要素。模型对于结构化指令的遵从度很高但前提是你把格式敲死。2.3 settings.json 里容易被忽略的三个开关claude-code-templates里一般还会带一份.claude/settings.json用来控制权限和行为。很多人忽略它结果要么是 Claude Code 频繁请求权限要么是它误改了不该动的文件。我常用这三个配置{ permissions: { allow: [ Bash(npm test:*), Read($HOME/**), Edit(**), WebFetch(domain:docs.python.org) ], deny: [ Bash(rm -rf *), Bash(git push --force *) ] }, hooks: { PreToolUse: [], PostToolUse: [] }, model: claude-sonnet-4-20250514 }permissions.allow和deny是白名单和黑名单。注意顺序deny 优先级高于 allow。WebFetch的域名限制是我后来加的否则模型遇到问题会随便抓网页。hooks 可以用来做自动化检查比如每次工具执行后跑一遍 lint不过配置起来有点门槛建议新手先从 permissions 和 model 开始。3. 实操过程从零搭建一套 claude-code-templates空谈无用。我把自己的模板库完整复现一遍你可以直接照着改。先说环境我用的 Claude Code 版本比较新旧版本可能在settings.json上略有差异但CLAUDE.md和命令目录在早期版本就原生支持兼容性没问题。3.1 第一步创建目录骨架我建议你在一个独立仓库里维护模板而不是直接塞进业务项目。这样更新一份模板所有引用它的项目可以通过 submodule 或复制同步。我本地的目录结构是这样claude-code-templates/ ├── README.md ├── scaffold.sh ├── claude/ │ ├── CLAUDE.md │ ├── CLAUDE.local.md.example │ └── settings.json └── commands/ ├── review.md ├── test.md ├── commit.md └── docs.mdscaffold.sh负责把claude/和commands/复制到目标项目并在复制过程中按需做变量替换。比如它会读环境变量PROJECT_TYPE如果值是python就在CLAUDE.md里填入 Python 相关技术栈如果值是node则填入 Express 相关配置。这就是模板能在不同项目间复用的关键。3.2 第二步写可复用的模板源文件这里我以 Python 后端项目为例。注意我不用复杂的模板引擎纯sed就能完成替换因为模板里需要变动的无非是项目名、技术栈、测试命令这几个字段。如果你团队项目很多量也大可以用 Jinja2但对大多数人来说sed足够。CLAUDE.md里我抽出了三个变量{{PROJECT_NAME}}{{TEST_CMD}}{{LINT_CMD}}然后写一个scaffold.sh核心片段#!/usr/bin/env bash set -euo pipefail TARGET_DIR${1:?用法: scaffold.sh 目标目录} PROJECT_NAME${PROJECT_NAME:-my_project} TEST_CMD${TEST_CMD:-poetry run pytest} LINT_CMD${LINT_CMD:-poetry run ruff check .} mkdir -p $TARGET_DIR/.claude/commands sed s/{{PROJECT_NAME}}/$PROJECT_NAME/g; \ s|{{TEST_CMD}}|$TEST_CMD|g; \ s|{{LINT_CMD}}|$LINT_CMD|g \ claude/CLAUDE.md $TARGET_DIR/CLAUDE.md cp claude/settings.json $TARGET_DIR/.claude/settings.json cp commands/*.md $TARGET_DIR/.claude/commands/有个细节坑sed的替换分隔符默认是/但测试命令里也可能有/所以我用|作为分隔符。另外set -euo pipefail必须写否则变量未设置时脚本会静默生成一份缺字的模板这种 bug 最坑人。3.3 第三步打造有参数的斜杠命令命令模板也可以带参数这是claude-code-templates特别妙的一点。以commit.md为例我不希望每次提交都要人工写一堆规范说明所以我定义了一个/commit命令根据当前 git 状态生成规范的提交信息。 当前分支{{branch}} 要求 1. 运行 git diff --stat 和 git diff 了解改动。 2. 提交信息使用 Conventional Commits 格式。 3. 第一行不超过 72 字符。 4. 类型限定为 feat / fix / docs / style / refactor / test / chore。 5. message 用中文描述但 type 和 scope 用英文。 输出示例 feat(auth): 增加 token 刷新接口参数{{branch}}可以让模型在生成提交信息时感知当前分支避免把分支名写进正文。实际调用时直接输入/commit然后 Claude Code 会自动替换变量。注意模板本身不要包含具体分支名必须用变量否则你切了分支模板就失效了。3.4 第四步配一个初始化钩子可选如果你希望模板项目在克隆后能自动完成初始化可以加一个.gitignore以外的 post-checkout 钩子。我自己没有用因为团队里有人不喜欢自动执行脚本。但如果你是一个人用建议加上这个体验# 在 .git/hooks/post-checkout 中 if [ -f scaffold.sh ]; then echo 检测到模板项目执行初始化... bash scaffold.sh . fi当然钩子不会被 git 跟踪所以需要你手动放到本机目录或者在README.md里写清楚让每个 clone 者手动执行一次。我更推荐后者因为自动化脚本一旦出错会立刻劝退新人。3.5 实操补遗不同的模板源如何处理如果你的项目涉及多种语言不要把规则写死在同一个CLAUDE.md里。我在模板库里放了多个变体文件例如CLAUDE.python.md、CLAUDE.node.md、CLAUDE.go.md。scaffold.sh根据参数选择复制哪一个。这也让模板本身能独立演进Python 的规范更新不会影响 Go 的。一个血泪教训变量名不要太长太杂。最初我定义了{{PROJECT_DESCRIPTION}}、{{BACKEND_FRAMEWORK}}、{{FRONTEND_FRAMEWORK}}等七八个变量结果每次创建新项目都要交互式问一堆问题最后直接把脚本拉黑。现在只保留三个必需变量其余都靠写死规则或模型自行推断反而更实用。4. 常见问题与排查技巧实录再完美的模板用起来也会遇到各种幺蛾子。以下是我在维护和推广这套模板过程中遇到的高频问题以及对应的解决思路。这部分是纯实战没有教科书内容每一条都是我用时间和脑细胞换来的。4.1 CLAUDE.md 没有被加载或加载了旧版本最典型的现象是你在项目根目录放好了CLAUDE.md但修改后又觉得模型行为没变化。先排查一下是不是缓存。Claude Code 对项目记忆文件是有缓存的虽然不是每次都会读磁盘但你应该先确认文件路径是否正确。注意CLAUDE.md必须放在启动会话时的当前工作目录或者按其规则放在用户主目录的.claude下。如果你在一个子目录里启动会话根目录的CLAUDE.md不一定会被读取。解决方法是检查会话日志或主动询问模型“你知道 CLAUDE.md 内容吗”如果不知道多半是路径问题。另一个坑是文件编码务必保存为 UTF-8不带 BOM。我第一次用 VSCode 默认编码创建文件没事但在 Windows 上换行符是 CRLF个别情况下模型会把\r当成内容的一部分导致规范判断失误。稳妥起见把CLAUDE.md统一转为 LF 换行。4.2 斜杠命令前缀冲突自定义命令名不能和内置命令重复比如/init、/compact、/clear这类的名字你覆盖不了也不应该覆盖。我最初建了一个init.md命令结果调用时完全没反应后来才发现内置/init优先级更高。命名上建议加前缀比如团队名缩写或功能域。我用pyr前缀表示 Python 相关命令/pyr-review、/pyr-test、/pyr-lint。这样既避免冲突也方便快速筛选。文件名大小写也要注意命令是区分大小写的/Review和/review是两回事统一用小写最省事。4.3 模板变量替换后出现路径分隔符问题当你用sed替换路径时容易遇到分隔符冲突。比如模板里写Run tests: {{TEST_CMD}}而TEST_CMD的值是poetry run pytest没问题但如果是./scripts/run_tests.sh里面的斜杠就会破坏sed的替换语法。我在脚本里已经用了|作为分隔符但如果路径里恰好也有|还是会炸。最保险的做法是改用awk或者分层传入环境变量然后读取而不是文本替换。不过说实话一般项目不会在路径里加竖线这个坑概率很低知道即可。4.4 多个项目同时使用一套模板更新同步难这是最痛的。我一开始把模板复制到每个项目里后来在CLAUDE.md中新增了一条规范发现所有旧项目都还是老规矩模型一直按旧的思路走。解决方案有两个我最终选了第二个用 git submodule 把claude-code-templates作为公共子模块挂进项目。把命令和配置集中在用户级目录~/.claude/项目级只保留个别差异文件。我最终选了第二个方案。理由很简单用户级CLAUDE.md和命令目录对所有项目全局生效不用每个项目都同步。但这也意味着你在这个机器上开的任何 Claude Code 都会读到这些模板所以用户级模板只能放放之四海皆准的内容比如代码风格总纲、审查流程、提交规范具体到某个项目的技术栈细节还是要放项目级CLAUDE.md。4.5 模型无视模板中的格式要求哪怕你模板里写了“输出必须使用表格”模型偶尔还是会输出大段文字。遇到这种情况不要急着怀疑模板有问题很可能是你没有限定输出格式的边界。我总结了一个有效套路在模板里先给一个“伪示例”再用“接下来按照上述示例”收尾。比如审查结果按以下格式输出示例 | 风险等级 | 文件 | 行号 | 问题描述 | 建议 | | --- | --- | --- | --- | --- | 如果不存在问题只输出一行未发现严重问题。模型对表格格式的遵从度在给出列名示例后显著提升。如果还是乱输出可能是模型在长上下文里丢失了这部分指令尝试把格式要求放在模板开头而不是结尾实践证明放在开头的效果更好。4.6 权限配置太严导致命令无法执行有些命令模板里需要跑测试或读文件但如果你的settings.json里permissions没开对Claude Code 会一直问你要授权。频繁授权会打断流程但全开allow又有风险。我的折中方案是把常见命令用小范围通配符放行比如Bash(pytest*)、Bash(ruff*)、Bash(git *)并把危险命令明确 deny。注意Bash(git *)会连git push --force也放行所以我在 deny 里加了一句Bash(git push --force *)。上一条说了 deny 优先于 allow所以这种配置是安全的。如果你不确定就先保守一点把deny写清楚遇到授权弹窗再逐步放行。5. 进阶扩展让模板自己长出更多模板到这里你已经能搭建一套可用的 Claude Code 模板库了。但我还想分享另一个思路模板本身也可以处理“生成模板”这件事。很多人没发现的点是Claude Code 的自定义命令里同样可以定义“生成新命令”的命令。这相当于给你的模板库装了一个自举循环。我建了一个/newcmd命令内容很简单我想要创建一个新的斜杠命令文件目标是处理{{task}}。 请按照以下规则生成: 1. 文件放在 .claude/commands/ 下文件名需符合 kebab-case。 2. 内容必须包含输入条件、处理步骤、输出格式、注意事项。 3. 处理步骤必须拆解为不超过 5 步的具体行为。 4. 如果涉及工具使用列出具体的工具名称和期望参数。 5. 输出直接可写入文件的原始 markdown不要包裹在代码块里。当我需要新增一个“审查日志格式”命令时我只需输入/newcmd 审查日志格式模型就会帮我把命令文件生成好。我再稍作微调即可投入使用。这样你的模板库会像滚雪球一样越用越顺手而不是永远只有手工写的两三个命令。另外我还用模板库维护了一份README.md里面记录了每个命令的使用样例和变更记录。这样哪怕半年后再看我也能快速知道每个模板为什么存在、适用于什么场景。模板是给别人和未来的自己看的注释很重要。以上是我对claude-code-templates这类项目从拆解到实操的全部经验。如果你之前只是把 Claude Code 当聊天窗口用我强烈建议你花半天时间把模板库搭起来它带来的改变不是省几分钟打字而是从根本上让 AI 辅助开发的流程变得稳定、可演进、可传承。最后再分享一个小技巧模板文件里多写“不行”少写“应该”。“不要修改迁移历史文件”比“请谨慎处理数据库迁移”有效十倍。模型对禁止性指令的响应更明确这也是我在无数轮调试中换回来的心得。祝你也能把自己的提示词资产化越用越香。
