企业官网建设流程全解析

如果你在项目里用过一段时间 Claude Code，应该很快会撞到同一个问题：同一个模型、同一个仓库，今天它对需求的理解和上周完全不一样，换个项目更是像换了个人。问题多半不是出在模型身上，而是你根本没有给它一套稳定的“工作规则”。我整理这套 claude-code-templates，就是把散落在多个项目里的规则文件、提示词、命令脚本、hook 配置全部沉淀成一套可以直接复用的模板集。

它解决的是三件事：让 AI 按照统一规范工作、把高频操作固化成命令、让多个人和多个项目共享同一套行为约束。适合已经装好 Claude Code 但还没系统配置过规则文件的开发者，也适合想给团队统一 AI 协作方式的人。

1. 这套模板到底解决什么问题

1.1 从“每次从头写提示词”到“一套配置跑多个项目”

Claude Code 这类 AI 编程助手最典型的用法，是你在终端里扔一句“帮我实现登录功能”，它就开始读代码、猜需求、动手改。前面几次确实快，但用久了就会发现：这个“快”是拿后续的返工时间换的。模型对项目的上下文一无所知，它不知道你团队用不用 TypeScript，不知道你的测试框架是哪一家，更不知道“改完代码必须跑一遍 lint”是你的红线。

于是你开始复制粘贴一大段项目说明到对话里，今天粘一份，明天粘一份，稍微换个人协作又得重新粘。这就是最原始的“模板需求”——把重复的指令内容沉淀成文件，让 Claude Code 每次启动时自动加载。

我在早期尝试时就走过这个弯路：把一大堆要求写在系统提示词里，每次开会话都要带进去，token 费了一堆，效果还不稳定。后来才意识到，真正的解法是把规则放到项目目录里，让 AI 自己读取。这就是 CLAUDE.md 文件存在的意义：它相当于一份“给 AI 看的 README”，既说明项目背景，也规定行为方式。模板的核心价值，就是把这层配置做成一套开箱即用的骨架，而不是让每个项目从零开始重写。

1.2 模板不是提示词收藏夹，而是一套工程化配置

很多人以为 Claude Code 模板就是“提示词合集”，这是误解。提示词收藏夹只解决单次对话质量，而真正的模板集要解决的是工程协作问题。一个合格的模板集至少包含四层内容：

• 规则层：CLAUDE.md、AGENTS.md 这类记忆文件，定义角色、流程、红线；
• 命令层：自定义斜杠命令，比如 /test、/review、/commit，把高频操作变成一键触发；
• 钩子层：hooks 脚本，在 AI 执行工具的某些节点自动检查质量、拦截错误；
• 脚本层：辅助脚本，用于格式化代码、收集测试反馈、提交前检查等。

为什么一定要分这么多层？因为职责单一原则同样适用于 AI 配置。如果所有约束都堆在一个 CLAUDE.md 里，文件会越来越长，模型读到后面就忘了前面，而且规则之间互相干扰。命令层和钩子层的存在，能让 AI 在正确的时机调用正确的逻辑，而不是靠“记忆”去承载所有行为。

我可以负责任地说，一个项目只要跑顺过这套分层模板，再让它去处理一个新的类似项目，效率提升是肉眼可见的。因为模型不只是在“理解代码”，它还在“理解这个项目的协作方式”，而协作方式恰恰是它以前最欠缺的信息。

2. 规则层模板设计：CLAUDE.md 与 AGENTS.md 到底怎么写

2.1 CLAUDE.md 主规则：角色、流程、红线

CLAUDE.md 是模板里最核心的文件，它决定了 AI 对整个项目的基本认知。我写这个文件的时候，坚持一个原则：只写模型必须知道且需要长期遵守的内容，不写临时指令。一份好的 CLAUDE.md 通常包含以下结构：

# CLAUDE.md ## 角色定位（你是谁） 你是本仓库的一名资深全栈工程师，负责在 project-name 中实现需求。 你的目标不是“写最快”，而是“写最少的问题”，优先保证可维护性。 ## 工作流程（先怎么做，后怎么做） 1. 接到新需求先读 README 和相关模块结构，明确改动范围。 2. 任何超过 50 行的改动，先向用户输出实现方案，确认后再编码。 3. 代码改动之后执行 npm test，确认无回归再结束任务。 4. 提交信息遵循 Conventional Commits 规范。 ## 代码风格（硬性要求） - TypeScript 优先，禁止使用 any。 - 组件函数使用大写驼峰命名，事件处理函数统一以 handle 开头。 - 单元测试使用 Vitest，测试文件放 __tests__ 目录，不允许跳过测试。 ## 红线（绝对禁止） - 不得修改 package-lock.json，除非用户明确要求。 - 不得绕过 ESLint 规则，更不允许在代码里加 eslint-disable 注释。 - 不跨越包与包之间的边界自由 import 内部模块，必须通过对外导出。

这个文件写完之后，最关键的一点是把它交给模型“读取”而不是“描述”。Claude Code 在启动时和代码变更时会自动加载项目根目录下的 CLAUDE.md，所以你不必在每次对话里重复这些内容。

实际操作中我踩过的一个坑是：把 CLAUDE.md 写得像项目百科，连数据库连接地址、第三方服务密钥都写进去了。这完全没必要。模型需要的是“行为约定”，不是机密信息。而且这类敏感信息写进去，一旦文件被同步到仓库，泄露风险很大。CLAUDE.md 应当像一份团队新成员入职手册，而不是运维手册。

2.2 AGENTS.md 子代理分工：什么时候需要一份“规定动作”

AGENTS.md 是比 CLAUDE.md 更细粒度的规则文件，它主要针对多代理协同的场景。如果你只是单人在单仓库里用 Claude Code，一个 CLAUDE.md 通常够用。但一旦项目变大，或者你想让 AI 在特定领域（比如文档、数据库迁移、代码评审）保持不同的行为方式，AGENTS.md 就很有用了。

我通常把 AGENTS.md 放在子目录里，形成分层规则。比如在 docs/ 目录下放一份 AGENTS.md，里面写：

# AGENTS.md for docs/ 执行本目录下的任务时，你是一名技术文档工程师。 - 文档命名必须与 API 名称对应，比如 user-api.md。 - 每个文档必须包含：功能说明、参数表、示例、错误码。 - 不要直接在文档中嵌入内网 IP 或真实令牌，一律用占位符。

这样做的逻辑很简单：规则离代码越近，越容易被模型注意到。当 AI 处理 docs/ 目录下的文件时，它会优先读取这个子目录里的 AGENTS.md，而不是翻到仓库根目录去找主规则。我实测下来，这种“就近原则”比把所有内容塞进一个 CLAUDE.md 要可靠得多，也不容易产生规则覆盖的混乱。

2.3 变量与占位符：模板怎么适配不同项目

模板最大的特点是可以复制，但直接复制往往不能用，因为每个项目的角色定位、包管理工具、测试框架都不一样。所以我在模板里做了一个很关键的约定：用占位符代替硬编码。

比如上面的 CLAUDE.md 里，project-name、npm test、Vitest 这些内容，在模板里都写成可替换的变量。初始化模板时，我会先运行一个初始化脚本，把占位符替换成实际值。这一步看似简单，却避免了一个常见问题：AI 宁可相信模板里的“默认值”，也不愿花时间去读真实的 package.json。你给它一份写着“使用 Mocha 测试”的模板，它就真的往项目里装 Mocha，哪怕你项目里用的是 Jest。

所以，变量替换这一步绝对不能省。一个靠谱的模板集必须配套一个初始化脚本，把占位符、项目名、测试命令、代码规范这些内容一次性替换到位。不要低估这一步的价值，我在一个客户项目里见过 AI 连续三次按照模板里的旧框架生成代码，就是因为模板没有完成替换。

3. 命令层模板：把高频操作变成斜杠命令

3.1 自定义 slash commands 怎么注册

Claude Code 的斜杠命令本质上就是存在 .claude/commands/ 目录下的 Markdown 文件，文件名就是命令名。你输入 /test，它就读取 test.md 并执行里面的指令。这个机制的妙处在于，它把“上下文 + 行为”绑定成了一个稳定入口。

一个命令文件长这样：

--- description: 运行测试并反馈结果 argument-hint: [可选] 测试名称过滤 --- 运行测试并给出结果总结： - 执行 `npm run test:unit -- <filters>`； - 若测试失败，列出前 3 个失败用例及对应堆栈； - 分析失败原因：是断言逻辑问题还是业务代码问题； - 针对失败原因给出修复建议，但不要直接修改代码，除非用户明确同意。

为什么要把这些内容写成文件而不是每次手打？因为命令文件里包含了两层价值：一是操作流程的标准答案，二是行为边界的预设。比如上面最后一条“不要直接修改代码”，就是防止 AI 在前置任务还没确认时就越权乱改。注册命令之后，团队里任何人敲 /test 都能得到一致的流程，不会因为某个人少说一句话导致结果不同。

3.2 /review、/commit 三个模板拆解

除了测试命令，我最常用的三个命令是 /review、/commit 和 /fix。它们的模板在设计上各有侧重。

/review 命令的核心是“独立评审视角”，避免 AI 陷入“自己写自己评”的怪圈。模板里我会强调：

--- description: 审查当前未提交的改动 --- 审查当前 git diff 内容，重点检查： 1. 是否有明显逻辑错误或边界遗漏； 2. 是否遵守项目 CLAUDE.md 中定义的代码风格； 3. 是否遗漏错误处理路径； 4. 是否引入安全风险（如拼装 SQL、硬编码密钥）。 输出格式：按严重程度分为 P0/P1/P2 列出问题，每条附上对应代码位置。

/commit 命令则相反，它要求 AI 先总结 diff，再生成符合规范的提交信息：

--- description: 生成提交信息 --- 把当前暂存区的改动整理成 Conventional Commits 格式的提交信息。 先输出改动摘要，再按 type(scope): subject 格式生成提交标题。 如果存在破坏性变更，必须在正文中注明 BREAKING CHANGE 及其影响。

这两个命令放在同一个项目里，正好形成一收一放：/review 是收紧环节，/commit 是收尾环节。两者都写成模板，最大的好处是 AI 不会因为“用户没要求”就跳过质量检查。

3.3 hooks 脚本：在关键节点自动卡质量

命令是主动触发的，而 hooks 是被动触发的。Claude Code 支持在工具调用的前后执行脚本，这个能力非常值得在模板里用起来。最常见的做法是配置 PreToolUse 和 PostToolUse 钩子。

举一个实测的配置例子。我想确保 AI 不会绕过测试目录的命名规范，于是在 .claude/settings.json 里加了这样的 hook：

{ "hooks": { "PreToolUse": [ { "matcher": "Write", "hooks": [ { "type": "command", "command": ".claude/hooks/check-test-path.sh \"$CLAUDE_TOOL_INPUT\"" } ] } ] } }

对应脚本 .claude/hooks/check-test-path.sh 的核心逻辑是：如果本次 Write 的目标路径是测试文件，就校验路径是否以tests开头，不满足则输出错误并以非零码退出，从而阻止 AI 把测试文件写到乱糟糟的位置。

hook 配置最值得注意的地方是它的退出码。脚本输出到 stderr 的信息会被 Claude Code 捕捉，退出码非零会中断当前操作。所以写 hook 脚本时，要区分“警告”和“阻断”两种力度。大部分场景用警告就够了，频繁阻断反而会让 AI 的任务执行变得碎片化，影响整体效率。

4. 实操过程：从零初始化一套项目模板

4.1 五步初始化：复制、替换、注册、验证

现在我把这套模板落到一个新项目里，整个过程分五步：

1. 复制模板骨架：把 .claude/ 目录和根目录的 CLAUDE.md、AGENTS.md 复制到目标项目。
2. 执行变量替换：运行初始化脚本，把占位符替换为真实项目名、包管理工具、测试命令。这一步一定要显式执行，不能靠 AI 自己推断。
3. 注册命令脚本：确认 .claude/commands/ 下的 .md 文件权限和路径无误，命令行输入 / 查看命令列表是否出现自定义命令。
4. 配置 hooks：将 .claude/settings.json 里的 hook 路径改为项目内实际脚本路径，并给脚本加可执行权限（chmod +x）。
5. 验证规则加载：新开一个 Claude Code 会话，随便问一句“这个项目的代码风格是什么”，看它能否正确回答出 CLAUDE.md 里定义的规范。这一步能快速暴露配置是否生效。

我遇到过的最典型的初始化错误，是在 Windows 环境克隆了仓库，脚本权限丢失导致 pre-commit 直接钩子什么都不干。所以在配置 hooks 这步，我会专门检查脚本的 shebang 行和可执行权限。复制模板后如果发现命令没有出现在斜杠菜单里，多半是文件后缀写成了 .markdown，而系统只认 .md 后缀。

4.2 第一次全流程验证：让它从头写一个功能

配置完成后，我通常会拿一个小需求做一次全流程验证，比如“给订单模块加一个导出 CSV 的接口”。看 AI 的表现，重点不是功能是否实现，而是它有没有遵守规则：

• 有没有先输出实现方案再动手编码；
• 测试文件是否放到了tests目录；
• 有没有用 TypeScript 而不是 any 泛滥；
• 命令行为是否符合 CLAUDE.md 的定义。

这套验证流程不是多余的，因为模板配置错误往往不会直接报错，只会表现为“AI 行为奇怪”。比如它写文件到了错误路径、不写测试、或者提交信息不符合规范。如果第一次验证就发现问题，八成是 CLAUDE.md 里的规则描述太模糊或者优先级冲突。此时我会先精简规则条目，再试一次。

我在给一个团队配置模板时，发现 AI 总是忽略测试要求，排查半天才意识到：CLAUDE.md 里写着“必须写测试”，但同一个项目根目录下的 AGENTS.md 里又有“优先实现功能，测试可后续补充”这句话。两条规则冲突时，模型选择了后者。这个案例给我们的教训是：模板里的规则必须互相补位，而不是互相打架；冲突规则比没有规则更糟。

4.3 多仓库复用与团队同步

模板的最后一层价值是团队复用。把整个 .claude/ 目录提交到仓库后，团队成员拉取代码就自动获得了同一套命令和规则，不需要每个人手动配置。这一点对团队协作帮助很大：同一套 /review 规则，不会有张三一个版本、李四一个版本的问题。

团推同步时需要注意版本控制。模板会随项目演进不断调整，如果 A 成员改了 CLAUDE.md，B 成员的本地内容还是旧版，就会出现规则不一致。我的习惯是：把 CLAUDE.md 和 .claude/ 目录纳入 Code Review 范围，任何修改都要像改业务代码一样过评审。这听起来有点重，但对于一个依赖 AI 协作的仓库来说，规则文件的稳定性直接影响产出质量，值得投入。

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

5.1 规则文件改了，AI 却不按新规则执行

这是反馈最多的问题。大多数人会以为是规则写得不到位，但实际上多半是上下文没有刷新。Claude Code 会在新会话开启时读取规则文件，但同一个会话里已经产生的上下文不会立刻失效。也就是说，你改了 CLAUDE.md，老会话里的 AI 可能还在按旧规则干活。

解决方法是：改完规则后，新开一个会话，或者用 /clear 清空当前上下文。另外还有一种情况：项目根目录的 CLAUDE.md 和子目录的 AGENTS.md 规则叠在一起，后读取的规则把前面的覆盖了。排查这类问题时，我会让 AI 输出“你当前遵循的规则摘要”，直接看它心里到底装了什么。这个方法比反复改文件快得多。

5.2 上下文被无关输出喂饱，规则被稀释

AI 的上下文窗口是有限的，如果 hook 脚本或者命令要求它输出大量原始日志，真正有用的规则反而会被顶出上下文。我见过一个项目，AI 执行测试命令时把整段十几万字符的测试输出原样贴回上下文，结果后续任务质量急剧下降。

模板里的测试命令必须强制要求 AI只总结结果，不粘贴原始日志。比如命令模板里明确写“输出前 10 行关键错误摘要”，而不是“输出全部日志”。另外，如果你的模板经常需要读取日志数据，最好配合 grep 或者 tail 这类 shell 命令做预过滤，让 AI 只拿到关键片段。这一步对于上下文预算紧张的场景是很实用的保命技巧。

5.3 hooks 无声失败与路径坑

hook 脚本最容易踩的坑是“无声失败”。脚本明明写错了，但因为输出格式不对、退出码被忽略，Claude Code 照样继续干活，看起来什么都没发生。第一次排查这类问题时，我花了整整一下午，最后发现是脚本里用了相对路径，而 hook 的工作目录并非项目根目录。

所以我的模板里统一规定：hook 脚本内所有路径引用都用绝对路径，并在脚本开头做环境检查。比如：

#!/usr/bin/env bash # 检查必要参数是否存在 if [ -z "$CLAUDE_TOOL_INPUT" ]; then echo "缺少工具输入参数" >&2 exit 1 fi

跨平台执行也要注意。同一个脚本在 Linux 上跑得好好的，到了 macOS 上 sed 命令语法就报错。模板集里所有 shell 脚本，我都会标注清楚适用平台，或者写成兼容写法。hooks 排查技巧总结下来就一句话：先看退出码，再看 stderr 输出，最后才怀疑业务逻辑。

6. 最后再分享一点个人经验

这套模板我用到现在，最大的感触是：它不像一个“加速工具”，更像是一个“约束工具”。AI 编程的体验不取决于模型有多强，而取决于边界画得多清楚。规则写得太松，AI 会放飞自我；写得太死，AI 又束手束脚。模板的价值，就是让这两者之间找到平衡。

在实际操作中，我最后总是提醒自己：模板是起点，不是终点。每个项目都有它自己的特殊性，模板只能提供一个共同底座。真正好用的规则文件，是在项目的实际迭代中一点点长出来的——你发现 AI 总在某个环节犯错，就去补一条规则；你发现某条规则总是引发误判，就删掉重写。保持 CLAUDE.md 精简，控制在一个文件能读完全部要点以内的长度，效果远好于写一份巨细无遗的“宪法”。

另外，如果你打算把模板分享给其他人，记得在初始化的脚本里加入自检命令。这会让第一次使用的人少走很多弯路，也会减少你收到“模板不好用”反馈的概率。我就是这样做的，现在团队里的新项目一律先跑一遍模板初始化，再谈具体开发，省下的沟通成本完全超出我的预期。