企业官网建设流程全解析

我最早接触 claude-code 的时候，最头疼的不是它不会写代码，而是每次开新任务都要把项目背景、技术栈、代码规范、输出要求重新敲一遍。敲少了它理解不到位，敲多了又占上下文额度，来回改 prompt 的时间比改代码还长。后来我把 claude-code-templates 这套模板体系系统地整理出来了，才真正感觉这个工具“顺手了”。这篇文章把我踩过的坑、沉淀下来的模板结构、参数设计的思路全部整理出来，包括怎么组织模板目录、怎么写 CLAUDE.md、怎么做 Slash Command、模板里放什么变量，以及最容易翻车的几个反模式。适合正在用 claude-code 做事、但觉得每次对话都要重复交代需求的开发者参考。

1. 为什么我最终选择建立一套模板体系

1.1 没有模板时，我每天都在重复劳动

先说一个很实际的场景。我维护一个前后端分离的项目，后端是 FastAPI，前端是 React，代码库里既有老的 JavaScript 文件又有新的 TypeScript 文件，lint 规则也和社区默认的不太一样。最开始我用 claude-code 时，每个新任务都要先花几分钟把这一堆背景信息说清楚，然后它才能开始干活。更麻烦的是，遇到让我写测试、做 code review、查 bug 这类重复性极高的任务，每次都要重新组织语言，而且两次表达方式稍有不同，它给出的结果风格和深度也完全不一样，后处理成本很高。

后来我把关键要求整理成一份文档放进了项目根目录，情况有所改善，但仍然不够。因为“项目背景”和“本任务的具体约束”是两类东西，前者适合长期记忆，后者适合临时注入，混在一起反而互相干扰。这就是模板要解决的核心问题：把稳定不变的部分固化下来，把变化的部分用参数暴露出来，让每次调用都像填表格而不是写作文。

1.2 模板的真正价值是稳定性和可预期性

我用模板不只是为了省那几个 token。我真正在意的是稳定性。同样是让 claude-code 给一个函数写单测，没有模板时它可能有时先写 mock 再写断言，有时直接复制一段类似代码，有时还自作主张改了被测函数的签名，这种不确定性的维护成本远高于一点点 prompt 开销。

模板把行为边界定死了：输入什么、检查什么、输出什么结构、哪些东西禁止改动。这就像给一个很聪明但没有纪律的工程师发了一张任务工单，聪明依然聪明，但工作方式变得可预测了，结果就可控了。claude-code-templates 这个名字看似只是“一堆提示词文件”，实际操作中它是一套完整的任务执行协议，我在里面定义了步骤顺序、输出格式、自检清单，这些东西叠加起来之后，它产出的代码才真正具备可审查性。

1.3 这套方法适合谁

如果你只是偶尔用 claude-code 问几个语法问题，模板对你来说是过度设计。但凡是需要让它在同一个项目里持续干活——改需求、修 bug、补测试、做重构——我都强烈建议搭一套模板。尤其是团队场景下，模板就是“团队经验沉淀”的载体，新成员拿过来就能用，老成员也不用反复传授上下文。帮我省下来的时间，算下来每周大概有两三个小时，而且质量还比以前稳定。

2. 搭建模板库的目录结构与设计原则

2.1 目录布局：我最终采用的方案

模板这个东西，最忌讳的就是堆成一锅粥。我见过有人把所有模板放在一个 markdown 文件里，几百行下来，每次要同时加载到上下文，既浪费额度又容易互相污染。我实践下来比较稳妥的目录结构是这样：

claude-code-templates/ ├── CLAUDE.md # 项目级核心上下文，启动即加载 ├── commands/ # Slash Command 模板 │ ├── review.md │ ├── test.md │ ├── refactor.md │ └── fix.md ├── prompts/ # 长任务模板，按场景分类 │ ├── architecture.md │ ├── api-design.md │ └── migration.md ├── snippets/ # 可复用的片段，用于组合拼接 │ ├── code-style.md │ ├── output-format.md │ └── escape-hatch.md └── variables.json # 公共变量定义，运行时注入

这种分层逻辑很直白：CLAUDE.md 是常驻记忆，每次会话自动加载；commands 目录下是高频短任务，通过斜杠命令触发；prompts 目录是低频长任务，手动读取；snippets 是“积木”，可以被我拼到任意模板里。这样做的好处是每一个文件都短小精悍，加载成本低，维护时也不需要大海捞针。

2.2 模板设计的第一原则：单一职责

我踩过最深的坑是写“万能模板”。当时我想做一个覆盖“开发、测试、审查、修复”的超级模板，结果里面内容太多，claude-code 反而抓不住重点，每次回答都要在多个目标之间摇摆。后来我把所有模板全部拆成单一职责，一个模板只解决一种任务类型，效果立刻好了不少。

单一职责意味着一个模板内只包含四类信息：目标描述、输入格式、处理步骤、输出规范。比如 review 模板只关心代码审查，我不在里面写“如果需要可以顺便重构”这种话。每一个附加目标都会稀释主目标的执行质量，这是 prompt 工程里反复被验证的经验，放在 claude-code 的模板体系里同样是铁律。

2.3 上下文预算控制：模板不能喧宾夺主

claude-code 的上下文窗口不是无限的，模板本身会占用容量。实测来看，合理的模板总长度应该在 2000 token 左右，太长则留给真实代码和对话的额度就少了。我一般会用下面这个经验值来约束：

CLAUDE.md：不超过 1000 token 单条命令模板：不超过 400 token 长任务模板：不超过 800 token 片段：不超过 200 token

这个量级在多数场景下足够表达清楚约束，又不会把模型的注意力全部吸到“遵守格式”上面去。等到模板越攒越多，我会定期审查，把很少用的合并或删掉。

3. 核心模板实操拆解：可直接复制的写法和设计逻辑

3.1 项目级 CLAUDE.md：让模型自带项目常识

CLAUDE.md 是整个模板体系的地基，它相当于给 claude-code 一份“入职手册”。我见过很多人把这文件写成了代码库目录说明书，这是浪费。真正有效的是写“行为准则”和“常见坑位”，而不是信息堆砌。

我当前项目的 CLAUDE.md 结构大致是这样：

## 技术栈 - 后端：FastAPI + SQLAlchemy - 前端：React + TypeScript + Vite - 数据库：PostgreSQL ## 架构约定 - 业务逻辑写在 service 层，不要在 controller 里堆逻辑 - 数据库迁移使用 Alembic，禁止手动改表结构 - API 响应统一使用 { code, data, message } 封装 ## 风格要求 - Python 代码行宽 100，使用 black 格式化 - TypeScript 使用 strict 模式 ## 常见陷阱 - 不要修改 auth_service.py 的 token 校验函数 - 不要在前端直接拼接 SQL 字符串 - 删除数据必须走软删除，除非任务明确要求物理删除

这么写之后，我开新会话不再需要重复说明“我们项目用什么技术栈”了。它天然知道要保持风格一致、避免哪些雷区。模板化的关键不是把所有细节塞给模型，而是给它足够多的高信号约束。

3.2 Slash Command 模板：把高频行为固化成命令

commands 目录里的模板是配合斜杠命令使用的。在 claude-code 的配置中，命令行入口可以设置自定义斜杠命令，每个命令对应一个 markdown 文件。我常用的一个是 code review：

# 执行代码审查 请对当前选中的代码或指定的文件进行审查。 ## 审查步骤 1. 先阅读完整上下文，确认这段代码在整个模块中的位置 2. 按“可读性 → 正确性 → 性能 → 安全性”的顺序逐项审查 3. 每个问题必须标注严重级别：严重 / 建议 / 提问 ## 输出格式 | 级别 | 位置 | 问题描述 | 改进建议 | |------|------|----------|----------| | 建议 | 第X行 | ... | ... | ## 自检要求 - 确认没有忽略错误处理分支 - 确认没有凭空猜测不存在的变量 - 不修改原代码，只输出审查意见

这个模板有三个设计亮点：把审查维度固定下来防止漏项；用表格强制输出结构化结果方便我扫读；加了自检要求来抑制模型的过度自信。用斜杠命令触发之后，我只要贴上代码范围就能开始，非常省事。

3.3 测试生成模板：常见 prompt 模板

单测生成是我日常最依赖 claude-code 的场景之一。测试代码的特殊性在于，它必须和被测代码的行为严格对应，不能靠猜。我的模板长这样：

请为以下函数编写单元测试。 ## 被测函数 ```language [粘贴函数代码]

测试要求

• 使用 pytest 框架，遵循项目现有测试风格
• 覆盖：正常输入、边界输入、异常输入三类
• 每个测试函数只能有一个断言点
• 所有外部依赖必须 mock，不访问真实网络或数据库
• 测试命名格式：test_<函数名>_<场景>

输出结构

1. 简述测试思路（不超过100字）
2. 测试代码
3. 手动检查清单

这个模板的价值在于把“好的测试长什么样”提前定义清楚了。尤其是 mock 要求，如果没有这条，claude-code 极有可能会直接调用真实的第三方服务，导致测试不稳定，这个坑我踩过不止一次。 ### 3.4 技术方案设计模板：压住发散和过度设计 让 claude-code 做技术方案时，它有时候会给出非常宏大的设计，动不动引入新框架。对此我设计了 architecture.md 模板，核心是用“约束条件”把方案压在合理范围： ```markdown 请基于以下需求设计技术方案。 ## 需求背景 [在此填入具体需求] ## 硬性约束 - 不得引入新的基础设施服务 - 必须兼容现有代码的架构模式 - 改动文件数尽量少于 5 个 - 必须考虑失败回退方案 ## 方案输出要求 1. 一句话方案概述 2. 改动点列表（按“新增/修改/删除”分类） 3. 关键代码示意（不要完整实现） 4. 风险点与回退策略 ## 禁止事项 - 禁止为了“优雅”而重构无关代码 - 禁止提前优化没有出现的性能瓶颈

这个模板在团队里口碑很好，因为它的“禁止事项”直接对上了 claude-code 最容易被诟病的地方：过度工程。把“不要做什么”写清楚，比“要做什么”更重要，这一点在方案设计类任务中尤其明显。

3.5 片段设计：用变量让模板活起来

固定写死的模板用久了会发现一个问题：不同任务之间的差异没法处理。我的做法是把差异点抽成变量，模板中使用占位符来表示，运行时从 variables.json 读取并替换。

## 变更范围 {{scope}} ## 目标语言 / 框架 {{framework}} ## 特殊要求 {{special_requirements}}

对应的 variables.json 示例：

{ "scope": "仅修改 auth_service.py，不涉及其他文件", "framework": "FastAPI + SQLAlchemy", "special_requirements": "保持现有异常处理结构不变" }

这个做法的本质是模板与数据分离。模板管行为逻辑，变量管具体场景，两者解耦之后，同一个模板能覆盖一批相似任务，而不会因为写死某个参数导致无法复用。实际执行的时候，我写一个简单的脚本或者让 claude-code 自己读取 variables.json，然后逐项替换占位符，非常顺手。

4. 模板的工程化：拼接、版本管理与团队共享

4.1 从固定模板走向模块化拼接

单一模板写多了之后，我开始思考能不能像搭积木一样组合片段。这个需求来自一个观察：大多数任务其实是“基础步骤”加“领域差异”的组合。比如写 Python 工具的 prompt 和写前端组件的 prompt，都需要“先理解需求、再写代码、最后自检”的基本流程，差异只在语言规范、测试框架、常见陷阱这些地方。

于是我把片段进一步细化成三种：

base-process.md # 通用执行流程：理解 → 计划 → 执行 → 验证 code-style-py.md # Python 代码风格片段 code-style-ts.md # TypeScript 代码风格片段 review-checklist.md # 通用自检清单

组装规则是：任务模板 = base-process + 针对性语言片段 + 项目级特殊说明。这种模块化带来的最大好处是，当我发现某个行为模式需要调整时，只需要改一个片段，所有引用它的模板自动生效。不需要把同一个修正复制到十个不同的文件里去。

4.2 用 Git 管理模板的演进

模板也是代码，也会需要回顾和回滚。我用 Git 做模板管理，每次调整都写清楚 commit message。比如“feat(template): review 模板增加安全扫描维度”、“fix(template): 测试模板的 mock 说明不清晰，补充示例”。这样做有两个额外好处：一是团队协作时大家知道模板为什么变成现在这样，二是当你发现新改法不合适时，切回旧版本只需一条命令。

模板库的版本发布我还会打 tag，每个 tag 对应一个可用的稳定组合。由于 claude-code 的底层模型会迭代，某些 prompt 策略可能在模型更新后失效，这时候版本管理就显得格外有价值：我能准确地定位到“上次还好使”的模板集，减小排查范围。

4.3 团队共享模板的落地方式

团队里推广模板，最大的阻力不是技术而是习惯。我一个人用模板很舒服，不代表同事也愿意用。我的做法是先提供“预设项目模板”而不是强迫大家改习惯：

# 在项目根目录创建配置文件 $ git clone <模板仓库> .claude-templates $ claude-code --init --from .claude-templates

同时我会在 CLAUDE.md 里强调：模板只是默认约束，任何任务都可以显式覆盖。这个退出机制很重要，它让同事们感觉模板是在帮他们，而不是在束缚他们。用了一段时间后，大部分人都体会到了“不用重复交代背景”的甜头，就会主动维护模板了。

4.4 模板的变量注入与动态执行

变量注入这块我再往深里讲一点。当模板数量变多，手动填变量会非常累，我写了一个简单脚本辅助执行。核心思路是读取模板文件和变量表，然后做占位符替换：

import json import re import sys def render(template_path, variables_path): with open(template_path, 'r', encoding='utf-8') as f: template = f.read() with open(variables_path, 'r', encoding='utf-8') as f: variables = json.load(f) for key, value in variables.items(): template = re.sub(r'\{\{' + key + r'\}\}', value, template) return template if __name__ == '__main__': rendered = render(sys.argv[1], sys.argv[2]) print(rendered)

这个脚本本身不复杂，但它把“手动复制粘贴模板”变成了“一条命令生成定制 prompt”。实际使用中我还会结合 shell 别名，比如ct review auth_service.py就直接把审查模板和文件路径一起渲染好，然后复制到剪贴板里进入 claude-code 会话。

5. 常见问题与避坑指南

5.1 问题一：模板跟任务不匹配，反而干扰输出

这是我用得最多的情况：某次任务其实并不需要完整的测试模板，但我还是把整个模板贴了上去。结果 claude-code 被模板里的“测试命名格式”等约束带偏，把它不该管的东西都按模板执行了。我的结论是模板不是越全越好，符合任务粒度最重要。

为了控制这种问题，我给每个模板都加了“适用场景”前置说明。比如 review.md 开头就写明“本模板用于代码审查，不适合代码生成”。调用前先判断场景是否匹配，不匹配就选择更轻量的模板，或者干脆不用模板，直接对话。这个判断过程虽然多花十秒，但避免了后续反复纠错的时间，反而更省钱。

5.2 问题二：CLAUDE.md 内容过时或互相矛盾

模板体系维护到一定规模，必然会出现文件之间互相“打架”的情况。比如 CLAUDE.md 里说“禁止使用 TypeScript 的 any”，但某个命令模板又写了“类型不明确时可以先用 any 占位”。这种冲突会导致 claude-code 在同类场景下行为忽左忽右。

我的对策是定期做一次“模板一致性审查”，重点检查两类冲突：行为约束冲突（一个禁止、一个允许）和命名冲突（对同一个概念用了两种说法）。另外我还定了一条铁律：任何模板都不能覆盖 CLAUDE.md 中的硬性规定，如果确实需要临时放宽，必须写在任务描述里而不是模板里。这样维护职责就清晰了。

5.3 问题三：上下文被模板吞噬，真实信息反而无处安放

还有一个常见问题是用模板后上下文占用暴涨。有一次我同时加载了 CLAUDE.md、commands 里的两个模板、snippets 里的三个片段，结果实际代码和需求信息没有空间了。模型开始在模板要求的格式上过度发挥，回答内容却抓不住重点。

我现在给每个会话只保留与当前任务直接相关的模板层。基本原则是：CLAUDE.md 必带，commands 按需注入，snippets 最多加一个。同时我会在开新会话时做一次“上下文清理”：把上一个会话遗留的临时变量清掉，保持模板库的干净。这个习惯对长任务的稳定性帮助很大。

5.4 问题四：模型升级后，旧模板突然失效

Claude 的底层模型升级后，我遇到过几次“旧模板不好使了”的情况。最典型的是，之前用“请一步不差地按照以下步骤执行”这种强调指令，新模型反而会过度字面化执行，导致流程僵化。这说明 prompt 的措辞边际在变化，模板真的需要持续维护。

我的应急方案是维护一个简单的回归测试集：把同一段代码、同一份需求，用新旧模板各跑一次，比较输出质量的差别。模型升级后先跑一遍回归测试，再决定要不要调整模板措辞。这个方法成本很低但极其有效，能避免“模板库低调吃灰”的命运。

最后分享一个我在实际操作中的体会

从开始折腾 claude-code-templates 到现在，我最大的感触是：模板不是用来“约束 AI”的，而是用来“沉淀自己的思路”的。每次我把一个重复了两遍以上的任务写成模板时，都会被迫想清楚“我到底希望它按什么顺序做事、输出什么结构、规避什么雷区”，这个思考过程本身就是收获。如果你刚开始搭模板库，不要追求一步到位，先从最常做的两三个任务写起，跑通之后再加复杂度。等模板库能稳定支撑你一周的工作节奏时，你会明显感觉到同样的时间里，产出质量和效率都比之前上了至少一个台阶。