企业官网建设流程全解析

Claude Code 用久了，最明显的感受不是模型懂多少，而是每一轮新会话里，你都在反复跟它解释同一个“怎么干活”的老问题。我刚开始用的时候，喜欢把完整背景、硬性约束、输出格式全写在 prompt 里，效果好是好，但一天开十几次会话，同样的话就得原封不动打十几次。后来实在受不了，我干脆把所有高频场景下的用法整理成了一个独立项目，也就是标题里的 claude-code-templates。前后折腾了差不多三周，从最早的几个 Markdown 文件，到现在可复用、可分发、可回溯的模板库，它彻底改变了我的工作方式。这篇文章就是整个设计和落地的完整记录，包括目录结构、配置拆解、能直接抄作业的模板示例，以及我在真实项目里踩过的坑。正准备用 Claude Code 或者想把 AI 编码工具带进团队的朋友，可以少走不少弯路。

1. 我给 claude-code-templates 定的形态：不是提示词合集，是工作流资产

先说清楚，我最早犯过一个方向性错误：以为模板库就是“一堆写得更好的 prompt”。我把十几个场景的提示词扔进一个文件夹，用了两天，发现效果提升有限，该重复沟通还是重复，该出错还是出错。后来我重新想了一轮，才意识到问题出在分类方式上——提示词只是模板库的表层，真正有价值的是把“工作方式”沉淀下来。

1.1 什么应该由模板承接，什么不应该

我的判断标准很简单：模板应该承载的是“稳定的、可迁移的做事规则”，而不是“一次性的具体内容”。比如“代码审查时应该按什么顺序检查、哪些问题必须停下来追问、哪些地方只提示不修改”，这类规则是稳定的，适合沉淀；而“这次要审查的是哪个分支、改动了哪几个文件”，这类具体信息应该由使用者在调用模板时临时补充。

我见过有人把模板写成这样：“请检查 src/user.ts 的第 45 行，这个函数有 bug。”这种模板一次能用，下次数据一变就作废。真正的模板应该是：

你是一个做过多年 Code Review 的资深工程师。请先了解本次改动的文件和 diff，再按下面的清单逐项审查，最后以指定格式输出结果。

具体文件、具体行号交给会话里的当前上下文，模板只负责审查流程、审查规范和输出要求。这么一拆，模板的复用率一下就起来了。

1.2 筛选场景的四个判断标准

不是什么场景都值得做模板。我整理 claude-code-templates 的时候，只给满足下面四个条件的场景做模板：

用这套标准筛了一遍，我身边日常能沉淀的场景大概就七八个，其中六个我反复打磨过，后面会展开写。剩下的场景比如“帮我想个函数名”“解释这段代码”，太轻、太个性化，模板反而显得笨重。

1.3 模板库和普通提示词文件的关键差异

模板库不是提示词仓库的换皮，至少有三点差异：

第一，模板库有明确的生命周期管理。每个模板有版本号、修改记录、适用条件，甚至能回滚到上一个版本。临时 prompt 是写了就忘，模板是改了要留痕。

第二，模板库对输入输出有约束。普通提示词可以任意发散，模板必须规定：需要使用者提供什么输入，模型应该给出什么结构的结果，哪些边界条件算“任务完成”。

第三，模板库要能批量交付。靠复制粘贴没法推广，必须有一个安装、更新、校验的机制，让团队里每个人拿到的都是同一套规则。

这三点说起来简单，落地的时候牵扯到配置、目录、脚本一堆细节，下面分步讲。

2. 骨架与配置：分层 CLAUDE.md、斜杠命令、输出约束

使用 Claude Code 的时候，真正决定模型长期表现的不是闲聊式对话，而是它在每轮工作前能读到什么。Claude Code 本身支持读取 CLAUDE.md 文件作为项目记忆，也支持通过自定义斜杠命令快速唤起一组复杂指令。claude-code-templates 的核心骨架就是把这些能力组合起来。

2.1 记忆分层：全局、项目、任务三级各放什么

我给它们定的边界非常明确，互不打扰。

全局层对应~/.claude/CLAUDE.md，放的是“无论面对什么代码库都成立”的个人偏好，比如：默认使用中文回复、涉及删除操作必须二次确认、对不确定的问题先承认不确定性再给出假设。

项目层对应仓库根目录的CLAUDE.md，放的是这个项目特有的长期事实，比如技术栈、目录职责、构建命令、测试方式、代码风格约定。这一层是模板库自动带入上下文的入口，我不需要每次说话都重复“这是一个 NestJS 项目，用 pnpm 管理依赖”，项目里的 CLAUDE.md 会替我说。

任务层对应.claude/commands/目录下的模板文件，放的是一件事怎么做：怎么审查，怎么重构，怎么调试。任务层的文件不会默认进入每轮上下文，只有我主动用/xxx命令触发时才会完整加载，这正好解决了“全局塞太多内容导致 token 浪费”的痛点。

三个层级的分工很清楚：全局层管风格，项目层管事实，任务层管操作流程。模板库主要建设的是任务层，但前两层如果没有理清，任务层再精致也容易带病运行。

2.2 斜杠命令是模板的真正入口

我把一条模板做成一个斜杠命令。命令文件的格式是 Markdown，文件头部可以写 YAML 元信息，正文就是给模型的指令。它的运作逻辑很直接：你在 Claude Code 里输入/review，它就自动读取对应的命令文件，把整段指令作为系统级上下文传给模型。

以我的一个命令文件为例：

--- description: 对当前改动执行一轮代码审查 agent: false allowed-tools: Read --- 你是一名拥有 10 年以上工作经验的代码审查者。 第一优先：理解改动意图 - 先读取 git 状态、git diff 和涉及文件的历史背景 - 如果差异过大，先向使用者确认本次改动范围 第二优先：按清单逐项检查 1. 逻辑正确性：分支条件、边界值、异常路径 2. 安全性：输入校验、权限判断、敏感信息泄露 3. 性能：循环嵌套、无意义的重复计算、不必要的大对象持有 4. 可维护性：命名、函数长度、重复代码 约束： - 只输出问题清单，不要直接把修改后的代码写出来 - 问题按严重程度分为 P0/P1/P2，P0 表示必须修复 - 如果清单中的某个项目不适用，明说“不适用”，不要编造

注意元信息里的agent: false，意思是这个命令不需要切换到多步代理模式，只要求单次阅读和审查，避免模型自作主张跑去改代码。allowed-tools限定它只能用读取工具，这是第一道安全阀。

这个设计解决了一个很实在的问题：我不需要在对话里事无巨细描述“你要做什么”，只需要一条/review，整段专业流程就稳定地加载了。

2.3 输出格式与退出条件的强制约定

模板容易失控的地方是“让模型自己决定怎么输出”。一旦允许自由发挥，同样的服务端逻辑，今天给你列条，明天给你写整段，后天给你画个表格，后续要把它接进脚本做统计就会非常痛苦。

我在每个模板里都固定了输出框架。比如审查类模板强制要求输出这样几块：

## 结论 一句话结论：本次改动是否可以合并，风险等级如何。 ## 问题清单 - [P0] 问题简述 / 文件位置 / 依据 / 建议 - [P1] ... - [P2] ... ## 未检查项 列出本次因为条件限制没有覆盖的部分，如未运行的测试、未查看的历史提交。

固定输出格式有两层价值。第一层，模型知道往哪个方向收敛，不会东拉西扯；第二层，我可以写脚本去扫描会话输出，统计每次审查发现的 P0/P1 数量，模板库的效果就有了量化依据。这一点在团队推广时特别重要，否则你永远只能用“感觉更好用”来向同事解释。

除了输出格式，还必须定退出条件。很多模板没有告诉模型“做到什么程度算完”，结果模型把简单审查无限延伸，开始给你报代码风格建议，真正致命的逻辑问题反而放过了。我在模板末尾都会写清楚：

当问题清单和结论都已输出后，任务即结束。不要补充无关建议，不要重写代码。

模板是给做事流程立规矩，不是给模型自由发挥的舞台。这个认知后面帮我避了好几个大坑。

3. 可直接抄作业：六类高频场景的模板设计

这一节我把自己打磨过并且一直在用的六个模板拆开讲。每个模板都会说明设计思路、核心指令和边界条件，你拿到之后改改项目名和技术栈就能用。

3.1 代码审查模板：只点评，不代写

开头已经展示了/review的主要结构，这里补充几个我在实战中不得不加的细节。

第一个细节是“先读历史再下结论”。有几次模型直接看着 diff 说“这里没错误”，但改动涉及的历史 bug 修复完全没有纳入考虑。我后来在模板里强制加了一步：

在输出结论之前，必须先检查 git log 中被改动文件的最近提交记录。 重点确认是否存在此前反复修改过的逻辑区域。

这一步非常值得，因为 AI 擅长盯住表象问题，却容易忽略“这个文件为什么长成这样”的演进脉络。

第二个细节是严格禁止“自动改代码”。审查和修改是两件事，一旦让模型在审查的同时给出修改方案，它很容易越权，甚至连带产生新的风险。所以我的模板反复强调：审查只输出问题和建议，不直接产出修改后的代码。真正要改的时候，重新调用/refactor命令。

3.2 重构模板：带安全网的渐进式改造

重构是 Claude Code 最容易翻车的场景。模型太喜欢一次性给你一版“更优雅”的整体重写，但这种输出几乎没法在真实代码里落地，一贴就会引入大量回归 bug。

我的/refactor模板是这样设计的：

--- description: 在保持行为不变的前提下执行一次渐进式重构 agent: true allowed-tools: Read, Edit, Glob, Grep --- 你是一名重构经验丰富的工程师。你的目标是：在不改变外部行为的前提下，提升代码可读性和可维护性。 第一步：定义安全边界 - 识别被重构代码的入口和出口 - 列出所有现有的测试用例，并指出哪些能覆盖这次改动 - 如果没有测试覆盖，明确告诉使用者，必须先补测试 第二步：小步重构 - 每次只改一个逻辑点，不要同时调整命名、结构和算法 - 每次修改后说明：影响范围、可能受影响的调用方、验证方式 第三步：提交提示 - 为每个独立重构步骤生成可单独提交的 git commit 信息

最关键的是“先补测试再动手”。我把这条写在模板靠前的位置，因为 Claude Code 默认没有强烈意愿去写测试，它会觉得直接改代码更快。但真实的重构经验告诉我们，没有测试网的重构就是在走钢丝。

另外，我在模板里设置了agent: true，允许模型调用多步工具去搜索引用、读取文件、逐步修改。这和审查模板刻意相反，说明模板工具本身应该根据任务灵活切换，不是所有场景都要限制。

3.3 故障调试模板：锁定嫌疑区，而不是瞎猜

调试类任务最怕模型“猜”。看到报错日志，直接说“这可能是数组越界，你改一下”。结果你改完一跑，报错还在，浪费一轮时间。

我的/debug模板把整个排查链路分成了四步：

1. 还原现场：读取报错信息、堆栈、输入数据，明确复现条件 2. 建立假设：列出 3 到 5 个可能导致问题的嫌疑点，并给每个嫌疑点一个排除证据 3. 逐项排除：按嫌疑从高到低读取相关代码或执行小范围验证 4. 定位根因：只有在证据充分时，才输出根因结论和修复建议

我在模板里给了一个关键词叫“证据优先”。模型在调试时的本能是“快速给答案”，而模板的作用是逼它先给证据链。这条规则显著减少了“看似对、实则隔靴搔痒”的调试结果。

实际使用中，我还加了 一条：

如果你无法在 3 轮工具调用内定位根因，请把当前进展输出给使用者，询问是否继续扩大排查范围。

这一步是为了防止模型在一个错误方向上无限深挖，带偏整个会话节奏。

3.4 测试与回归模板：产出可追踪的覆盖报告

写测试这件事，很多开发者自己不乐意做，模型也不会主动给自己找活干。所以我专门做了/test模板，把它变成一个固定仪式。

--- description: 为指定模块补充测试并输出覆盖报告 agent: true --- 请为当前模块设计测试策略。 第一，明确被测对象：模块的公开接口、核心函数、边界条件。 第二，参考项目已有测试风格，不要发明新的测试模式。 第三，补充缺失用例，重点是： - 正常路径 - 空输入 / 非法输入 - 边界值 - 异常分支 第四，用项目现有的测试命令执行全部测试并报告结果。 输出要求： - 列出本次新增的测试用例清单 - 对整个模块给出覆盖薄弱点的判断 - 不要为了覆盖率而编写无意义的断言

这个模板的价值不在于替你把测试写完，而在于它把“测试策略思考”前置了。模型会先描述模块的外部行为再写用例，生成的测试质量明显高于那种“看到函数就顺手补一句 assert”的随手产出。

我还定了一个硬规则：新增用例必须和项目原有测试风格一致。有些团队用 Jest，有些用 Vitest，有些喜欢 describe/it，有些喜欢 test，模型默认会选择最常见写法，模板必须强制它跟着现有习惯走。

3.5 提交信息模板：把团队规范揉进单条命令

一个很轻但收益很实在的模板是/commit。每个项目对提交信息格式都有要求，有的要求带需求单号，有的要求类型前缀，这些规则写进模板后，每次提交都稳定格式化。

--- description: 生成符合团队规范的 git 提交信息 agent: false allowed-tools: Read --- 请根据当前 git diff 和 git status 生成提交信息。 规范： - 格式：<type>(<scope>): <subject> - type 取值为 feat / fix / refactor / docs / test / chore - subject 使用简体中文，不超过 50 个汉字，结尾不加句号 - 正文部分说明为什么做出这个修改，而不是做了什么 要求： - 先读取 diff，理解真实改动内容 - 如果 diff 范围过大，拆分出多个建议提交 - 一次提交只表达一个原子改动，不要混写无关内容

这里有个小技巧：命令的正文自然语言是给模型的指令，description 字段则是给使用者看的命令提示，两个地方都要写清楚，一个给机器，一个给人。

3.6 遗留代码文档化模板：先梳理行为，再动笔

给老代码补文档，最容易出现的问题是模型照着代码表面写文档，等于把代码翻译成文字，读者依然看不懂。我的/docs模板要求模型先“重建行为模型”，再动笔：

1. 从调用入口开始，画出模块的输入输出链路 2. 列出所有外部依赖和副作用（数据库、缓存、文件、第三方接口） 3. 找到代码里隐含的业务规则（如状态机、超时时间、重试策略） 4. 文档结构必须包括：模块职责、关键流程、边界情况、变更注意事项

这一条的难点在于“隐含规则”。模型往往意识不到某个魔法数字背后的业务含义，我在模板里专门加了引导语：“如果代码中存在无法解释的常量或条件分支，请明确标注为需向原作者确认。”这比让模型强行编一个解释安全得多。

4. 仓库结构、版本分发与团队协作接入

模板写在本地是一回事，能安装到不同机器、能跟着团队一起演进，是另一回事。claude-code-templates 走到第三周时，我已经把它重构成一个标准的 Git 仓库，配合脚本做分发。

4.1 我最终采用的仓库目录

直接看我当前维护的仓库结构：

claude-code-templates/ ├── CLAUDE.md ├── README.md ├── CHANGELOG.md ├── commands/ │ ├── review.md │ ├── refactor.md │ ├── debug.md │ ├── test.md │ ├── commit.md │ └── docs.md ├── scripts/ │ ├── install.sh │ ├── verify.sh │ └── stats.py ├── docs/ │ ├── conventions.md │ └── guides/ └── versions/ └── v1.2.0/

根目录的 CLAUDE.md 是给“未来准备接手维护这个模板仓库的人”看的，它的作用是告诉维护者：命令文件如何命名、frontmatter 里必须包含哪些字段、模板的更新流程是什么。这就是“元模板”——用 Claude Code 的方式管理 Claude Code 模板。

commands/是模板主目录，每个文件对应一条斜杠命令。scripts/里放安装、校验、统计脚本。versions/是发版时生成快照的目录，正常开发不太需要手动碰它。

4.2 模板的版本标识与变更流程

模板是会被反复引用的“代码”，它同样需要版本管理。我规定每个命令文件头部必须写清楚版本号：

--- description: 对当前改动执行一轮代码审查 version: 1.2.0 last_updated: 2025-01-10 ---

版本号的作用在团队场景里非常明显。有同事问我“你现在的 /review 是不是比上周改过了”，只需要把版本号亮出来就能对齐，不需要逐字对比内容。

变更流程我定成三条：

1. 影响判断的变更（比如增加了审查检查项）必须至少提升一个 minor 版本，不能悄悄改。
2. 每次变更在 CHANGELOG.md 里留一行，写明变化点和原因。
3. 禁止在未通知的情况下删除某个命令文件，必须废弃就保留文件并标注 deprecated。

这套流程不会增加多少负担，但能让模板库在多人维护时不乱。当然了，如果你只是一个人用，流程可以砍半，但至少版本号和 changelog 建议留着。

4.3 团队接入的最小成本方式

团队接入的最大障碍不是模板内容，而是“我凭什么要用你的方式干活”。为了降低接入成本，我写了一个安装脚本，同时也提供了手动复制两种方式。

安装脚本的核心逻辑很简单，就是把 commands 目录里的文件软链接到用户的~/.claude/commands/下：

#!/usr/bin/env bash # scripts/install.sh set -euo pipefail TEMPLATE_DIR="$(cd "$(dirname "$0")/.." && pwd)/commands" TARGET_DIR="${HOME}/.claude/commands" mkdir -p "$TARGET_DIR" for file in "$TEMPLATE_DIR"/*.md; do name="$(basename "$file")" ln -sfn "$file" "$TARGET_DIR/$name" echo "linked $name -> $file" done echo "done."

软链接的好处是：模板仓库更新代码后，使用者下一次触发斜杠命令时自动读取的是新版本，不需要手动同步。缺点是如果你不打算让远程仓库的变更立刻影响本地行为，请换成 copy 而非 symlink。这取决于团队管理风格——我们团队选择了 symlink，因为想让“模板版本统一”成为默认状态。

团队接入还应该配一个简单的 README，告诉同事模板到底覆盖哪些场景。我见过最好的方式是在 README 里提供一张速查表：

这张表不用太长，但足以让不了解模板的人一眼判断“我这个场景该不该用”。

5. 实测翻车的三个坑与修复链路

模板库不是搭好就完事，实际跑起来问题一堆。下面这三个坑是我自己踩过的，每一个我都给还原一下当时现象和排查过程，不直接甩结论。

5.1 上下文过载：什么都想写进模板，结果每轮都在烧 token

第一版模板我写得非常“大而全”，每个命令都恨不得把公司业务背景、编程规范、项目架构、用户偏好全塞进去。结果很直接：每次触发命令，上下文占用暴涨，响应变慢，而且模型开始被大量背景信息淹没，反而忽略了当前代码的实际问题。

排查过程让我意识到问题在于“层级混淆”。项目长期信息应该放在项目根目录的 CLAUDE.md 里，而不是塞进任务模板。任务模板应该只负责“这件事怎么做”，不该反复重复“项目用什么框架”。

修复方式是做一次信息拆分：把所有项目常识类内容移出命令文件，只保留流程规则和审查清单。实际效果是同样的 /review 命令，上下文占用降了大约三分之一，响应准确性反而上升了。

这里我总结出一个经验：模板信息的密度和任务质量不是简单的正相关，信息太挤会稀释模型对核心指令的注意力。模板宁可短而明确，也不要长而全面。

5.2 约束反噬：AI 把模板当教条，低级判断都不做了

第二个翻车现象出现在模板里的约束过多之后。我的 /refactor 模板原本写了很多“不要做”的禁令，比如“不要调整公共接口签名”“不要修改缩进风格”“不要动配置文件”。结果模型变得极度保守，遇到真正应该修改公共接口的情况也不敢动了，它宁可不做，也好过违反模板指令。

有一次重构中，某个内部函数已经是明显的坏味道，正确做法就是改签名并同步所有调用点，但模型面对模板里的禁令，直接告诉我“按模板约束，这个改动超出范围”。我当时挺无语，排查到最后发现，问题不在模型能力，而在模板的约束粒度太粗。

修法是把“一刀切禁令”改成“附带判断条件的约束”：

约束： - 默认不修改公共接口签名；但如果现有签名阻碍了本次重构目标，请明确指出，并说明前置影响后再动手。 - 不要调整无关文件的格式；如果工具自动格式化误伤，请精确回退。

给约束加上例外判断，模型才有空间在真实场景里做合理裁决。这个坑特别值得注意，因为模板最初的初衷是规范行为，但过度规范会反过来削弱模型的使用价值。我后来加了一条总原则在所有模板里：“模板规则是默认行为，现实冲突时以现实为准，但你必须把冲突点输出给使用者确认。”这条原则现在仍然保留。

5.3 输出格式过度精确：模型生成的伪结构化输出更难解析

第三个坑来自我“强制结构化”的执念。初版模板要求每个输出必须是严格的 JSON：

{"result": "PASS", "issues": [{"level": "P0", ...}]}

我用一周后发现，模型经常产出一段夹杂着解释文字的 JSON，甚至偶尔在 JSON 后面追加“不然呢？”之类的自然语言结尾。反而更难解析，我用脚本去抓 JSON，不但要处理外层杂质，还要容忍字段缺失。

排查之后，我的结论是：让模型输出 JSON 格式没问题，但别要求它不用 Markdown 包裹，也别禁止任何额外解释。更好的做法是允许它先给出自然语言结论，再附加结构化数据区，我用脚本只提取标记区块。比如：

## JSON_RESULT { ... } ## END

同时，脚本侧做好容错，解析失败时主动回退到整段文本提取关键信息。这件事教会我一个原则：模板的输出规范要照顾模型的生成习惯，而不是单纯从“机器解析方便”出发。模型生成和脚本解析是同一个系统的两端，设计时必须同时考虑。

6. 我把模板库再往前推一步：统计、反馈与轻量自动化

到了这一步，模板库已经能稳定解决日常问题。但我发现它还有两个隐藏价值没有榨干：一是用数据告诉大家模板到底有没有用，二是把模板库自身的健康度变成可观测指标。所以我加了统计脚本和反馈机制。

6.1 用量统计：靠日志，也靠输出锚点

我没有在 Claude Code 内部埋点，而是用了一个笨办法。所有模板输出都带有固定锚点，比如审查模板输出## 结论，测试模板输出## 测试结果，我可以直接翻历史会话记录，统计每个模板被调用的次数和结论分布。这个方式不需要接入内部 API，纯粹基于文本扫描，成本低，也足够用。

配合scripts/stats.py能生成一张每周用量表格：

# scripts/stats.py import re, collections, glob logs = glob.glob("~/.claude/projects/**/*.md", recursive=True) counter = collections.Counter() for path in logs: text = open(path, encoding="utf-8", errors="ignore").read() for key in ["review", "refactor", "debug", "test", "commit", "docs"]: counter[key] += len(re.findall(f"/{key}\\b", text)) for k, v in counter.most_common(): print(f"{k}: {v}")

数据出来以后，我立刻发现commit模板是最常被触发的，debug模板使用率最低。一开始觉得奇怪，后来一想也合理——大家提交代码次数多，调试反而更依赖自己读日志，不太愿意让模型介入。于是我有意识地在debug模板上投入更多精力推广，因为那正是模型能帮上大忙的场景。

6.2 反馈回路：遇到模板不好使，就当场记一笔

模板不可能一次写好，我养成的习惯是“当场记问题”。每次觉得某个命令的输出不对劲，就在一个固定的反馈文件里追加一笔：

2025-01-10 /review：跨文件改动时，没有读取调用方上下文，导致误报。

这个反馈文件积到 20 条左右，我再集中修一轮模板。修完删除对应条目，避免问题反复出现。这比每周复盘更即时，也不依赖记忆，属于成本最低的改进机制。

反馈文件也会共享到团队仓库，同事发现问题可以直接提，不需要等我来收集。模板库的进化不再靠某一个人的灵感，而是靠每个人日常使用中的触觉。

6.3 可以把模板库再往前推一步的扩展方向

目前我做的还是“规则驱动”的模板，下一步我想把模板和自动校验串起来。具体来说，在代码审查模板里嵌入项目自定义的 lint 规则输出，让模型先跑工具，再结合工具结果做判断，而不是只靠阅读代码。

另一个方向是把模板按“任务难度”分成轻量和深度两档。轻量版给简单任务，深度版用于高风险重构或跨模块改动。这套分级目前在实验，预期能进一步降低低风险场景的 token 消耗。

最后分享一个我个人的体会：模板库最大的价值不在于省了多少打字时间，而在于它把你脑子里的“隐性知识”变成了团队里看得见、改得动、吵得起来的“显性规则”。这个转变一旦完成，AI 编码工具的使用水平就会从一个工程师的私房技巧，变成一个组织可积累的能力。以后哪怕有同事离职或者项目换人，这套做事方式还能继续留在仓库里，这就是我折腾 claude-code-templates 最值得的部分。