企业官网建设流程全解析

用 Claude Code 做开发的人越来越多了，但我发现个普遍现象：工具装好之后，大多数人第一反应是敲一句 prompt 开干，然后下一轮换机器、换仓库、换项目，同样的问题又得重新解释一遍。我自己维护的 claude-code-templates 这个项目，就是专门来解决这种"重复解释"问题的。它不是一个单纯收集提示词的文件夹，而是一套能直接放进.claude目录、能被 Claude Code 自动加载的项目级模板体系，覆盖个人记忆、项目说明、任务指令、工作流规则和常见编码场景的脚手架。

这篇文章想把我在实际维护和使用这套模板库过程中的完整思路写出来：为什么模板要按"记忆层 + 指令层 + 流程层"来拆，而不是扔一堆 prompt；.claude目录怎么布局才能让模型稳定读取；任务模板、工作流模板各自适合什么场景；以及最关键的——模板库怎么维护才不会越用越乱。无论你是刚接触 Claude Code，还是已经用它产了段时间代码，这套思路应该都能直接用上。

1. 先明确模板库的价值边界：压缩重复决策，不是收集提示词

1.1 单独的提示词为什么经常失效

很多人对"模板"的理解还停留在"把一段好用的 prompt 存下来，下次复制粘贴"。但实际上 Claude Code 这类终端编程工具和网页版对话有一个本质区别：它每次启动时能看到的东西不止是你的 prompt，还有整个工作目录、git 状态、文件内容，以及通过 CLAUDE.md 注入的长期记忆。如果你只把一段 prompt 塞给它，而没有配套的项目上下文，那这段 prompt 大概率会给出泛泛而谈的回答。

举个例子，我早期写过一个"生成 README"的提示词，里面详细规定了章节结构、语气、命令示例的格式。单独使用的时候，模型经常忽略项目里的实际命令行，自己编造一些不存在的参数，因为 prompt 里只说了"要写清楚安装步骤"，却没有告诉它"本项目使用 pnpm，所有命令必须从 package.json 中提取真实脚本"。这说明单点提示词能约束输出风格，却约束不了上下文缺失的问题。模板库真正要解决的，是把"每次都要重新交代的环境信息、项目约束、操作习惯"变成默认值，让模型每次进入项目都自带这些背景。

1.2 模板要压缩的三类重复决策

我把模板库要覆盖的内容分成三类，这个分类直接决定了目录结构怎么设计：

• 环境类决策：这个项目用什么包管理器、测试框架、代码风格、Node/Python 版本要求、是否 monorepo。这些信息每个项目都不同，但每个项目内部是稳定的。
• 任务类决策：常见的开发动作，比如提交信息怎么写、分支怎么命名、单元测试跑哪些命令、依赖升级之后要做哪些回归检查。这类决策在一个团队里基本是固定的，值得固化。
• 流程类决策：涉及多个步骤或多文件的工作流，比如"新增 API 接口"，它天然包含路由定义、参数校验、文档更新、测试用例四个步骤；再比如"修改数据库表结构"，它包含迁移脚本、模型更新、查询语句回归、数据清理验证。这类流程如果每次靠临场发挥，很容易漏步骤，所以必须模板化。

模板库的本质不是"让 AI 说出正确的话"，而是"让 AI 在没有收到额外指令时，也能默认做出正确决策"。这是我后来才想明白的一点：模板的价值权重，取决于它能替你做多少默认决策，而不是文本有多精美。

2. 模板库的最小骨架：目录结构、加载机制与命名规范

2.1 .claude 目录的布局

Claude Code 在项目里会自动识别.claude目录中的内容。我推荐的最小骨架是这样的，这也是 claude-code-templates 这个项目当前采用的布局：

.claude/ ├── CLAUDE.md # 个人级 / 全局记忆，通常放用户目录，见第3节 ├── commands/ # 斜杠命令模板 │ ├── commit.md │ ├── pr.md │ ├── add-api.md │ └── fix-test.md ├── agents/ # 子 Agent 定义 │ ├── backend.md │ └── release.md ├── skills/ # 技能包，可按需引用 │ ├── unit-test/ │ └── db-migration/ └── hooks/ # 生命周期钩子，可调用脚本 └── pre-commit.sh

commands目录里的每个.md文件就是一个可通过/commit、/add-api这类快捷指令触发的内容块。agents目录用来定义专业角色，比如后端开发 Agent、发版 Agent，它们可以各自维护独立的记忆和操作偏好。skills目录放技能包，比如"数据库迁移模板"，其中含说明文件和示例脚本。hooks则是在特定事件（比如提交前）自动执行的脚本。

这套目录不是凭空设计的，它的核心思想是"按使用方式分区，而非按主题分区"。主题分区容易造成混乱，比如一个"数据库模板"到底属于命令、技能还是 Agent 记忆？而按触发方式分区就清晰：是人主动敲/xx用，还是模型在特定场景自动想起，还是某个生命周期节点自动触发。

2.2 让模板能自动加载的关键路径

Claude Code 的记忆加载路径主要分两层。个人级配置放在~/.claude/CLAUDE.md，它会跟随用户在所有项目中生效，适合写"我习惯用什么风格、我禁止用什么命令"这类跨项目偏好。项目级配置放在项目根目录的CLAUDE.md或.claude/CLAUDE.md，适合写这个仓库特有的事实。两层的优先级关系是：项目级内容会覆盖或补充个人级内容，所以"全局习惯 + 项目约束"的组合是一个很好的配置策略。

我在模板库里专门放了两个层级的模板文件，项目的 CLAUDE.md 模板里会写明：所有 crate 用 snake_case 命名、所有数据库访问必须走 repository 层、修改公共接口前必须通知前端组等。而个人级模板写的是：commit message 遵循 conventional commits、代码注释用中文还是英文、遇到不确定需求先列出假设再动手。看起来简单，但真正稳定运行的模板库，靠的就是这个清晰的两层记忆结构。

另外要注意一个细节：CLAUDE.md文件的头部最好写一行"本文件是项目记忆，不是执行指令，只有在需要判断项目约束时参考它"。原因后面我会展开讲，模型在任务执行过程中可能会把记忆文件当成"待执行任务"处理，导致每次对话都复述一遍项目规则，干扰效率。

2.3 命名规范如何定

模板文件名看起来是小事，但它决定了两个东西：斜杠命令好不好记、模型在索引文件时能不能一眼看出用途。我的命名规范是"动词开头、单一职责"：commit.md表示生成提交信息，add-api.md表示新增 API 接口，fix-test.md表示修复测试。避免用utils.md、helper.md这种含义模糊的名字，也不要让一个模板同时承担"生成接口+生成测试+生成文档"三个功能。

对于skills目录下的技能包，命名要更具体一点，比如db-migration/、unit-test/、dependency-audit/。技能包内部一般包含一个说明自身使用边界的SKILL.md文件，加上示例文件或脚本。这里有一个容易踩的坑：技能包文件夹名会用连字符还是下划线？实测下来连字符在斜杠命令和引用短语中更自然，下划线在某些 shell 脚本中更容易引起转义问题，所以统一用连字符。

命名规范决定的是可发现性。这个听起来很虚，但实际维护超过 20 个模板之后，你会发现很多时候不是没有模板，而是你根本想不起来某个模板叫什么。动词开头 + 单一职责的命名方式，配合claude命令列表的自动补全，能让你在三四个月后依然找到需要的模板。

3. 个人级与项目级 CLAUDE.md 模板：上下文管理的两种深度

3.1 个人级 CLAUDE.md：写自己的操作习惯

个人级配置默认位于~/.claude/CLAUDE.md。这一层的模板要回答的问题不是"这个项目怎么做"，而是"我这个人怎么干活"。我在模板里沉淀的三类偏好供你参考：

• 命令偏好：我不希望 AI 修改文件后自动执行测试，所以明确写了"修改代码后不要自动运行测试，先展示 diff 给我确认"。这看起来反效率，但对于代码库较大、测试耗时的项目，这个设定能避免它陷入"改一个文件跑一次全量测试"的低效循环。
• 语言偏好：我给代码注释、commit message 都设定了默认语言。这里要具体到"commit message 用英文写，但代码内注释用中文写"，否则模型会凭感觉混用。
• 工具链偏好：我最常用 pnpm、uv、cargo 这类现代工具，所以个人级 CLAUDE.md 里明确写了"安装依赖优先使用各语言官方的现代包管理器，避免使用全局安装"。

个人级模板的关键是你得诚实面对自己的使用习惯。我见过有人把个人级 CLAUDE.md 写成了教科书，列了三十多条规则，结果模型反而不知道怎么执行。好的个人级配置应该控制在 10 到 15 条以内，每条都是"你踩过一次坑之后不希望它再犯"的硬规则。

3.2 项目级 CLAUDE.md：写项目持久事实

项目级 CLAUDE.md 是模板库中最重要的一块，因为它是模型判断"当前代码库里发生了什么"的依据。我在 claude-code-templates 项目中维护了一份项目级模板骨架，核心字段如下：

项目级模板的核心不在于格式多么精美，而在于它必须和真实仓库保持同步。模板库里可以放一个通用的 CLAUDE.md 模板，但每个项目使用时要让人手工核对一遍"常用命令"表和实际的 package.json。我曾经遇到过模板里写的测试命令是npm test，但项目实际用的是pnpm vitest run，结果模型每轮测试都用错命令，白白浪费了几次调用。

3.3 两个层级的组合原则：全局优先，项目覆盖

个人级和项目级配置的组合原则，我总结为"全局优先，项目覆盖"。所有项目共通的东西放个人级，只有某个项目独有的事实才放项目级。千万不要把个人偏好复制到每个项目里，那会让 CLAUDE.md 越来越臃肿。

实际操作中我建议用一小段"合并约定"来兜底：在项目级 CLAUDE.md 的末尾写一行"本项目技术栈与命令以本文件为准，个人级配置中的命令偏好仅作为兜底"。这样当个人级配置说"优先使用 pnpm"，而项目由于历史原因必须使用 npm 时，模型能够明确判断以谁为主，不至于在两份配置之间反复横跳。

还有一个灵活技巧：在项目根目录之外的子项目里，可以用更小的.claude/CLAUDE.md覆盖根级配置。比如 monorepo 里前端工程和后端工程的技术约束完全不一样，在后端目录放一个"本目录是 Go 服务，所有测试命令以这里为准"的迷你配置文件，效果比在整个仓库根配置里堆砌分支逻辑更清晰。

4. 任务模组与工作流模板：把多步动作变成一次指令

4.1 斜杠命令：常见动作的快速入口

.claude/commands/是模板库中最容易见效的部分。它的原理很简单：你输入/commit，模型读取commit.md的内容，结合当前 git diff 生成提交信息。我在 claude-code-templates 里维护的命令模板有三个等级：

第一级是纯文本指令，适合依赖上下文判断的任务。比如commit.md的内容只有几行：先看git diff --stat和git diff，理解改动范围，再按 conventional commits 规范生成提交信息，最后展示给用户确认，不要直接执行。这类模板不需要任何参数，因为所需信息全部来自当前工作区状态。

第二级是带状态的指令，适合需要加载额外文件的任务。比如refactor.md，它要求模型先读CLAUDE.md中的代码约束，再找到目标函数的所有调用点，列出一个重构影响面清单，最后才开始动手。我踩过的一个坑是：如果不让模型先列影响面，它经常只改目标文件本身，导致调用方类型报错。

第三级是组合指令，适合跨文件的复合任务。比如add-api.md内部定义了一个严格顺序：确认路由归属 → 实现 handler → 添加参数校验 → 补测试 → 更新 API 文档。模型通过读取这个模板，相当于执行一个"必含步骤清单"，漏掉任何一步都算完成得不好。

4.2 工作流模板：把步骤清单固化成规则集

斜杠命令适合"用户主动发起"的场景，但 Claude Code 里还有另一类需求：希望在某个任务被发现时自动进入多步流程。这类需求我用agents/目录下的工作流模板来处理。

以"新增数据库迁移"为例，我在agents/db-migration.md里定义了一个后端架构师 Agent，它接到的任务指令不是"帮忙建表"，而是一整套约束：读取现有迁移文件命名规范 → 分析当前表结构与关联关系 → 生成新的迁移 SQL → 同步更新 ORM 模型 → 补充 down 迁移脚本 → 提醒用户执行pnpm migration:up。这个模板和斜杠命令的区别在于，Agent 拥有独立记忆，它在处理数据库任务时不会被"通用开发指令"干扰，而且可以配置为"当对话中出现建表、改表、加索引等关键词时自动被引用"。

工作流模板的核心设计原则是：把顺序写死，把判断留给模型。顺序写死是为了不漏步骤，判断留给模型是为了适应真实代码的差异。比如"生成迁移 SQL"不会规定每一列怎么写，而是让模型根据现有模型文件判断字段类型、可空性和索引策略。

4.3 模板中的变量、参数与上下文传递

斜杠命令模板支持参数，这在实际使用中非常关键。语法是在文件名后跟着参数，模板内部用$ARGUMENTS引用。以add-api.md为例，用户可以输入/add-api "创建订单接口，POST /api/orders"，模板内部用$ARGUMENTS拿到这段描述，再结合工作区代码推断接口所需字段。

但这里有一个重要经验：模板不要过度依赖参数，因为用户往往懒得打完整参数。我第一次设计模板时规定了一堆必填参数，比如 method、path、description，结果用了几次就发现每次都要打一长串，最终选择放弃。后来我改成"参数只是意图说明，具体路径从问题描述推导"，模板反而被团队接受。

上下文传递还有一个容易忽略的环节：斜杠命令执行完毕后，模型的分析结果应该写入会话上下文，而不是只输出到终端。所以我在模板里常加一句"完成本任务后，用三句话总结变更内容，方便后续对话引用"。这句话看起来多余，但它让后续的"再帮我改一下刚才那个接口"这类追问变得非常顺滑。

5. 实战拆解：模板库如何把一次 API 对接任务从半小时压到五分钟

5.1 场景设定：一个典型的第三方支付接入

我拿最近在 claude-code-templates 上实测的一个场景来演示。假设项目需要新增一个第三方支付回调接口，业务需求是：接收支付平台的回调通知、验签、解析订单号、更新订单状态、返回确认应答。这个任务在过去没有模板支撑时，我通常会自己手写步骤：先看现有支付模块的代码结构，找到订单模型，再配路由……每一步都要在对话里给 Claude Code 交代上下文。半小时是常态，如果中间模型理解偏了，可能要往返四五轮。

现在我在项目里维护了agents/payment-integration.md和commands/add-webhook.md两个模板，这套流程被压缩成了四步操作。

5.2 执行过程：模板是怎么一步步起作用的

第一步，我在终端输入/add-webhook "支付回调"。add-webhook.md模板被加载，它要求模型完成以下动作：

1. 搜索项目里已有的 webhook 或 callback 相关目录，评估是新建模块还是复用现有入口；
2. 读取当前支付相关的 Service，确认验签逻辑是在 controller 层还是 service 层；
3. 列出影响范围，包括路由文件、DTO 定义、订单状态枚举；
4. 实现接口：验签、解析参数、更新订单状态；
5. 添加针对性的单元测试，至少覆盖"验签失败"和"重复通知"两个分支；
6. 用一句话总结变更，提醒人工复核。

这个模板之所以高效，是因为它把"找代码结构"这件最消耗上下文的事变成了默认动作。模型通过在模板指令下搜索文件结构，很快就定位到项目的支付模块位于src/payments/，并且发现验签工具函数已经存在于src/payments/utils.ts中。如果没有模板指令，它可能会直接从"我该建哪些文件"开始想，思路完全不同。

第二步，在处理过程中模型发现订单状态枚举里缺少"PAYMENT_CONFIRMED"这个状态。按照普通对话流程，我大概率需要新开一轮对话让它处理，但因为我预设的payment-integrationAgent 记忆里写了"修改枚举必须同步检查所有 switch 分支"，它主动搜索了所有引用这个枚举的代码，发现有两个地方需要补全，然后一并处理了。这个"主动的额外动作"正是工作流模板的收益——它把隐性约束嵌入了 Agent 的记忆，而不是等我这个人类去发现。

第三步，模型完成测试后，自检了一下"重复通知"场景。正常情况下这需要我主动提醒，但模板中规定了"所有支付回调必须考虑幂等"。它自动在订单表里查找是否有callback_id字段，没有，则通过添加一个payment_callbacks表来记录回调 ID 和通知状态。这一步虽然在执行模板之前完全不可预知，但模板中的幂等规则让我不用在对话中额外强调。

5.3 效果和边界：模板能加速什么，不能替代什么

整个流程跑通大约花了不到五分钟，最终提交包含一个路由、一个 Service 方法、一个 DTO、一次数据库迁移和两组测试。而历史经验中，同样的任务人工推进时需要完成：向模型解释代码结构、强调验签逻辑的位置、指出订单状态可能缺失、提醒幂等要求……省掉的每一轮对话，本质上都是模板库的执行收益。

不过要清楚模板的边界：它能帮你规范流程、提醒约束，但不能替你做架构决策。我遇到的情况是模板要求"评估是新建模块还是复用现有入口"，这一步模型给出了两个方案并让我选择，而不是擅自决定。这是我在模板里特意的设计——凡涉及"要不要引入新目录、要不要改公共接口"这类有长期影响的决策，模板强制先问人；只有那些影响可控、可以快速回滚的局部修改，才可以自动执行。

6. 模板库的维护与迭代：真实环境里踩过的坑

6.1 模板和真实代码脱节是最大的坑

模板写出来之后放在那里，它不会自己更新。最典型的场景是：项目从 Fastify 换成了 Encore，但CLAUDE.md里还写着"框架为 Fastify，路由请参考 src/routes.ts"。结果模型每次生成新接口都按旧的框架写法，报错了还不知道为什么。我后来养成了一个习惯：每次重构涉及框架、命令、目录结构时，第一时间更新相关模板，并把"更新文档/模板"作为重构任务的收尾步骤写在工作流规则里。

另一个脱节场景是模板之间的互相引用失效。比如commands/api.md引用了一个叫"统一错误码规范"的约束，但这个规范已经改过了，导致模型按旧规范生成代码，测试阶段才发现错误码体系早已迁移。这比单文件过期更隐蔽，因为模板本身看起来没什么问题。解决办法是在模板头部写明"最后验证时间"和"依赖文件路径"，并周期性抽查。

6.2 模板库的版本管理：把它当代码看待

claude-code-templates 这个项目本身就应该用 git 管理，而且我建议直接使用 commons 仓库的方式：模板的变更必须走 PR，配套一个CHANGELOG.md，说明每个模板的改动理由。很多人觉得模板是小东西，改一下无伤大雅，但模板恰恰是"低频率、高风险"的文件——它平时不出声，一旦出错就是系统性出错，所有用到它的生成任务都会受牵连。

我之前犯过的一个错误是：为了"快速修复"，直接改了团队共享模板库里的一个规则，没通知任何人，结果另外两位同事的生成代码风格都变了，review 时才发现。从那以后我规定：模板变更必须带说明，且至少有一名同事 review。这里推荐一个简单可行的版本方案：

6.3 模板避免"腐化"的日常维护节奏

我给这个模板库定的维护节奏是三件事：季度审查、任务后更新、废弃机制。

季度审查是指每三个月过一遍所有模板，对照当前项目实际代码，删除已经无用的，更新过时的。这个周期不能太长，否则模板和代码之间的偏差会累积到失控。任务后更新是指每次用模板执行完一个较大任务后，如果发现模板漏了某一步，或者某一步的描述让模型产生了错误理解，就当场修改模板，并记录修改原因。废弃机制比想象中重要：给模板写上"适用场景"和"已不适用场景"两行，可以避免后来者在错误场景下套用模板。

最后，我想分享一个维护上的小技巧：用 Claude Code 本身来审查模板库。定期让它读取所有模板文件，找出重复、互相矛盾、措辞模糊的规则。模板库的本质是让模型少踩坑，而 AI 最擅长的事情恰恰是发现文本之间的不一致。这个循环跑起来之后，模板库的价值会越来越大，而维护成本并不会同步上涨。