企业官网建设流程全解析

我第一次意识到claude-code-templates这个概念的分量，是在一次把 CLAUDE.md 写进项目根目录之后。之前我一直把 Claude Code 当成聊天框使：想让它看文件就看文件，想让它改代码就改代码，每次都要重新讲解一遍项目背景。直到我把项目结构、技术栈、编码规范、常用命令全部沉淀成模板文件，才发现之前浪费了多少 token 和耐心。这篇内容不聊抽象概念，专门讲我实际用过、踩过坑、也尝到甜头的模板构建方法，适合正在用 Claude Code 但总觉得每次对话都要“重新调教”的人，也适合准备在团队里推行 AI 编程工作流的技术负责人。

1. 为什么说 Claude Code 的模板体系是项目的第二份需求文档

1.1 我最初的误区：把 AI 当一次性咨询

刚开始用 Claude Code 时，我的习惯是直接描述任务，比如“帮我看看 login 模块为什么登录超时”。结果它确实会看代码，但它不了解项目的整体结构，不了解登录接口的上下游依赖，更不了解我们团队约定俗成的错误处理方式。于是每一次排查都要先问“这个模块在哪”“用了什么框架”“日志在哪打”，来回拉扯好几轮。

更尴尬的是，对同一个问题，上午和下午问它，它给出的方案可能是两套。原因很简单：我没有给它一个稳定可复用的“上下文锚点”。Claude Code 本身是上下文窗口模型，它一次能读取的内容有限，如果你不主动把项目的关键规则、路径、约定写在固定位置，它就只能在零散对话里猜。

后来我才意识到，问题不在工具，在于我从来没用“模板”去约束它。所谓claude-code-templates，往小了说是几个 Markdown 文件，往大了说，是给 AI 编程助手准备的一份结构化需求文档，决定了它拿到任务时第一反应是“基于什么背景去理解”。

1.2 模板解决了我最头疼的三个问题

第一个问题是重复。过去每个新会话，我都得像复读机一样说明项目背景。写好模板后，Claude Code 启动时会自动读取项目根目录下的 CLAUDE.md，相当于每次开工前先“读一遍合同”。

第二个问题是行为不收敛。没有模板时，让它“优化接口”，它可能顺手帮你改了数据库字段；让它“写单元测试”，它可能先重构了被测代码。这不是它故意跑偏，而是因为它不知道你团队对“优化边界”的定义。模板把“哪些能做、哪些不能做、做之前先看什么”写清楚之后，行为立刻规矩很多。

第三个问题最隐蔽：接手别人的任务。我们组里有几个项目，代码风格差异很大。换一个人维护时，如果不看 CLAUDE.md，完全不知道这个项目的特殊约定。模板某种意义上成了项目的第二份需求文档，比散落在群聊里的“当时我说过要这样”靠谱得多。

1.3 模板体系到底包含哪几类

我理解的 Claude Code 模板，不是单一文件，而是一组结构化的 Markdown 文件，按职责可以分成四类：

刚开始不需要全部铺开，从第一类“项目规则模板”入手，后面再逐步加命令模板，这个顺序是最顺的。

2. CLAUDE.md 的分层设计：全局、项目、用户三级模板怎么分

2.1 全局模板：只放你不想对每个项目重复说明的东西

全局模板位于用户目录下的~/.claude/CLAUDE.md，它是 Claude Code 在任何项目里都会读取的个人配置。很多人的第一反应是“把所有东西都塞进去”，这是个陷阱。全局模板的目标是“跨项目稳定复用”，内容包括：你喜欢的代码风格、默认避免的写法、对某些已知问题的通用处理方式、输出语言的偏好。

举个例子。我在全局模板里写了这样几条：

• 默认使用 TypeScript 时优先用显式类型，不要滥用any
• 输出代码前先考虑边界情况和错误路径，不要只写 happy path
• 回答问题时先给出结论，再给分析过程
• 不要删除我代码里的注释，除非注释内容明显过时

这些规则不针对某个项目，但能有效把 Claude Code 的默认行为往我喜欢的方向拉。它不会占用多少上下文，却能让每次对话的“第一反应”正常很多。

2.2 项目模板：放架构、规范、关键路径

项目根目录的CLAUDE.md是重头戏，它决定了 AI 对这个项目理解得准不准。我建议至少覆盖六块内容：

• 技术栈说明：前端 React + Vite，后端 Node.js + Express，数据库 PostgreSQL，用 Prisma 操作
• 目录结构地图：哪一层的代码放在哪个目录，新增文件时应该遵循什么归类逻辑
• 常用命令：启动、测试、lint、构建、迁移数据库分别执行什么
• 架构约定：状态管理方案、接口层怎么组织、错误处理统一在哪个中间件做
• 本项目的特殊规则：例如“不要直接修改 utils/auth.ts，必须先看 auth 相关 README”“所有新增接口必须写 openapi 注释”
• 已知坑位：哪些模块容易出问题，处理时要注意什么

写模板时有一个心态特别重要：不要把 CLAUDE.md 写成代码仓库的说明书，要写成“给一个聪明的实习生看的入职手册”。它不需要背诵每个细节，但需要知道遇到问题时去哪看。

2.3 优先级与冲突处理

三级模板之间可能有重叠。拿代码风格来说，全局模板写了“优先显式类型”，项目模板可能写了“本项目的旧代码不使用泛型，新增代码可以逐步引入”。当两者冲突时，我的经验是：越具体的模板优先级越高，项目模板里的规则应覆盖全局模板。另外，在单次对话里直接追加的指令优先级最高，这也是 Claude Code 的常见行为逻辑。

为了避免冲突，我有一条铁律：全局模板里绝不写涉及项目具体文件、具体路径、具体框架的规则。只要守住这条，项目层级和全局层级的冲突就少一大半。真出现不一致时，也不用慌，在对话里明确说一句“以项目 CLAUDE.md 的规则为准”就能把方向拉回来。

2.4 一份可直接参考的 CLAUDE.md 最小骨架

下面是某项目中后期沉淀出的一个精简骨架，你可以按自己的项目改：

# 项目背景 这是一个内部权限管理平台，前端 React + Ant Design，后端 Express + Prisma + PostgreSQL。 # 常用命令 - 开发启动：npm run dev - 单测：npm run test:unit - 数据库迁移：npm run prisma:migrate # 目录结构 - src/api：接口定义与路由 - src/services：业务逻辑，禁止直接在路由里写业务 - src/db：Prisma schema 与数据库访问 # 架构约定 - 所有业务错误必须抛出 AppError，由 src/middleware/error.ts 统一处理 - 接口命名遵循 RESTful：资源名复数，动词交给 HTTP 方法 - 新增依赖前先搜索项目是否已有类似实现 # 本项目特殊规则 - 涉及 Auth 模块的改动，必须参考 docs/auth-design.md 后再动手 - 不要在 src/services/export.ts 里做文件导出以外的逻辑 # 已知坑位 - 迁移超时多半是本地数据量过大，先清掉开发库的过期数据再跑迁移 - prisma.raw 查询里的字符串拼接容易注入，不要绕过参数化

这段模板我实际用过，效果立竿见影。写完这几十行后，AI 对项目的理解至少提升了一个档次，很多“它怎么又在瞎猜”的抱怨都消失了。

3. 实测好用的 slash command 模板：5 个直接可抄的 Markdown 命令

3.1 为什么把高频任务固化成命令模板

Claude Code 支持自定义 slash command：你只要在~/.claude/commands/或项目.claude/commands/下放一个 Markdown 文件，文件名去掉.md就是命令名。比如放一个review.md，用它的时候只需要输入/review。

命令模板最大的价值，是让 AI 每次执行同一类任务时，都能按照一套固定的结构来。我们自己写代码时都知道，code review 应该看什么、git commit 信息应该怎么组织、排查 bug 应该先做什么后做什么，但这些经验藏在脑子里，AI 不知道。把流程写进命令模板后，等于把“最佳实践”固化成了可重复执行的流程。

3.2 /commit：生成符合规范的提交信息

这是我每天使用频率最高的模板。原来我提交代码时，要么自己憋半天写个“修复若干问题”，要么让 Claude 随便生成一段英文。有了固定模板后，它每次都会按统一的 Commit 规范输出。

# 文件：~/.claude/commands/commit.md 根据当前的 git diff 生成一条提交信息： 1. 先执行 git diff HEAD 查看变更 2. 识别变更类型：feat / fix / refactor / docs / test / chore 3. 提取核心变更内容，生成一句 summary，语言使用中文 4. 如果 diff 涉及多个模块，在正文中分组列出关键影响点 5. 不要出现“优化代码”“修复问题”这类过于泛化的描述 输出格式： <type>(<scope>): <summary> - 变更点1：... - 变更点2：... > 注意：如果 diff 超过 200 行，忽略样式类文件的细节，聚焦逻辑变更。

用这个模板的好处是，它每次提交前都会自己拉取最新 diff 而不是凭借记忆编造。你只需要扫一眼它列出的变更点是否准确，不满意可以再追加一句让它调整。

3.3 /review：把代码审查变成固定流程

写代码的人说自己不 review 是偷懒，但如果让 AI 也随便“扫一眼”，那跟没 review 差不多。我建议把审查维度写在模板里，逼它从固定角度检查，特别是安全性和边界条件这种容易被忽略的环节。

# 文件：~/.claude/commands/review.md 对当前分支相对 main 分支的改动进行代码审查： 1. 运行 git diff main...HEAD 获取变更列表 2. 先浏览变更文件清单，判断影响范围 3. 按以下维度逐一审查并输出结论： - 安全问题：是否有注入、越权、敏感信息泄露风险 - 错误处理：异常路径是否覆盖，失败后是否会造成脏数据 - 一致性：命名、错误码、响应结构与项目现有约定是否一致 - 性能：是否存在明显的 N+1、重复计算、内存泄漏 - 测试覆盖：新增逻辑是否有对应单测或集成测试 4. 每条建议必须附上具体文件路径和行号参考 5. 不输出空泛意见，例如“代码质量良好”要说明依据 输出格式： ## 变更概述 ## 问题列表（按严重程度排序，附文件:行号） ## 改善建议

实测下来，这个模板最大的帮助是“按维度审查”这一条。过去 AI 很容易只盯着一个文件看，忽略了调用方、数据结构变更、配置同步这些跨文件影响。固定维度后，它至少会从几个不同角度把 diff 扫一遍，虽然不能完全替代人工 review，但能提前拦住一批低级问题。

3.4 /debug：只读排查，先假设后验证

排查问题时最忌讳上来就改代码。我给 Claude 定的规矩是：先给出假设，再做实验验证，最后才谈修复。这样既不容易引入新问题，也方便你复核它的推理链路。

# 文件：~/.claude/commands/debug.md 你是调试助手。当前任务：定位并分析一个 bug 的根因。 第一步：先只读探索，不要修改任何文件。 第二步：根据现象，列出最多 3 个候选假设，按可能性排序。 第三步：针对每个假设，指出项目里哪些文件、日志、接口可以验证。 第四步：如果无法确定，提出需要哪些调试信息（日志、入参、复现步骤）。 输出格式： ## 现象 ## 候选假设（按概率排序） ## 每个假设的验证方法 ## 当前结论（未验证的假设不要写“已定位”）

这个模板的精髓是“不要直接改代码”。AI 在对话中容易显得很有把握，但实际上只是猜了一个还算合理的答案。限定它先验证，能显著减少“改一次跑一次”的循环。我遇到过好几次，它按假设排查后发现自己最初的判断错误，转而定位到真正的根因。

3.5 一个顺手的 /docs 模板：让文档跟代码同步

很多程序员不爱写文档，但让 AI 从模板生成文档的初稿并不难。我的/docs命令会针对指定文件生成 README 片段或接口说明，关键是要求它“只写代码中存在的内容，不要脑补”。这样一个模板配合/commit，基本能覆盖大多数日常场景。

# 文件：~/.claude/commands/docs.md 读取指定文件，生成或更新文档说明： 1. 只描述代码中真实存在的接口、参数、返回值，禁止脑补 2. 模块级文档写明职责边界和依赖关系 3. 函数级文档写明输入输出、异常情况 4. 如果文档已存在，标注出与代码不一致的地方

3.6 常用命令模板速查

命令模板不需要一次配齐，先从最痛的高频场景开始，比如 commit 和 review，用顺手了再加别的。

4. 模板落地防翻车清单：从上下文占用到团队协作的坑

4.1 CLAUDE.md 不是越厚越好

很多人写完模板会有一种“写得越全越安心”的错觉。但 Claude Code 每次启动都要读取模板内容，它是有上下文成本的。写满 500 行的 CLAUDE.md 可能把重点淹没，AI 真的记不住那么多规则，反而容易产生行为漂移。

我的经验是：核心规则控制在 40 行以内，只保留高频、强制性、容易违反的规则。那些低频但复杂的细节，比如数据库迁移的完整手册、某模块的详细设计文档，放到单独的文档里，在 CLAUDE.md 中写一句“如果需要了解模块 X 的细节，先读取 docs/xxx.md”。这样既保住了上下文空间，又留了按需加载的路径。

4.2 命令模板里的占位符问题

不同版本的 Claude Code 对命令模板里的变量支持略有差异，例如有些版本能用$ARGUMENTS接收跟在命令后面的参数，有些版本需要用更朴素的描述方式。我的建议是：不要在模板里依赖特定变量，而是把参数获取方式写清楚，比如“以$ARGUMENTS中的内容作为任务目标；如果没有参数，则使用 git diff 确定任务范围”。这样即使未来版本变化，模板依然能正常工作。

占位符另一个容易踩的坑是：在模板里写了$1、$2之类的位置参数，但实际调用时用户并没有传参，AI 会忽略占位符直接按模板执行，导致和预期不符。稳妥做法是：凡是必要信息，模板里都写明“如果没有提供，先向用户确认，不要自行假设”。

4.3 团队协作：模板必须有 owner

团队一起维护 CLAUDE.md 时，最常见的灾难是“人人往里加自己的偏好”。张三喜欢 4 空格缩进，李四说项目现在用 2 空格，王五又加了一句“推导类型比显式类型好”，最后模板前后矛盾，AI 的行为完全看运气。

我建议每个项目的 CLAUDE.md 明确一个 owner，其他人的修改统一走 PR 评审。这点和代码评审一样，不是不让提意见，而是避免直接往主分支塞未经评审的规则。团队协作时，全局模板是个人私有，项目模板才是团队资产，两者一定要分开。

4.4 我见过的最常见的错误写法

• 过度设限：写“禁止修改任何文件”，结果 AI 连正常任务都做不了。约束要具体到问题场景，而不是一刀切。
• 模糊指令：写“代码要优雅”，AI 无法量化“优雅”是什么，它只会随便选择它觉得优雅的方式。应该写“不新增无意义的中间函数，确保每个函数职责唯一”。
• 复制大段代码进模板：模板里放一段完整的历史代码，AI 容易模仿错误写法。模板应该放路径引用和要点说明，而不是整段代码。
• 从不更新：模板写完后三个月不动，项目结构已经重组了，CLAUDE.md 还写着旧目录。模板必须跟着项目演进，否则会误导 AI 更久。

4.5 我还会定期给模板做体检

每隔几周，我会有意识地观察一下哪些命令模板经常被触发，哪些从来没用过。经常用的继续留着，没用过的要么是场景消失了，要么是模板本身写得不好导致不好用。我会打开一个从未触发过的命令模板重读一遍，如果自己也觉得它鸡肋，就直接删掉。

CLAUDE.md 也一样。每次项目做大调整，比如换框架、改目录结构、引入新的架构约定，我都会有意识地更新对应条目。这个维护动作虽然看起来不起眼，但正是模板能持续产生价值的关键。

最后再分享一个我自己的习惯：新建项目时，我不会一上来就写一份完备的 CLAUDE.md，而是先搭一个 20 行的最小骨架，然后随着项目推进逐步补充。模板的价值是积累出来的，不是写出来的。从/commit和 CLAUDE.md 骨架开始，跑通第一个项目后，你自然能感受到这种工作流的分量。