企业官网建设流程全解析

我第一次认真把 Claude Code 接进日常开发，是在一个维护了三年多的 Python 服务上。功能改到一半，它突然开始重写模块里的异常处理——不知道团队约定用自定义异常而不是裸 raise，不知道测试命令要指定 service 目录，更不知道 build/ 是生成产物、永远不该手动碰。那一刻我意识到，问题不在模型能力，而在我的项目里从来没有一份 AI 需要遵守的书面约定。

Claude Code 这类跑在终端里的 AI 编程助手，核心价值在于能直接读代码库、跑命令、改文件。但它默认不认识你项目的特殊规则。templates 解决的就是这个信息差：把项目背景、代码规范、常用操作、角色分工，写成结构化的 Markdown 文件，让 Claude 在每次会话开始时就读进去。相当于给 AI 同事准备一份入职手册，而且是入职第一天就能背下来的那种。

这篇文章就围绕 claude-code-templates 展开。我会先讲清楚模板到底在解决什么，再拆解一个模板仓库里常见的文件类型和职责，接着给出一套可以直接抄的目录结构和编写方法，最后聊聊我实际用下来踩过的坑，以及模板体系怎么跟着项目一起成长。适合正在用 Claude Code 但总觉得它"差一点意思"的开发者，也适合想在团队里统一 AI 协作规范的工程负责人。

1. 没有模板的 Claude Code，问题到底出在哪

1.1 每次会话都是一张白纸

很多人第一次用 Claude Code 的感觉是"惊艳又失控"。惊艳在于它能自己读代码、跑测试、改 bug；失控在于它经常按自己的想法来，和你项目里的实际情况对不上号。原因其实很简单：每个新会话都是一张白纸，它不会记住你上一个会话里交代过什么约定。

我举一个最典型的例子。我的项目测试命令是poetry run pytest tests/service/，第一次使用 Claude Code 时，我口头告诉它"测试用这条命令"。这一个会话里它确实照做了。但第二天开新会话，它又开始用pytest直接跑，结果因为依赖环境不对，测试一片红。这不是它笨，是我没有把约定变成跨会话、跨项目的稳定输入。

后来我把这类信息写进 CLAUDE.md，问题就消失了。Claude 每次进入项目都会自动加载这个文件，相当于每句话都在重复一遍"测试请用这条命令"。一次写入，每次生效，这才是模板和口头交代的本质区别。

1.2 口头交代只活在一个回合里

口头交代还有一个更隐蔽的问题：它只对当前回合有效。你可以在对话中说"接下来所有数据库操作都走 repository 层"，模型大概率会在这个会话里照做，但过几个小时后它可能就忘了，又开始在 service 里直接写 SQLAlchemy 查询。原因在于模型遵循的是"最近上下文"，你的那句叮嘱被大量代码内容冲刷得越来越弱。

而写入模板文件的规则不一样。它位于每条对话消息之前，等效于每一轮 Claude 在回答前都会先看到"数据库操作必须走 repository 层"这条约束，优先级被显著抬高。从信息论的角度看，模板文件里的内容等于在有限上下文窗口里做了"固定席位预留"，比一闪而过的口头指令要稳固得多。

另一个现实场景是多人协作。同一个仓库，三个开发者各自用 Claude Code，各说各的话，产出的代码风格天差地别。有人要求用单引号，有人不管格式，有人要求提交前必须跑全量测试。最后 git log 一团糟。模板仓库的价值就是把这些口头约定收敛成一份团队共同维护的书面规范。

1.3 模板真正规范的三件事：指令、记忆、角色

我在整理模板的过程中发现，不管什么项目，需要规范的东西归根结底就三类。

第一类是指令。测试怎么跑、lint 怎么执行、部署命令是什么、编译产物放哪，这类操作型知识。Claude Code 自己不会魔法般地猜出你的工程用什么包管理工具，更不知道编译参数里那些历史坑。指令类模板的价值是把"怎么做"变成可复用的标准动作。

第二类是记忆。项目是干什么的、模块怎么划分、哪些目录是生成产物、哪段代码是大家公认的"雷区"。这类静态知识充当项目的长期背景，让 Claude 在分析问题时不至于提出"重写整个模块"这种离谱方案。

第三类是角色。让 Claude 以什么身份、用什么视角工作。是让它在代码评审时扮演一个挑剔的资深工程师，还是让它在调试时扮演一个关注边界条件的测试人员？不同的角色设定直接影响输出质量。

这三点分别对应模板仓库里的三类核心文件：CLAUDE.md、自定义斜杠命令和角色模板。下面详细拆开看。

2. 拆开模板仓库：每类文件都在干什么

2.1 CLAUDE.md：项目的"入职手册"

CLAUDE.md 是 Claude Code 体系里最基础也最重要的模板文件。项目根目录下的CLAUDE.md会在每次会话启动时自动加载；用户主目录下的~/.claude/CLAUDE.md则对所有项目生效。两者的关系类似于"公司规章制度"和"个人工作习惯"——全局的管底线，项目的管具体。

一份合格的 CLAUDE.md 内容应该包括：

• 项目一句话介绍和核心目标，让 AI 快速进入语境
• 架构速览，包括各模块职责和依赖方向
• 常用命令的完整写法，比如启动、测试、lint、构建
• 编码约定，包括命名规范、错误处理习惯、日志方式
• "不准动"清单，比如生成目录、锁定文件、某些历史悠久的兼容层
• 常见的坑和已知注意事项

我自己的经验是，写了 CLAUDE.md 之后，Claude 犯低级错误的频率至少下降一半。尤其是"架构速览"这一节，价值远超想象。之前它经常在改一个路由函数时顺手重构了整个 service 层，因为根本不了解模块边界。写清楚"app/api/ 只做参数校验，业务逻辑必须放 app/services/"之后，这种行为基本绝迹。

2.2 自定义命令：把高频操作变成一条斜杠指令

CLAUDE.md 管"知道什么"，自定义命令管"做什么"。在.claude/commands/或~/.claude/commands/目录下，你可以放一些 Markdown 文件，它们会变成终端里的斜杠指令。

每个命令文件用一个 YAML frontmatter 做元信息，常用的字段包括：

• description：描述命令作用，这个会显示在斜杠命令的提示列表里
• argument-hint：告诉使用者可以传什么参数
• allowed-tools：限定这条命令执行时 Claude 能使用哪些工具

命令正文就是一段结构化指令，Claude 执行斜杠命令时会完整读取正文，并按照正文里的步骤去执行。比如我写了一个/review命令，专用于代码评审：

--- description: 对当前改动做一次完整代码评审 argument-hint: [可选] 指定文件路径 allowed-tools: Read, Bash --- 1. 如果没有指定参数，先用 `git diff HEAD` 查看最近改动 2. 按以下顺序检查： - 正确性：逻辑是否与既有行为一致 - 边界条件：空输入、异常输入、并发场景 - 错误处理：是否统一走 AppError，有没有裸 raise - 日志：是否有足够的关键日志，是否误用 print - 命名：是否与项目现有风格一致 3. 每个问题标注严重程度：阻塞 / 建议 / 可选 4. 只在确实存在问题时给出修改建议，不要擅自重写代码

这套形式相当于把一次高质量评审的完整流程固化下来。没有命令模板时，每次我都得在对话里重新描述一遍评审要求；有了命令之后，输入/review就得到一份格式统一的评审结果。而且allowed-tools限定了它只能用读和命令执行类工具，有效防止 Claude 评审到一半突然开始改代码。

2.3 角色模板：让 AI 以固定身份切入

如果说 CLAUDE.md 是给 AI 看的手册，角色模板就是给 AI"化妆上岗"。在.claude/agents/目录下可以定义专门的子代理（agent），每个代理有独立的提示词、工具权限，承担特定任务。

我常用的一个角色模板是 code-reviewer：

--- name: code-reviewer description: 资深代码评审专家，专注找问题，不写代码 allowed-tools: Read, Bash --- 你是一名有十年经验的资深代码评审专家。你的职责是严格审查代码并输出结构化评审意见。 你不需要修改代码，不要给出完整代码示例，只需要明确指出问题和改进建议。 评审时重点关注： - 潜在的业务逻辑漏洞和边界条件缺失 - 错误处理是否完备，有没有吞异常的情况 - 是否引入不必要的复杂度 - 测试覆盖是否充分 输出格式： - [阻塞] 必须修复的问题 - [建议] 建议改进的点 - [可选] 可忽略的细节

这种角色模板的好处是隔离复杂度。评审任务不需要关心技术栈细节，也不需要写代码，把工具权限限定为只读和高频命令类后，它的行为模式非常稳定。相比在同一个会话里让 Claude 既写代码又自审，拆出专门角色，评审质量会明显更高。

2.4 hooks 与 settings：容易被忽略的"规矩文件"

模板不只是 Markdown 提示词。.claude/settings.json里的钩子配置和权限配置，同样是模板体系的重要组成部分。钩子可以在工具执行前或执行后介入，比如拦截某些危险命令，或者在做完测试后自动把结果写回上下文。

举个例子，我服务里的build/目录是生成产物，我不希望 Claude 手动修改它。光在 CLAUDE.md 里写"禁止修改 build/"其实不够，模型在长篇对话里偶尔会忘记。处理办法是在 settings 里加一条 PreToolUse 钩子，检查 Bash 工具的参数里是否包含对 build/ 的写操作，一旦命中就阻止执行并提示。这种"规则写在提示词里、强制落在钩子里"的双保险模式，我后面会再详细展开。

3. 从零搭一套能落地执行的模板仓库

3.1 仓库结构：先想清楚怎么组织

一个 claude-code-templates 仓库最重要的是结构清晰。我自己用的是"基础模板 + 项目覆盖层"的两级组织方式：

claude-code-templates/ ├── README.md ├── install.sh ├── base/ │ ├── CLAUDE.md │ ├── commands/ │ │ ├── review.md │ │ ├── test.md │ │ ├── fix.md │ │ └── commit.md │ └── agents/ │ ├── code-reviewer.md │ └── debugger.md └── projects/ ├── python-service/ │ └── CLAUDE.md ├── web-frontend/ │ └── CLAUDE.md └──># Python Service 项目约定 ## 项目一句话 订单履约服务的后端，FastAPI + PostgreSQL + Redis。 ## 常用命令 - 启动本地服务: `uv run uvicorn app.main:app --reload` - 跑测试: `uv run pytest tests/ -q` - 代码检查: `uv run ruff check app/ tests/` ## 架构速览 - `app/api/` 路由层，只做参数校验和响应组装 - `app/services/` 业务逻辑层，禁止直接操作数据库 - `app/repos/` 数据访问层，所有 SQLAlchemy 操作集中在这里 - `migrations/` 数据库迁移，由 alembic 生成，不要手动改 ## 硬性约定 - 异常统一抛 `AppError`，禁止裸 `raise Exception` - 日志使用 `logging.getLogger(__name__)`，禁止 `print` - `build/` 和 `.venv/` 是生成目录，永远不要修改 - 新增依赖必须更新 `pyproject.toml` 并在 PR 里说明原因 ## 已知的坑 - 本地 Redis 是弱依赖，测试里不要依赖真实 Redis - `app/utils/` 里的代码是历史遗留，新增逻辑不要放这里

这份模板每一条都是可以验证的具体规则，没有任何废话。写 CLAUDE.md 的核心原则就一条：每条内容都要能直接变成 Claude 的行动依据。比如"禁止裸 raise Exception"这种规则，Claude 完全可以照做；而"注意代码质量"这种表述则毫无价值，AI 无法把它量化成具体行为。

3.3 命令模板这么写，才不浪费上下文

命令模板的编写方法和 CLAUDE.md 类似，但更强调可执行性。优质命令的特点是：步骤明确、检查顺序固定、输出格式统一。

我以/test命令为例来说明设计思路。如果直接对 Claude 说"跑一下测试"，它会问你要跑哪些、用什么命令、不过怎么办，来回浪费好几轮。封装成命令后：

--- description: 运行项目测试并生成问题摘要 argument-hint: [可选] 指定测试文件或目录 allowed-tools: Bash, Read --- 1. 如果有参数，直接运行 `uv run pytest <参数> -q` 如果没有参数，运行 `uv run pytest tests/ -q` 2. 根据测试输出判断失败原因，是断言失败还是代码异常 3. 如果失败，进一步读取对应测试文件和被测代码 4. 输出总结：通过数 / 失败数 / 失败原因 / 建议修复方向

注意这里我把"失败后要读取对应代码"也写进了命令流程里。不写的话，很多情况下 Claude 只会把失败信息贴给你，不会主动去分析根因。一条命令就是一个完整的操作工作流，这是它和普通聊天最大的区别。

argument-hint字段也别忽略。当用户输入/test app/api/order.py时，参数会传给命令正文，Claude 就知道让它测指定文件。参数设计得越清晰，命令的适用范围就越广。

3.4 一键安装与多项目同步

模板仓库建好后，最烦人的问题是怎么分发到各个项目里。我一开始是手动拷贝，很快发现改模板时要同步好几个项目，非常容易漏。后来写了一个安装脚本，核心逻辑就是用软链接把仓库里的文件映射到对应位置：

#!/usr/bin/env bash # 同步 base 模板到用户级 ~/.claude 目录 set -euo pipefail REPO_DIR="$(cd "$(dirname "$0")" && pwd)" for f in "$REPO_DIR"/base/CLAUDE.md \ "$REPO_DIR"/base/commands/*.md \ "$REPO_DIR"/base/agents/*.md; do dest="$HOME/.claude/$(basename "$(dirname "$f")")/$(basename "$f")" mkdir -p "$(dirname "$dest")" ln -sf "$f" "$dest" done echo "模板已同步到 ~/.claude"

项目级的同步稍微有讲究。如果这个项目是你个人在维护，用软链接指回模板仓库就好；如果是多人协作仓库，我建议直接把.claude/目录提交进项目仓库，让所有人都用同一套配置。软链接的优点是一处修改处处生效，缺点是脱离模板仓库就没法工作；提交进仓库则恰好相反。两种方式按团队协作模式取舍，没有绝对的对错。

4. 实测跑通后的四个坑，每个都值得记一笔

4.1 模板越长，后面的对话越容易"失忆"

这是我踩过最深的一个坑。一开始我以为模板越详细越好，于是把团队 wiki、接口文档、部署手册全摘要进 CLAUDE.md，写到四百多行。用了一周发现效果反而变差——会话刚开始时 Claude 表现很好，但对话进行到中途，它开始出现"前后矛盾"的行为，比如忘记禁用 print 的约定，甚至开始建议我修改 build/ 目录下的文件。

后来我理解了原因：CLAUDE.md 的内容会驻留在整个会话的上下文里，占用的是宝贵的上下文窗口。模板越长，留给代码和对话内容的空间就越小；当上下文接近上限时，模型会倾向于优先保留最近的信息，早期的模板内容就被"挤出"了有效注意力范围。

解决方法很简单：CLAUDE.md 只保留最高优先级的规则，详细的技术文档和背景资料让 Claude 按需读取而不是常驻内存。比如"数据库操作必须走 repos/ 层"这种高频约束放 CLAUDE.md，"某个接口的完整字段说明"放在项目 docs 目录下，需要时命令里指定Read docs/xx.md就好。核心模板瘦身之后，会话稳定性明显恢复。

4.2 命令撞名与优先级

自定义命令多了以后，另一个问题是撞名。Claude Code 自带一批内置命令，如果你自定义的命令和内置命令重名，或者用户级命令和项目级命令重名，实际生效的可能是你不期望的那个。我有一阵子项目里突然不能用/init，排查了很久才发现是模板仓库里放了一个同名命令文件，把它盖住了。

团队场景这个问题更隐蔽。假设你分发了一套模板给团队，某个人自己又装了一套带review.md的命令模板，那么同一台机器上这个人的行为就和别人不一样，出现问题时很难复现。

我现在的做法是给自定义命令加业务前缀，比如ci-test、code-review、make-commit，尽量避免使用test、review这种过于通用的名字。同时在模板仓库的 README 里维护一张命令注册表，写明每条命令放在哪个作用域，让使用者一眼看出哪些是内置、哪些是自定义。

4.3 "必须"不等于"会执行"

模板里写着"永远不允许修改 build/ 目录"，但实际对话中 Claude 仍然可能在特定场景下动它。原因在于模型本质上是依据概率选择回复的，它遵循的是最近上下文的整体语境。用户说了"帮我清理一下项目空间"，它就可能把 build/ 当成可清理对象。

这不是模型"不听话"，而是提示词天然的局限性。模板是约定，不是纪律。对于真正不能出错的约束，需要用机制来保证。我在 settings 里加了钩子，当 Claude 试图通过 bash 命令修改受保护目录时，钩子直接拦截。另外自建了权限配置，把危险操作设为需要人工确认。把安全关键约束从提示词层下沉到机制层，这才是可靠的方案。

4.4 模板更新后，旧项目还在用老规矩

模板是活的东西，会跟着实践迭代。但如果你用拷贝方式分发模板，那么每次更新后，所有旧项目里的模板都是过期版本。我之前更新了代码评审命令的检查清单，结果发现只有最近新建的两个项目在用新清单，老项目依然执行旧流程。

解决方法是软链接分发，或者给模板文件加一个版本标记。我在 base/CLAUDE.md 的末尾加了一行template-version: 2.3.0，安装脚本里可以对比版本号，版本不一致就提示重新同步。另外注意一点：CLAUDE.md 的修改只对新开始的会话生效，已经在跑的会话不会热加载。改完模板后，记得新开会话再验证。

5. 进阶：让模板体系跟着项目一起长大

5.1 基础模板 + 项目覆盖层的组合模式

前文提到了base/和projects/的两级结构，实际使用中我还会在两者之间加一层"团队覆盖层"。基础模板管的是个人通用能力；团队覆盖层放的是团队特有的约定，比如提交信息规范、PR 描述模板、代码评审必须检查的清单；项目覆盖层再放具体技术栈的信息。

分层的好处是让模板适配不同粒度。你不会希望所有项目都背一份"提交信息必须包含 issue 编号"的规则，但如果团队统一要求，放到团队层就很合适。项目覆盖层只需要关心这个项目独有的架构和命令，内容更短，加载更快。三个层次叠加时注意优先级，最具体的项目层优先，避免冲突时规则打架。

5.2 从个人沉淀走向团队规范

当模板仓库从个人使用变成团队共享时，重要的是区分"硬规范"和"软建议"。硬规范是团队必须执行且可以自动检查的，比如测试必须通过、不允许使用明文密码、提交信息必须按格式；软建议是高效但不强制的要求，比如"推荐在 service 层做参数组装"。

区分这两类的标准很简单：违反硬规范会造成实际经济损失或事故，违反软建议只是降低代码质量。把硬规范写进 CLAUDE.md 并在 hooks 层做强制拦截，软建议留给角色模板和命令模板去引导。我见过一些团队把软建议当成硬规范写进模板，导致模板越来越长，Claude 的行为反而变得束手束脚——明明是一条"建议"，模型却当成"禁止"，连合理的变通都不敢做了。

另外，团队模板一定要有 owner。没有 owner 的模板仓库一周就会落伍，因为没人负责检查旧规则是否还适用、新实践是否需要沉淀。这个角色不能是"人人有责"，必须是具体某个人，哪怕只是每两周花半小时维护。

5.3 定期给模板"减脂"

模板不是越写越多就好。前面说过上下文窗口有限，每一条规则都有使用成本。我给自己定了一条规矩：每两周回顾一次模板里的每一条规则，凡是在实际对话记录中从未触发过价值的行为，直接删掉，或把详细版移到按需读取的文件里。

有一个非常典型的例子。我最早在模板里写了一大段关于 Python 版本兼容性的说明，后来发现当前项目根本没在 Py2 环境跑过，这条规则一次都没用上，反而每次会话都在占用上下文。删掉之后神清气爽。

经过两三个月的迭代，一个健康的模板通常会经历"膨胀-收缩-稳定"的过程：一开始什么都想写，后来发现真正高频生效的规则其实就那么二十来条，模板最终会收敛到一个比较精简的状态。这很像我日常代码重构里的"最简可维护集"思想——留下的一定是经过实践检验、真正影响行为的东西。

最后说一点我自己的感受。整理 claude-code-templates 这件事，本质上不是在调教工具，而是把团队里的隐性知识做了一次显性化。刚开始会有点痛苦，因为你会发现在这之前，很多约定从没有被写下来过。但一旦写下来，AI 变得好用只是副产品，最大的受益者其实是刚加入项目的人，以及三个月后的自己。我的建议是别追求一次到位，先放一条命令、一份项目说明，用起来之后再慢慢加。模板是活的东西，它不是配置文件的堆砌，而是你和你的工具之间越来越默契的语言。