我维护一个叫claude-code-templates的模板库已经有一段时间了。最开始只是自己写的几个零散 prompt 文件后来发现团队里好几个朋友也在用 Claude Code 干活一个个都在重复造轮子干脆把这些年踩过的坑、沉淀下来的协作模式整理成了一套可复用的模板体系。Claude Code 本质上是跑在命令行里的编程助手它可以直接读你仓库里的代码、改文件、执行测试命令甚至能拿着终端输出继续帮你排查问题。听起来很强大但实际用起来你会发现一个问题每次新开一个会话它对你的项目背景、代码规范、输出要求一无所知你又要从“我们是做什么的、代码在哪个目录、命名习惯是什么”开始解释一遍。这就像每次来一个新实习生你都得把部门规章制度从头讲一遍讲完还得盯着他干活。模板要解决的就是把这套“入职培训”固化成标准文件让 AI 开箱即用。这套模板库适合谁正在用或者准备用 Claude Code 做日常开发的工程师尤其是那些觉得“AI 写出来的代码总差口气还得自己反复改提示词”的人。它会告诉你差的不是模型是你没有把协作规范讲清楚。这篇文章我会把这套模板体系的目录设计、核心模板的写法、以及实际接入工作流的方法全部拆开讲内容偏实操你可以直接抄走。1. 为什么需要 Claude Code 模板从“每次调教”到“开箱即用”1.1 Claude Code 的协作逻辑与模板的切入点要理解模板的价值得先理解 Claude Code 的工作方式。它跟你平时在网页端问 ChatGPT 不太一样——它在你的终端里运行有文件读写权限能执行终端命令这意味着它更像一个“坐在你旁边的结对编程伙伴”而不是一个只负责回答问题的对话框。既然是结对编程伙伴就涉及协作习惯的问题。真人伙伴跟你配合久了知道你写 Python 喜欢用 type hint知道你的测试用 pytest 而不是 unittest知道你提交代码要走 conventional commits。这些“默契”不是天生的是长期磨合出来的。AI 也一样你以为它聪明到能自己从代码里推测出你的偏好其实它每次会话都是“失忆”的只能依赖你在对话里给的有限信息加猜测。模板就是把这些“默契”外化成文件。我在模板库里定义了一套分层结构全局配置管角色和通用规范项目配置管当前仓库的上下文任务模板管具体活儿的执行流程。这样每次调用 Claude Code它读一遍这些文件就等于瞬间完成了“入职培训”直接进入干活状态。1.2 模板化要解决的三个核心痛点第一个痛点是重复解释。很多团队用 Claude Code 干的第一件正事是“帮我看下这几个文件的代码问题”结果 AI 上来先问“请问您的项目是什么语言主要功能是什么代码在哪个目录”你明明已经给了它整个仓库的访问权它却像个没做过功课的新人。有了项目级 CLAUDE.md 模板这些问题都不需要你回答AI 自己读完模板就能把项目背景、技术栈、关键目录全部搞清楚。第二个痛点是输出不可控。同一个项目你让 AI 写一段业务代码它可能这次给你一坨大函数下次给你拆成五个小函数。不是它飘了是你没跟它说清楚你的代码风格偏好。我在模板里会写“业务代码优先拆小函数单个函数不超过 40 行”“所有公共函数必须带 docstring”“变量命名使用 snake_case”AI 的输出立刻稳定下来了。第三个痛点是经验无法沉淀。今天你费了半天功夫调出了一套完美的代码审查提示词明天换台电脑就丢了。模板库天然就是沉淀经验的载体——把一次性的优秀口头提示词整理成 markdown 文件存进 git 仓库团队所有人都能复用。1.3 模板设计的顶层原则在设计模板库结构之前我给自己定了几条规矩这里也分享给你。第一分层管理。全局模板管“你是个什么样的 AI 助手”项目模板管“你面对的是一个什么样的项目”任务模板管“这次活儿具体怎么干”。三层职责不重叠全局模板不能写项目相关的东西任务模板不写全局职责。第二原子化。一个模板文件只干一件事。你不要搞一个超级大模板里面既有代码规范又有部署流程。我见过有人把上百行提示词塞进一个文件结果 AI 一读上下文就是几千 token还没干活呢预算烧了一半。拆开的好处是你可以按需组合比如“代码审查”任务只需要加载审查模板 项目上下文不需要加载“新功能开发”模板。第三模板必须参数化。模板里留好变量占位符比如{{language}}、{{test_framework}}用脚本或者 Claude Code 自己的变量替换能力填值。这样一份模板可以适用于 Java 项目、Python 项目、Go 项目不用每个项目重新写一份。2. 模板库的目录结构与核心模板拆解2.1 目录结构设计我的claude-code-templates仓库目录长这样claude-code-templates/ ├── CLAUDE.md # 全局入口AI 启动时自动读取 ├── global/ │ ├── system-prompt.md # 角色定义与核心工作原则 │ ├── code-style.md # 代码风格通用约定 │ ├── output-format.md # 输出格式与汇报规范 │ └── workflows.md # 常用工作流TDD、重构、调试 ├── tasks/ │ ├── review.md # 代码审查任务模板 │ ├── refactor.md # 重构任务模板 │ ├── feature.md # 新功能开发模板 │ ├── bugfix.md # Bug 修复模板 │ └── docs.md # 文档生成模板 └── projects/ ├── python-service/ │ └── CLAUDE.md # 具体项目上下文 └── web-frontend/ └── CLAUDE.md这个结构你可以直接抄。全局模板放在global/下所有项目共享具体某类活在tasks/下按任务类型拆分不同项目的差异化上下文放在projects/项目名/CLAUDE.md里。2.2 CLAUDE.md 全局配置模板CLAUDE.md是 Claude Code 的入口文件它之所以叫这个名字是因为 Claude Code 启动时会在工作目录里自动寻找这个文件并读取。所以你只要把模板库 clone 到机器上然后在项目里软链或复制一份CLAUDE.mdAI 启动时就会自动加载配置。我写的全局CLAUDE.md简化版长这样# 角色定位 你是一名资深的全栈软件开发工程师擅长代码审查、架构设计、重构、调试和文档编写。 你习惯用工程化思维解决问题优先考虑可维护性和可测试性。 # 工作基本原则 1. 动手改代码之前先输出简要的方案和影响面分析等确认后再执行。 2. 保持代码改动最小化不要顺手重构无关代码。 3. 涉及删除操作文件删除、数据删除必须二次确认。 4. 不确定的需求先列出假设不要猜。 # 默认输出规范 - 技术方案描述使用简洁的要点式说明不要写大段散文。 - 给出代码示例时必须标注语言类型。 - 提出修改建议时同时说明理由和潜在风险。 # 引入任务模板的方式 如果用户要求执行代码审查、重构、修复 Bug 等特定任务先读取 tasks/ 下对应模板文件再开始工作。这个模板的作用是把“角色”和“底线”立住。注意我写的是“动手改代码之前先输出方案”——这一条特别关键它防止 AI 拿到权限后自作主张把你不希望碰的文件也改了。2.3 任务模板以“代码审查”为例任务模板是复用价值最高的部分。我把tasks/review.md写给你看它的结构值得逐段拆解。# 任务代码审查 ## 审查范围 - 待审查文件{{files}} - 审查目标{{goal}} ## 审查维度按优先级排列 1. 正确性逻辑错误、边界条件遗漏、并发问题 2. 安全性注入风险、敏感信息硬编码、越权访问 3. 性能不必要的重复计算、N1 查询、内存泄漏隐患 4. 可维护性命名是否表意、函数是否过长、是否存在重复代码 5. 可测试性是否有单测覆盖、依赖是否容易 mock ## 输出格式 按以下 Markdown 结构输出审查报告 ### 问题清单 | 严重度 | 文件位置 | 问题描述 | 修改建议 | |--------|----------|----------|----------| ### 总体评价 对本次审查范围给出 2-3 句总体判断说明是否需要优先处理某些问题。 ## 注意事项 - 只审查列出范围内的文件不要扩大到整个仓库。 - 每个问题必须给出具体的行号和可操作的修改建议禁止空泛评价。 - 如果发现审查目标之外的严重问题单独列出不要混入主报告。这个模板的关键在于约束了审查范围和输出格式。不写模板的时候AI 审查代码经常出现两种极端要么只给一句“看起来不错”要么把整个文件重写一遍。模板里的“审查维度”让它的检查有章法“输出格式”让它的结果可以直接贴在 PR 评论里你不需要再二次整理。3. 实战从零搭建一套可复用的模板体系3.1 初始化与目录搭建先在你常用的目录下建一个模板仓库mkdir claude-code-templates cd claude-code-templates git init mkdir -p global tasks projects然后创建上节提到的CLAUDE.md和各个目录下的文件。如果你是团队使用建好之后直接推到私有 Git 仓库成员各自 clone 一份即可。接下来让你自己的项目能使用这套模板。有两种方案我推荐第二种。方案一把模板库 clone 到本地后在项目目录里创建软链ln -s /path/to/claude-code-templates/CLAUDE.md /path/to/your-project/CLAUDE.md方案二直接复制。复制的好处是你可以按项目微调但后续模板更新不会自动同步。cp /path/to/claude-code-templates/CLAUDE.md /path/to/your-project/CLAUDE.md如果项目里已经有自己的CLAUDE.md你需要手动合并内容不要直接覆盖。Claude Code 只读取当前目录下的这一个CLAUDE.md文件所以合并时要保留项目特有的信息把通用规范和角色定义替换成模板里的版本。3.2 编写系统提示词模板系统提示词是模板体系里最核心的部分。它定义了 AI 面对任务时的底层行为方式。网上很多教程会让你写“你现在是一个专家”之类的套话说实话效果一般因为模型本身已经知道自己是 AI你要做的是给它设定协作规则而不是给它戴高帽。我的global/system-prompt.md内容如下你可以参考# 协作模式 - 每次接手任务先复述你对任务的理解再开始行动。 - 遇到任务描述含糊的地方列出你的假设并给一个默认处理方案。 - 修改代码前若涉及多个文件先画一个简单的改动清单。 # 问题解决思路 - 先定位问题根因再讨论解决方案。禁止绕开根因打补丁。 - 排查问题时输出你的推理链包括你尝试过的方案和排除掉的原因。 # 对话风格 - 回复使用中文技术名词保留英文。 - 要点式输出优先用表格、列表呈现结构化信息。 - 不要输出与任务无关的客套话不要频繁重复确认。这里面“先复述任务理解”是最实用的。AI 经常理解偏需求你让它改 A 它理解成改 B复述这一条能让偏差点提前暴露省去返工成本。3.3 变量替换与参数化实现任务模板里我用了{{files}}、{{goal}}这样的占位符。实际使用的时候最简单的方案是复制模板文件然后手动把变量替换成真实值。不过次数多了你会发现还是麻烦尤其是变量多的时候。我建议写一个几十行的 Python 小脚本自动完成变量替换#!/usr/bin/env python3 从模板渲染任务文件。用法python render.py templates/review.md --var filessrc/main.py --var goal检查登录模块 import argparse from pathlib import Path def render(template_path: str, variables: dict) - str: content Path(template_path).read_text(encodingutf-8) for key, value in variables.items(): placeholder {{ key }} if placeholder not in content: print(f警告模板中不存在占位符 {placeholder}) content content.replace(placeholder, value) return content def main(): parser argparse.ArgumentParser() parser.add_argument(template, help模板文件路径) parser.add_argument(--var, actionappend, default[], helpkeyvalue 格式) args parser.parse_args() variables {} for item in args.var: key, _, value item.partition() variables[key.strip()] value.strip() rendered render(args.template, variables) print(rendered) if __name__ __main__: main()用法很简单python render.py tasks/review.md --var filessrc/auth.py --var goal检查登录鉴权逻辑脚本会把渲染好的内容输出到终端你直接复制给 Claude Code或者把它重定向追加到某个prompt.md文件然后用cat prompt.md | claude-code喂给 AI。3.4 把模板接入日常工作流模板不接入工作流就是一堆死文件。我的日常用法有三个场景。场景一每次 Claude Code 启动前先让它读模板。在项目根目录启动 Claude Code 的时候它会自动读CLAUDE.md。如果你的CLAUDE.md里有“遇到代码审查任务先读取 tasks/review.md”这样的指令那你只需要在对话里说一句“做一次代码审查范围是 src/auth.py”AI 就会自己去读任务模板按模板执行。场景二手动拼装组合。如果项目里的CLAUDE.md没配置“自动读取任务模板”你可以在对话里手动指定请先阅读 /path/to/claude-code-templates/tasks/review.md 中的任务要求然后按该要求审查 src/auth.py一次指定本次会话内 AI 都会记住这个模板的内容。场景三写一个 shell 别名一条命令拉起带模板的会话。在.zshrc或.bashrc里加alias crcd /path/to/your/project claude-code (cat /path/to/claude-code-templates/tasks/review.md)启动后直接把模板内容作为首轮对话发给 AI省去手工复制。4. 常见问题与排查技巧实录4.1 模板内容被截断我在做代码审查模板的时候一开始写得特别长恨不得把所有审查规则全塞进去。结果发现 Claude Code 上下文有限读到一半就把模板截断了后半段的质量规则完全没生效。这里有个典型的误区你以为模板写得越细 AI 效果越好实际是“过犹不及”。后来我控制每个模板文件在 100 到 200 行以内只保留高优先级的内容。同时把审查维度按优先级排列即使上下文被截断保留下来的也总是最重要的规则。另外注意CLAUDE.md 里不要放重复指令。全局模板、项目模板、任务模板三层加起来总 token 数越少越好越精简 AI 越能抓住重点。4.2 模板之间内容冲突最常见的情况是全局模板里写了“使用 camelCase 命名”项目模板里写了“本仓库使用 snake_case”AI 读到冲突内容时会懵掉表现为代码风格随机切换。排查思路很简单把项目目录下的CLAUDE.md、global/目录文件、以及任务模板里可能涉及同一主题的段落全部列出来逐一检查关键词。我维护了一个简单的冲突检查脚本扫描所有 md 文件里的“代码风格”“命名规范”“缩进”等关键词列出重复或冲突的内容位置。写完模板后跑一遍能省不少后面调试的精力。4.3 换行和 Markdown 格式错乱Claude Code 读取模板文件时对空行和缩进的敏感度比你想的高。我踩过一个坑模板里用四个空行分隔段落结果 AI 把这些空行也当作内容的一部分输出报告时格式变得非常松散。解决办法模板文件统一用标准 Markdown 格式段落之间一个空行列表缩进保证一致。不要用制表符不要用四个空格缩进列表项统一用两空格或直接顶格加-。这些细节看着不起眼直接决定 AI 生成报告时是否能保持格式稳定。4.4 模板不生效明明把CLAUDE.md放到了项目根目录启动 Claude Code 之后它却不按模板行事。排查步骤按顺序来确认文件名和位置。必须叫CLAUDE.md必须放在启动命令所在目录。我之前犯过一个错把它放到了docs/子目录下AI 根本读不到。确认模板里没有语法错误。有的模板可能残留未替换的{{}}占位符AI 读到未定义变量会跳过相关指令。确认模板编码是 UTF-8不要用带 BOM 的 UTF-8 文件否则第一行可能乱码AI 读不懂。如果以上都排除了直接在对话里问 AI“请复述你刚读到的 CLAUDE.md 内容。”它能完整复述说明加载成功了复述不出来说明文件路径或权限有问题。我把这些高频问题整理成了速查表问题可能原因处理方案模板内容被截断单文件过长或总上下文过大精简模板按优先级排列控制行数输出风格不稳定多层模板冲突扫描关键词合并冲突指令格式错乱换行和缩进不规范统一 Markdown 格式避免制表符模板不生效文件名、路径、编码不对检查位置、名称、BOM让 AI 复述验证AI 擅自扩大改动范围缺少“最小改动”约束在全局模板里强加改动边界规则5. 模板体系的进阶扩展5.1 跨项目共享模板把模板库放到 Git 仓库多个项目共享听起来简单实际操作中有个细节不同项目的技术栈差异太大全局模板里写死了编码规范Java 项目和 Python 项目用同一套就不合适。我的做法是在项目级CLAUDE.md里做“覆盖”。全局模板写的是通用底线项目模板用更具体的规则覆盖全局。比如全局写“变量命名使用 snake_case”项目模板里写“本仓库使用 camelCase覆盖全局 snake_case 规范”。要保证“覆盖”生效项目模板的表述必须明确指出是对哪条规则的覆盖算是对 AI 的明确暗示。5.2 为不同编程语言定制风格模板模板库到后期一定会往这个方向演化。同一个“代码审查”任务审查 Python 项目和审查 Go 项目运行的重点完全不同。Python 要看类型标注、异常处理Go 要看错误处理是否规范、是否有 goroutine 泄漏。我把tasks/review.md做成了基础版然后为常用语言维护了几个变体tasks/ ├── review.md # 通用 ├── review-python.md # Python 专用 ├── review-go.md # Go 专用 └── review-java.md # Java 专用语言专用模板里不再写“审查维度”这种通用部分而是直接写该语言最容易出问题的点。比如review-go.md里我会写“检查每个错误是否都被正确处理禁止使用 _ 忽略错误”。这个文件是从真实项目的代码评审记录里提炼的比通用模板针对性高很多。5.3 与自动化流程结合模板库积累多了之后每次手动执行变得繁琐。我可以把渲染脚本和模板路径配置进Makefile一条命令生成指定任务的完整提示词review: python render.py tasks/review.md --var files$(FILES) /tmp/prompt.md cat /tmp/prompt.md refactor: python render.py tasks/refactor.md --var module$(MODULE) /tmp/prompt.md cat /tmp/prompt.md你也可以更进一步把生成好的提示词通过管道直接传给 Claude Code 的非交互模式实现半自动化的代码审查流水线。这个方向我还在完善暂时不在这里展开太多但值得关注。我个人的体会是模板库不是一次性建设完就万事大吉的东西它需要跟着团队的实际使用情况持续迭代。我是每个月月底翻一次“近期哪些 prompt 我重复写了”“哪些模板生成的代码质量明显更好”把经验回流进模板里。经过几轮迭代之后你会明显感觉到AI 写代码的综合表现不再是掷骰子而是稳定在一个可以预期的水准上。最后分享一个我一直在用的小技巧给模板文件里所有“禁止类”条款加上明确后果例如“如果修改了审查范围外的文件本次工作将被判定为不合格”。AI 对明确后果的感知比对道理的感知更敏锐这个细节比你在提示词里加多少感叹号都管用。 Claude Code模板库实战：从重复调教到开箱即用
我维护一个叫claude-code-templates的模板库已经有一段时间了。最开始只是自己写的几个零散 prompt 文件后来发现团队里好几个朋友也在用 Claude Code 干活一个个都在重复造轮子干脆把这些年踩过的坑、沉淀下来的协作模式整理成了一套可复用的模板体系。Claude Code 本质上是跑在命令行里的编程助手它可以直接读你仓库里的代码、改文件、执行测试命令甚至能拿着终端输出继续帮你排查问题。听起来很强大但实际用起来你会发现一个问题每次新开一个会话它对你的项目背景、代码规范、输出要求一无所知你又要从“我们是做什么的、代码在哪个目录、命名习惯是什么”开始解释一遍。这就像每次来一个新实习生你都得把部门规章制度从头讲一遍讲完还得盯着他干活。模板要解决的就是把这套“入职培训”固化成标准文件让 AI 开箱即用。这套模板库适合谁正在用或者准备用 Claude Code 做日常开发的工程师尤其是那些觉得“AI 写出来的代码总差口气还得自己反复改提示词”的人。它会告诉你差的不是模型是你没有把协作规范讲清楚。这篇文章我会把这套模板体系的目录设计、核心模板的写法、以及实际接入工作流的方法全部拆开讲内容偏实操你可以直接抄走。1. 为什么需要 Claude Code 模板从“每次调教”到“开箱即用”1.1 Claude Code 的协作逻辑与模板的切入点要理解模板的价值得先理解 Claude Code 的工作方式。它跟你平时在网页端问 ChatGPT 不太一样——它在你的终端里运行有文件读写权限能执行终端命令这意味着它更像一个“坐在你旁边的结对编程伙伴”而不是一个只负责回答问题的对话框。既然是结对编程伙伴就涉及协作习惯的问题。真人伙伴跟你配合久了知道你写 Python 喜欢用 type hint知道你的测试用 pytest 而不是 unittest知道你提交代码要走 conventional commits。这些“默契”不是天生的是长期磨合出来的。AI 也一样你以为它聪明到能自己从代码里推测出你的偏好其实它每次会话都是“失忆”的只能依赖你在对话里给的有限信息加猜测。模板就是把这些“默契”外化成文件。我在模板库里定义了一套分层结构全局配置管角色和通用规范项目配置管当前仓库的上下文任务模板管具体活儿的执行流程。这样每次调用 Claude Code它读一遍这些文件就等于瞬间完成了“入职培训”直接进入干活状态。1.2 模板化要解决的三个核心痛点第一个痛点是重复解释。很多团队用 Claude Code 干的第一件正事是“帮我看下这几个文件的代码问题”结果 AI 上来先问“请问您的项目是什么语言主要功能是什么代码在哪个目录”你明明已经给了它整个仓库的访问权它却像个没做过功课的新人。有了项目级 CLAUDE.md 模板这些问题都不需要你回答AI 自己读完模板就能把项目背景、技术栈、关键目录全部搞清楚。第二个痛点是输出不可控。同一个项目你让 AI 写一段业务代码它可能这次给你一坨大函数下次给你拆成五个小函数。不是它飘了是你没跟它说清楚你的代码风格偏好。我在模板里会写“业务代码优先拆小函数单个函数不超过 40 行”“所有公共函数必须带 docstring”“变量命名使用 snake_case”AI 的输出立刻稳定下来了。第三个痛点是经验无法沉淀。今天你费了半天功夫调出了一套完美的代码审查提示词明天换台电脑就丢了。模板库天然就是沉淀经验的载体——把一次性的优秀口头提示词整理成 markdown 文件存进 git 仓库团队所有人都能复用。1.3 模板设计的顶层原则在设计模板库结构之前我给自己定了几条规矩这里也分享给你。第一分层管理。全局模板管“你是个什么样的 AI 助手”项目模板管“你面对的是一个什么样的项目”任务模板管“这次活儿具体怎么干”。三层职责不重叠全局模板不能写项目相关的东西任务模板不写全局职责。第二原子化。一个模板文件只干一件事。你不要搞一个超级大模板里面既有代码规范又有部署流程。我见过有人把上百行提示词塞进一个文件结果 AI 一读上下文就是几千 token还没干活呢预算烧了一半。拆开的好处是你可以按需组合比如“代码审查”任务只需要加载审查模板 项目上下文不需要加载“新功能开发”模板。第三模板必须参数化。模板里留好变量占位符比如{{language}}、{{test_framework}}用脚本或者 Claude Code 自己的变量替换能力填值。这样一份模板可以适用于 Java 项目、Python 项目、Go 项目不用每个项目重新写一份。2. 模板库的目录结构与核心模板拆解2.1 目录结构设计我的claude-code-templates仓库目录长这样claude-code-templates/ ├── CLAUDE.md # 全局入口AI 启动时自动读取 ├── global/ │ ├── system-prompt.md # 角色定义与核心工作原则 │ ├── code-style.md # 代码风格通用约定 │ ├── output-format.md # 输出格式与汇报规范 │ └── workflows.md # 常用工作流TDD、重构、调试 ├── tasks/ │ ├── review.md # 代码审查任务模板 │ ├── refactor.md # 重构任务模板 │ ├── feature.md # 新功能开发模板 │ ├── bugfix.md # Bug 修复模板 │ └── docs.md # 文档生成模板 └── projects/ ├── python-service/ │ └── CLAUDE.md # 具体项目上下文 └── web-frontend/ └── CLAUDE.md这个结构你可以直接抄。全局模板放在global/下所有项目共享具体某类活在tasks/下按任务类型拆分不同项目的差异化上下文放在projects/项目名/CLAUDE.md里。2.2 CLAUDE.md 全局配置模板CLAUDE.md是 Claude Code 的入口文件它之所以叫这个名字是因为 Claude Code 启动时会在工作目录里自动寻找这个文件并读取。所以你只要把模板库 clone 到机器上然后在项目里软链或复制一份CLAUDE.mdAI 启动时就会自动加载配置。我写的全局CLAUDE.md简化版长这样# 角色定位 你是一名资深的全栈软件开发工程师擅长代码审查、架构设计、重构、调试和文档编写。 你习惯用工程化思维解决问题优先考虑可维护性和可测试性。 # 工作基本原则 1. 动手改代码之前先输出简要的方案和影响面分析等确认后再执行。 2. 保持代码改动最小化不要顺手重构无关代码。 3. 涉及删除操作文件删除、数据删除必须二次确认。 4. 不确定的需求先列出假设不要猜。 # 默认输出规范 - 技术方案描述使用简洁的要点式说明不要写大段散文。 - 给出代码示例时必须标注语言类型。 - 提出修改建议时同时说明理由和潜在风险。 # 引入任务模板的方式 如果用户要求执行代码审查、重构、修复 Bug 等特定任务先读取 tasks/ 下对应模板文件再开始工作。这个模板的作用是把“角色”和“底线”立住。注意我写的是“动手改代码之前先输出方案”——这一条特别关键它防止 AI 拿到权限后自作主张把你不希望碰的文件也改了。2.3 任务模板以“代码审查”为例任务模板是复用价值最高的部分。我把tasks/review.md写给你看它的结构值得逐段拆解。# 任务代码审查 ## 审查范围 - 待审查文件{{files}} - 审查目标{{goal}} ## 审查维度按优先级排列 1. 正确性逻辑错误、边界条件遗漏、并发问题 2. 安全性注入风险、敏感信息硬编码、越权访问 3. 性能不必要的重复计算、N1 查询、内存泄漏隐患 4. 可维护性命名是否表意、函数是否过长、是否存在重复代码 5. 可测试性是否有单测覆盖、依赖是否容易 mock ## 输出格式 按以下 Markdown 结构输出审查报告 ### 问题清单 | 严重度 | 文件位置 | 问题描述 | 修改建议 | |--------|----------|----------|----------| ### 总体评价 对本次审查范围给出 2-3 句总体判断说明是否需要优先处理某些问题。 ## 注意事项 - 只审查列出范围内的文件不要扩大到整个仓库。 - 每个问题必须给出具体的行号和可操作的修改建议禁止空泛评价。 - 如果发现审查目标之外的严重问题单独列出不要混入主报告。这个模板的关键在于约束了审查范围和输出格式。不写模板的时候AI 审查代码经常出现两种极端要么只给一句“看起来不错”要么把整个文件重写一遍。模板里的“审查维度”让它的检查有章法“输出格式”让它的结果可以直接贴在 PR 评论里你不需要再二次整理。3. 实战从零搭建一套可复用的模板体系3.1 初始化与目录搭建先在你常用的目录下建一个模板仓库mkdir claude-code-templates cd claude-code-templates git init mkdir -p global tasks projects然后创建上节提到的CLAUDE.md和各个目录下的文件。如果你是团队使用建好之后直接推到私有 Git 仓库成员各自 clone 一份即可。接下来让你自己的项目能使用这套模板。有两种方案我推荐第二种。方案一把模板库 clone 到本地后在项目目录里创建软链ln -s /path/to/claude-code-templates/CLAUDE.md /path/to/your-project/CLAUDE.md方案二直接复制。复制的好处是你可以按项目微调但后续模板更新不会自动同步。cp /path/to/claude-code-templates/CLAUDE.md /path/to/your-project/CLAUDE.md如果项目里已经有自己的CLAUDE.md你需要手动合并内容不要直接覆盖。Claude Code 只读取当前目录下的这一个CLAUDE.md文件所以合并时要保留项目特有的信息把通用规范和角色定义替换成模板里的版本。3.2 编写系统提示词模板系统提示词是模板体系里最核心的部分。它定义了 AI 面对任务时的底层行为方式。网上很多教程会让你写“你现在是一个专家”之类的套话说实话效果一般因为模型本身已经知道自己是 AI你要做的是给它设定协作规则而不是给它戴高帽。我的global/system-prompt.md内容如下你可以参考# 协作模式 - 每次接手任务先复述你对任务的理解再开始行动。 - 遇到任务描述含糊的地方列出你的假设并给一个默认处理方案。 - 修改代码前若涉及多个文件先画一个简单的改动清单。 # 问题解决思路 - 先定位问题根因再讨论解决方案。禁止绕开根因打补丁。 - 排查问题时输出你的推理链包括你尝试过的方案和排除掉的原因。 # 对话风格 - 回复使用中文技术名词保留英文。 - 要点式输出优先用表格、列表呈现结构化信息。 - 不要输出与任务无关的客套话不要频繁重复确认。这里面“先复述任务理解”是最实用的。AI 经常理解偏需求你让它改 A 它理解成改 B复述这一条能让偏差点提前暴露省去返工成本。3.3 变量替换与参数化实现任务模板里我用了{{files}}、{{goal}}这样的占位符。实际使用的时候最简单的方案是复制模板文件然后手动把变量替换成真实值。不过次数多了你会发现还是麻烦尤其是变量多的时候。我建议写一个几十行的 Python 小脚本自动完成变量替换#!/usr/bin/env python3 从模板渲染任务文件。用法python render.py templates/review.md --var filessrc/main.py --var goal检查登录模块 import argparse from pathlib import Path def render(template_path: str, variables: dict) - str: content Path(template_path).read_text(encodingutf-8) for key, value in variables.items(): placeholder {{ key }} if placeholder not in content: print(f警告模板中不存在占位符 {placeholder}) content content.replace(placeholder, value) return content def main(): parser argparse.ArgumentParser() parser.add_argument(template, help模板文件路径) parser.add_argument(--var, actionappend, default[], helpkeyvalue 格式) args parser.parse_args() variables {} for item in args.var: key, _, value item.partition() variables[key.strip()] value.strip() rendered render(args.template, variables) print(rendered) if __name__ __main__: main()用法很简单python render.py tasks/review.md --var filessrc/auth.py --var goal检查登录鉴权逻辑脚本会把渲染好的内容输出到终端你直接复制给 Claude Code或者把它重定向追加到某个prompt.md文件然后用cat prompt.md | claude-code喂给 AI。3.4 把模板接入日常工作流模板不接入工作流就是一堆死文件。我的日常用法有三个场景。场景一每次 Claude Code 启动前先让它读模板。在项目根目录启动 Claude Code 的时候它会自动读CLAUDE.md。如果你的CLAUDE.md里有“遇到代码审查任务先读取 tasks/review.md”这样的指令那你只需要在对话里说一句“做一次代码审查范围是 src/auth.py”AI 就会自己去读任务模板按模板执行。场景二手动拼装组合。如果项目里的CLAUDE.md没配置“自动读取任务模板”你可以在对话里手动指定请先阅读 /path/to/claude-code-templates/tasks/review.md 中的任务要求然后按该要求审查 src/auth.py一次指定本次会话内 AI 都会记住这个模板的内容。场景三写一个 shell 别名一条命令拉起带模板的会话。在.zshrc或.bashrc里加alias crcd /path/to/your/project claude-code (cat /path/to/claude-code-templates/tasks/review.md)启动后直接把模板内容作为首轮对话发给 AI省去手工复制。4. 常见问题与排查技巧实录4.1 模板内容被截断我在做代码审查模板的时候一开始写得特别长恨不得把所有审查规则全塞进去。结果发现 Claude Code 上下文有限读到一半就把模板截断了后半段的质量规则完全没生效。这里有个典型的误区你以为模板写得越细 AI 效果越好实际是“过犹不及”。后来我控制每个模板文件在 100 到 200 行以内只保留高优先级的内容。同时把审查维度按优先级排列即使上下文被截断保留下来的也总是最重要的规则。另外注意CLAUDE.md 里不要放重复指令。全局模板、项目模板、任务模板三层加起来总 token 数越少越好越精简 AI 越能抓住重点。4.2 模板之间内容冲突最常见的情况是全局模板里写了“使用 camelCase 命名”项目模板里写了“本仓库使用 snake_case”AI 读到冲突内容时会懵掉表现为代码风格随机切换。排查思路很简单把项目目录下的CLAUDE.md、global/目录文件、以及任务模板里可能涉及同一主题的段落全部列出来逐一检查关键词。我维护了一个简单的冲突检查脚本扫描所有 md 文件里的“代码风格”“命名规范”“缩进”等关键词列出重复或冲突的内容位置。写完模板后跑一遍能省不少后面调试的精力。4.3 换行和 Markdown 格式错乱Claude Code 读取模板文件时对空行和缩进的敏感度比你想的高。我踩过一个坑模板里用四个空行分隔段落结果 AI 把这些空行也当作内容的一部分输出报告时格式变得非常松散。解决办法模板文件统一用标准 Markdown 格式段落之间一个空行列表缩进保证一致。不要用制表符不要用四个空格缩进列表项统一用两空格或直接顶格加-。这些细节看着不起眼直接决定 AI 生成报告时是否能保持格式稳定。4.4 模板不生效明明把CLAUDE.md放到了项目根目录启动 Claude Code 之后它却不按模板行事。排查步骤按顺序来确认文件名和位置。必须叫CLAUDE.md必须放在启动命令所在目录。我之前犯过一个错把它放到了docs/子目录下AI 根本读不到。确认模板里没有语法错误。有的模板可能残留未替换的{{}}占位符AI 读到未定义变量会跳过相关指令。确认模板编码是 UTF-8不要用带 BOM 的 UTF-8 文件否则第一行可能乱码AI 读不懂。如果以上都排除了直接在对话里问 AI“请复述你刚读到的 CLAUDE.md 内容。”它能完整复述说明加载成功了复述不出来说明文件路径或权限有问题。我把这些高频问题整理成了速查表问题可能原因处理方案模板内容被截断单文件过长或总上下文过大精简模板按优先级排列控制行数输出风格不稳定多层模板冲突扫描关键词合并冲突指令格式错乱换行和缩进不规范统一 Markdown 格式避免制表符模板不生效文件名、路径、编码不对检查位置、名称、BOM让 AI 复述验证AI 擅自扩大改动范围缺少“最小改动”约束在全局模板里强加改动边界规则5. 模板体系的进阶扩展5.1 跨项目共享模板把模板库放到 Git 仓库多个项目共享听起来简单实际操作中有个细节不同项目的技术栈差异太大全局模板里写死了编码规范Java 项目和 Python 项目用同一套就不合适。我的做法是在项目级CLAUDE.md里做“覆盖”。全局模板写的是通用底线项目模板用更具体的规则覆盖全局。比如全局写“变量命名使用 snake_case”项目模板里写“本仓库使用 camelCase覆盖全局 snake_case 规范”。要保证“覆盖”生效项目模板的表述必须明确指出是对哪条规则的覆盖算是对 AI 的明确暗示。5.2 为不同编程语言定制风格模板模板库到后期一定会往这个方向演化。同一个“代码审查”任务审查 Python 项目和审查 Go 项目运行的重点完全不同。Python 要看类型标注、异常处理Go 要看错误处理是否规范、是否有 goroutine 泄漏。我把tasks/review.md做成了基础版然后为常用语言维护了几个变体tasks/ ├── review.md # 通用 ├── review-python.md # Python 专用 ├── review-go.md # Go 专用 └── review-java.md # Java 专用语言专用模板里不再写“审查维度”这种通用部分而是直接写该语言最容易出问题的点。比如review-go.md里我会写“检查每个错误是否都被正确处理禁止使用 _ 忽略错误”。这个文件是从真实项目的代码评审记录里提炼的比通用模板针对性高很多。5.3 与自动化流程结合模板库积累多了之后每次手动执行变得繁琐。我可以把渲染脚本和模板路径配置进Makefile一条命令生成指定任务的完整提示词review: python render.py tasks/review.md --var files$(FILES) /tmp/prompt.md cat /tmp/prompt.md refactor: python render.py tasks/refactor.md --var module$(MODULE) /tmp/prompt.md cat /tmp/prompt.md你也可以更进一步把生成好的提示词通过管道直接传给 Claude Code 的非交互模式实现半自动化的代码审查流水线。这个方向我还在完善暂时不在这里展开太多但值得关注。我个人的体会是模板库不是一次性建设完就万事大吉的东西它需要跟着团队的实际使用情况持续迭代。我是每个月月底翻一次“近期哪些 prompt 我重复写了”“哪些模板生成的代码质量明显更好”把经验回流进模板里。经过几轮迭代之后你会明显感觉到AI 写代码的综合表现不再是掷骰子而是稳定在一个可以预期的水准上。最后分享一个我一直在用的小技巧给模板文件里所有“禁止类”条款加上明确后果例如“如果修改了审查范围外的文件本次工作将被判定为不合格”。AI 对明确后果的感知比对道理的感知更敏锐这个细节比你在提示词里加多少感叹号都管用。