企业官网建设流程全解析

在工程团队里把 Claude Code 用起来之后，我最大的体会是：真正决定 AI 编程助手产出质量的，往往不是模型本身，而是你递给它的那套模板。claude-code-templates这个关键词最近在开发者社区里讨论得非常多，我自己的代码库和团队规范里也已经沉淀了几十套实用模板，这篇就来把从命令设计、规则编写到项目级模板落地的完整思路和实操过程拆开讲讲。

这套东西适合谁用？如果你正在写 Claude Code 的 CLAUDE.md、自定义命令（slash command），或者想让 AI 在接手新项目、生成代码、做 Code Review 的时候稳定输出，而不是泛泛而谈“给我写个登录模块”——那这篇文章就是给你准备的。我会尽量把为什么这样设计、踩过哪些坑、最后怎么调整的都交代清楚。

1. 模板体系设计：先搞清楚你缺的是哪一层

1.1 三种模板，对应三种诉求

我最早犯的错误是，以为模板就是给 Claude Code 写一份“项目说明书”，把 README 复制进去就行。实际用下来，模板至少分成三层：

• 项目级模板（CLAUDE.md）：相当于给 AI 的“长期记忆”，描述项目背景、代码结构、技术约束、常用命令。每次对话开始时自动加载，是质量和风格的地基。
• 命令级模板（custom slash commands）：像给 AI 快速指令的“快捷键”。比如输入/review就自动执行一套代码审查流程，输入/gen-api就按团队规范生成接口代码。
• 代码片段模板（code snippets）：具体到函数、组件、脚本的骨架。解决“结构对不对”的问题，让 AI 生成的代码和团队既有风格一致。

三者的关系，可以理解成：CLAUDE.md 决定 AI 的“岗位认知”，slash command 决定“工作流程”，code snippet 决定“交付物形态”。我见过很多团队只做了第一层，结果 AI 知道项目背景但不知道该怎么干活，产出还是飘。

1.2 模板文件放在哪里、怎么命名

项目根目录下的CLAUDE.md是默认入口。但如果你有多个团队、多个子项目共用一个仓库，建议用.claude/目录来组织：

.claude/ ├── CLAUDE.md # 全局项目信息 ├── commands/ │ ├── review.md # /review 命令 │ ├── gen-api.md # /gen-api 命令 │ └── test-run.md # /test-run 命令 └── templates/ ├── component.tsx # React 组件模板 └── service.ts # 服务层模板

有个细节是，Claude Code 的命令目录放在.claude/commands/下，文件名就是命令名。比如review.md对应/review。模板目录没有强制约定，templates/是社区常用做法，你也可以用snippets/或者blueprints/，关键是让团队一眼能看懂。

提示：命名要短、可预测。/review、/api、/fix这种就是好名字；/help-me-refactor-this-module这种又长又难记的，团队根本不会用。

1.3 先定义“质量基线”，再写模板

很多团队做模板失败，是因为没有先回答一个问题：什么叫做“写得好”？我建议开一次短会，把团队里最常见、最痛的三类任务列出来，然后分别定义产出标准。举例：

• 新增一个后端接口：必须包含参数校验、错误处理、单元测试、接口文档注释。
• 新增一个前端页面：必须包含 loading 态、空态、错误态，组件按功能拆分而不是一个巨型 JSX。
• Code Review：必须关注并发安全、边界条件、性能隐患，而不是只挑拼写错误。

把这个质量基线写进 CLAUDE.md，AI 的产出才有“锚点”。后面所有模板都是围绕这些基线设计的。

2. 核心组成拆解：命令、规则、工作流怎么设计

2.1 命令模板的结构化写法

自定义命令本质上是“一份带目标的提示词”。写得好不好，差别很大。先看一个反面例子：

# /gen-api 为 {{feature}} 生成接口代码。

这基本等于没说。AI 不知道你的项目用什么框架、错误码怎么定义、日志打在哪里、测试用什么断言。写命令模板的时候，我总结了一个结构：

# /gen-api ## 目标描述 为 {{feature}} 生成完整的后端接口实现。 ## 项目上下文 - 框架：Express + TypeScript，仓库内已有 src/modules 下的模块化结构 - 数据库访问：统一走 src/db/repository.ts 中的 Repository 基类 - 错误处理：统一抛 ApiError，错误码规范见 CLAUDE.md 第 3 节 - 日志：使用 src/utils/logger.ts 导出的 logger 对象 ## 交付要求 1. 实现路由、服务、仓储三层代码 2. 参数校验使用 zod，所有字段需声明 3. 补充单元测试，至少覆盖正常分支和异常分支 4. 所有对外函数补充 JSDoc 注释 ## 输出格式 按以下代码块分别输出： - route.ts - service.ts - repository.ts - *.test.ts

注意几个关键点：

• 用{{feature}}这类占位符，让命令可以复用。Claude Code 会把用户输入自动替换到占位符位置，所以命令文件里能抽象的部分尽量抽象。
• 指明代码位置。“仓库内已有 src/modules 下的模块化结构”这句话很关键，AI 生成代码时会自动对齐已有文件组织方式，大幅减少后续移动文件的工作量。
• 列明交付物清单，AI 很擅长“完成任务”，但如果你不告诉它任务包含哪些产出，它会默认只给你核心代码，测试和注释常常被忽略。

2.2 规则模板：如何让 AI 真正“记住”约束

CLAUDE.md 并不仅仅是项目简介，它更像一份行为规范。我把规则分成硬性约束和软性偏好：

硬性约束建议放在 CLAUDE.md 靠前的位置，用加粗或列表突出。因为上下文很长时，AI 对中后段内容的注意力会下降，把“最不能违反”的规则放在前面，能显著提高遵守率。

一个容易被忽略的点是：规则要写“为什么”。比如“日期处理必须使用 dayjs”——如果不说明原因，AI 可能觉得也可以使用原生 Date。后面加上“因为项目同时涉及多时区业务，dayjs + timezone 插件已经做了统一封装”，AI 就会意识到这不是可选偏好，而是有实际背景决定的约束。

2.3 工作流模板：把多步操作变成一键流程

比单命令更进阶的是工作流模板。比如“开发一个新功能”，涉及“需求理解 → 代码设计 → 编码 → 测试 → 更新文档”五个阶段。你可以把整个流程写在一个命令里，让 AI 按阶段执行，每完成一步停下来等待确认。

# /feature ## 阶段一：需求澄清 列出你已经理解的需求要点，并向我提出至少 3 个澄清问题。 等我确认后再进入下一阶段。 ## 阶段二：设计要点 基于确认后的需求，输出： - 涉及的文件清单 - 关键函数/组件接口设计 - 数据流说明 ## 阶段三：编码实现 按阶段二的设计逐个实现文件。 每个文件实现完成后简述关键决策。 ## 阶段四：测试补充 为本次变更补充或更新测试用例。 确保 `npm test` 能够通过（如果现有测试环境允许的话）。 ## 阶段五：文档与收尾 更新 README 或相关文档。 列出本次变更的 commit message 建议。

这样设计的好处是：阶段一让 AI 先问问题，而不是直接开写。我实测下来，这个改动极大提升了需求理解准确率。很多“AI 写出了一堆不是我要的东西”的问题，本质上是 AI 没有收到足够信息，而你也没有给它提问的机会。

3. 实战模板示例：从通用配置到领域落地

3.1 一个能直接抄的 CLAUDE.md 模板

下面这个模板我用了挺久，覆盖了我自己的技术项目里大部分需求。你可以在这个基础上按团队情况增删。

# 项目概览 这是一个基于 TypeScript + Express 的 REST API 服务，提供数据采集、存储与查询能力。 仓库采用 monorepo 结构，核心代码在 packages/api 下。 # 技术栈与关键依赖 - 语言：TypeScript 5.x（严格模式） - 运行时：Node.js 20 LTS - Web 框架：Express 4 - 数据库：PostgreSQL + Prisma ORM - 校验：zod - 测试：Vitest - 日志：pino # 硬性约束 1. 禁止使用 `any`。如需处理未知类型，使用 `unknown` 配合类型守卫。 2. 所有数据库操作必须走 Prisma Client，不允许拼原生 SQL。 3. 接口必须返回统一结构：`{ code, data, message }`。 4. 异常必须统一抛 `ApiError`，在全局错误处理中间件中捕获。 5. 新增字段或接口时，必须同步更新 `packages/api/docs` 下的接口文档。 # 代码风格 - 使用命名导出，避免默认导出。 - 函数、变量使用完整英文单词命名，禁止缩写（`getUser` 而不是 `getUsr`）。 - 组件粒度控制在 200 行左右，超出则考虑拆分。 - 所有对外导出的函数必须写 JSDoc，说明参数、返回值和可能抛出的异常。 # 常用命令 - 启动开发服务：`npm run dev` - 运行全部测试：`npm test` - 运行单个测试：`npx vitest run src/modules/xxx/xxx.test.ts` - 数据库迁移：`npx prisma migrate dev` - 构建：`npm run build` # 项目结构说明 - `src/modules/`：按业务模块划分，每个模块下含 `router.ts`、`service.ts`、`repository.ts`、`schema.ts` - `src/utils/`：通用工具函数 - `src/middlewares/`：Express 中间件 - `tests/`：集成测试目录 # 行为要求 - 当需求描述不清晰时，先列出疑问，等待用户确认，不要擅自假设。 - 涉及数据删除或结构变更时，先输出影响范围说明，等用户确认后再执行。 - 运行时出现报错，先阅读日志和类型定义，再给出修复方案；不确定的根因要明确说明“不确定”。

这份配置的关键在于：每个条目都具体到可以直接操作。“禁止使用any”是一种可以被检查的规则，AI 在生成代码时可以通过类型自检来判断是否符合。而“按业务模块划分”则帮助 AI 在生成新模块时自动对齐目录结构。

3.2 前端组件与页面生成的模板

做前端开发的时候，最容易让 AI 自由发挥的地方是组件拆分和状态管理。如果缺乏约束，AI 经常会把所有交互写在一个组件里，或者把状态提升到不该提升的位置。所以我单独做了一个组件生成模板：

# /gen-component ## 需求 创建一个 {{componentName}} 组件，用于 {{usageScenario}}。 ## 技术约束 - 使用 React + TypeScript，函数组件风格。 - 样式方案：CSS Modules，样式文件与组件同目录。 - 状态管理：优先使用组件局部 state；需要跨组件共享时，提炼到最近的公共父组件。 - 数据请求：通过 `src/hooks/useRequest.ts` 提供的 `useRequest` 钩子完成。 ## 组件必须处理的三种状态 1. loading：展示骨架屏或 loading 文案 2. empty：展示空态组件 `EmptyState` 3. error：展示错误信息，并提供重试按钮 ## 交付要求 - 生成 `index.tsx`、`index.module.css`、`types.ts` 三个文件。 - 对外暴露的 props 使用 interface 定义并导出。 - 关键交互逻辑补充注释。

为什么特别强调“三种状态”？因为这是前端组件可用性的底线。AI 生成组件时默认只会处理“正常数据到达”的场景，loading、empty、error 往往被忽略。你把状态列出来，它才会逐一实现。从实际效果看，加了这一条之后，生成的组件基本不需要我再返工补状态。

3.3 数据仓库与后端服务模板

后端代码生成模板必须和具体框架绑定。我团队里用的后端命令模板，把 Express 路由、Service 层、Repository 层的模板写在一起，做成一个/gen-backend命令。

# /gen-backend ## 场景 新增后端模块 {{moduleName}}。 ## 输出文件与结构 按以下顺序生成： ### 1. repository.ts - 继承 `src/db/repository.ts` 中的 `BaseRepository<T>` - 每个方法返回 `Promise<T>` 或 `Promise<T[]>` - 所有查询输入必须经过 `schema.ts` 中的 zod 校验 ### 2. service.ts - 调用 repository 层，不直接操作数据库 - 业务错误抛 `ApiError(status, code, message)` - 记录关键操作日志，使用 `src/utils/logger.ts` ### 3. router.ts - 统一挂载到 `/api/{{moduleName}}` 路径 - 仅做参数校验和调用 service，不写业务逻辑 - 路由方法按 RESTful 风格：GET / POST / PUT / DELETE ### 4. schema.ts - 使用 zod 定义所有入参结构 - 每个接口的查询参数、路径参数、请求体逐一声明 ### 5. {{moduleName}}.test.ts - 至少覆盖： - 正常创建/读取/更新/删除流程 - 参数校验失败的异常分支 - 业务规则违反时的错误码断言 ## 通用要求 - 所有文件使用命名导出 - 每个函数携带 JSDoc，标注异常类型 - 生成结束后，简要说明每个文件的关键函数和测试命令

可能有人会觉得，五层结构太重了，写个小接口也要生成五个文件？我这里想说的是：这套模板更适合有一定规模、需要长期维护的项目。如果你的项目只是几十个接口的工具服务，可以合并 layers，把 repository 和 service 合写。模板的价值是随项目复杂度增长的，不建议在很小的项目里强行套用。

3.4 自动化测试与 CI 辅助模板

测试模板是我觉得回报率最高的一个类型。原因很简单：AI 写测试时如果没有模板，通常只会写“happy path”，也就是正常流程。一旦涉及异常分支、边界条件、并发场景，它几乎完全靠猜。

我用的测试生成命令长这样：

# /test-gen ## 测试对象 {{testTarget}} ## 测试框架 Vitest + @testing-library/react（如为前端组件） ## 测试用例要求 1. 正常流程：输入合法参数，断言正确返回。 2. 异常流程：参数缺失、类型错误，断言抛出对应错误码。 3. 边界情况：空数组、空字符串、超大数值、null/undefined。 4. 时序情况（如涉及）：请求超时、并发请求、重复提交。 5. 幂等性：同一个操作执行两次，结果一致（如适用）。 ## 断言风格 - 不使用 snapshots 作为唯一断言，明确断言具体字段值。 - 异步逻辑使用 `await expect(...).resolves.toEqual(...)`，不滥用 `setTimeout`。 - 测试名称按“should + 行为描述”格式命名。 ## 输出要求 - 输出测试文件的完整内容。 - 运行方式：`npx vitest run <文件路径>`。 - 如某个用例因测试环境限制无法实现，在注释里说明原因。

注意里面有一条“测试名称按 should + 行为描述格式命名”。这个看似小细节，实际作用很大。因为 Vitest/Jest 在输出失败信息时会显示测试名，如果名字是“test1”“case2”，报错后根本不知道是哪个场景挂了。用 should 句式能让每个用例的意图一目了然，排查效率提升非常明显。

4. 常见问题与排查经验

4.1 AI 不遵守模板中的规则

这是最让人头疼的问题。模板写了“禁止使用 any”，但 AI 生成的代码还是频繁出现any。我排查下来，有几个原因：

1. 规则被埋在长文本中间，AI 的注意力在长上下文中会衰减。
2. 规则太抽象，AI 没理解适用场景。
3. 规则与当前任务重叠度低，AI 默认它不相关。

解决办法：

• 把最重要的规则放到 CLAUDE.md 最前面，确保每轮对话首批加载的内容包含它。
• 给规则配上“正确 vs 错误”的示例。比如：

# 错误 const data: any = await fetchData(); # 正确 const data: unknown = await fetchData(); if (isValidData(data)) { // 类型收窄后再使用 }

• 在命令模板里显式重申核心规则。虽然 CLAUDE.md 里有，但命令文件里再说一遍也不嫌多，命令模板是更短、更聚焦的上下文，AI 在短上下文中的遵守率明显更高。

4.2 同一个命令在不同项目上表现不一致

命令模板如果写死在.claude/commands/下，但项目不同、技术栈不同，命令里的上下文可能不匹配。比如/gen-api在 Express 项目里好用，拿到 Fastify 项目上就会生成一堆不适配的代码。

我的做法是：把命令拆成两层——通用命令和项目定制部分。通用命令描述阶段、交付物类型，项目定制部分引用 CLAUDE.md 里的仓库约定。命令文件用类似这样的结构：

# /gen-api ## 执行标准 按 CLAUDE.md 中的“接口实现规范”执行。 ## 阶段 1. 先读取项目内已有模块的目录结构，总结现有代码风格。 2. 参照最近三个已实现模块的写法，输出新模块代码。 3. 输出后用 `npm run typecheck` 自查类型错误。

这里加了一个“读取项目内已有模块结构”的步骤。AI 具备足够的文件检索能力，让它在生成代码前先看一遍实际代码，比任何抽象描述都准确。这是我认为最实用的一条经验。

4.3 模板太长导致 AI 忽略细节

有些团队的 CLAUDE.md 写了一万多字，结果效果反而差。上下文太长之后，AI 其实难以消化全部信息，更别提逐条执行。

控制长度的经验值是：项目级 CLAUDE.md 控制在 800～1500 字左右，命令级文件控制在 300～600 字左右。超出部分放到单独文档中，需要时通过命令让 AI 去读取。

比如“接口文档规范”如果很长，不要直接写进 CLAUDE.md，而是放在docs/api-style.md，然后在 CLAUDE.md 里写：

# 接口文档 新增接口时，需阅读 `docs/api-style.md` 并遵循其中的格式。

这样既能保证上下文精简，又能让 AI 在相关任务中主动加载细节文档。实测下来，长篇文档放在 CLAUDE.md 里的遵守率，通常比这种“按需加载”方式低不少。

4.4 模板更新后 AI 还在用旧规则

这不是 AI 的问题，而是会话上下文没有刷新。Claude Code 在对话早期装载了 CLAUDE.md，如果中途你改了模板，当前会话里 AI 可能还沿用旧规则。

处理方式很直接：更新模板后，开一个全新会话再测试。或者主动说一句“请重新阅读项目根目录的 CLAUDE.md，并总结本次对话要遵守的规则”，让 AI 重新加载上下文。对于长期运行的任务，我也会在命令末尾加上“本次命令执行中若发现项目模板与当前生成方式不符，以项目内最近三个文件的风格为准”，给 AI 一个纠错出口。

4.5 代码语言与模板脱节

这是个容易被忽略的坑。命令模板里写的技术栈如果和项目里实际用的版本不同，AI 很容易按模板里的旧 API 生成代码。比如项目里已经用了 Next.js 14 的 App Router，但模板里写的是 Pages Router，那生成结果就非常灾难。

所以我建议在模板里少写“版本号+API 名称”，而是写“以项目内现有代码为参考”。另一个实用技巧是，每个命令模板开头设置一句话：

## 先做上下文对齐 在生成代码前，先查看 package.json、tsconfig.json、项目示例文件，确认依赖版本与技术选型。

这句话成本极低，但能避免一大堆因为版本偏差导致的问题。

5. 效率对比与工作流整合

5.1 用模板前后对比：同一个需求，差别有多大

我拿一个真实的项目案例做了对比。需求是：写一个用户列表接口，支持分页查询。

无模板时，AI 给出的代码大致结构是：一个路由函数、一个简单的分页查询、只有正常返回值，没有参数校验、没有异常测试。整个文件大概 60 行，看起来“能跑”，但放到团队代码库，你会发现缺少错误处理、缺少 zod 校验、没有 repository 层，代码风格也和其他模块对不上。

使用模板之后，AI 自动生成了 schema.ts、repository.ts、service.ts、router.ts、测试文件五个文件，每个文件结构与团队规范一致。错误码、日志、JSDoc 齐全，测试覆盖正常流程和参数异常。整段代码拿到仓库里基本可以直接跑，需要人工修改的部分很少。

这个对比不是说 AI 变聪明了，而是模板把“团队隐性知识”显式化了。AI 的能力一直都在，缺的是让它理解“什么叫符合团队标准”的上下文。模板解决的就是这个问题。

5.2 把模板接入日常协作流程

模板不应该只是个人工具，它更适合作为团队规范的一部分沉淀。操作上有几个推荐做法：

• 模板放入仓库并纳入 Code Review：.claude/目录和业务代码一样，需要维护、需要评审。
• 通过 MR/PR 管理模板变更：模板改动要写清楚原因，比如“新增前端 loading 态要求”“修正错误码定义”。
• 新人入职看模板就能了解代码规范：新同学进组之后，读一遍 CLAUDE.md 和命令模板，比翻十篇文档更快理解项目全貌。
• 定期审视模板使用率：如果某条命令一个月没人用，说明模板设计有问题，要么命令名不好记，要么它生成的代码不符合需求，需要迭代。

另外我建议每个团队都有一个/onboard命令，专门用于新环境或新成员初始化。它可以这样做：读取 CLAUDE.md、列出常用命令、给出第一个任务的推荐流程，让新人的前几次 AI 交互不出大错。

5.3 模板库的版本管理思路

随着模板数量增多，跨项目复用会成为诉求。比如你同时维护三四个前端项目，每个项目的组件模板大方向一致，只有细节不同。这时候不建议把同一套模板复制到每个仓库，因为每次更新都要同步好几次。

更合理的做法是：单独维护一个模板仓库，用脚本把模板同步到各个项目。具体做法可以简单一些，项目里放一个sync-templates.sh：

#!/bin/bash # 从模板仓库同步命令到当前项目 TEMPLATE_REPO=~/work/my-templates DEST_DIR=.claude cp -R "$TEMPLATE_REPO/commands/" "$DEST_DIR/commands/" cp -R "$TEMPLATE_REPO/templates/" "$DEST_DIR/templates/" echo "templates synced from $TEMPLATE_REPO"

然后每个项目保留自己的 CLAUDE.md，命令模板和代码模板统一从中心仓库同步。这样既保证了团队写法的统一，又保留了项目个性化配置的能力。

6. 模板的后续扩展与维护建议

写模板这件事，第一步永远比完美重要。你不必一开始就把 CLAUDE.md、命令、代码片段全做完，先从一个最常用的命令模板起步，用了之后根据团队反馈迭代。

我自己的习惯是，每隔两周检查一次模板库，看看哪些命令还在用、哪些已经没人用、有没有新的重复劳动场景值得做成模板。这种“从真实需求倒推模板设计”的做法，比坐在那里凭空设计要有效得多。

最后根据我个人的实际体会，再分享一个小技巧：在命令模板里加入“结束前自查”环节。比如在/gen-api命令的最后加上“依次检查：是否所有函数都写了 JSDoc？是否所有接口返回都符合统一结构？是否有合法异常抛出的类型覆盖？”这会让 AI 在交付前自我检查一遍，很多低级遗漏能在生成阶段就被拦截下来，省下大量返工时间。

模板本质上是对抗 AI 随机性的工具。你投入在模板上的每一行，都会体现在后续每一次生成的稳定性上。如果能把团队里那些“大家都知道但没人写下来的”规矩，逐一沉淀成模板，你的 Claude Code 工作流就算真正成型了。