企业官网建设流程全解析

先说个实在的。Claude Code 这类终端里的 AI 编程助手，解决的是“靠编辑器插件写代码”和“动不动切网页去聊天”之间的割裂感，真正用它干活的人会承认：能不能发挥价值，一半看模型，另一半看你怎么把自己的项目交代清楚。只靠现场临时写 prompt，效果全凭运气。正常情况下，同样的功能，用模板组织过的任务描述比裸写 prompt 在稳定性、执行连续性、修改便捷性上都高一截，这也是“claude-code-templates”这个主题真正值得研究的地方。

这篇文章不聊虚的。我会直接把 Claude Code 模板体系拆开，从为什么需要模板、模板分哪几层、具体怎么写、怎么接入日常工作流，到实际踩坑记录和排查思路，一次性说清楚。适合已经把 Claude Code 装好但觉得“这玩意好像没那么聪明”的人，也适合准备把团队规范沉淀成配置文件、想统一工具行为的人。

1. 模板到底是什么，它解决什么问题

模板听起来像是“把一段提示词存下来反复用”，但真用起来远不止这个。Claude Code 是一个有状态的交互式终端工具，它有对话历史、有文件系统访问能力、能感知项目结构，还能通过 MCP 调用外部工具。你对它说的每一句话，其实都依赖于上下文窗口里塞了什么信息。模板的本质，是在这个上下文窗口里替你预先摆好一套“工作台布景”——包括角色定义、任务目标、约束条件、运行环境说明、输出格式要求、检查清单。

我观察下来，多数人用 Claude Code 的方式有两种极端。一种是什么都不配，上来就敲“帮我看看这个代码有什么问题”，结果模型对项目结构、技术栈、代码规范一无所知，只能靠猜。另一种是把什么都塞进 prompt，每次开会前重新粘贴一大段说明，累不累先不说，稍不注意就粘错了版本，模型越用越乱。

模板解决的就是这两个极端之间的平衡问题。它把该固定的东西固化下来——项目背景、工具链、编码规范、默认行为，把该变的留成参数——具体任务、文件路径、目标分支。这样做有三个直接好处：第一，上下文里的信息高度相关，模型不会在无关细节上浪费注意力；第二，行为可预期，同一类任务来回的结果差异不会太大；第三，沉淀下来的模板可以逐渐迭代，今天发现一个坑，改一次模板，以后所有项目都受益。

这里要提一处容易被忽略的设计。Claude Code 在启动时会自动加载项目内的说明文件，约定的叫法是CLAUDE.md，同时社区也在推进AGENTS.md之类的通用上下文规范。这个文件本质上就是“全局常驻模板”——它不需要你每次手动粘贴，工具启动时自动进入上下文。很多人不知道这个机制存在，于是拿着临时 prompt 去硬怼模型，这是第一道认知门槛。想用好 Claude Code，第一件事不是写命令，而是把CLAUDE.md写好。

2. 一套可落地的模板体系该怎么搭

我把自己在项目里稳定使用的模板体系分成四层，各管一摊，互相不抢活。

第一层是项目级常驻层，就是CLAUDE.md。它负责回答“这个项目是什么、怎么运行、遵循什么约定”。里面我固定写五块内容：项目简介与技术栈、常用命令（启动、测试、构建、部署）、代码结构约定、风格约定、常见注意事项。这一层是地基，占上下文大约两三百行 markdown，但它让模型在接下来的所有对话里都有一个稳定的坐标系。

第二层是命令层，也就是 Claude Code 的斜杠命令。它放在.claude/commands/目录下，一个文件一个命令，比如/review、/test、/commit。斜杠命令适合承载“高频重复、流程固定”的任务。比如我想做代码审查，直接敲/review src/utils/auth.ts，命令文件里定义好审查的维度、输出格式、严重程度分级，模型就会照着执行。这一层最厉害的地方在于——每次执行都加载同一份模板，结果不会“失忆”。

第三层是角色层，适合放在交互期通过/role或者系统提示词注入。角色层解决的是“以什么身份、站在什么立场干活”的问题。比如让 Claude Code 当“资深安全工程师”审查代码，和让它当“追求性能的开发者”做优化，关注点天然不同。角色不必单独写文件，可以用命令文件里的 frontmatter 属性来定义，也可以让模板文件开头直接写“你是一位...”，关键是保持每次身份一致，别让模型飘忽不定。

第四层是工具层，指的是 MCP Server 里给 Claude Code 配的各类能力。工具层本身不算模板，但工具怎么被调用、什么时候被调用，应该写进前面的模板里约束。举个例子，如果你配了数据库 Schema 的 MCP，模板里就要写明“涉及数据表变化时优先查 Schema 再动手”，避免模型放飞自我直接猜字段名。

搭建顺序也有讲究。别一上来就写一堆花哨的斜杠命令，先把CLAUDE.md弄扎实。这个文件写得好，后面三层都会省力很多——因为命令文件里不需要再重复介绍项目背景，直接引用“按项目约定来处理”即可，上下文占用自然就降下来了。

2.1 CLAUDE.md 里到底写什么，怎么写

很多人把CLAUDE.md写成“说明文档”，这是一个大坑。它要的不是全面，而是“高杠杆”——模型每次决策前最需要的那些信息。

我会按下面的结构组织，基本稳定不动：

• 项目一句话介绍，别超过三行，让模型快速定位这是什么领域的事。
• 技术栈清单，框架、语言版本、包管理器、关键依赖，越简明越好。这里注意写版本，不然模型可能按自己的知识默认生成旧版 API。
• 本地开发命令，依优先级排列：起服务、跑测试、lint、构建。每条命令要给出“可直接复制执行”的原文。
• 目录结构说明，不需要完整树，只需要标出“哪里是核心源码”“哪里是配置”“哪里容易踩坑”。
• 编码风格约定，比如“接口返回统一用{ code, data, message }”“函数命名用动词开头”“禁止在业务代码里直接写 SQL”。
• 已知注意事项，写上这个项目里“雷区”，比如“不要动scripts/migration.ts的顺序，依赖链很脆”“底层网络库替换过两版，老代码里的坑很多”。

关于篇幅，我的经验是控制在 200 到 400 行之间。太短交代不清楚，太长了反而稀释重点。模型对上下文前段的关注度明显更高，把最重要的约定放在文件前三分之一，效果最好。

会把CLAUDE.md存储在项目根目录，别放子目录。还要注意一点，尽量写“要做什么”而不是“不要做什么”的绝对禁止列表。只写负面约束，模型容易陷入“怕犯错不敢动”的行为模式。想表达“不要直接改公共组件的签名”，不如写成“如果涉及公共组件签名变更，先列出所有调用方并评估影响”。同样的约束，用正面行动描述，模型执行得更靠谱。

2.2 斜杠命令的设计原则与存放规范

斜杠命令是模板体系里最容易见效的部分，也是最容易写废的部分。核心原则是“命令只做一件事，流程闭环，输出可验证”。

先看存放位置，Claude Code 约定在.claude/commands/下放 markdown 文件，文件名就是命令名。一颗星级别的例子：.claude/commands/review.md，这样在对话里输入/review就能触发。

命令文件内部用 YAML frontmatter 定义元信息，正文写执行步骤。我常用的几个字段包括description（给模型看的命令说明）、argument-hint（提示用户需要传什么参数）、allowed-tools（限制这个命令允许调用的工具）、model（指定模型名）。这些字段的存在不光是约束，更是在减少模型自主发挥的空间。

正文部分，我按“角色设定 → 任务目标 → 输入获取 → 执行流程 → 输出格式 → 验收校验”来组织。角色设定写清楚“你是一名高级代码审查者，关注正确性、安全性、性能与可维护性”，任务目标写得具体但不死板，执行流程最好带序号和判断分支——比如“如果发现错误，先定位最小复现范围，再找根因，不要停在表面结论”。输出格式固定成 markdown 结构，比如“问题清单：严重程度 / 文件位置 / 问题描述 / 修复建议 / 预估改动范围”五列。这能让模型输出稳定，也方便你直接把它还原成工作任务列表。

参数处理是很多人忽视的细节。斜杠命令天然支持$ARGUMENTS这个变量，它会把用户输入“/review src/utils/auth.ts”后面的路径传给模板。但只传文件名不够，最好是模板里约定“如果传入了文件路径，优先审查该路径；如果没有传入，自动分析 git diff 或最近变更的源文件”。这样命令就有了默认行为，不会因为用户少打参数就报错或泛泛而谈。

如果你为团队维护这套模板，命名时务必用动词开头：/review、/test、/refactor、/explain、/commit、/release。动词开头的好处是命令意图清楚，用户不需要记住每个命令的完整拼写和内部逻辑。

3. 典型模板逐段拆解

光说设计原则不够，我直接把几个已经在用的模板写出来，逐段解释为什么这么写。你可以直接复制回去改成自己的项目版本。

3.1 代码审查模板：让 AI 从“看过”变成“看出问题”

先看代码审查这个场景最典型的问题——模型看完代码给出的建议经常是“泛泛而谈的常识”，什么“建议增加类型定义”“建议提取公共函数”，放在哪个项目都能用。真正有价值的审查要求模型先理解项目约束，再基于约束找矛盾。我的/review命令就是这么写的：

模板开头三行先把项目环境钉死：

你是本仓库的一名资深代码审查者。 你熟悉仓库的架构约定与开发规范，任何建议必须符合约定的目录结构、命名规则与 API 设计惯例。 本次审查重点：正确性、边界条件、错误处理、兼容性、安全隐患。

这三个句子的信息量很大。第一个是身份锚，防止模型降级成“通用编程助手”；第二个是上下文钩子，它会让模型主动去读CLAUDE.md里的项目约定，而不是只盯着用户给的单个文件；第三个是焦点清单，把审查范围从“无限”缩成“五个具体维度”。

接下来的执行流程我写得很细，分四步：

1. 先读取传入文件及其直接依赖，如有必要读相关测试文件。
2. 对比代码与项目约定的风格/架构要求，列出不一致的项。
3. 针对每个不一致项判断严重级别：致命（会导致线上故障或安全问题）、较大（会引入隐蔽 bug 或严重影响可维护性）、一般（风格、冗余、命名建议）。
4. 给出“需要处理的”和“可选的”两组合并，明确指出哪些改动会影响接口兼容性。

输出格式是模板里最重要的部分。我强制它用一个 markdown 表格，每行一个问题，列头是“严重程度、文件: 行号、风险类别、问题说明、修复建议、预估影响范围”。表格形式比段落更容易阅读，也方便你直接复制到 issue 里。最后一行总是“总体评价”加“建议下一步动作”，让收尾有结论。

这套模板跑了几十次以后我自己的体会是：想让模型审查出真问题，关键不在“请仔细审查”，而在给它“目标维度”和“输出结构”。没有维度，它只会流于表面；没有结构，它容易写一堆没说清楚的话。

3.2 测试生成模板：先给行为，再写用例

自动写测试是很多人对 Claude Code 的期待，但裸写 prompt 生成出来的测试经常有两个毛病：要么只覆盖 happy path，要么测试断言里直接抄了实现逻辑，导致测试代码变成“实现代码的一面镜子”，什么都证明不了。

我的/test模板从行为出发，要求模型先列行为清单再写用例。核心流程是：

先要求模型读取被测文件，梳理出“对外暴露的行为”。这个梳理必须带上输入条件、预期输出、边界值和异常分支。举例，一个文件读取函数，行为清单至少要覆盖文件不存在、文件为空、编码不对、超大文件、正常命中五个场景。模型不列清单就直接写测试，多半会漏掉至少一半。

第二步是要求模型按项目现有测试框架来生成用例，不引入新依赖。该用 jest 就用 jest，该用 pytest 就用 pytest，不要自作主张换工具。模板里我会写“优先复用项目已有的测试工具函数和工厂”，这句话能很大程度上确保新测试符合项目风格。

第三步是输出格式约束。我要求它生成两样东西：一个表格（测试名/场景描述/对应行为/预期断言），再加一段可直接套用的测试代码。表格是给人看的，方便人工补漏；代码是给机器跑的，可以直接落地。这一步逼着模型先想清楚再动手，比直接让它写代码靠谱得多。

踩过一次坑要提醒：对于疑似 bug 的代码，模型自动生成的测试有时会把 bug 当成“预期行为”来断言。要规避就得在模板最后加一句“如果测试用例发现被测代码行为与直觉或业务预期不符，单独开一节说明存疑点，不要自行决定正确行为”。这句话看起来简单，但能挡住不少自作主张的“修正”。

3.3 commit 信息模板：约束提交习惯

换到另一个实用场景——/commit命令。这个命令要解决的是“提交信息混乱、类型不统一”的团队惯性问题。模板设计很简单，只有一个核心：让模型先看git diff --stat和git diff，再做分类。

分类规则我直接写在模板里：feat 表示新增功能，fix 表示修 bug，refactor 表示重构不改行为，test 表示补测试，docs 表示文档。如果一次 diff 涉及多个类型，以占比最高的为准，其余的在正文列举。提交信息的结构是：标题一行 + 正文若干行，正文用“做了什么”“为什么做”“影响范围”三个小标题组织。

这个模板的价值看起来只在规范性，用久了你会发现它其实在倒逼你“小步提交”。因为一旦改动跨域太大，模板会提示“本次改动跨多个类型，建议拆分为多个提交”，这句话每次执行都像一个温和的提醒。长期下来，能明显感觉到提交粒度变得更可控，review 起来也轻松许多。

有一点要说明，涉及敏感信息的 diff（比如密钥误提交）模型不会自动识别，团队应该在模板里额外指定黑名单路径，让模型遇到这类文件时跳过分析并直接告警。

4. 把模板接入真实工作流

模板写出来不接入工作流就是收藏夹里的摆设。这一节讲实际接入时的三个关键位置：初始化阶段、执行阶段、事后回溯阶段。

初始化阶段要解决的问题是“每个项目都得重新写一遍模板太累”。我自己的做法是建一个模板仓库，目录结构如下：

claude-code-templates/ ├── base/ │ └── CLAUDE.md ├── commands/ │ ├── review.md │ ├── test.md │ └── commit.md └── install.sh

install.sh做的事情很简单：把基础模板文件复制到目标项目的.claude/目录，并根据项目类型追加技术栈专属内容。例如项目是 Node.js 应用，就追加一段“node 版本管理、包管理器、构建脚本目录”的说明；是 Python service，就加虚拟环境路径和 pytest 配置。这个脚本不值得写得多优雅，能用就行，关键是把“手动粘贴”变成“一条命令”。

执行阶段要处理的是“什么时候让模型看模板”。斜杠命令的优势是即时加载，CLAUDE.md的优势是常驻记忆。它们的配合逻辑是这样的：CLAUDE.md管“通用背景”，斜杠命令管“单项任务目标”。比如/review执行时，上下文里既有CLAUDE.md的项目背景，又有命令模板的审查流程，模型就有足够信息做出有质量的判断。

还有一个很容易踩的坑是 .gitignore。.claude/commands/里有些文件如果涉及团队内部规范，你可能不想每一条都进公共仓库，但CLAUDE.md又是应该进仓库的，因为每个 clone 这个项目的人都需要同样的上下文。我的处理是：CLAUDE.md进版本库，个人实验性的命令模板放在~/.claude/commands/，不进仓库，团队的共享命令放在.claude/commands/并进版本库。这样既保留了团队一致性，又不耽误个人扩展。

执行完之后，回溯阶段是模板迭代的真相时刻。我每次跑完一个命令会关注三个点：这次的报告有没有踩中真实问题？有没有哪个步骤让模型理解跑偏了？生成结果里有没有重复出现的“废话建议”？如果连续三次同类任务里模型都在生成无意义内容，那就是模板的问题——要么任务描述太宽泛，要么输出结构约束不明，需要立刻改。

举一个真实的迭代例子。我最早给/review命令写的输出结构只有“问题列表”，结果模型每次都会写一堆“代码整体质量不错，可维护性尚可”之类的空话。后来我把输出格式改成结构化表格 + “总体评价”只能写一句，这句的格式必须是“是否达到合入标准 + 主要风险 + 建议动作”，废话立刻减少了一半。模板不是一次写成的，是拿真实项目“喂”出来的。

5. 常见问题与排查技巧实录

下面这些坑我不止一次看到别人踩，自己也都踩过一遍，直接按问题现象、排查思路、解决方式来列，方便你对照排查。

问题：模型完全无视 CLAUDE.md 里的约定

这个优先级最高。正常情况模型应该优先遵循项目说明文件，但有些时候它还是“按自己的常识”干活，比如你明明写死“用 pnpm”，它还会在命令里建议 npm。

排查思路：第一，确认文件位置是否在项目根目录，文件名是否拼写准确，Claude Code 认的是根目录下的约定文件。第二，确认表述是“清晰的指令”还是“模糊的建议”，比如“尽量用 pnpm”就比“统一使用 pnpm 作为包管理器”弱很多——前者给了模型可选余地，后者是明确约束。第三，看上下文有没有被挤掉，如果之前对话已经聊了太长，早期的指令优先级会被模型降低，这种时候直接开新会话，或者在模板里加一句“在生成任何命令之前，先确认当前项目的包管理器声明”。

解决模板写法上的经验是：把关键决定写进“行动前置条件”，让模型先确认再行动，比单纯描述规则更可靠。

问题：斜杠命令不生效，显示找不到命令

最常见的三个原因：文件扩展名不对（必须是.md，写成.txt肯定不行），目录路径不对（用户级命令放用户目录，项目级命令放.claude/commands/，不要两个混淆），以及文件名带空格或者大小写与触发名不一致。

排查方式很简单，执行/help看一下可用命令列表里有没有目标命令。如果根本没列出，说明文件路径或命名有问题；如果列出了但执行时报错，多半是模板内部有语法问题，比如 frontmatter 里的allowed-tools写错了工具名，也会导致加载失败。

问题：上下文太长，模型越聊越笨

这个属于使用习惯问题。Claude Code 的上下文窗口有限，对话轮次一多，早期信息会被压缩或遗忘。模板能帮忙缓解，但治不了根。

我的处理习惯是：如果当前任务链已经超过三四轮，就先开新会话。开新会话并不丢上下文，因为CLAUDE.md和斜杠命令会重新加载，模型的“记忆”反而比挤在长对话里清晰。模板的价值在这里再次体现——项目上下文不依赖对话历史，所以每次新会话模型都能迅速回到正确的上下文状态。

问题：模板生成的结果模板化严重，千篇一律

这个说法听起来有点矛盾，模板生成了模板化内容——但这是真实存在的。模型如果被约束得过死，输出会失去针对性，比如审查报告永远写“建议补充错误处理”，却不说清楚是在哪个文件哪个函数里怎么补。

解决方式是在模板里加“针对性”要求。我在 review 模板输出格式后面加了一行：“每条建议必须给出具体到函数/类/行的定位，禁止泛泛而谈，如果做不到就回溯代码再查一遍。”一旦模型知道“泛泛而谈会被打回”，它就会主动深入代码找细节。模板约束的是结构和流程，但内容本身必须是从当前项目代码里长出来的，不能是结构漂亮的空壳。

问题：模型生成了设计模式或依赖，但项目里根本没用过

例如你明明在写一个简单的工具脚本，模型却给代码套了一个工厂模式加依赖注入，因为它觉得这看起来“更专业”。这个问题的根因是模板里缺少“技术约束边界”。

我的解决方式是在CLAUDE.md里加一节“技术原则”，比如“优先使用标准库”“不要引入新的依赖除非有明确必要的理由”“保持简单直接，不做过度设计”。这几句话成本很低，但能极大地约束模型的放飞程度。模型并不是天生爱炫技，它只是没有被告知这个项目的工程师文化是什么。

6. 个人经验收尾

我在实际使用中发现，模板体系和“能不能用好 Claude Code”几乎强相关。没有模板的时候，它像一个聪明但不知道项目背景的实习生——你问什么它答什么，但答得总是隔着一层；有了模板之后，它更像一个熟悉仓库的老师傅，你交代一个任务，它知道先看哪、怎么写、输出什么格式，还会主动按约定来。

几个让我印象深刻的收益，梳理一遍也算给这篇文章做个沉淀：一是审查代码的误报率下降明显，模型开始关注真实业务逻辑里的边界问题，而不是只会说“建议加类型”；二是新成员接手项目时，把CLAUDE.md和命令模板发过去，基本不用嘴对嘴解释太多，工具本身就把项目的上下文带上了；三是长期维护的模板每一次微调都在给后续所有会话“攒经验”，这是裸 prompt 给不了的复利。

最后分享一个小技巧，在CLAUDE.md末尾加一个“ChangeLog”小节，记录这个文件每一次增删改的原因。这样过一个月回看，你能清楚地知道哪些模板约束被证明有效、哪些被删掉了。这比在脑内凭感觉迭代更踏实。模板系统不是越写越多，而是越写越准，去掉无效约束和添加有效约束同等重要。