企业官网建设流程全解析

去年我一度很崩溃。当时我已经离不开 Claude Code 了，但每次新开一个会话，都要花好几分钟重新解释项目背景、技术栈、代码结构、命名习惯；遇到稍微复杂的任务，我还要打一大段提示词去描述“你帮我看看这里为什么要这么写”“这次改动的影响面到底在哪里”。最气人的是，同一个问题换个姿势问一遍，得到的回答风格还能完全不同——有时候很稳，有时候像第一次见我。

后来我决定认真收拾这套东西，把那些反复使用的说明、命令、角色设定全部固化到一个仓库里，取了个直白的名字就叫claude-code-templates。这一收拾不要紧，直接把我跟 AI 协作的效率拉高了一个台阶：新项目不用再从零解释，团队新人也有一套统一的交互标准，以前每次要手打一长串的审查要求，现在一个斜杠命令就搞定。

这篇文章就是我基于claude-code-templates这个主题，把整套设计思路、目录结构、踩过的坑一次性梳理出来。无论你是刚开始用 Claude Code 的开发者，还是已经用了一段时间但觉得“总在重复对话”的人，都很适合照着搭一套属于自己的模板库。

1. 从“裸跑”到“模板化”：为什么你总在跟 AI 重复聊天

先说清楚一个概念：我这里说的“模板库”，不是指一套写死的代码脚手架，而是围绕 Claude Code 这个命令行 AI 编程工具，沉淀下来的一系列可复用配置文件。它通常包含项目记忆文件、自定义斜杠命令、子代理定义、钩子脚本，以及对应的使用文档。一句话概括就是：把原本要打字输入的上下文和指令，固化成文件里的结构化资产。

1.1 “裸跑”模式的三个明显痛点

我回顾了一下自己最早的使用方式，问题基本集中在三件事上。

第一，上下文靠嘴喂。每个新会话都是白纸一张。我得告诉它这个项目是 monorepo 还是单仓，前端用 React 还是 Vue，后端是 FastAPI 还是 NestJS，测试框架用什么，CI 里跑哪些检查……这些话翻来覆去说了几十遍，每次还可能有遗漏。结果就是它经常在错误的假设下干活，比如明明项目是 pnpm workspace，它给你按 npm 的路径查找包。

第二，指令质量不稳定。同样是“帮我写个测试”，状态好的时候我会写得详细，指定 mock 哪些模块、断言哪些行为；状态差的时候我就敲四个字“加个测试”。出来效果就可想而知了——有时候它能自动补齐思路，更多时候写的用例要么太弱、要么干脆跑不过。

第三，没有角色分工。让 AI 在“代码审查”和“功能开发”两种模式之间来回横跳，它自己都不知道当前应该以什么标准执行。你说“审查一下这个 PR”，它可能真的就只挑挑格式问题，完全没注意到你实际想让它关注的安全边界和异常处理。

1.2 模板库是怎么解决这些问题的

我把模板库引入工作流之后，最直观的感受是：新会话不再失忆了。

项目根目录下的CLAUDE.md会在每次会话启动时自动加载，里面写清楚项目是干什么的、目录结构长什么样、技术栈是哪套、代码风格有什么约定、有哪些坑需要规避。这相当于给 AI 发了一本“入职手册”，它还没开工就知道你是哪家的、该怎么干活。

高频诉求被固化成自定义 slash 命令后，我再也不用临场组织语言。敲一个/review就能触发一套完整的代码审查流程，敲一个/test就会按项目规范生成测试文件，敲一个/refactor就会先分析影响面再动刀。这些命令背后是写好的提示词框架，稳定、可控、可复用。

角色分工则交给子代理（agent）来解决。代码审查有专门的 reviewer 角色，排查问题有专门的 debugger 角色，写提交信息有专门的 commit 角色。每个角色有自己的 system prompt 和技能范围，不再“一人分饰多角”。

1.3 模板库的全景视图

我维护的claude-code-templates仓库大概是下面这个样子：

. ├── CLAUDE.md ├── CLAUDE.local.md ├── .claude/ │ ├── commands/ │ │ ├── review.md │ │ ├── test.md │ │ ├── refactor.md │ │ └── explain.md │ ├── agents/ │ │ ├── code-reviewer.md │ │ └── debugger.md │ ├── hooks/ │ │ └── precommit.sh │ └── settings.json └── docs/ ├── usage.md └── best-practices.md

别急着被这一堆文件吓到，后面我会逐个拆开讲设计逻辑。这里先记住一句话：模板库的本质是把“你希望 AI 怎么工作”这件事，从口头禅变成工程资产。

2. 模板库的三件套：记忆文件、命令目录与子代理

外面很多人把 Claude Code 的配置玩法讲得玄乎，但剥开来看，核心就是三块：记忆文件负责“让 AI 懂项目”，自定义命令负责“让 AI 听指挥”，子代理负责“让 AI 有专长”。这三块拼起来，才是完整的claude-code-templates。

2.1 记忆文件：CLAUDE.md 到底该怎么写

很多人对CLAUDE.md有个误解，以为写得越多越好。我见过有人把整篇 README 复制进去，甚至把接口文档都塞进去，结果每次对话加载一堆噪音，AI 反而抓不住重点。

我自己的写法是分五块：

1. 项目概况：三到五句话说明项目做什么、服务的用户是谁、核心业务链路是什么。
2. 技术栈清单：列出语言、框架、包管理器、构建工具、测试框架，最好具体到版本。
3. 目录地图：用简短的树状结构标出各模块的位置，并注明哪些目录是核心、哪些是边缘。
4. 硬性约定：比如“提交信息必须符合 Conventional Commits”“禁止在业务代码里使用any”“新增后端接口必须附带 OpenAPI 注释”。
5. 常见坑：写清楚哪些事容易做错，比如“数据库迁移不要手改，必须走工具生成”“这个模块依赖外部缓存，改完要清缓存”。

关键就一句话：给 AI 的上下文必须可操作，不是用来充门面的百科。

至于CLAUDE.local.md，则是我个人本地偏好和公共配置的隔离带。举个例子，团队公共的CLAUDE.md里写的是通用规范，而我个人希望 AI 在回答里多用中文、把解释写得简略一点，这些个人偏好就放 local 文件里，不进 git，也不会干扰别人。

2.2 命令目录：把高频诉求固化成斜杠命令

.claude/commands/目录下的每个 Markdown 文件，就是一个自定义斜杠命令。文件本身就是一条提示词，通过 YAML frontmatter 声明元信息，正文部分写具体的指令。

我写命令的时候会遵循一个模板：

--- description: 审查当前分支的改动，重点关注设计意图与风险 agent: code-reviewer --- 请审查当前分支相对主干分支的 `git diff`。 审查时请重点看以下内容： 1. 改动是否符合项目在 CLAUDE.md 中声明的架构约束 2. 是否存在隐含的行为变化（比如修了 A 却影响了 B） 3. 异常路径是否有妥善处理 4. 是否引入了不必要的复杂度 最后按「设计问题 / 风险点 / 可改进项」三块输出结果。

这里有个容易被忽略的细节：description字段非常重要。因为斜杠命令的触发列表就是靠这个字段展示的，你写得太模糊，AI 和人都看不懂这条命令什么时候该用。

命令正文里还可以用$ARGUMENTS接收用户传参。比如/review --focus=security，我可以在命令里根据参数调整审查侧重点。

再进阶一步，命令文件支持执行外部脚本，用脚本输出动态提示词。比如我可以写一个命令，运行一个脚本来抓取最近一条失败的 CI 日志，然后把日志内容作为上下文注入给 AI。这个玩法后面细说。

2.3 子代理：让专门的 AI 干专门的事

子代理是 Claude Code 里比较进阶的概念。它本质上是一个具有专属 system prompt 的 AI 角色，你可以在命令里指定“让哪个角色来执行”。

我的经验是，子代理的数量宁少勿多，职责边界要清晰。比较经典的角色是 code-reviewer 和 debugger：

• code-reviewer：专注代码审查，不吃业务上下文，只盯着 diff 的安全性、一致性、可维护性。
• debugger：专注排查问题，拥有“提假设-验证-缩小范围”的工作流，适合处理偶发性 Bug。

给子代理写 system prompt 时，我习惯给它加一句“你是 xxx 角色，你关注的是 xxx，你忽略的是 xxx”。这比单纯说“你是专家”有用得多，因为限制比赋能更值钱。

3. 手把手搭建自己的模板库：五步实操

理论讲完，下面直接进入实操。我会按我自己的搭建顺序一步步走，你照着做就能跑起来一个最小可用的模板库。

3.1 第一步：初始化骨架

在项目根目录下创建.claude目录，并初始化 git 仓库以便跟踪配置变更。

mkdir -p .claude/commands .claude/agents .claude/hooks git init

如果你打算跨项目复用同一套配置，也可以把模板库单独建一个仓库，然后用同步脚本拷到各个项目里。我目前的做法是：模板库作为 template 仓库，每个新项目初始化时把它复制过去，再基于项目特色修改CLAUDE.md。

3.2 第二步：写一份不为“好看”而是为“好用”的 CLAUDE.md

这一步是整个模板库的地基。我写的时候有个小技巧：先从一篇真实的会话记录里提取 AI 问过的问题。

你回看自己过去一周的对话，AI 反复问过什么是很清楚的。把这些问题的答案写进CLAUDE.md，它下次就不用问了。比如 AI 总问“这个项目的测试命令是什么”，那你就写在文件里：测试：pnpm test --runInBand。

我的一份典型CLAUDE.md长这样：

# 项目记忆 ## 项目概述 这个项目是一个面向中小团队的任务协作工具，后端使用 NestJS 提供 REST API， 前端使用 Next.js 和 TailwindCSS，数据存储使用 PostgreSQL 和 Redis。 ## 技术栈 - 包管理器：pnpm - 测试：Jest，测试文件放在 `__tests__` 下 - Lint：ESLint + Prettier，提交前必须通过 `pnpm lint` - 类型约束：禁止在业务代码中使用 `any` ## 目录地图 - `apps/web`：前端应用入口 - `apps/api`：后端服务入口 - `packages`：共享包，包括 UI 组件、工具函数、类型定义 - `docs`：技术文档 ## 硬性约定 - API 响应统一使用 `{ code, data, message }` 包装 - 新增数据库字段必须走 migration，不允许手动修改表结构 - 所有对外接口都要有 OpenAPI 注释 ## 常见坑 - Redis 里缓存的用户信息 15 分钟过期，查完用户要留意过期时间 - 前端路由的权限判断在 `middleware.ts` 中，不要在页面组件里散落权限逻辑

这段文字看起来朴素，但它解决的是“每次会话都要重新对齐”的大问题。

3.3 第三步：写第一个斜杠命令

先在.claude/commands/下创建一个review.md，先做最简单的一版。

--- description: 审查当前分支的改动，输出结构化评审结果 --- 请审查当前分支相对主干分支的代码改动。 审查要求： - 输出按「问题 / 风险 / 建议」分类 - 每个问题标明涉及的文件和代码位置 - 风险项需要给出修复建议 注意：不要纠结代码风格，优先关注逻辑正确性、边界条件和潜在缺陷。

写完这个命令后，在 Claude Code 里敲/review就能触发。使用git diff作为改动来源，AI 会自动获取分支差异，不需要我额外说明。

我建议你从“最常用、最重复”的两三个场景入手，不要贪多，先把单个命令打磨好。

3.4 第四步：加入子代理与动态脚本

下一步把我前面提到的code-reviewer子代理写出来。

--- name: code-reviewer description: 专注代码审查的专家，关注改动意图与潜在缺陷 --- 你是一名资深代码审查专家。你的工作是对代码改动进行结构化审查。 你重点关注： 1. 改动是否符合项目的架构约定 2. 是否存在隐藏的行为变更 3. 异常路径是否正确处理 4. 是否引入了不必要的外部依赖或复杂度 你不需要关注： 1. 代码格式（交给 linter 处理） 2. 纯粹的拼写或注释问题 在给出结论时，请为每个发现标注「必须修改 / 建议修改 / 可忽略」。

然后再把review.md里的agent字段指向它：

--- description: 审查当前分支的改动，输出结构化评审结果 agent: code-reviewer --- 请审查当前分支相对主干分支的代码改动。

这样/review触发时，代码审查会交给专门的角色，而不是让主对话里的 AI 临时切换状态，输出的稳定性和专业度高很多。

3.5 第五步：测试迭代与回归

模板库建好不是终点，我把它当代码一样对待，每次改完命令或记忆文件，都要跑一次“回归测试”。

我的回归方式很朴素：准备一个测试项目，准备几个固定的测试任务，比如“给这个组件补测试”、“解释这段逻辑”、“审查这次改动”。然后分别用旧版模板和新版模板跑一遍，对比输出质量。

这一步很容易被跳过，但恰恰是最重要的。模板改了之后不是一定变好，有时候你加的上下文反而干扰了 AI 的判断。保持可对比，才能持续优化。

4. 高频场景模板实例：审查、重构、测试、定位问题

有了上面的骨架，我来分享四个我自己用得最勤的模板设计。这些不是让你照抄的最终答案，而是给你参考“遇到这类需求该怎么拆解”。

4.1 代码审查：不审代码风格，审改动意图

很多人写的 review 命令太“糊”，没有约束重点，导致 AI 输出一堆“这里的变量名可以改得更语义化”之类的废话。我的做法是强制它关注意图和风险。

--- description: 审查当前分支改动，输出结构化评审结果 agent: code-reviewer --- 审查当前分支相对主干分支的代码改动。 输出格式： ## 必须修改 列出会引发 Bug、安全隐患或行为错误的改动。 ## 建议修改 列出设计上的隐患或可维护性风险。 ## 可忽略 列出不影响正确性，但值得留意的小问题。 每个问题都要给出文件路径和行号。

有一个特别的技巧：我让它基于改动目的来判断“必须修改”。因为有些改动看起来是删了代码，其实是故意简化；有些改动看起来只是改了个参数名，其实悄悄改掉了业务逻辑。模板里加一句“如果改动目的不明确，请主动询问，而不要猜测”，能避免很多误报。

4.2 重构命令：先画影响面，再动手

重构类任务最怕 AI 乱动手。它可能直接把一处逻辑改了，结果十几个测试跟着挂。所以我给重构命令设计了两个阶段。

--- description: 对指定模块进行重构，先分析影响面再执行 --- 阶段一：影响面分析 - 找出目标模块的所有调用方 - 列出该模块被依赖的方式（直接调用 / 事件触发 / 反射调用） - 评估重构后可能受影响的功能点 阶段二：重构执行 - 确保阶段性可编译、可测试 - 每完成一步都要跑相关测试 - 如果发现影响面超出预期，立即停止并汇报 在开始前，先输出影响面分析结果，等待确认后再动手。

这个命令实际上把“重构”这个模糊请求，拆成了两个可检查的步骤。AI 不会在第一步还没做完的情况下贸然动代码，因为它已经被要求“等待确认”。用下来最明显的感受是：它不再自作主张大改了，而是像一个会先提方案的工程师。

4.3 测试模板：让 AI 按角色生成用例

生成测试这件事，很多人以为很简单，其实坑也不少。AI 很容易写“假测试”——断言全是toBeTruthy()，或者断言了实现细节而不是行为。

我的测试命令设计成让 AI 扮演测试工程师：

--- description: 根据指定模块生成测试用例 --- 请为 $ARGUMENTS 模块生成测试用例。 生成要求： 1. 测试文件放在 `__tests__` 目录下，命名为 `$ARGUMENTS.test.ts` 2. 不 mock 被测试模块内部的函数，只 mock 外部依赖 3. 覆盖以下场景：正常路径、边界条件、异常输入 4. 每个用例的断言必须是对行为结果的验证，而不是对实现过程的验证 额外要求： - 先列出你认为需要覆盖的测试场景清单，再开始写代码 - 写完代码后运行测试，确认通过

加了“先列场景清单”这一步之后，测试质量提升非常明显。因为列出场景迫使 AI 先思考“这个模块到底有哪些行为”，而不是直接上手写实现。

4.4 定位问题：仓库考古式排查

处理线上 Bug 时，我最常用的命令是“仓库考古”。目标是还原一段代码的演变历史和设计意图。

--- description: 对指定文件或函数进行追溯分析，还原演化过程与设计意图 --- 请对 $ARGUMENTS 进行追溯分析。 步骤： 1. 使用 `git log --follow` 查看这个文件的提交历史 2. 找出最近三次实质性改动，分别说明改动背景 3. 分析当前实现中哪些代码是历史遗留，哪些是刻意为之 4. 基于以上分析，解释这段代码当前存在的原因 输出要求： - 按时间线还原演化过程 - 标注每次改动可能的动机 - 最后给出你对这段代码的整体判断

用了这个命令之后，我问 AI“为什么这段代码这么写”，它不再只会看当前文件内容瞎猜，而是真去翻 git 历史，给的答案靠谱得多。

5. 模板库的版本化与团队协作

模板库这东西，一个人用是效率工具，一群人用就是协作基础设施。我把它当普通代码库一样对待，走上版本化和团队协作的道路后，收益更大。

5.1 像管代码一样管提示词

既然模板库是 git 仓库，那就应该享受版本管理的全部好处。我每次修改命令或CLAUDE.md，都会走“提变更-评审-合并”的流程，不至于出现“昨天还能用，今天改了就坏了”的情况。

这里有一个重要的心理转变：提示词如果不进版本库，它就不是资产，而是随手扔掉的想法碎片。只有进了 git，你才有机会回顾，才知道某个命令从 v1 到 v5 经历了什么，才能把有效的经验沉淀下来。

5.2 公共模板与个人偏好的分离

团队场景里最核心的规矩是：公共的CLAUDE.md和.claude/目录进代码库，个人偏好的东西放CLAUDE.local.md，并且本地文件不进 git。

这样做的价值在协作中特别明显。我习惯让 AI 用中文、输出简短；另一个人可能更喜欢英文、带大段解释。如果这些偏好互相污染，AI 在同一个项目里的行为就会飘忽不定。分离之后，公共模板保证下限，个人偏好保证各自的上限。

团队还可以推进“命令即文档”的文化。新人刚加入时，让他先翻一遍.claude/commands/目录，就能快速了解团队常用的开发动作有哪些，比看几十页 wiki 直观得多。

5.3 多项目复用与模板同步

当你有多个项目时，就会出现模板同步的问题。每个项目都放一份完整拷贝，改起来会非常痛苦。我目前采用的是“基础模板 + 项目覆盖层”的方案。

基础模板放在一个独立仓库里，包含通用约定，比如“代码审查要求”“Commit 信息规范”；项目里只放一份“覆盖层”，也就是这个项目特有的命令和约束。每次基础模板更新，我会用同步脚本把通用部分推到各项目里，但保留项目自身的覆盖文件。

你要留意一点：模板同步别做太勤，也别在所有项目里“一刀切”。每个项目团队的约定差异很大，强行统一模板有时反而制造摩擦。基础模板管“通用习惯”，项目模板管“特定边界”，这个分寸拿捏好了，模板库才有生命力。

5.4 命名规范能帮你少踩很多坑

模板文件多了之后，命名混乱会严重影响使用。我总结了一套相对顺手的规范：

• 命令名用动词，比如review、test、refactor、explain，让人一眼看出“这个命令让我干什么”。
• 子代理用名词+职责，比如code-reviewer、debugger，强调角色身份。
• 文档按用途分目录，usage.md写给使用者，best-practices.md写给维护者。

这套规范的价值不在于好看，而在于降低记忆成本。你文件夹里躺着 30 个命令，如果命名不统一，那 AI 和人都不知道什么场景该用哪个。

6. 踩坑总结：模板库不是万能开关

最后我想认真说说我踩过的坑。模板化确实提升了效率，但它不是没有代价的。下面这几条，是我用claude-code-templates大半年之后的真实清醒时刻。

6.1 模板太重，反而拖垮上下文

我早期犯过一个错误：为了“让 AI 更懂项目”，往CLAUDE.md里塞了 3000 字，还把各种接口文档都塞进命令里。结果 AI 每次对话前加载一堆无关内容，响应速度变慢，输出里的噪声也变多了。

后来我才想明白一个道理：上下文是有限的，模板是放大器，不是硬盘。模板里每多一段废话，都在占用 AI 真正思考的空间。理想的CLAUDE.md应该像一张便签，而不是一本书。我现在会定期回顾模板内容，删掉那些一个月都没用过的条款。

6.2 越具体的模板越好用，越通用的命令越没用

我写过一条通用命令叫“优化代码”，结果触发后 AI 完全不知道该优化哪里——性能？可读性？依赖？它只能挑几个不痛不痒的小毛病糊弄我。

后来我把这条命令拆成了“优化重复代码”“优化性能热点”“优化可读性”，每个命令只负责一个维度，效果立刻不一样。这件事给我的教训是：如果你设计的命令描述里出现了“等”字，那这个命令基本不会好用。模板库设计的核心是收敛，不是发散。

6.3 模板会过期，需要和项目一起演进

项目技术栈升级了，目录结构调整了，第三方库换版本了，模板却不跟着改，它就会从“帮手”变成“误导源”。我经历过一次很深刻的翻车：项目已经从 ESLint 切到 Biome 了，但CLAUDE.md里还写着“提交前必须跑 ESLint”，于是 AI 每次都会跑一个不存在的命令，然后跟我道歉。

从那以后，我把模板库维护列进了项目的日常维护清单里，每次大的技术决策变更时，都要顺手更新模板。这个动作不费事，但漏掉之后的成本很高。

6.4 安全与隐私：密钥和敏感信息绝对不能进模板

模板库通常是要提交进代码仓库的，那就意味着它会跟着代码走。有些命令设计得比较顺手，会把内部服务地址、数据库名称、甚至是 API Key 写进命令模板里，这非常危险。

我现在的规矩是：模板里只写配置的引用方式，比如“密钥从process.env.DATABASE_URL获取”，绝不写具体值。涉及内部信息一律用占位符，比如<service-name>、<db-cluster>，具体值通过环境变量或本地文件注入。这条规矩听起来很基础，但真的能救命。

6.5 模板只是起点，沉淀工作流才是终点

把模板库搭好，只是完成了一半。另一半是把它融入你的日常工作习惯：新项目初始化第一件事，先铺模板骨架；写代码遇到卡点，先想想有没有现成命令能用；用完某个命令觉得效果不好，立刻记录下来准备迭代。

我现在的真实状态是：打开一个新仓库，如果里面没有.claude目录，我会觉得“这项目还没初始化好”。这种习惯不是一朝一夕养成的，而是一遍遍踩坑、改模板、再踩坑、再改模板，慢慢长出来的。

最后说一句切身体会：模板库这东西，真正价值不在于省下那几个 token，也不在于少打几句话，而在于它逼着你想清楚了自己到底希望 AI 以什么方式工作。你想得越清楚，写出来的模板就越少，效果却越好。这也是为什么我现在越来越觉得，与其到处收集别人的模板库，不如从零搭一套属于自己的claude-code-templates——过程中想明白的事，比最终那几个文件值钱得多。