企业官网建设流程全解析

维护 claude-code-templates 这个仓库一年多之后，我越来越确信一件事：对于 Claude Code 这类编程代理，模板不是可有可无的装饰，而是把它从“好用的对话助手”变成“能稳定交付结果的工作流引擎”的钥匙。这个仓库最初只是我本地一堆零散的 markdown 文件，后来逐步整理成一套可复用的模板集，覆盖代码审查、测试生成、重构迁移、文档同步等高频开发场景。如果你已经上手过 Claude Code，觉得它“会用但不够稳”，或者在团队里推 AI 编程时发现每个人用出来的效果天差地别，这篇文章会讲清楚模板到底应该怎么设计、怎么存放、怎么演进。

1. 空手用 Claude Code 的困境：我为什么从零攒这套模板

1.1 会话漂移：模型会忘记几轮之前说好的约定

我先说一个大部分人第一次用 Claude Code 都会遇到的场景。你让它帮你写一个新模块，一开始给了很详细的要求：“错误处理统一用 Result 类型，不要直接 throw”，前两轮它执行得很好。结果对话进行到二十分钟，你开始让它改别的文件，它突然就写了一个throw new Error出来。你质问它为什么违反约定，它很诚恳地道歉，然后改掉。但再过几轮，同样的问题又出现。

这不是模型“笨”，而是上下文窗口中只有一部分信息始终处于激活状态。对话越长，早期约束的权重越低。我们的口头约定只存在于这个会话的气泡里，气泡一长，边缘就模糊。这个问题靠“每次都重新说一遍要求”能缓解，但治标不治本，尤其当你在同一个项目里连续工作一整天时，重复描述要求本身就成了巨大的精力消耗。

1.2 团队协作时，效果方差大得吓人

第二个让我下决心整理模板的契机是我所在的团队。最开始我建议同事们都用 Claude Code 辅助写代码，结果反馈两极分化：有人觉得是“神器”，有人觉得“还不如自己写”。我把两边的对话记录对比了一下，发现差距根本不在于模型能力，而在于使用者给出的上下文质量。

会用的人会在对话开头就扔进项目的 CLAUDE.md、相关模块的接口文档，然后精确说明输入输出。不会用的人只会说“帮我改一下这个文件，让它更好”。更棘手的是，即使是同一个“帮我看代码”的指令，A 同事期望的是找 bug，B 同事期望的是评估架构，C 同事期望的是补注释。指令本身没有规范，输出自然各说各话。

我当时意识到，如果能把“好的提问方式”沉淀成一套可复现的模板，再把这套模板放进仓库里统一管理，那么团队里每个人调用 Claude Code 时的基础线就能被拉齐。这就是 claude-code-templates 的起点。所以这个仓库从第一天起就不只是给我自己用的，而是为了让团队的协作经验能被固化下来。

1.3 模板化的收益：不是限制工具，而是统一口径

有人会担心，把 Claude Code 的用法模板化会让它变得死板。我的实际感受恰恰相反。好的模板是在约束之下留出自由度：它限制了“角色定位”“输出格式”“验收标准”这些容易跑偏的部分，但给具体执行方案留了很大的想象空间。模型被约束得越清楚，发挥得越稳定。

就像写代码要有 lint 规则一样，AI 编程也需要一套“提示词层面的 lint 规则”。模板让模型的行为方差变小，让结果中的意外只出现在真正需要创造力的地方，而不是出现在“用户说的是 A、AI 理解成 B”这种低级偏差上。

2. 模板仓库的骨架：四层分离的设计思路

2.1 目录结构总览

我设计 claude-code-templates 的第一步是定目录结构。一开始我只是把所有 markdown 文件堆在一个文件夹里，很快发现不行：模板一多，“代码审查”这种模板有七八个变体，连我自己都会搞混，更别说团队协作。后来我参考了代码分层的思想，把模板分成四个层面。

claude-code-templates/ ├── memories/ │ ├── global.CLAUDE.md │ └── project.CLAUDE.md ├── prompts/ │ ├── code-review.md │ ├── test-generation.md │ ├── refactoring-migration.md │ └── documentation-sync.md ├── agents/ │ ├── review-specialist.md │ ├── test-designer.md │ └── migration-planner.md ├── hooks/ │ ├── pre-tool-use-check.sh │ └── post-stop-commit.sh ├── commands/ │ ├── /review.md │ ├── /test.md │ └── /migrate.md └── scripts/ └── render_template.py

四个层面的分工也很明确：memories 是长期记忆层，prompts 是任务技能层，agents 是角色分工层，hooks 是自动触发的保障层。

2.2 记忆层：CLAUDE.md 的写法要点

我见过很多人把 CLAUDE.md 写成了一篇散文，或者干脆写了一堆放之四海而皆准的废话，比如“请写出清晰、可维护的代码”“请保证高质量”。这种写法可以说是浪费了它最宝贵的价值。CLAUDE.md 的功能是给 Claude Code 注入项目专属的长期上下文，它的内容越具体、越可验证，效果越好。

以我仓库里的一份前端项目 CLAUDE.md 为例：

## 项目规范 - 类型定义统一放 src/types.ts，禁止在组件内内联复杂类型 - 所有异步请求必须走 src/api/client.ts，不直接使用 fetch - 新增状态管理时必须经过全局 Store 目录，不引入新依赖库 - 组件样式优先使用项目自带 design system 的类名，不写内联 style - 测试文件与被测文件同目录，命名 *.test.ts

每条规则都指到了一个具体文件，产生了一个明确的动作。模型不需要“理解精神”，直接照做就好。这就像给新人发了一份带路标的操作规程，而不是一句“你要努力工作”。

另一个容易被忽略的点：CLAUDE.md 不必追求大而全，只写那些“不做就一定会出事”的规则。规则太多，每条的注意力权重都会被稀释。如果二十条规则之间还有隐含冲突，模型就会经常陷入两难。

2.3 技能层：提示词的“角色—上下文—任务—验收”四要素

prompts 目录下放的是每个高频任务的核心提示词模板。我发现好的任务级模板都有一个共同的骨架，我把它们提炼成四个要素。

• 角色：明确 AI 以什么身份执行任务，比如“资深后端工程师”“只关注安全问题的审计员”。这一步在特定领域特别有用。
• 上下文：给出必要的背景，包括要处理的文件目标、相关约束、已知条件。这是模板的“输入口”。
• 任务：动作要具体可执行。避免“优化一下”这类模糊动词，尽量换成“找出变量名与职责不符的代码，并列出行号”。
• 验收：定义输出形式和判断标准，可以要求“只输出表格”“必须给出证据”“不得超出本次涉及范围”。

我每次写新模板的时候，都会按这四个要素检查一遍。缺了哪个环节，输出就容易跑偏。

3. 三套核心模板解剖：审查、测试与迁移

3.1 代码审查模板：从“看一眼”到“查档案”

代码审查是我用到最多的一类模板。最开始我用 Claude Code 做代码审查的时候，往往直接说“帮我 review 这段代码”，它的回答很流畅，但也很浅，经常给出一堆“可读性有待提高”“建议增强健壮性”这种无法落地的建议。后来我把审查过程分成两步：先收集档案，再逐项排查。

我仓库里的代码审查模板长这样：

你现在是一名一线开发团队中做 code review 的资深工程师。 审查我指定的文件之前，必须先读取该文件涉及的调用关系、依赖定义和测试文件。 审查输出必须按以下五部分组织，每部分用表格呈现： 1. 变更影响面：本次改动会影响哪些模块，有哪些副作用 2. 隐藏缺陷：重点排查并发、异常处理、资源释放、边界条件 3. 一致性：是否符合项目 CLAUDE.md 中定义的规范 4. 安全性：输入校验、权限校验，SQL/命令注入风险 5. 建议分级：必须修改 / 建议修改 / 可选优化 每条发现必须标注文件路径和行号，并给出可直接落地的修改示例。 禁止输出“代码质量有待提高”这类空话。

模板生效的关键在最后两行。要求“标注文件路径和行号”直接消灭了空泛的建议；“禁止空话”则从输出层面做了硬性过滤。我在实测中对比过，用模板的版本和不用的版本相比，真正能定位问题的发现数大约是后者的三倍。

3.2 测试生成模板：围绕边界条件自动铺设用例

写测试是 Claude Code 很擅长、但经常做不完整的一件事。如果你只说“给这个函数补测试”，它大概率会很快生成一组 happy path 用例，边界条件和异常分支基本漏光。问题在于模型默认情况下倾向于“生成看起来不错的代码”而不是“穷举可能的失败场景”。

所以我的测试生成模板里专门加了一个“失败清单”步骤：

你是测试设计专家。给指定函数设计测试用例时，必须先穷举以下清单： - 正常输入的最小值、最大值、典型值 - 空值、null、undefined、空数组 - 超过类型范围的输入 - 并发调用时的竞态条件 - I/O 失败、超时、磁盘满 - 依赖服务返回错误码 只有清单中的每一项都落到了具体测试用例里，你才可以输出代码。 测试代码必须用项目中已有测试框架，不允许新增依赖。

模板的作用其实就是强制模型走一遍“测试设计 checklist”。我用这个模板生成了一个工具函数的测试集，覆盖了大概八十多个用例。后来项目跑回归的时候，有两个用例真的拦住了线上才暴露的问题。那次之后，我把测试模板升级成了仓库里的旗舰模板。

3.3 重构迁移模板：给旧代码换心脏的安全网

重构迁移是最容易出乱子的场景。模型一旦开始动一个存在了四五年的旧模块，很有可能会把原本有意为之的怪写法当成错误“修正”掉。所以迁移类模板的核心玩法不是“敢动”，而是“先立规矩再动刀”。

我写的一版更是强调“先出迁移影响面分析，等用户确认后才能动手”。模板的关键段落如下：

在修改任何代码前，先产出一份迁移计划，包括： - 现状文件清单：每个文件的大小、依赖数量、外部调用方 - 目标架构映射：每个现状模块对应到新架构的哪个位置 - 风险分级：高风险的放在最前面，标注原因 - 回滚方案：如果迁移到一半失败，如何恢复到原状态 计划得到用户明确确认之前，禁止修改任何代码文件。 迁移过程中每改完一个文件，必须运行对应测试，并提供测试通过的证据。

为什么我要加“得到确认才能动手”这句？因为模型在面对“帮我重构”这种大任务时，经常会高估自己的判断，直接一口气改十几个文件。等用户反应过来，已经很难定位哪些改动是有意的、哪些是误伤。模板在这里起到的效果是设置了一个安全闸门，让每一步都有显式的检查和确认点。

4. 让模板真正生效：CLAUDE.md、子代理与 Hooks 的组合打法

4.1 自定义命令：把常用模板变成斜杠指令

有了模板文件之后，我遇到的第一个问题是：怎么方便地调用它。每次复制粘贴模板主体进对话，依然很原始。Claude Code 的自定义命令机制解决了这个问题。在.claude/commands/目录下放一个带斜杠命令名称的 markdown 文件，就可以在对话里用/命令名直接调起对应模板。

比如我把审查模板放进.claude/commands/review.md之后，每次只要输入：

/review src/utils/token.ts

模板内容就会自动加载，后面的文件路径会被当作参数传入。这大大降低了我写提示词的心理门槛，也让团队里其他人更容易上手——他们不需要知道自己该怎么“写好提示词”，只要知道用哪个命令就行。

命令文件里还可以用$ARGUMENTS接收参数，我把这个能力用在了“指定审查深度”“指定要跳过的文件”等场景。

4.2 子代理：把大而全的模板拆成专业顾问

模板越写越多之后，我又发现了一个新问题：把它塞给同一个模型，角色切换太频繁会不稳定。比如我在一个会话里先让它做代码审查，紧接着又让它生成测试，它容易把前面的“资深审查者”语气带到后面的测试设计里去。

在 Claude Code 里可以用子代理来解决这个角色冲突的问题。我给每个高频任务定义了一个专门的子代理，每个子代理有自己的名称、职责描述和工具权限。在设计上，一个子代理就对应一个稳定的专业角色。

name: code_reviewer description: 专门做代码审查，只输出定位到文件路径和行号的问题 tool: - read - grep - glob - bash 你是一个只负责代码审查的资深工程师。你会严格遵守以下规则： 1. 着手审查前必须读取被审查文件的调用链 2. 每条问题必须标注文件路径和行号 3. 所有输出按“必须修改 / 建议修改 / 可选优化”分类 4. 你不负责修复代码，只负责给出审查结论

把任务拆给子代理之后，主对话只需要调度它们干活就行。这就像你带了一个团队，而不是把一个全栈工程师绑在同一个岗位上。对于稍有规模的代码库，这个设计带来的稳定性提升非常明显。

4.3 Hooks：让模板在关键时刻自动触发

模板也可以套在事件上。Claude Code 的 Hooks 可以在工具调用前后、对话结束等时机触发自定义脚本。我把其中一些规则自动化之后，就再也不依赖自己逐个手动传递模板了。

一个很实用的配置是在工具调用前检查“是否触碰了不该碰的文件”。

{ "hooks": [ { "matcher": "PreToolUse", "hook": "/path/to/pre-tool-use-check.sh", "commands": ["Write", "Edit"] } ] }

脚本里可以定义“受保护路径”清单。如果模型执行写操作的对象是src/generated/或者config/production.yaml这类文件，就直接拦截并抛出一条说明。这种做法相当于把模板里“不要修改未授权的文件”这条约束，从软性提示变成了硬性门禁。

我同时也在Stop事件上挂了一个钩子，事件触发后自动运行测试套件。这算是给模型收尾加了一道自动检查。Hooks 的定位是给模板一个执行时机，让好的规则不只是存在于大脑中，而是嵌在流程里。

5. 模板失灵的三种典型情况与修复过程

5.1 冲突式约束：当模板自己打架

我最早踩过的一个坑是模板里的约束互相矛盾。有一版 CLAUDE.md 我同时写了“保持代码简洁，避免冗余”和“每个函数必须补全详细注释”。看起来好像没问题，但碰上复杂业务函数时，模型就会陷入两难：注释写细了显得代码冗余，代码精简了又不够注释量。它的具体表现就是在两个约束之间摇摆，输出时而详细时而精简，毫无规律。

修复办法是给规则分优先级，并且在规则里给出边界：

- 所有规则中，「代码简洁」优先级最高 - 函数注释只要求写清楚参数含义和返回值约定，禁止抄代码行 - 复杂逻辑超过 20 行时，注释优先详细；其余情况注释从简

模型在遇到冲突时需要有明确的裁决依据。如果模板设计者自己都没想到规则之间会冲突，那结果只能靠模型自由发挥。

5.2 上下文缺失：模板引用了会话里不存在的信息

另一种常见的失败是模板里提到了某个文件，但会话当时并没有读取那个文件。模型不会像浏览器一样自动去打开所有相关页面，它很容易在讨论一个接口时依赖自己对文件内容的猜测去生成回答。

我第一次用重构模板时就遇到了这个情况。模板要求它给出“受影响文件清单”，它直接写了一个不存在的文件名上来，原因是它根本没读过源文件，只是在凭经验推断。

修复方式是在模板最前面强制加一条前置动作：

执行任何任务前，先用 grep / glob 确认相关文件是否存在。 所有涉及的文件路径必须先读取，再进入分析。

这条规则看起来简单，但对模型来说却是一个“强制加载上下文”的开关。加了它之后，幻觉文件名的出现率直线下降。

5.3 模板过长：注意力被稀释

最后一个坑是我们自己造成的。随着模板越写越全，一些关键模板的篇幅开始膨胀，代码审查模板一度写到了三百多行，里面塞了很多历史上碰到过的特殊场景。结果我发现，模型在长模板下面反而表现变差，“必须修改级别”的发现率反而有点下降。

原因不难理解：上下文窗口中信息过载后，模型会顾此失彼，前面说过的重要要求被后面的细节挤占。后来我把长模板按职责拆分成多个子代理，每个子代理只专注一个细分环节。审查模板拆成了“架构影响检查”“实现细节检查”“安全漏洞检查”三个代理，每个文件都控制在六十行以内。

拆分后效果立刻不一样了。与其训练一个什么都会但什么都不精的模型，不如给它几个专职同事。

最后，说一点维护 claude-code-templates 的实际体会

模板库不是一劳永逸的工程，它像一个活的协议，得跟着实际踩坑不断演进。我给自己定了一个硬规矩：每次让 Claude Code 干砸一件事，都要把它失败的原因写回对应模板。有一次它在迁移时误改了配置文件，我就把那个配置目录加进了“禁止修改清单”；还有一次它在生成测试时编造了一个 mock 数据，我把“禁止编造运行时不存在的对象”写进了测试设计模板。慢慢地，这套模板就成了团队最真实的代码纪律沉淀池，比任何文档都有执行力。

如果你准备开始建自己的模板库，我的建议是小步快跑：先挑一个你每周都会重复的任务，例如代码审查，写一份二十行左右的模板，跑通之后再加第二个场景。不要想着第一天就建出一个大而全的体系。工具会更新，模型会升级，但是“把好的协作方式固化成模板”这件事，永远不会过时。