企业官网建设流程全解析

如果你把 claude-code 当成一个普通的对话式代码助手，用上一周就会发现一个特别别扭的现象：每次新建会话，它都像失忆了一样。目录结构要重新解释，代码规范要重新教，测试命令要重新说，昨天刚纠正过的同一个问题，今天换个文件它又犯了。我最早整理 claude-code-templates 这个仓库，就是被这些重复劳动逼出来的——把项目背景、行为规则、高频任务的执行流程全部固化成模板，让 Claude Code 一进来就进入状态，而不是每次从零开始教。这个仓库解决的核心问题，简单说就是：把"每次都要重新说的东西"变成"启动时自动加载的东西、敲一下斜杠就能触发的东西"。适合所有日常重度使用 Claude Code 的开发者，尤其是同时维护多个项目、或者需要和团队共享同一套 AI 工作方式的人。

这套思路不复杂，但里面有几个很容易踩的坑。比如 CLAUDE.md 写太长导致上下文被撑爆、命令模板的指令太模糊导致输出风格飘忽不定、全局模板和项目模板互相打架等等。这篇文章我会把我实际整理这套模板库的过程、每一类模板的设计思路、以及踩过坑之后的修正方案全部写出来，你照着搭一套自己的模板体系应该没什么问题。

1. 这个模板仓库到底在整理什么：先看清问题的本质

1.1 模板不是提示词堆砌，而是"入职文档"

很多人第一次看到 claude-code-templates 这类仓库，第一反应是"这不就是一堆提示词吗"。这句话对了一半，但恰恰是没想清楚的那一半，导致很多人抄了模板也用不好。

Claude Code 本质上是一个通用能力很强的模型外壳，它有海量的编程知识，但缺少对你项目特有的知识。每次会话都是全新的上下文，它不记得你上周说的"这个项目的 service 层不允许直接操作数据库"。你可以在对话里教它一次、两次、十次，但它不会主动记住，下一次会话照样按自己最顺手的习惯来。这就像一个业务能力很强的资深工程师被外派到一个新团队，第一天没人给他看项目文档和代码规范，他写出来的东西大概率风格和团队完全不搭。

模板的作用就是补上这个缺口，而且要做的事只有两件：第一，注入上下文——让 AI 知道这个项目长什么样、用什么技术栈、目录怎么划分、测试怎么跑；第二，注入行为约束——让 AI 知道你希望它怎么干活，是先出方案再动手，还是直接改代码，代码审查要按什么维度检查，提交信息用什么格式。这两件事想清楚了，模板的内容基本就定了。想不清楚，堆再多华丽辞藻，模型该自由发挥还是自由发挥。

1.2 三类模板的划分：记忆型、命令型、流程型

我最初整理模板的时候尝试过按技术栈分、按场景分、按任务类型分，最后发现最实用的分法其实是按"加载方式"来分。因为不同加载方式的模板，对内容的要求完全不一样，混在一起写会非常别扭。

记忆型模板的核心是"自动"两个字。CLAUDE.md 放在项目根目录，每次会话启动都会自动读进上下文，所以适合放那些每次工作都必须知道的信息：项目一句话说明、常用命令、目录职责边界、强制规范。它要求精简，因为每次加载都占 token，塞太多低价值内容会拖慢响应速度，还会稀释真正重要的指令。

命令型模板的核心是"按需触发"。你敲/review、/commit、/test，它才会执行，相当于把高频任务封装成了快捷键。这类模板可以写得比 CLAUDE.md 更详细，因为它不是每次会话都加载，只有你明确调用时才消耗上下文。命令型模板特别适合那些步骤多、格式要求严格的任务——与其每次手打一遍审查清单，不如把清单固化成一个文件。

流程型模板更像一份操作手册。它描述的是"当一个复杂任务发生时，应该按什么顺序执行哪些环节"，比如新功能开发的完整流程、报错排查的定位路径。它可以是独立的 Markdown 文档，也可以直接内嵌到命令模板的正文里。我实际用下来的感觉是：流程型模板适合处理那些"一上来就动手容易翻车"的任务，它的价值在于强制 AI 在动手之前先做分析和规划。

2. 核心模板内容与设计要点拆解

2.1 CLAUDE.md 应该写什么、不写什么

CLAUDE.md 是整套模板体系的地基，也是最容易写烂的一份文件。我见过很多人把它写成一本项目百科，恨不得把每个模块都拆出来讲一遍，结果模型看了半天抓不住重点，而真正想约束的行为反而被淹没了。

一份好用的 CLAUDE.md 我建议只包含六块内容：项目的一句话说明、技术栈与关键依赖、常用开发命令、目录结构与职责边界、代码规范与禁止事项、运行与部署注意事项。每块都尽量短，短到不能再短。

# 项目：订单服务 ## 技术栈 - Node.js 20 + TypeScript + Express - PostgreSQL + Prisma ORM ## 常用命令 - 测试：npm run test - Lint：npm run lint - 类型检查：npm run typecheck ## 目录约定 - src/routes：只放路由定义 - src/services：业务逻辑 - src/repository：数据库访问层 ## 代码规范 - 新增功能必须附带单元测试 - 错误信息统一从 errors.ts 中引用 - 禁止在 service 层直接操作数据库

注意我写的是"禁止在 service 层直接操作数据库"，而不是"建议在 service 层保持业务逻辑纯净"。模型对"禁止"这种强约束词的遵循率，远高于"建议""尽量""最好"这类弱表述。这是我在对比多种写法之后确认的：一份 CLAUDE.md 里指令越明确，AI 的行为就越稳定；写得像散文，它就会把你的话当参考意见。

不写什么同样重要。版本号不用写，依赖升级就会过期；个人的任务待办不写，那是你自己的清单不是 AI 的；历史的变更记录不写，模型不需要知道三个月前重构过什么。每次会话都会加载 CLAUDE.md，所以你写的每一句话都在消耗上下文窗口。真正合理的状态是：这份文件压到一页以内，每一行都是不可删减的高价值信息。如果有些细节确实需要让 AI 知道但没必要常驻，可以用@README.md这种方式引用外部文件，让 Claude 在需要时再去读完整内容。

2.2 高频命令模板：从 /review 到 /commit

命令模板是 claude-code-templates 里数量最多、也最容易被拿来即用的一类。它的机制不复杂：在.claude/commands/或用户级~/.claude/commands/目录下放一个 Markdown 文件，文件名就是命令名，会话里敲/文件名就能触发。文件头部可以有一段 YAML 格式的 frontmatter，里面写description，命令列表里会显示这段说明。

以代码审查为例，一个能直接落地的/review命令长这样：

--- description: 对当前改动做代码审查，输出结构化评审意见 --- 你是一名严格的代码审查者。请执行以下步骤： 1. 读取当前分支的改动 diff。 2. 按以下维度逐项检查： - 逻辑正确性与边界条件 - 错误处理是否完整 - 测试覆盖是否到位 - 命名与代码风格是否符合项目约定 3. 输出格式： - 问题列表，按严重程度排序 - 每个问题给出具体位置或函数名 - 能直接修复的给出修改建议 - 最后给出结论：approve 或 request changes 注意：不要输出空洞的赞美，不要复述代码，只关注真正影响质量的问题。

这个模板里最值钱的是最后那句"负面约束"。我实测下来，如果你不告诉模型"不要复述代码"，它至少会花三分之一篇幅把代码重新讲一遍；加了这句之后，输出立马变得干净。很多命令模板失效，不是因为模型能力不够，而是因为模板里只有正向要求，没有负面约束。

再看/commit命令，它的价值在于把提交信息的格式统一起来：

--- description: 根据当前改动生成符合规范的提交信息 --- 根据当前 git diff 生成一条提交信息。 要求： - 遵循 Conventional Commits 格式：type(scope): summary - type 只在 feat / fix / refactor / docs / test / chore 中选择 - summary 使用祈使句，不超过 50 个字符 - 如果有破坏性变更，在正文中说明 BREAKING CHANGE 如果 diff 内容不足，先询问我要提交的范围。

设计命令模板时的关键点有两个。第一，正文开头要明确定义角色，比如"你是一名严格的代码审查者"，模型对角色设定的响应非常敏感。第二，步骤要分点列出，模型按清单执行的稳定性远高于让它读一段散文式的描述。一个命令模板写完后，在真实项目里跑一次，看输出和期望的差距，再反向修改措辞，这比凭空堆砌指令高效得多。

2.3 流程型模板：把"怎么做"固化成 SOP

流程型模板是我后来才补上的一类，起因是一次惨痛的教训。当时我让 Claude Code 直接实现一个涉及多模块的新功能，它跳过了需求分析，直接开始改核心文件，改到一半我发现它完全理解错了方向。问题不在模型能力，而在于我没有告诉它"遇到复杂任务应该先做什么、后做什么"。

一个可用的新功能开发流程模板大概是这样的：

你现在要协助实现一个新功能。请严格按下面的流程执行： 1. 复述你对需求的理解，列出涉及的文件和模块。 2. 评估影响面：这个改动会影响哪些现有功能？是否存在破坏性风险？ 3. 给出实现方案：包括要新增的文件、要修改的文件、数据结构变化。 4. 停下来向我确认，得到确认后再开始写代码。 5. 实现过程中，每完成一个子步骤，先自测再继续下一步。 6. 全部完成后，更新相关文档并运行测试。

这份流程里最重要的是第 4 步。如果你不强制模型在方案确认前停下来，它大概率会自作主张往下做，而一旦方向错了，损失的不只是时间，还可能引入一堆需要回滚的代码。模板的价值就是给 AI 戴上一道"刹车"，把它从"急于完成"的倾向拉回到"先规划再执行"的轨道上。调试类流程模板也同理，应该强制它先复现问题、看日志、定位根因，再谈修复，否则它就大概率上来就试一堆看似合理的方案。

3. 从零搭建自己的模板库：实操记录与配置要点

3.1 先设计仓库目录结构

模板仓库的目录结构我建议按"用途"划分，而不是按"项目"划分。这样做的原因是：命令模板和流程模板往往可以跨项目复用，只有 CLAUDE.md 这类记忆型模板和具体项目强相关。我最终采用的目录结构是这样的：

claude-code-templates/ ├── project/ │ ├── nodejs-ts.md │ ├── python-fastapi.md │ └── react-nextjs.md ├── commands/ │ ├── review.md │ ├── plan.md │ ├── commit.md │ └── test.md ├── workflows/ │ ├── feature-dev.md │ ├── debugging.md │ └── refactoring.md └── install.sh

project 目录下放的是不同技术栈的 CLAUDE.md 模板，每个文件对应一种项目脚手架，初始化新项目时直接复制改名为 CLAUDE.md 即可。commands 目录下是所有命令模板，文件名就是命令名，复制到项目的.claude/commands/或用户级~/.claude/commands/就能用。workflows 目录下的流程模板比较特殊，它们既可以作为独立文档供对话时引用，也可以把核心步骤内嵌进命令模板正文——我比较推荐后一种方式，因为内嵌后少一步手动搬运。

3.2 写一份可复用的 CLAUDE.md：逐段拆解

以 Node.js + TypeScript 项目为例，一份可复用的 CLAUDE.md 模板我会写成下面这样，然后每段解释为什么要这么写。

# 项目：<项目名称> ## 技术栈 - Node.js 20 + TypeScript + Express - PostgreSQL + Prisma ORM - 测试框架：Vitest ## 常用命令 - 启动开发服务：npm run dev - 运行测试：npm run test - 类型检查：npm run typecheck - Lint：npm run lint ## 目录约定 - src/routes：路由定义，不写业务逻辑 - src/services：业务逻辑，禁止直接操作数据库 - src/repository：数据库访问层，唯一的 Prisma 调用位置 ## 强制规范 - 所有新增业务功能必须附带单元测试 - 错误信息统一从 errors.ts 导出，禁止在业务代码里硬编码错误文案 - 提交信息遵循 Conventional Commits - 修改公共接口时，必须先列出调用方再进行变更 ## 禁止事项 - 禁止在 components 目录写业务逻辑 - 禁止绕过 repository 层直接使用 Prisma Client - 禁止在没有测试的情况下重构核心交易流程

"强制规范"和"禁止事项"我故意分成两块的。前者告诉 AI 应该主动做什么，后者明确划出红线。实际使用中，负面表述的红线往往比正面要求更有效，模型在生成代码时对"明确不可做"的约束的遵守率显著更高。目录约定部分，关键不是罗列目录结构，而是说明每个目录的职责边界，尤其是"什么不允许在这里出现"。AI 一旦知道了边界，就不会在路由文件里塞一堆业务逻辑。

这份模板里我没有写任何版本号，也没有写业务的详细说明。版本号会过期，业务细节应该在对话里临时提供或通过@README.md引用。模板只承载那些每时每刻都需要遵守的稳定规则，这是它保持长期有效的前提。

3.3 命令模板的 frontmatter 与正文写法

命令模板的创建步骤很简单，但有几个细节会影响最终效果。第一步是在.claude/commands/或~/.claude/commands/下新建一个.md文件。第二步写 frontmatter，至少要写description，因为命令菜单里显示的就是这段描述，它必须让人一眼看懂这个命令是干什么的。第三步写正文，正文前 1 到 3 行必须是最核心的指令，比如角色设定和任务目标，因为模型对长文本前部的注意力最强。第四步是在真实项目中测试，根据输出调整措辞。

--- description: 编写单元测试，确保覆盖核心逻辑和边界情况 --- 你是这个项目的测试工程师。为指定的模块或函数编写单元测试。 执行步骤： 1. 阅读被测代码，列出所有公共方法和主要逻辑分支。 2. 检查是否已有测试文件，确认测试框架和现有写法。 3. 编写测试，覆盖正常路径、边界输入、异常输入三类情况。 4. 运行测试并确认全部通过。 5. 输出测试文件和用例清单。 约束： - 不修改被测代码，除非发现明显的 bug，且修改后必须另行说明 - 不使用 any 逃逸类型检查 - 测试命名用 given_when_then 结构

frontmatter 里除了description，部分版本还支持限制工具或指定模型等元信息，但这个不在必需范围内，新手阶段只要写好 description 就够了。正文写作时有个容易被忽略的点：负向约束要单独放一段，不要混在步骤里。我早期的命令模板把"不要修改被测代码"写在步骤 3 的括号里，结果模型经常忽略它；单独成段之后，遵守率明显提升。

这里还有一个优先级问题：项目级.claude/commands/会覆盖用户级~/.claude/commands/的同名命令。所以我的实践是：用户级目录放所有项目通用的命令，比如 commit、review；项目级目录放那些和当前项目绑定的命令，比如特定框架的测试生成命令。这样可以避免同名冲突，也让模板在不同粒度上各自复用。

3.4 版本管理与跨项目复用

模板仓库本身应该用 git 管理，这一点毫无疑问。真正的问题是：怎么把模板安装进一个新项目。我最初是手动复制，后来觉得麻烦，写了一个 install.sh 脚本。

#!/usr/bin/env bash # 用法：./install.sh <project-type> <target-dir> # 示例：./install.sh nodejs-ts ./my-app PROJECT_TYPE=$1 TARGET_DIR=$2 if [ -z "$PROJECT_TYPE" ] || [ -z "$TARGET_DIR" ]; then echo "用法: ./install.sh <project-type> <target-dir>" exit 1 fi if [ ! -f "project/${PROJECT_TYPE}.md" ]; then echo "错误: 未找到 project/${PROJECT_TYPE}.md 模板" exit 1 fi # 安装 CLAUDE.md cp "project/${PROJECT_TYPE}.md" "${TARGET_DIR}/CLAUDE.md" # 安装命令模板 mkdir -p "${TARGET_DIR}/.claude/commands" cp commands/*.md "${TARGET_DIR}/.claude/commands/" echo "模板已安装到 ${TARGET_DIR}"

这个脚本的思路是：根据项目类型把对应的 CLAUDE.md 复制过去，然后把所有通用命令模板一次性复制到项目的.claude/commands/目录。理论上也可以支持符号链接，这样模板仓库更新后项目里的命令自动同步，但实际使用下来，链接方式在多人协作时容易造成困惑，复制方式虽然"笨"一点，但胜在隔离性好、行为可控。

团队协作时的最佳实践是：把模板仓库作为团队公共资产维护，CLAUDE.md 提交到项目的 git 仓库，这样所有人共享同一套 AI 行为约束。但要注意，个人偏好不要写进项目级 CLAUDE.md，比如"代码行宽 80 字符"这类个人习惯应该放到用户级~/.claude/CLAUDE.md。项目级只放团队共识，用户级放个人偏好，这个边界一旦混乱，模板的维护成本就会直线上升。

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

4.1 CLAUDE.md 没有生效

最典型的症状是：你明明在 CLAUDE.md 里写清楚了目录约定和命令，但 AI 的行为完全不像看过这份文件的样子。我建议按下面这个顺序排查。第一，确认文件名是CLAUDE.md全大写，而不是claude.md、Claude.md，大小写错了不会加载。第二，确认文件在项目根目录，不在 src 或子目录里——子目录也有 CLAUDE.md，但那是作用于该子目录的，不会在项目根会话里加载。第三，确认你是新开的会话，已经启动的会话不会读取后续修改的 CLAUDE.md。第四，也是最容易被忽略的：文件太长了，模型在长上下文里会把后面的内容遗忘或忽略。

排查时可以开一个新会话，直接问一句话："请列出 CLAUDE.md 中定义的项目目录约定。"如果它答不上来，说明文件没有被加载或内容没被重视；如果答得上来但行为不遵守，那问题就出在措辞太模糊上，需要改成强约束词。

4.2 模板输出风格不理想

命令模板触发成功了，但输出风格和预期差很远。比如让它做代码审查，它给你写了一篇温和的建议书，而不是带严重程度排序的问题清单。这通常是正文里只有要求没有格式导致的。模型对"输出格式"这种明确指令的遵循度很高，但对"认真审查""仔细检查"这种抽象要求会自由发挥。解决办法是：在模板里把输出格式写死，分点列出应该输出的结构，甚至可以给一个最小示例。另外，负面约束需要放在正文的独立段落，像"不要输出空洞的赞美""不要复述代码"这类话，放在步骤中间容易失效。

4.3 token 开销过大，响应变慢

CLAUDE.md 写得太长是响应变慢的主要原因。每句话都会随每次会话加载进上下文，写三千字的项目说明书，等于每次请求都带着三千字背景，模型处理时间自然变长。一个简单的衡量标准是：CLAUDE.md 超过一页纸（大概 1200 字）就要警惕。遇到这种问题，先把明显冗余的段落删掉，比如项目背景介绍、团队介绍、冗长的架构描述。再把那些"需要时才知道"的细节移到外部文档，用@README.md或其他引用方式按需加载。需要常驻这份文件的，永远只有项目目录约定、强制规范、禁止事项这类每次干活都离不开的信息。把不常用内容强行塞进 CLAUDE.md，是这套体系里性价比最低的操作。

4.4 全局模板与项目模板冲突

用户级~/.claude/CLAUDE.md、项目根目录的 CLAUDE.md、子目录的 CLAUDE.md 会叠加加载，子目录的规则优先级最高。一旦内容冲突，模型行为就会飘忽不定。比如用户级说"代码风格使用 StandardJS"，项目级 CLAUDE.md 里又写"使用 ESLint 的 Airbnb 配置"，模型每次遇到风格问题时就会在两个规则之间摇摆。

解决方式是在模板体系设计阶段就划分好职责。用户级只放不可协商的基本规则，比如"永远不要在未确认的情况下删除代码"这类底线；项目级放项目特有的规范；子目录级只放目录专属约束。每加一条规则之前，先想想这条规则会不会在另一层出现冲突。我在实际维护模板仓库时，定期会跑一遍所有模板，搜索互相矛盾的词条，比如不同层级同时出现风格、路径或命令规范的情况，及时清理。

最后再分享一个我自己维护这套模板库的小习惯。每当我发现 Claude Code 连续两次在同一个问题上犯错，我不会在对话里反复纠正它，而是停下手头的活，花十几分钟把这个教训固化成一条模板规则。比如它总是把没测过的代码直接提交，我就会在 commit 模板里加上"在生成提交信息之前，先确认测试已运行通过"这一条。使用模板的时间越长，这个仓库就越像一份"和 AI 一起工作的行为契约"——每一轮纠错都在修订契约，而不只是在单次对话里发脾气。这个思路，比模板本身更值得你借鉴。