做claude-code-templates这套东西的起因特别朴素我受够了每次开新会话都要把项目背景、代码规范、审查要求从头教一遍。Claude Code 本身能力很强但它的“强”恰恰会让你付出代价——不给足约束它就能在一句话的任务里给你自由发挥出三个不同的实现方案。模板不是让 Claude 变得更笨而是把项目常识、技术栈约定和固定检查流程变成可复用的 Markdown 文件通过 CLAUDE.md 和斜杠命令自动灌进每一次对话。这篇文章把我从想法到落地的完整过程写下来包括每一套模板的使用场景、设计原因和踩过的坑。整个项目适合两类人一是想把自己的 Claude Code 从“偶尔好用的玩具”变成“稳定干活的生产力工具”的开发者二是需要在团队里统一 AI 编码行为的同学。如果你是第一次听说 Claude Code文章里的模板机制也能让你快速理解这类 CLI 编程助手该如何被约束和复用。1. 为什么需要模板先解决“每次重新教一遍”的问题1.1 一个让我崩溃的真实会话最初我用 Claude Code 干一件挺简单的活给一个 Python 服务加一个导出接口。我在会话里描述了需求、贴了相关文件它一上来就“体贴”地帮我重构了模块里的异常处理逻辑还顺手调整了几个函数命名。代码能跑但 code review 的时候被同事问了一句“这次改动里那几处重构是谁提的需求”我愣了半天。这个问题的根源不是 Claude 笨而是它太想把事情做好。LLM 本质上是一个“过度顺从”的系统你给的信息越少它就越倾向于用自己脑补的“最佳实践”来填补空白。这在工作里非常危险——它补出来的东西往往不是你项目的真实约定。你项目的测试命令是pnpm test不是npm test你的错误处理要求用返回码而不是抛异常你的新代码必须兼容 Python 3.8这些背景如果不提前告诉它它就用通用知识来猜。当时我意识到与其每次手动把这些话反复敲不如把它们写成文件让 Claude Code 在每次会话开始时自动读到。这就是模板的起点。1.2 模板的本质是上下文工程在深入模板结构之前有必要先建立一个认知Claude Code 和传统脚本不一样它没有“记住你上次说了什么”的能力。每个新会话都是一张白纸唯一能影响它行为的是你在本次会话里提供给它的上下文。模板的本质就是把“你希望它始终遵守的约定”固化下来变成每次请求里的隐性上下文。这里有个很形象的类比你新招了一个能力很强的实习生第一周你花了大量时间讲项目背景、代码规范、git 工作流。时间长了你会发现真正有价值的不只是那些零散的对话而是把约定写成一份新人手册。Claude Code 的模板就是给 AI 的一份新人手册。没有手册它能干活但干出来的活充满了不可控的“即兴发挥”有了手册它的输出会稳定非常多。有个反直觉的经验是模板不是越长越好而是越“稳”越好。我见过有人把几百条规范全塞进 CLAUDE.md结果上下文被撑爆Claude 反而抓不住重点。真正有效的模板体系是把“常驻规则”和“按需规则”分开前者只保留必须每次都遵守的硬性约定后者通过斜杠命令或文件引用按需加载。后面我会详细拆解这套分层逻辑。2. 模板体系怎么搭CLAUDE.md、斜杠命令和规则片段2.1 CLAUDE.md项目级自动加载的“使用说明书”Claude Code 会自动读取当前工作目录下的CLAUDE.md把里面的内容作为每次对话的默认背景。这是整个模板体系的基石也是我最早开始整理的地方。一份合格的 CLAUDE.md应该回答这几个问题这个项目是干什么的用了什么技术栈启动、测试、构建、类型检查的命令分别是什么代码风格有哪些硬性约定这次会话里 Claude 应该遵守哪些工作守则我常用的一个项目级 CLAUDE.md 模板大概长这样# 项目定位 这是一个面向内部使用的数据同步服务采用 Python 3.9 FastAPI PostgreSQL。 核心业务是拉取上游 API 数据做清洗后写入本地库。 # 高频命令 - 启动开发服务uvicorn app.main:app --reload - 运行全部测试pytest - 单测某个模块pytest tests/test_xxx.py - 构建 Docker 镜像docker build -t sync-service . # 代码风格 - Python 代码必须通过 mypy 严格模式检查 - 禁止使用 Any 绕过类型检查 - 函数命名用动词开头模块命名用下划线分隔 - 数据库操作必须走 SQLAlchemy Core禁止裸 SQL # 工作守则 1. 改动任何文件之前先说明改动理由和影响范围 2. 每次改动必须同步运行相关测试 3. 当命令报错时先读日志定位根因再给修复方案 4. 不要修改与本次任务无关的文件 5. 对外输出的所有 API 变更必须附带文档建议这个文件我在实际使用中调整过很多次最大的体感差异来自“工作守则”部分。光写“请遵守项目约定”是没用的要写清楚遇到什么情况应该怎么做。比如第 3 条如果不写Claude 看到测试报错可能会直接改测试去“修复”写了之后它会更倾向于先分析根因。2.2 斜杠命令把固定流程变成一句话CLAUDE.md 负责“常驻规则”但还有一类需求是“偶尔要用到的固定流程”。比如代码审查、重构、生成 commit message、写接口文档。这些流程如果全塞进常驻上下文会让每次对话的开销变大而且大多数时候用不上。正确的做法是做成斜杠命令。Claude Code 的斜杠命令机制很直接在.claude/commands/目录下放 Markdown 文件文件名就是命令名。比如我放了review.md那么在会话里输入/review 文件路径就会触发这个模板。最简单的命令文件长这样--- description: 对指定文件或改动做一轮代码审查 --- 请对 $ARGUMENTS 进行严格的代码审查按以下顺序输出报告 1. 正确性问题按严重程度排序 2. 安全隐患 3. 性能隐患 4. 可读性和维护性问题 5. 测试覆盖缺口 硬性规则 - 先看完整个文件再下结论 - 每个问题必须给出文件路径和行号 - 只输出建议不要直接修改代码 - 如果没有问题明确写出“未发现阻塞性问题”$ARGUMENTS是一个内置变量会被替换成用户在命令后输入的文本。也就是说执行/review src/main.py时Claude 实际上收到的是“请对 src/main.py 进行严格的代码审查……”。有几个细节直接影响斜杠命令好不好用description会在/help里展示所以别写“审查代码”这种毫无区分度的描述写成“按安全性和可维护性维度审查单个文件”更有价值。硬性规则要比建议更具体我习惯用“禁止”“必须”这类词。命令模板尽量避免超过 30 行太长会稀释指令的强度。2.3 规则片段按场景拆分的可插拔内容有些项目规范非常庞大比如数据库迁移文档、接口设计规范、前端组件约定。全部写进 CLAUDE.md 不现实做成斜杠命令又偏流程化。我的做法是把它们拆成独立的规则片段放在固定目录里需要的时候通过引用让 Claude 读取。Claude Code 支持在对话里通过文件路径把文件内容加入上下文。我习惯在项目里建一个docs/ai-rules/目录专门放这类规则片段docs/ai-rules/ ├── database.md # 数据库变更约定 ├── api-design.md # 接口设计规范 ├── git-workflow.md # 分支和提交约定 └── frontend.md # 前端组件样式约定然后在 CLAUDE.md 里写上一句# 文档引用 涉及数据库变更的任务先读取 docs/ai-rules/database.md 再动手。 涉及 API 设计时先读取 docs/ai-rules/api-design.md。这样常驻上下文不会膨胀同时让规则在恰当时机被调用。我比较常用的场景是数据库迁移因为这类任务对安全性的要求极高临时口述规则远不如让 Claude 先完整读一遍专项规范。这套“三层结构”——常驻的 CLAUDE.md、按需的斜杠命令、可插拔的规则片段——基本构成了我整个 claude-code-templates 项目的主干。3. 核心模板细节我打磨过的几套方案3.1 新项目启动模板把“从零到一”标准化新项目启动是个高频场景但它的坑往往是 Claude 太喜欢“自作主张”。我在 bootstrap 模板里专门加了约束让它不要过度设计。--- description: 初始化一个新项目的目录结构和基础文件 --- 请根据 $ARGUMENTS 描述的项目类型完成以下步骤 1. 创建标准的项目目录结构 2. 生成 README.md包含项目简介、启动命令、测试命令 3. 生成基础配置文件依赖管理、代码检查、格式化 4. 生成一个最小可运行的示例 硬性约束 - 依赖全部使用当前最新稳定版本 - 不要引入与任务无关的第三方库 - 目录结构要保持扁平化避免多层嵌套 - 不要生成任何认证、权限相关代码 - 完成后给出 3 条下一步建议有了这个模板我创建一个新 Python 服务或者前端项目时只需要输入/bootstrap python fastapi 项目就能得到一份基础骨架。相比手动初始化省去的不只是打字时间更重要的是输出质量稳定——它每次都会遵守“不过度设计”的约束。3.2 代码审查模板强制输出结构化报告代码审查是我用得最多的斜杠命令也是最容易“失效”的命令。最初的版本只写了“请审查代码”结果 Claude 给的回合一上来就是表扬全是空话。改进后的模板把输出格式钉死了加了严重程度分级和行号要求。核心变化是要求它先列问题再说理由而不是反过来。--- description: 按安全性和可维护性维度审查代码输出结构化报告 --- 请审查 $ARGUMENTS输出按以下格式组织 ## 阻塞性问题 必须修复才能合并的问题包含文件路径和行号 ## 严重问题 可能导致线上事故或明显性能劣化的问题 ## 建议改进 可读性、健壮性方面的改进建议 ## 亮点 值得保持的设计或写法 规则 - 如果某个分类没有问题写明“无” - 问题按严重程度降序排列 - 不要修改代码只输出报告 - 对于每个问题给出一个最小修复思路不必写出完整代码这套模板在团队里推广后最大的价值是破除了一个常见心理障碍以前让 Claude 审查代码它总会先说一堆优点来“讨好人”现在格式规定了“没有问题的分类写无”它就没法用空话填充了。3.3 重构模板给行为加上安全网重构是 Claude Code 的高危操作。它重构完测试偶尔会绿但实际上改了外部行为。所以我给重构命令设计了一个“测试基线先行”的硬性流程。--- description: 在行为不变的前提下重构指定模块 --- 重构目标$ARGUMENTS 执行流程 1. 先运行现有测试记录通过数量作为基线 2. 阅读目标模块的完整实现梳理对外暴露的接口 3. 制定重构计划先向用户展示计划再动手 4. 分小步执行每步必须保持代码可编译、测试可运行 5. 全部完成后运行完整测试对比基线 硬性约束 - 禁止改变任何外部接口的签名和返回值语义 - 禁止顺手清理与本次重构无关的代码 - 禁止升级或修改依赖版本 - 最后输出改动文件清单、风险点和测试结果用这个模板前我会手动提醒“先跑测试再看代码”但经常漏。现在模板强制了流程而且把“展示计划再动手”作为中间步骤给了人一次叫停的机会。在我看来这是整个模板里最值得复制的设计。3.4 提交信息模板让 git log 变得可读生成 commit message 这种事让 Claude 做要远比手写省力但默认生成的风格往往过于华丽。模板要做的就是标准化格式。--- description: 根据当前工作区的改动生成符合约定格式的 commit message --- 请基于用户提供的改动概述生成 commit message。 格式要求 - 第一行用动词开头不超过 50 个字符 - 第二行空行 - 第三行起用要点列出具体改动内容 - 如果涉及破坏性变更在末尾单独列出 禁止 - 不要使用 emoji - 不要添加“这是一个...”“本次提交...”这类废话 - 不要编造未在改动中出现的内容这里一个实际操作经验是Claude 生成 commit message 时最好由我先把改动内容过一遍再传给模板。完全让它自己去看 git diff很容易把一些临时调试代码也写进提交信息。3.5 架构评审模板给重大决策留痕当讨论涉及模块划分、依赖方向或数据模型设计时我会用架构评审模板。它不追求输出完整方案而是强制 Claude 把决策依据和取舍列出来这样人可以在关键岔路口做判断。--- description: 评审一个架构方案输出决策建议和风险清单 --- 架构方案背景$ARGUMENTS 输出内容 1. 方案的核心设计思想 2. 与常见替代方案的对比至少列出 2 个替代方案 3. 当前方案的主要优点 4. 当前方案的主要风险和适用边界 5. 如果采用此方案建议的落地步骤 要求 - 每个结论必须给出理由 - 风险部分必须具体到模块或接口禁止写“可能存在性能问题”这类空泛描述 - 如果替代方案在某些维度明显更优明确指出来这套模板让架构评审不只是“一个人对着 Claude 脑暴”而是能在团队里留下来一份可读的决策记录。我之后会把输出整理进项目文档方便回头看当初为什么这么设计。4. 实操把模板装进自己的 Claude Code4.1 目录规划项目级与用户级模板装在哪里决定了它能作用到哪些场景。Claude Code 支持两个层级的模板用户级和项目级。用户级目录通常在~/.claude/下~/.claude/ ├── CLAUDE.md # 对所有项目生效的全局约定 └── commands/ # 用户级斜杠命令项目级目录则放在当前仓库里你的项目/ ├── CLAUDE.md └── .claude/ └── commands/我的经验是用户级只放两类东西——类如“回复尽量用中文”“代码要写注释”这种与项目无关的个人偏好而项目相关的任何内容都放进项目级并且跟着 Git 走。这样做的好处是团队其他人 clone 仓库后一模一样的 AI 行为约定也随之落地。有一个容易踩的坑是目录层级。如果你在子目录里新建了另一个CLAUDE.md它的优先级会更高适合处理“这个子目录有自己的特殊规则”的情况。但普通项目里最好不要到处放 CLAUDE.md不然规则冲突会让人抓狂。4.2 创建和调试一个斜杠命令以创建一个/test-case命令为例完整流程如下第一步建立命令目录。如果项目里还没有.claude/commands/手动创建。mkdir -p .claude/commands第二步创建test-case.md文件写入模板内容--- description: 为指定函数或模块生成测试用例 --- 请为 $ARGUMENTS 生成一组测试用例。 要求 1. 先梳理函数的输入、输出、边界条件 2. 覆盖正常路径、异常路径、边界值 3 类场景 3. 遵循项目现有的测试框架和命名风格 4. 不要修改被测代码 5. 输出时先说明每个用例的意图再放具体代码第三步在 Claude Code 会话里直接输入/test-case src/utils/format_date.py观察输出。如果命令不生效我通常会按下面顺序排查检查文件名后缀是不是.md检查是不是放在.claude/commands/而非其他目录检查 front matter 里的描述是否被错误地放在正文中间输入/看看命令列表里有没有出现如果不出现重启会话再试。调试中有个很关键的点斜杠命令里$ARGUMENTS的大小写一定要准确写成$arguments不会被替换。我自己至少在这里翻过一次车。4.3 团队协作模板要进 Git变更要走评审把模板带到团队里最大的改变是“AI 的使用行为”突然变得可控了。这时候模板本身就成了需要被管理的资产。我建议团队把.claude/目录纳入 Git 版本控制同时把 CLAUDE.md 作为项目文档的一部分来维护。任何对模板的修改都应该走和普通代码变更一样的流程提 PR、有人 review、合入后更新说明。团队协作里另一个值得注意的点是不要在用户级个人环境的 CLAUDE.md 里写团队规范。如果张三习惯写“所有代码用 TypeScript”李四的全局配置里写了“优先用 JavaScript”两人在同一个项目里的 AI 行为就会莫名其妙地不一致。正确的做法是团队规范只出现在项目级文件里用户级只保留个人偏好。当一个团队刚开始使用这套模板体系时建议从一个高频痛点场景切入比如统一/review命令而不是一上来就堆全套模板。这样大家的学习成本低也更容易验证模板是否真的有用。5. 常见问题与排查实录5.1 Claude 完全无视模板里的规则这个问题我遇到过很多次而且往往不是模板没生效而是模板里的规则“失效”了。表现是CLAUDE.md 里明明写了“禁止修改与本次任务无关的文件”结果它还是顺手改了配置文件的格式。我的排查顺序是先确认指令本身是否足够明确。像“请遵守项目规范”就是典型的无效指令“禁止修改未在任务说明中提到的文件”这种带明确边界的话才有效。再确认指令位置。越靠前的指令优先级越高关键规则尽量放在 CLAUDE.md 很靠前的位置。最后确认是否有冲突。如果用户级 CLAUDE.md 里有相反的习惯要求项目级规则会被干扰。处理方式是统一以项目级为准并在用户级减少强约束。而且有几个词对模型特别有效“必须”“禁止”“唯一例外是”。这些强约束词虽然听起来像是在训小孩但对 AI 的输出稳定性帮助非常大。5.2 模板导致上下文被撑爆CLAUDE.md 文件过长是最常见的上下文杀手。Claude Code 每次请求都会把 CLAUDE.md 内容放进上下文如果里面有几百行不痛不痒的内容会把有限的上下文窗口占用掉导致真正干活时可用空间变小。我的控制策略是CLAUDE.md 只放“每句话都值得 Claude 知道”的信息。凡是某个场景才用的内容一律拆到斜杠命令或者规则片段里。比如“数据库迁移时必须先跑一个 dry-run”这种规则我会放进database.md规则片段而不是写进常驻的 CLAUDE.md。现在我的项目级 CLAUDE.md 基本控制在 100 行以内。超过这个长度我会自动怀疑是不是有内容应该被拆出去。5.3 斜杠命令不生效或行为不对斜杠命令不生效九成是路径或文件名的问题。命令目录必须是.claude/commands/文件名不能带空格不能写中文名至少我建议不要。命令列表里没显示重启会话通常能解决。另一个隐蔽问题是命令文件更新了但当前会话里触发的还是旧版本。Claude Code 在会话中会有上下文累积改了命令文件后最稳妥的做法是开一个新会话再测别在长会话里反复验证。我还会在命令模板里故意放一个“验证点”比如让命令输出里必须包含“本次审查基于模板”字样这样我能一眼看出它到底有没有加载到新模板。如果输出的格式还是老样子说明加载有问题。5.4 团队里的模板版本冲突多人协作时有人改了项目级命令文件但没提交 Git有人本地有旧的用户级命令把项目级命令覆盖了。这类冲突排查起来很烦。我的处理方案是给命令模板的 front matter 加一个version: 1.x字段同时在输出里要求它体现版本。合入 PR 前跑一次冒烟测试确认命令输出包含目标版本号。这套机制让我们团队在一段时间内稳定识别出“谁的本地配置是旧的”。5.5 常见问题速查表症状可能原因优先处理方式CLAUDE.md 内容没生效文件不在工作目录根路径或名称大小写不对检查路径与文件名重启会话模板规则被无视指令太模糊或与用户级配置冲突改用强制词检查用户级 CLAUDE.md斜杠命令不出现目录或文件名错误检查.claude/commands/*.md重启会话$ARGUMENTS没被替换变量名大小写写错确认写成$ARGUMENTS上下文太小CLAUDE.md 过长将大段规则拆到按需加载的文件中团队行为不一致用户级配置覆盖项目级把团队规范统一下沉到项目级文件这张表也是我团队的docs/ai-rules/git-workflow.md里的一部分每次新人接入时直接发过去能省掉大量重复答疑。6. 几个让我省时间的进阶玩法模板体系稳定之后我又顺手做了几个小工具型模板灵活度更高。一个是“链式任务模板”先用一个命令让 Claude 输出实现方案得到确认后再发另一个命令让它按方案立刻编码。两个命令之间的衔接点就是人的决策点这样既保留了 AI 的效率又不至于让它一路狂奔到错误的终点。第二个是“文档迭代模板”。每次接口变更后我会用/doc-update模板让它同步更新接口文档和 CHANGELOG。模板里写明了“对比上一次文档找出差异并更新”比手动找 diff 靠谱得多。这些进阶模板没有进入最初的核心模板集因为它们的普适性没有前几套那么高。但它们的出现恰恰说明了这套模板体系的扩展性——只要你能把重复的流程抽象成 Markdown 文件就能让 Claude Code 按你的节奏工作。我个人在实际操作中的体会是模板最值得投入时间的地方不是写出漂亮的提示词而是持续观察“Claude 在哪里出现了意想不到的行为”然后把对应的约束补进去。每个模板从第一版到稳定版中间基本都要改三四次这是很正常的过程。最后再分享一个小技巧每次 Claude Code 大版本升级之后我会用一个空仓库跑一遍全部斜杠命令的冒烟任务确保模板里依赖的行为没被新版本破坏。这个习惯帮我提前避掉过不少升级带来的“隐性不兼容”。 
长河君 · 2026/9/26 17:35:53 · 阅读 1.2k Claude Code模板实战：从上下文工程到团队统一AI编码行为
做claude-code-templates这套东西的起因特别朴素我受够了每次开新会话都要把项目背景、代码规范、审查要求从头教一遍。Claude Code 本身能力很强但它的“强”恰恰会让你付出代价——不给足约束它就能在一句话的任务里给你自由发挥出三个不同的实现方案。模板不是让 Claude 变得更笨而是把项目常识、技术栈约定和固定检查流程变成可复用的 Markdown 文件通过 CLAUDE.md 和斜杠命令自动灌进每一次对话。这篇文章把我从想法到落地的完整过程写下来包括每一套模板的使用场景、设计原因和踩过的坑。整个项目适合两类人一是想把自己的 Claude Code 从“偶尔好用的玩具”变成“稳定干活的生产力工具”的开发者二是需要在团队里统一 AI 编码行为的同学。如果你是第一次听说 Claude Code文章里的模板机制也能让你快速理解这类 CLI 编程助手该如何被约束和复用。1. 为什么需要模板先解决“每次重新教一遍”的问题1.1 一个让我崩溃的真实会话最初我用 Claude Code 干一件挺简单的活给一个 Python 服务加一个导出接口。我在会话里描述了需求、贴了相关文件它一上来就“体贴”地帮我重构了模块里的异常处理逻辑还顺手调整了几个函数命名。代码能跑但 code review 的时候被同事问了一句“这次改动里那几处重构是谁提的需求”我愣了半天。这个问题的根源不是 Claude 笨而是它太想把事情做好。LLM 本质上是一个“过度顺从”的系统你给的信息越少它就越倾向于用自己脑补的“最佳实践”来填补空白。这在工作里非常危险——它补出来的东西往往不是你项目的真实约定。你项目的测试命令是pnpm test不是npm test你的错误处理要求用返回码而不是抛异常你的新代码必须兼容 Python 3.8这些背景如果不提前告诉它它就用通用知识来猜。当时我意识到与其每次手动把这些话反复敲不如把它们写成文件让 Claude Code 在每次会话开始时自动读到。这就是模板的起点。1.2 模板的本质是上下文工程在深入模板结构之前有必要先建立一个认知Claude Code 和传统脚本不一样它没有“记住你上次说了什么”的能力。每个新会话都是一张白纸唯一能影响它行为的是你在本次会话里提供给它的上下文。模板的本质就是把“你希望它始终遵守的约定”固化下来变成每次请求里的隐性上下文。这里有个很形象的类比你新招了一个能力很强的实习生第一周你花了大量时间讲项目背景、代码规范、git 工作流。时间长了你会发现真正有价值的不只是那些零散的对话而是把约定写成一份新人手册。Claude Code 的模板就是给 AI 的一份新人手册。没有手册它能干活但干出来的活充满了不可控的“即兴发挥”有了手册它的输出会稳定非常多。有个反直觉的经验是模板不是越长越好而是越“稳”越好。我见过有人把几百条规范全塞进 CLAUDE.md结果上下文被撑爆Claude 反而抓不住重点。真正有效的模板体系是把“常驻规则”和“按需规则”分开前者只保留必须每次都遵守的硬性约定后者通过斜杠命令或文件引用按需加载。后面我会详细拆解这套分层逻辑。2. 模板体系怎么搭CLAUDE.md、斜杠命令和规则片段2.1 CLAUDE.md项目级自动加载的“使用说明书”Claude Code 会自动读取当前工作目录下的CLAUDE.md把里面的内容作为每次对话的默认背景。这是整个模板体系的基石也是我最早开始整理的地方。一份合格的 CLAUDE.md应该回答这几个问题这个项目是干什么的用了什么技术栈启动、测试、构建、类型检查的命令分别是什么代码风格有哪些硬性约定这次会话里 Claude 应该遵守哪些工作守则我常用的一个项目级 CLAUDE.md 模板大概长这样# 项目定位 这是一个面向内部使用的数据同步服务采用 Python 3.9 FastAPI PostgreSQL。 核心业务是拉取上游 API 数据做清洗后写入本地库。 # 高频命令 - 启动开发服务uvicorn app.main:app --reload - 运行全部测试pytest - 单测某个模块pytest tests/test_xxx.py - 构建 Docker 镜像docker build -t sync-service . # 代码风格 - Python 代码必须通过 mypy 严格模式检查 - 禁止使用 Any 绕过类型检查 - 函数命名用动词开头模块命名用下划线分隔 - 数据库操作必须走 SQLAlchemy Core禁止裸 SQL # 工作守则 1. 改动任何文件之前先说明改动理由和影响范围 2. 每次改动必须同步运行相关测试 3. 当命令报错时先读日志定位根因再给修复方案 4. 不要修改与本次任务无关的文件 5. 对外输出的所有 API 变更必须附带文档建议这个文件我在实际使用中调整过很多次最大的体感差异来自“工作守则”部分。光写“请遵守项目约定”是没用的要写清楚遇到什么情况应该怎么做。比如第 3 条如果不写Claude 看到测试报错可能会直接改测试去“修复”写了之后它会更倾向于先分析根因。2.2 斜杠命令把固定流程变成一句话CLAUDE.md 负责“常驻规则”但还有一类需求是“偶尔要用到的固定流程”。比如代码审查、重构、生成 commit message、写接口文档。这些流程如果全塞进常驻上下文会让每次对话的开销变大而且大多数时候用不上。正确的做法是做成斜杠命令。Claude Code 的斜杠命令机制很直接在.claude/commands/目录下放 Markdown 文件文件名就是命令名。比如我放了review.md那么在会话里输入/review 文件路径就会触发这个模板。最简单的命令文件长这样--- description: 对指定文件或改动做一轮代码审查 --- 请对 $ARGUMENTS 进行严格的代码审查按以下顺序输出报告 1. 正确性问题按严重程度排序 2. 安全隐患 3. 性能隐患 4. 可读性和维护性问题 5. 测试覆盖缺口 硬性规则 - 先看完整个文件再下结论 - 每个问题必须给出文件路径和行号 - 只输出建议不要直接修改代码 - 如果没有问题明确写出“未发现阻塞性问题”$ARGUMENTS是一个内置变量会被替换成用户在命令后输入的文本。也就是说执行/review src/main.py时Claude 实际上收到的是“请对 src/main.py 进行严格的代码审查……”。有几个细节直接影响斜杠命令好不好用description会在/help里展示所以别写“审查代码”这种毫无区分度的描述写成“按安全性和可维护性维度审查单个文件”更有价值。硬性规则要比建议更具体我习惯用“禁止”“必须”这类词。命令模板尽量避免超过 30 行太长会稀释指令的强度。2.3 规则片段按场景拆分的可插拔内容有些项目规范非常庞大比如数据库迁移文档、接口设计规范、前端组件约定。全部写进 CLAUDE.md 不现实做成斜杠命令又偏流程化。我的做法是把它们拆成独立的规则片段放在固定目录里需要的时候通过引用让 Claude 读取。Claude Code 支持在对话里通过文件路径把文件内容加入上下文。我习惯在项目里建一个docs/ai-rules/目录专门放这类规则片段docs/ai-rules/ ├── database.md # 数据库变更约定 ├── api-design.md # 接口设计规范 ├── git-workflow.md # 分支和提交约定 └── frontend.md # 前端组件样式约定然后在 CLAUDE.md 里写上一句# 文档引用 涉及数据库变更的任务先读取 docs/ai-rules/database.md 再动手。 涉及 API 设计时先读取 docs/ai-rules/api-design.md。这样常驻上下文不会膨胀同时让规则在恰当时机被调用。我比较常用的场景是数据库迁移因为这类任务对安全性的要求极高临时口述规则远不如让 Claude 先完整读一遍专项规范。这套“三层结构”——常驻的 CLAUDE.md、按需的斜杠命令、可插拔的规则片段——基本构成了我整个 claude-code-templates 项目的主干。3. 核心模板细节我打磨过的几套方案3.1 新项目启动模板把“从零到一”标准化新项目启动是个高频场景但它的坑往往是 Claude 太喜欢“自作主张”。我在 bootstrap 模板里专门加了约束让它不要过度设计。--- description: 初始化一个新项目的目录结构和基础文件 --- 请根据 $ARGUMENTS 描述的项目类型完成以下步骤 1. 创建标准的项目目录结构 2. 生成 README.md包含项目简介、启动命令、测试命令 3. 生成基础配置文件依赖管理、代码检查、格式化 4. 生成一个最小可运行的示例 硬性约束 - 依赖全部使用当前最新稳定版本 - 不要引入与任务无关的第三方库 - 目录结构要保持扁平化避免多层嵌套 - 不要生成任何认证、权限相关代码 - 完成后给出 3 条下一步建议有了这个模板我创建一个新 Python 服务或者前端项目时只需要输入/bootstrap python fastapi 项目就能得到一份基础骨架。相比手动初始化省去的不只是打字时间更重要的是输出质量稳定——它每次都会遵守“不过度设计”的约束。3.2 代码审查模板强制输出结构化报告代码审查是我用得最多的斜杠命令也是最容易“失效”的命令。最初的版本只写了“请审查代码”结果 Claude 给的回合一上来就是表扬全是空话。改进后的模板把输出格式钉死了加了严重程度分级和行号要求。核心变化是要求它先列问题再说理由而不是反过来。--- description: 按安全性和可维护性维度审查代码输出结构化报告 --- 请审查 $ARGUMENTS输出按以下格式组织 ## 阻塞性问题 必须修复才能合并的问题包含文件路径和行号 ## 严重问题 可能导致线上事故或明显性能劣化的问题 ## 建议改进 可读性、健壮性方面的改进建议 ## 亮点 值得保持的设计或写法 规则 - 如果某个分类没有问题写明“无” - 问题按严重程度降序排列 - 不要修改代码只输出报告 - 对于每个问题给出一个最小修复思路不必写出完整代码这套模板在团队里推广后最大的价值是破除了一个常见心理障碍以前让 Claude 审查代码它总会先说一堆优点来“讨好人”现在格式规定了“没有问题的分类写无”它就没法用空话填充了。3.3 重构模板给行为加上安全网重构是 Claude Code 的高危操作。它重构完测试偶尔会绿但实际上改了外部行为。所以我给重构命令设计了一个“测试基线先行”的硬性流程。--- description: 在行为不变的前提下重构指定模块 --- 重构目标$ARGUMENTS 执行流程 1. 先运行现有测试记录通过数量作为基线 2. 阅读目标模块的完整实现梳理对外暴露的接口 3. 制定重构计划先向用户展示计划再动手 4. 分小步执行每步必须保持代码可编译、测试可运行 5. 全部完成后运行完整测试对比基线 硬性约束 - 禁止改变任何外部接口的签名和返回值语义 - 禁止顺手清理与本次重构无关的代码 - 禁止升级或修改依赖版本 - 最后输出改动文件清单、风险点和测试结果用这个模板前我会手动提醒“先跑测试再看代码”但经常漏。现在模板强制了流程而且把“展示计划再动手”作为中间步骤给了人一次叫停的机会。在我看来这是整个模板里最值得复制的设计。3.4 提交信息模板让 git log 变得可读生成 commit message 这种事让 Claude 做要远比手写省力但默认生成的风格往往过于华丽。模板要做的就是标准化格式。--- description: 根据当前工作区的改动生成符合约定格式的 commit message --- 请基于用户提供的改动概述生成 commit message。 格式要求 - 第一行用动词开头不超过 50 个字符 - 第二行空行 - 第三行起用要点列出具体改动内容 - 如果涉及破坏性变更在末尾单独列出 禁止 - 不要使用 emoji - 不要添加“这是一个...”“本次提交...”这类废话 - 不要编造未在改动中出现的内容这里一个实际操作经验是Claude 生成 commit message 时最好由我先把改动内容过一遍再传给模板。完全让它自己去看 git diff很容易把一些临时调试代码也写进提交信息。3.5 架构评审模板给重大决策留痕当讨论涉及模块划分、依赖方向或数据模型设计时我会用架构评审模板。它不追求输出完整方案而是强制 Claude 把决策依据和取舍列出来这样人可以在关键岔路口做判断。--- description: 评审一个架构方案输出决策建议和风险清单 --- 架构方案背景$ARGUMENTS 输出内容 1. 方案的核心设计思想 2. 与常见替代方案的对比至少列出 2 个替代方案 3. 当前方案的主要优点 4. 当前方案的主要风险和适用边界 5. 如果采用此方案建议的落地步骤 要求 - 每个结论必须给出理由 - 风险部分必须具体到模块或接口禁止写“可能存在性能问题”这类空泛描述 - 如果替代方案在某些维度明显更优明确指出来这套模板让架构评审不只是“一个人对着 Claude 脑暴”而是能在团队里留下来一份可读的决策记录。我之后会把输出整理进项目文档方便回头看当初为什么这么设计。4. 实操把模板装进自己的 Claude Code4.1 目录规划项目级与用户级模板装在哪里决定了它能作用到哪些场景。Claude Code 支持两个层级的模板用户级和项目级。用户级目录通常在~/.claude/下~/.claude/ ├── CLAUDE.md # 对所有项目生效的全局约定 └── commands/ # 用户级斜杠命令项目级目录则放在当前仓库里你的项目/ ├── CLAUDE.md └── .claude/ └── commands/我的经验是用户级只放两类东西——类如“回复尽量用中文”“代码要写注释”这种与项目无关的个人偏好而项目相关的任何内容都放进项目级并且跟着 Git 走。这样做的好处是团队其他人 clone 仓库后一模一样的 AI 行为约定也随之落地。有一个容易踩的坑是目录层级。如果你在子目录里新建了另一个CLAUDE.md它的优先级会更高适合处理“这个子目录有自己的特殊规则”的情况。但普通项目里最好不要到处放 CLAUDE.md不然规则冲突会让人抓狂。4.2 创建和调试一个斜杠命令以创建一个/test-case命令为例完整流程如下第一步建立命令目录。如果项目里还没有.claude/commands/手动创建。mkdir -p .claude/commands第二步创建test-case.md文件写入模板内容--- description: 为指定函数或模块生成测试用例 --- 请为 $ARGUMENTS 生成一组测试用例。 要求 1. 先梳理函数的输入、输出、边界条件 2. 覆盖正常路径、异常路径、边界值 3 类场景 3. 遵循项目现有的测试框架和命名风格 4. 不要修改被测代码 5. 输出时先说明每个用例的意图再放具体代码第三步在 Claude Code 会话里直接输入/test-case src/utils/format_date.py观察输出。如果命令不生效我通常会按下面顺序排查检查文件名后缀是不是.md检查是不是放在.claude/commands/而非其他目录检查 front matter 里的描述是否被错误地放在正文中间输入/看看命令列表里有没有出现如果不出现重启会话再试。调试中有个很关键的点斜杠命令里$ARGUMENTS的大小写一定要准确写成$arguments不会被替换。我自己至少在这里翻过一次车。4.3 团队协作模板要进 Git变更要走评审把模板带到团队里最大的改变是“AI 的使用行为”突然变得可控了。这时候模板本身就成了需要被管理的资产。我建议团队把.claude/目录纳入 Git 版本控制同时把 CLAUDE.md 作为项目文档的一部分来维护。任何对模板的修改都应该走和普通代码变更一样的流程提 PR、有人 review、合入后更新说明。团队协作里另一个值得注意的点是不要在用户级个人环境的 CLAUDE.md 里写团队规范。如果张三习惯写“所有代码用 TypeScript”李四的全局配置里写了“优先用 JavaScript”两人在同一个项目里的 AI 行为就会莫名其妙地不一致。正确的做法是团队规范只出现在项目级文件里用户级只保留个人偏好。当一个团队刚开始使用这套模板体系时建议从一个高频痛点场景切入比如统一/review命令而不是一上来就堆全套模板。这样大家的学习成本低也更容易验证模板是否真的有用。5. 常见问题与排查实录5.1 Claude 完全无视模板里的规则这个问题我遇到过很多次而且往往不是模板没生效而是模板里的规则“失效”了。表现是CLAUDE.md 里明明写了“禁止修改与本次任务无关的文件”结果它还是顺手改了配置文件的格式。我的排查顺序是先确认指令本身是否足够明确。像“请遵守项目规范”就是典型的无效指令“禁止修改未在任务说明中提到的文件”这种带明确边界的话才有效。再确认指令位置。越靠前的指令优先级越高关键规则尽量放在 CLAUDE.md 很靠前的位置。最后确认是否有冲突。如果用户级 CLAUDE.md 里有相反的习惯要求项目级规则会被干扰。处理方式是统一以项目级为准并在用户级减少强约束。而且有几个词对模型特别有效“必须”“禁止”“唯一例外是”。这些强约束词虽然听起来像是在训小孩但对 AI 的输出稳定性帮助非常大。5.2 模板导致上下文被撑爆CLAUDE.md 文件过长是最常见的上下文杀手。Claude Code 每次请求都会把 CLAUDE.md 内容放进上下文如果里面有几百行不痛不痒的内容会把有限的上下文窗口占用掉导致真正干活时可用空间变小。我的控制策略是CLAUDE.md 只放“每句话都值得 Claude 知道”的信息。凡是某个场景才用的内容一律拆到斜杠命令或者规则片段里。比如“数据库迁移时必须先跑一个 dry-run”这种规则我会放进database.md规则片段而不是写进常驻的 CLAUDE.md。现在我的项目级 CLAUDE.md 基本控制在 100 行以内。超过这个长度我会自动怀疑是不是有内容应该被拆出去。5.3 斜杠命令不生效或行为不对斜杠命令不生效九成是路径或文件名的问题。命令目录必须是.claude/commands/文件名不能带空格不能写中文名至少我建议不要。命令列表里没显示重启会话通常能解决。另一个隐蔽问题是命令文件更新了但当前会话里触发的还是旧版本。Claude Code 在会话中会有上下文累积改了命令文件后最稳妥的做法是开一个新会话再测别在长会话里反复验证。我还会在命令模板里故意放一个“验证点”比如让命令输出里必须包含“本次审查基于模板”字样这样我能一眼看出它到底有没有加载到新模板。如果输出的格式还是老样子说明加载有问题。5.4 团队里的模板版本冲突多人协作时有人改了项目级命令文件但没提交 Git有人本地有旧的用户级命令把项目级命令覆盖了。这类冲突排查起来很烦。我的处理方案是给命令模板的 front matter 加一个version: 1.x字段同时在输出里要求它体现版本。合入 PR 前跑一次冒烟测试确认命令输出包含目标版本号。这套机制让我们团队在一段时间内稳定识别出“谁的本地配置是旧的”。5.5 常见问题速查表症状可能原因优先处理方式CLAUDE.md 内容没生效文件不在工作目录根路径或名称大小写不对检查路径与文件名重启会话模板规则被无视指令太模糊或与用户级配置冲突改用强制词检查用户级 CLAUDE.md斜杠命令不出现目录或文件名错误检查.claude/commands/*.md重启会话$ARGUMENTS没被替换变量名大小写写错确认写成$ARGUMENTS上下文太小CLAUDE.md 过长将大段规则拆到按需加载的文件中团队行为不一致用户级配置覆盖项目级把团队规范统一下沉到项目级文件这张表也是我团队的docs/ai-rules/git-workflow.md里的一部分每次新人接入时直接发过去能省掉大量重复答疑。6. 几个让我省时间的进阶玩法模板体系稳定之后我又顺手做了几个小工具型模板灵活度更高。一个是“链式任务模板”先用一个命令让 Claude 输出实现方案得到确认后再发另一个命令让它按方案立刻编码。两个命令之间的衔接点就是人的决策点这样既保留了 AI 的效率又不至于让它一路狂奔到错误的终点。第二个是“文档迭代模板”。每次接口变更后我会用/doc-update模板让它同步更新接口文档和 CHANGELOG。模板里写明了“对比上一次文档找出差异并更新”比手动找 diff 靠谱得多。这些进阶模板没有进入最初的核心模板集因为它们的普适性没有前几套那么高。但它们的出现恰恰说明了这套模板体系的扩展性——只要你能把重复的流程抽象成 Markdown 文件就能让 Claude Code 按你的节奏工作。我个人在实际操作中的体会是模板最值得投入时间的地方不是写出漂亮的提示词而是持续观察“Claude 在哪里出现了意想不到的行为”然后把对应的约束补进去。每个模板从第一版到稳定版中间基本都要改三四次这是很正常的过程。最后再分享一个小技巧每次 Claude Code 大版本升级之后我会用一个空仓库跑一遍全部斜杠命令的冒烟任务确保模板里依赖的行为没被新版本破坏。这个习惯帮我提前避掉过不少升级带来的“隐性不兼容”。