企业官网建设流程全解析

刚接触Claude Code那阵子，我其实挺不以为然的。这不就是个挂在终端里的对话窗口吗？无非能把代码库读完、能帮你跑命令而已。真正让我改观的，是某次新开一个会话准备继续开发时，发现自己又在重复粘贴同样的项目背景、技术栈说明、测试命令、编码规范……差不多的文字，这个月我已经粘贴了七八次。那一刻我才意识到，Claude Code这个工具，真正的分水岭不在“对话能力”，而在你有没有一套属于自己的 claude-code-templates。

模板化之后的效果是很直接的：原来一个新会话从零进入状态，至少得花掉两三千token去“交底”，而且对话一长，上下文稀释，它还是会忘记前面交代过的约定。现在打开终端，Claude自动就把项目背景、技术规范、工具链逻辑全部加载好了，不用你多说一个字，它就知道项目是干什么的、代码往哪放、测试怎么跑、commit格式长什么样。那种感觉，相当于从“每次面试一个聪明但没有记忆的新人”，变成了“手下有一个看过你全部文档、完全清楚你规矩的老员工”。

这篇文章我不打算讲怎么装Claude Code，那属于官方README的范围。我想记录的是更实用的部分：一套完整的、可复用的、能直接抄作业的模板体系该怎么搭，包含CLAUDE.md该怎么写、斜杠命令怎么设计、hooks怎么挂、子代理怎么分，以及我实测踩过的各种坑。适合已经用Claude Code跑过基础对话、觉得它“还行但不够顺手”的开发者。

1. 模板到底是什么：从裸对话到可复用工作流的转变

1.1 我的低效现状：每次对话都在重复交底

先说个真实场景。我的一个中型全栈项目，技术栈是Next.js + TypeScript + Prisma + PostgreSQL，测试用Jest，Lint用ESLint，代码规范里有一堆约定——比如组件目录用kebab-case、数据库表名用snake_case、commit message必须符合Conventional Commits。

在没有模板之前，我每次打开一个新终端窗口启动Claude Code，都要在第一条消息里把这些写一遍。起初还好，后来项目大了，光项目结构说明就能写一大堆。更要命的是，Claude Code虽然是带记忆的，但对话窗口一长，它还是会“忘事儿”——不是它傻，是上下文窗口塞满了修改记录、报错信息，早先交代的规范被挤出去了。

于是我不得不把“项目记忆”压缩成一段核心说明，在每次新会话开头重新粘贴。这就是最原始的“模板”，但效率太低了。

1.2 模板化的本质：把“上下文”和“流程”固化成资产

后来我开始研究Claude Code提供的模板能力，才意识到我需要的不是“一段能复制的文字”，而是一整套系统。简单说，claude-code-templates的核心理义是：

• 把上下文资产化：项目背景、技术栈、规范这些“一次写清、反复使用”的信息，固化到自动加载的文件里，不用再每次手动给。
• 把流程系统化：高频任务（写commit、做code review、生成接口文档、补测试）固化成一条条斜杠命令，一条命令就是一个标准作业流程。
• 把自动化落在关键节点上：通过hooks机制，让Claude在执行某些操作前后自动触发检查，省去人工盯细节。

打个比方：你请了个实习生，能力很强但对你这个项目一无所知。你每天都要花二十分钟给他讲背景、讲规矩、布置任务。模板系统就是给这个实习生准备的一份《岗位手册》外加一套《标准作业流程》。手册他每天自动读一遍，布置任务不用你说话——你只需要敲一下命令按钮，他看完SOP就开始干活。你省下来的，是每天重复的“交底时间”。

1.3 模板解决的典型场景清单

我实际使用下来，模板体系对下面这些场景的价值最大：

• 新项目初始化：说完需求，模板自动带入技术栈约定和目录结构，开局不用从零解释。
• 多项目并行切换：切到A项目，Claude自动加载A的规范；切到B项目，自动加载B的规范，两者互不污染。
• 团队协作规范落地：把团队的Git规范、命名规范、评审清单写进模板，每个成员在同一条起跑线上。
• 高频任务标准化：生成commit、提MR、写测试、刷文档这种重复劳动，全部命令化，减少心智负担。
• 自动化质量检查：hooks在文件变更后自动触发Lint或测试，不等代码写完就发现问题。

1.4 和“普通prompt库”的本质区别

有人会问：模板不就是一堆prompt吗？我把常用提示词存个小本本，要用的时候复制粘贴不一样吗？

说实话，我一开始也是这么想的，甚至真用过一阵子“个人prompt收藏夹”。但用起来完全是两码事。差别可以这样看：

所以如果你只把templates理解成“收藏夹”，你会错失它真正有价值的部分——自动加载和流程触发机制。这两件事，纯靠复制粘贴是做不出来的。

2. 拆解Claude Code模板的四根支柱

我给自己的模板体系总结了四根支柱：CLAUDE.md、自定义斜杠命令、hooks、子代理。下面逐个拆开讲，都是实际在用的东西。

2.1 CLAUDE.md：项目记忆文件，模板的地基

CLAUDE.md是Claude Code的“项目记忆文件”。它放在项目根目录（或全局用户目录），每次Claude启动时会自动读取，把里面的内容当作长期记忆和行为准则。用一句话概括：这是Claude对这个项目的“入职培训”，每一天开工自动重播一遍。

我的CLAUDE.md长这样（这是简化后的结构）：

# 项目概况 - 项目名称：XX零售后台管理系统 - 技术栈：Next.js 14 + TypeScript + Prisma + PostgreSQL - 核心目录：app/（页面路由）、server/（API逻辑）、lib/（工具与中间件） # 开发约定 - 组件文件一律使用 kebab-case 命名 - 新增数据库表必须同时生成迁移文件 - API返回统一包裹为 { code, data, message } 结构 - 单测用Jest，测试文件与源码同目录，后缀 .test.ts # 常用命令 - dev: npm run dev - test: npm run test - lint: npm run lint - migrate: npx prisma migrate dev # 行为规则 - 修改涉及数据库schema时必须先执行 migrate 生成SQL预览，确认后才执行 - 对代码做大规模重构前，先给出改动影响面清单 - 所有新增依赖需说明用途，避免无意义引入

这里有个关键设计原则：只写Claude需要用到的信息，不是项目README的搬运。README是给人看的，CLAUDE.md是给AI执行规则用的。什么东西该写、什么不该写，我后面会在踩坑部分详谈，这里先记住一个判断标准——这条信息如果Claude不知道，会导致它做出错误决策，那就该写；如果只是“项目背景知识”，写不写无所谓，那就别写。

另外，CLAUDE.md可以按目录细分。Claude Code支持在子目录里放子CLAUDE.md，当它在该目录下操作时会额外加载。我通常在server/目录下放一份，专门记录API设计规范；在app/目录下放一份，记录页面开发规范。这样既避免主文件过长，又能让规则精确命中对应代码区域。

2.2 自定义Slash Commands：把高频任务固化成斜杠命令

Slash Commands是模板体系里最容易获得成就感的部分。简单说，就是你自己定义“/命令”，把复杂任务拆解成一套预置流程。我在初始版本中做的第一件事，就是把一周内重复三次以上的操作全部命令化。

命令用YAML定义，我习惯放在项目的.claude/slash-commands/目录里。目录结构长这样：

.claude/slash-commands/ ├── commit.yaml ├── review.yaml ├── test.yaml └── api-doc.yaml

拿最常用的commit命令举例，看它的完整定义：

description: 生成符合Conventional Commits规范的提交信息 agent: Code allowed-tools: Read, Grep prompt: | 你的任务是分析当前工作区中的git diff，生成一条符合Conventional Commits规范的commit message。 步骤： 1. 运行 git diff --staged 查看已暂存的改动 2. 运行 git diff 查看未暂存改动 3. 归纳本次变更的类型（feat/fix/refactor/chore/docs等） 4. 输出 commit message，格式为：类型(模块): 简短描述 5. 附加body说明影响范围，关联issue编号如有 注意： - 不要将多个类型合并成一条 - 描述控制在50个字符以内 - 如有breaking change，在commit message中标注

看到这个结构的价值了吗？你不需要每次跟Claude解释“什么是Conventional Commits”，不需要每次说明“看staged和unstaged的diff”，更不需要强调“commit message要写清楚impact”。这些全固化在命令里了。你只需要在终端敲/commit，它自己按SOP走完流程。

我个人的经验是：命令数量控制在5到8个最舒服。太少覆盖不了高频任务，太多则维护成本和误用概率同时上升。值得做命令的标准很简单——一周内这个操作你重复做了三次以上，就有理由固化成命令。

2.3 Hooks：在关键节点挂上自动化检查

如果CLAUDE.md是“入职培训”，斜杠命令是“标准作业流程”，那hooks就是“贴在工位上的巡检横幅”。

Hooks的作用是在Claude执行某些动作的节点上挂载你自己的逻辑。常用事件节点有：

• PreToolUse：Claude调用某个工具之前触发。适合做“安全门禁”，比如禁止写某个敏感目录。
• PostToolUse：工具执行完成后触发。适合做“自动检查”，比如改完代码自动跑Lint。
• Stop：Claude完成回复，准备结束。适合做“收尾校验”。

我的hooks配置长这样（JSON格式，放在项目级.claude/hooks.json）：

{ "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npm run lint -- --quiet", "timeout": 30 } ] } ], "PreToolUse": [ { "matcher": "Write", "hooks": [ { "type": "command", "command": "bash scripts/check-protected-paths.sh", "timeout": 10 } ] } ] }

第一个hook的效果是：每当Claude使用Edit工具修改代码后，自动运行Lint检查。它改完代码如果引入了Lint错误，马上就能看到，不用等到最后才爆雷。第二个hook的效果是：当Claude准备写文件时，先检查是不是敏感目录（比如node_modules、.git、dist），阻止误写入。

hooks有一个执行顺序问题需要注意：多个hook按配置顺序执行，任意一个hook返回非零退出码，Claude就会被通知中断当前操作。所以快递门禁类的hook要写在最前面，检查类的hook可以靠后放，这样即使后续检查失败，门禁逻辑也已经执行过了。

2.4 子代理（Subagents）：把专用任务拆给专职Agent

最后一个支柱，也是我后面越来越依赖的：子代理（Subagents）。如果说斜杠命令是“把任务流程化”，那子代理就是“把人设专业化”。

默认情况下，Claude像一个全能选手，什么任务都能接，但也意味着它处理专项任务时不够“专”。比如我让它写测试，它默认会用一种通用思路，未必贴合这个项目的Mock约定；让它做代码审查，它会按通用Best Practice来，未必了解团队特定的安全规范。

子代理的思路是：定义一批“专职员工”，每个Agent拥有自己独立的人设、专属指令和工具权限。Claude主进程像一位项目负责人，遇到对应任务，就委派给专职子代理来完成。

我的子代理放在.claude/agents/目录下，一个文件一个代理。以我的测试工程师子代理为例：

name: test-engineer description: 负责单元测试与集成测试的编写与执行，熟悉Jest测试框架和项目的Mock约定 tools: Read, Grep, Write, Edit, Bash prompt: | 你是这个项目的测试工程师。你负责编写和修正测试用例。 项目测试规范： - 测试文件与源码同目录，命名后缀为 .test.ts - 优先使用 describe/it 结构描述行为 - 数据库相关测试必须使用内存数据库，不依赖本地PostgreSQL实例 - 涉及外部API调用的测试使用 jest.mock 隔离 当你接到测试相关任务时： 1. 先阅读相关源码，理解被测函数的边界输入 2. 查看同目录是否有既有测试约定可参考 3. 编写/修正测试用例 4. 运行针对性测试命令验证，失败则继续修复

这样定义的好处是，一旦我提出“给这个模块补测试”的需求，Claude会把这个任务委派给test-engineer，而test-engineer自带的记忆让它在第一轮产出就更贴合项目约定，不再需要我临时啰嗦一遍Mock规范、命名规则、数据库注意事项。

子代理的核心理念是“把人员分工做在配置里，而不是每次对话里”。团队成员越多、规范越细，这个支柱带来的收益就越明显。

3. 手把手实战：从零搭出一套“能用的模板”

理论说了一圈，接下来是我建议的实操路径。我踩过的弯路是：一开始试图把模板设计得大而全，结果写了一堆规则，真正跑起来反而被自己的规则绊住脚。后来我调整了策略：先画流程，再写规则，最后加自动化。

3.1 先画流程，再写规则：模板设计的前置思路

动手写CLAUDE.md之前，我先花半小时做了一次任务盘点。方法是翻出过去两周和Claude的对话记录，按任务类型分组，数一下每类任务出现多少次。我当时的高频任务排序大概是：

1. 生成commit message
2. 做代码审查 / 解释一段复杂逻辑
3. 写接口文档
4. 补单元测试
5. 排查某个报错

对应这个清单，我决定第一版只做四件事：写一份精简CLAUDE.md，定义/commit和/api-doc两条斜杠命令，挂一个自动Lint的hook，其余的都放后面。这个“最小可用模板”的思路帮我快速跑通了整套机制，后面再逐步增加其他功能。

如果你盘下来发现高频任务完全不同，那完全没问题——模板的设计就是从你的真实工作流里长出来，不是别人给你一套通用的就完事了。

3.2 第一步：写一个“克制”的CLAUDE.md

“克制”是我反复强调的词。我见过不少人的CLAUDE.md写得跟法典一样，几百行规则，结果实际用起来效果奇差——token消耗大，而且规则之间互相冲突，Claude会陷入“先遵守哪条”的两难。

我建议按这个框架写第一版：

# 角色 你是本项目的开发助理。你的目标是高效、安全地完成用户交代的编码任务，并严格遵守项目规范。 # 项目背景（2~3条） 一句话说明项目是什么、主要服务谁、代码库多大。 # 技术栈与目录（3~5条） 列出最关键的技术栈、核心目录的用途。不写成结构说明书，只写Claude要干活时必须知道的路标。 # 常用命令（最多5条） dev / test / lint / build / migrate，按需列举。 # 硬性规范（最多8条） 只放违反后会导致严重问题的规则，比如数据库迁移流程、敏感信息保护、必须运行测试等。 # 行为禁忌（3~5条） 明确告知什么不能做，例如不要假设删除不存在的文件、不要绕开Prisma直接改数据库等。

每一条规则都要能被快速验证。写完之后检查一遍：这条规则如果删掉，Claude的行为会立刻变差吗？不会的话就删了。保持文件在你常对话轮次内不把上下文撑爆，是模板长期好用的关键。

3.3 第二步：定义两个高频命令拿到即时反馈

接着定义命令。我当时最需要的是/commit和/api-doc。commit命令的YAML前面展示过了，这里看下/api-doc：

description: 为指定API路由生成接口文档 agent: Code allowed-tools: Read, Grep, Write prompt: | 请基于以下信息生成该API接口的Markdown格式文档。 目标文件：$ARGUMENTS 生成步骤： 1. 读取指定路由文件，理解HTTP方法、参数结构、返回结构 2. 查询对应的Prisma模型或数据库表结构定义 3. 输出文档，包含：接口地址、HTTP方法、请求参数表（名称/类型/必填/说明）、 返回示例、错误码列表（如有） 4. 文档输出到 docs/api/ 目录下，文件名与路由名一致 注意：文档中不包含任何敏感信息，如数据库连接串、内部跳转地址。

这里有个细节：$ARGUMENTS是斜杠命令内置的参数占位符。我执行/api-doc server/routes/user.ts时，Claude会把server/routes/user.ts替换进prompt里。这让一条命令能适用于同类型的多个目标文件，而不是把文件路径烧死在命令里。

两条命令上线后，我当天就感觉到变化：commit不再是我逐字敲的煎熬事，接口文档从“拖延到被催”变成了“顺手生成”的状态。这就是即时反馈带来的正循环，你会自然而然地想继续加命令。

3.4 第三步：配置hooks，让模板真正做到“自动化”

斜杠命令解决的是“主动触发的任务”，hooks解决的是“需要被动拦截或自动检查的场景”。要让模板真正变得“省心”，这一步不能省。

我强烈建议第一个hook先做“Lint自动检查”，收益最直接。在你确认能稳定运行之后，再加“PreToolUse安全拦截”。

我记得第一次配置hooks时踩了个坑：没有设置timeout，结果有一次Lint执行卡住，整个Claude操作被挂起，终端像死了一样。后来养成习惯了，所有command类hook都带上timeout，单位按秒。Lint这种通常10到30秒足够，写死30秒就对了。

另一个经验是hooks的matcher要尽量写准。matcher是匹配工具名称的，比如Edit、Write、Bash。如果你希望在“写文件时”才触发检查，matcher写Write，不要让无关的工具触发。范围宽了容易误触发，范围窄了有漏网之鱼，这个度要靠一段时间的运行日志来调。

3.5 第四步：目录化与版本化，让模板可复制、可演进

模板最怕的是“一次性搭建，用完就忘”。我的处理方式是把它做成独立的Git仓库，目录结构是这样：

claude-code-templates/ ├── templates/ │ ├── next-fullstack/ │ │ ├── CLAUDE.md │ │ ├── .claude/ │ │ │ ├── hooks.json │ │ │ ├── agents/ │ │ │ └── slash-commands/ │ │ └── docs/ │ └── python-fastapi/ │ └── ... ├── scripts/ │ └── apply.sh └── README.md

每个业务项目对应一套模板，模板仓库独立保存版本历史。新项目开工时，跑一下apply.sh，传入目标项目路径，脚本把对应模板的CLAUDE.md和.claude目录复制过去，再根据项目名替换少量变量即可。

版本化带来的最大好处是“可演进”。每次你在项目里调整了一条规则、新增了一个命令，改动沉淀在模板仓库里；下个项目直接继承最新版本。我自己的模板仓库到现在迭代了十几个commit，每次改动都有记录，不会出现“改着改着忘了当初为什么这么改”的糊涂账。

4. 模板调优与踩坑实录：实测中的参数参考和翻车现场

这一部分是我最想分享的。网上讲Claude Code模板设置的教程不少，但大多停留在“介绍有哪些功能”层面，真正操作时会遇到的坑，只有自己踩过才知道。下面是我实测几个月攒下来的调优经验和翻车记录。

4.1 坑一：CLAUDE.md写成了“字典”，token被无效消耗

第一版CLAUDE.md，我几乎是把项目文档和API手册浓缩了一下全塞进去了。结果每次对话的token消耗明显上涨，而且Claude的行为并没有因为有“完整文档”而变好——因为信息量太大，关键规则反而被淹没了。

后来我做了个清理：把CLAUDE.md压缩到约2500 token以内，只保留“行为规则”和“关键路径”两类信息，其余背景知识全部移到docs目录，Claude需要时再去检索。效果立竿见影，不仅token消耗降下来了，规则命中率也高了。现在我的经验参数是：

• CLAUDE.md主文件控制在 1 ~ 3 KB 左右，对应约 500 ~ 1500 token，看你项目复杂度。
• 超过3000 token就强烈建议拆分：把细粒度规范移到子目录的CLAUDE.md，或文档文件中。

记住：CLAUDE.md不是让你把文档翻译一遍，而是给AI指路和定规矩用的。

4.2 坑二：斜杠命令的命令权限过宽

那次是给一个斜杠命令配置了比实际需要更多的工具权限。命令本身是生成文档的，我却把allowed-tools写成了Read, Grep, Write, Edit, Bash。结果Claude在执行过程中自作主张跑了个Bash命令修改了某个配置文件——虽然改动不致命，但足够吓人。

从此以后，我严格执行“最小权限”。写文档的命令，给Read, Grep, Write就够了，永远不会给它Edit和Bash。做审查的命令，给Read, Grep足矣。需要跑测试、改代码的命令才放Bash, Edit进来。这个原则跟给服务器开防火墙端口是一样的：默认拒绝，按需放行。

4.3 坑三：hooks误触发与死循环

这是我踩过最严重的一次坑。当时挂了一个PostToolUse hook，逻辑是“每当工具执行完，自动运行一次测试”。问题是，当Claude运行测试命令本身时，Bash工具执行完也会触发PostToolUse，于是又触发一次测试……直接形成无限循环，最后被Claude的自我保护机制中断。

排查过程比较痛苦，我一度以为是Claude变傻了，后来翻了hooks的执行日志才发现，死循环的根因是“hook没有排除自己”。解决方案是在hook脚本里加一个判断：如果正在执行的命令包含测试命令自身，就跳过本次触发。或者更简单的做法，把自动触发条件限定为只对Edit工具生效，如下：

{ "PostToolUse": [ { "matcher": "Edit", "hooks": [ { "type": "command", "command": "npm run lint -- --quiet" } ] } ] }

现在配置里对Edit工具的触发仍然是安全的，但“无限循环”这个词成了我在团队里的警示教材。设计hooks时，务必问自己：这个hook触发后产生的动作，会不会反过来再次触发同一个hook？

4.4 坑四：模板版本与Claude Code版本兼容性

Claude Code的迭代速度非常快。配置文件格式、命令定义字段、hooks事件的详细参数，都可能在某个小版本更新后发生变化。我最初写的hooks配置格式是参考当时的文档来的，结果两个月后升级Claude Code，PostToolUse的配置结构变了，之前能用的hook静默失效。

我现在做两件事来避免这类问题：

• 模板仓库的README里记录“最后验证的Claude Code版本号”。比如我当时验证的是 1.0.x 系列，换版本前先看Release Notes。
• 升级Claude Code后，不急着切全部项目，先在一个测试项目里跑一遍模板的核心命令和hooks，确认无误后再做全面切换。

这是个听起来不够酷但极其有效的流程。工具版本是流水，模板是基石，基石跟着流水漂一定会出问题。

4.5 什么才是好的claude-code-templates：我的几条判断标准

几个月用下来，我把“好模板”的标准沉淀成几条可验证的规则，分享给你作为调优基准：

• 高频命令化：一周内重复3次以上的操作，就应该做成斜杠命令。如果一条命令你用了不到5次，考虑删掉。
• 规则数克制：当CLAUDE.md里某条规则已经“三个月没有被触发”时，说明它不是刚需，大胆删。
• 命令权限最小化：每个命令的allowed-tools只给够用的，多一个都不行。
• hooks留日志：给hook脚本的执行结果留日志，出现异常时能快速定位。
• 模板可迁移：新项目套上模板后，半小时内能达到“Claude已经很懂这个项目”的状态，否则说明模板还不够好。

还有一个容易被忽略的点：模板是人机协作的契约，不是枷锁。设计时留出“允许偏离规则”的空间。CLAUDE.md里有几条禁忌其实Claude偶尔会违背，我的处理是看违背之后的结果是好是坏再决定要不要把禁忌写得更硬。完全没有弹性空间的行为规则，会让工具显得僵化，而它的优势恰恰是比普通脚本更灵活。

项目跑了大半年，我的模板仓库已经更新了十来个版本，每次调整都来自真实使用中的反馈。模板不是写出来的，是长出来的。刚开始你可能只有一个好的CLAUDE.md，用着用着，你开始觉得某个操作值得一条斜杠命令，某个环节需要挂一个hook，某个固定任务应该拆给专用子代理。这个过程才是模板化玩法真正有价值的地方。

最后分享一个小技巧：给CLAUDE.md末尾留一个“升级日志”区块，让Claude每次更新记忆时顺便记录一下改动。它会成为你最诚实的模板使用史，也是回看自己工作流进化轨迹的好材料。