企业官网建设流程全解析

用Claude Code写代码有一阵子了，最大的体感是：这玩意儿确实能干活，但前提是你得先把它“喂饱”。我所谓“喂饱”，不是让它多读几遍代码，而是给它一套完整的项目上下文和一套可复用的工作指令，否则每次对话都要从“这个项目用了什么框架、测试跑什么命令、代码风格是什么”开始解释，效率大打折扣。为了解决这个问题，我把平时积累的初始化配置、角色提示词、命令模板整理成了一个仓库，叫 claude-code-templates，这篇就来聊聊这个仓库是怎么搭起来的，以及每一类模板背后有哪些值得留意的细节。

这个仓库解决的不只是“少打字”的问题，它让 AI 编程助手从一个“偶尔靠谱的实习生”变成一个“了解项目规矩的老同事”。适合正在重度使用 Claude Code、或者准备在日常开发里引入终端型 AI 助手的朋友参考，尤其推荐给那些需要在多个项目之间来回切换的人。

1. 模板体系全貌：claude-code-templates 到底解决什么问题

1.1 没有模板时的典型痛点

先说我最早期的状态。大概在第三周左右，我发现自己每天在 Claude Code 里反复输入同样一些话：

• “这个项目是 FastAPI + SQLAlchemy，模型在 app/models 下，路由在 app/api 下”
• “测试用 pytest，配置文件在 pyproject.toml，跑测试的命令是 pytest tests/ -x”
• “不要动 migrations 目录下的文件，自动生成的迁移我自己审”
• “改动之后跑一下 ruff 检查，风格按 Google Python Style Guide 来”

这些话本身不复杂，但每个项目都要说一遍就非常消耗耐心。更麻烦的是，Claude Code 记不住上次会话的对话历史，重新开一个会话就得从头说一遍。我试过把上面这些信息塞进代码仓库的 README，但 Claude Code 默认不会主动去读 README，而是靠用户输入和代码库扫描获取信息。于是每次会话的前十分钟都在“重新介绍项目”，真正开始写代码反而是十分钟之后的事。

1.2 模板体系的三层拆解

claude-code-templates 这个仓库的核心理念，是把“告诉 AI 怎么干活”这件事拆成三个层面，分别对应不同的生命周期和加载时机：

• 项目级模板：以 CLAUDE.md 为核心，放在项目根目录，每次会话自动加载。承载的是“这个项目是什么、怎么跑、有哪些规矩”这类长期稳定的信息。
• 会话级提示词模板：以各种角色和工作流 prompt 为主，在需要的时候手动调用，比如“代码审查”“生成测试”“重构某个模块”。承载的是“这次任务你要扮演什么角色、关注什么点、输出什么格式”。
• 命令级模板：通过 .claude/commands 目录配置自定义斜杠命令，把上面两种模板封装成/review、/test、/refactor这样的快捷指令，配合 Claude Code 的权限控制、钩子机制（hooks）使用。

这套分层设计和人带新人的逻辑很接近：新人入职先看团队手册（CLAUDE.md），具体任务有 SOP 文档（提示词模板），执行过程中的例行检查有 Checklist（slash 命令）。三层各司其职，缺了哪一层都会觉得别扭。

1.3 模板叠加使用的实际效果

三份模板叠加之后，一次会话的开场会变得非常高效。比如我做代码审查：

• CLAUDE.md 告诉 AI 这个项目的技术栈、目录结构、测试命令和迁移文件的处理规则；
• /review命令告诉 AI 审查的范围、关注点（数据一致性、边界条件、性能隐患）和输出格式（按严重程度分级列出，每条附带修改建议）；
• 会话中我再补一句“重点看 user_service 这次提交”，AI 就能立刻进入工作状态，而不是先把整个项目扫描一遍再问我“您希望我做什么”。

这套体系跑通之后，我明显感受到一个变化：AI 的回答质量从“泛泛而谈”变成了“贴着项目实际说事”。原因很简单，模板给了它足够的地基，它就不需要靠猜测来补足上下文。

2. 项目级模板：CLAUDE.md 的结构化写法与加载机制

2.1 CLAUDE.md 到底放在哪里、什么时候被加载

Claude Code 支持三个层级的 CLAUDE.md 文件：

• 用户级：放在~/.claude/CLAUDE.md，所有会话都会加载，适合放通用的工作偏好，比如“代码必须附带测试”“不要主动修改 lock 文件”“提交信息按 Conventional Commits 写”。
• 项目级：放在项目根目录的CLAUDE.md，进入项目时自动加载，适合放项目的技术栈、目录结构、常用命令、代码风格约定。
• 子目录级：Claude Code 会按照读取顺序，可能访问到子目录里的CLAUDE.md，适合放某一模块的特定说明，比如backend/CLAUDE.md只描述后端部分。

我自己实际用的最多的是用户级和项目级两层。用户级模板给了 AI 一套统一的“职业素养”，项目级模板给了它每个项目的“具体岗位描述”。两层的优先级是叠加的，用户级先加载，项目级补充，后定义的规则会覆盖或细化前面的规则，所以不用担心冲突。

2.2 一份实用的项目级 CLAUDE.md 结构示范

直接给你看一个我为 FastAPI 项目准备的 CLAUDE.md 模板，这份模板目前在我的仓库里，拿过去改改就能用。

# 项目：User Service（用户中心服务） ## 技术栈与目录 - 框架：FastAPI + SQLAlchemy 2.0 + Alembic - 语言版本：Python 3.11 - 目录约定： - `app/api/`：路由层，只做参数校验和响应组装 - `app/services/`：业务逻辑层，核心逻辑都在这 - `app/models/`：SQLAlchemy 模型定义 - `app/repositories/`：数据访问层，查询逻辑封装 - `tests/`：测试目录，结构和 `app/` 保持镜像 ## 常用命令 - 本地启动：`uvicorn app.main:app --reload` - 跑测试：`pytest tests/ -x -q` - 代码检查：`ruff check .` - 生成迁移：`alembic revision --autogenerate -m "desc"` - 执行迁移：`alembic upgrade head` ## 代码风格 - 类型注解必须完整，禁止 `Any` 裸奔 - service 层异常使用自定义业务异常，由全局异常处理器转换 HTTP 状态码 - repository 层只做数据操作，不写业务判断 ## 特殊约定 - 不修改 `migrations/` 目录下已经提交的迁移文件 - `app/core/config.py` 的配置项由运维平台下发，本地开发读 `.env` - 所有对外接口的返回结构统一为 `{code, message, data}` 包装格式

这份模板的关键在于“每一条都指向一个可验证的事实”。技术栈、命令、目录约定，全部是 AI 在编码时真的会用到的信息。我见过很多人把 CLAUDE.md 写成项目述职报告，大段大段描述业务背景，但对 AI 来说最有用的是“怎么跑、代码放哪、别碰什么”。

2.3 写 CLAUDE.md 的三个注意点

第一，不要超过 120 行。Claude Code 的上下文窗口再大，CLAUDE.md 也只是入口之一，太长会挤压真正的对话空间。如果项目内容多，就拆成子目录级的 CLAUDE.md，或者在主文件里写“更多细节参见docs/architecture.md”，让 AI 按需去读。

第二，用祈使句，不要用描述句。与其写“项目使用了 PostgreSQL 数据库”，不如写“数据库连接串从环境变量 DATABASE_URL 读取，本地默认连 5432 端口的 postgres”。前者是静态信息，后者是可执行指令。

第三，把“禁忌”单独列一节。AI 编程助手的一大特性是“过度主动”，你不告诉它哪些不能碰，它就会碰。比如不修改迁移文件、不动锁文件、不改第三方库的代码，这些规则一定要白纸黑字写出来。

3. 可复用提示词模板：角色、任务和输出格式的固化

3.1 为什么提示词模板比临场发挥稳定

我过去也喜欢临场写提示词，但慢慢发现一个问题：同一类任务，状态好的时候提示词写得好，AI 输出质量就高；状态差或者赶时间的时候，提示词写得潦草，AI 就开始自说自话。这类不确定性在编程任务里是非常致命的——你不想跟一个“今天心情不佳”的 AI 合作写涉及资金计算的代码。

于是我把高频任务全部固化成了提示词模板。每个模板都包含四个要素：

• 角色定义：告诉 AI 它现在是谁，比如“资深后端工程师”“测试架构师”“代码重构专家”；
• 任务现场：给出文件路径、改动范围、已知约束；
• 执行步骤：把任务拆成 3～5 步，让 AI 按顺序做，而不是一次输出一个大杂烩；
• 输出格式：规定最终交付物的结构，比如“代码 diff + 说明 + 测试建议”。

3.2 一个完整的代码审查提示词模板示例

这是我仓库里最常用的一份模板，用 Custom Slash Command 封装成了/review：

你是资深后端工程师，请对下面的代码变更进行审查。 ## 审查范围 - 变更文件：{files} - 关联提交：{from_commit}..{to_commit} ## 审查关注点 1. 数据一致性：是否有并发写入、事务边界缺失、脏读风险 2. 边界条件：空值、超长输入、重复请求、权限绕过 3. 性能隐患：N+1 查询、循环内调用外部服务、无索引查询 4. 可维护性：命名是否表意、是否有重复逻辑、是否违背单一职责 ## 输出格式 按以下 Markdown 结构输出： - 风险等级：P0（必须修）/ P1（应该修）/ P2（建议修） - 位置：文件 + 行号 - 问题描述：一句话说清楚 - 修改建议：给出具体代码片段 ## 约束 - 不要修改任何文件，只做审查分析 - 拿不准的地方标注“存疑”，不要强行下结论

用{files}和{from_commit}..{to_commit}这类占位符，是因为我不想为每次审查都新建一个模板文件，只需要在调用的时候填入实际值。Claude Code 的 slash command 支持在命令里引用当前会话上下文，所以我通常是先选中文件或者告诉它“看这两个 commit”，然后斜杠调用命令。

3.3 模板的迭代与沉淀

我一开始写了六个角色模板：代码审查、测试生成、重构、文档编写、Bug 定位、性能分析。跑了一段时间之后，测试生成那份模板用得最多，因为每天写新接口都要配套测试。重构模板次之。文档编写模板反而很少用，因为 Claude Code 生成的文档经常跟实际代码脱节，后期还要人工核对，不如直接让它根据 diff 写 commit message 来得实在。

所以模板仓库是要做减法的。不要把什么都塞进去，而是让真正高频、真正稳定的任务沉淀下来。每周回头看一次，哪个模板用了不到两次，就考虑删掉或者合并。留下一堆吃灰的模板，不仅浪费仓库空间，还增加调用时的选择成本。

4. 命令级自动化：.claude/commands 与 settings.json 配置

4.1 用 slash command 把提示词变成一条命令

CLAUDE.md 负责让 AI “懂项目”，slash command 负责让 AI “快速进入某个工作状态”。Claude Code 支持在项目根目录下创建.claude/commands/目录，目录下每个 Markdown 文件对应一条斜杠命令，文件名前面带一个名称，比如review.md，调用时的格式是/review。

文件内容就是我们上文看到的提示词模板，但多了一个前置区域，用 YAML front matter 来描述命令的基本信息：

--- description: Code review for current changes argument-hint: [optional args] allowed-tools: Bash(git diff:*), Read ---

description字段会在你敲/的时候出现在候选列表里，方便快速识别。allowed-tools字段非常实用，它限定了这条命令在执行时能用到哪些工具。比如我的/review命令只允许它跑git diff，不允许它直接改文件，这样就从机制上杜绝了“审查着审查着顺手改了代码”这类失控操作。

4.2 我的常用 commands 目录清单

我目前的.claude/commands/目录长这样：

• review.md：代码审查，只读不改
• test.md：为指定文件生成测试，输出 pytest 风格的测试代码
• refactor.md：重构指定模块，要求先列计划再执行
• commit.md：根据 git diff 生成 Conventional Commit 格式的提交信息
• explain.md：解释某段代码的逻辑，要求逐行拆解并绘制流程图（用文字描述）

每一条命令内部都遵循同一套结构：角色定义、任务现场、执行步骤、输出格式、约束条件。这样当我需要临时手动补充说明的时候，AI 也知道在哪个环节插入，而不是把补充信息当作整体指令的一部分，导致后面的步骤全部跑偏。

4.3 settings.json 的关键配置项

除了命令级的工具权限控制，Claude Code 还提供了全局级的settings.json，它决定了 AI 在会话中的基础行为边界。我的配置里比较重要的几个字段：

{ "permissions": { "defaultMode": "acceptEdits", "allow": [ "Bash(git status)", "Bash(git diff)", "Bash(pytest tests/*)", "Write" ], "deny": [ "Bash(rm -rf *)", "Bash(git push --force)" ] }, "hooks": { "PostToolUse": [ { "matcher": "Write", "hooks": [ { "type": "command", "command": "python scripts/check_style.py" } ] } ] } }

permissions.allow和permissions.deny控制 AI 能执行哪些操作。我的原则是“默认给最小权限，按需放权”。比如它跑测试命令我允许，但它不能用rm -rf这种破坏性命令，也不能强制推送 git。hooks字段用于在 AI 执行完某个动作后自动触发自定义脚本，比如每次写完代码自动跑一遍风格检查，如果检查不过就不再继续，尽量把低级问题挡在提交之前。

4.4 命令和模板的联动场景

命令级模板真正发挥威力，是在多个命令串联成一个工作流的时候。举个例子，我一个常见的开发循环是：

1. 写完代码跑/test生成测试文件
2. 跑一遍pytest看是否通过
3. 通过之后跑/review做一次代码审查
4. 根据 review 的结果修改问题
5. 最后跑/commit生成提交信息

这套流程平时要切换多个工具、多轮对话，现在基本在一个终端里完成。每个模板各自负责一段，组合起来就是一个完整的“本地闭环”。这比单独依赖任何一个提示词模板都要可靠得多，因为每一步的输入输出都由命令模板限定了格式，AI 没有机会自由发挥到别的地方去。

5. 工作流模板：从计划到执行的完整闭环

5.1 计划先行模板：让 AI 先动脑再动手

我用的最多的一个工作流模板，是“计划先行”模板。它强迫 AI 在动手改代码之前，先输出一份具体的实施计划，等我确认之后才开始写代码。这个模板对应的提示词大概是：

你是这个项目的核心维护者。你的任务是为下面这个需求输出一份实施计划。 需求：{requirement} ## 计划输出要求 1. 涉及文件清单：列出需要新增、修改、删除的文件 2. 每项改动的内容描述：一句话讲清楚在哪个文件做什么 3. 依赖关系：哪项改动必须在哪项之前完成 4. 测试策略：如何验证这次改动没有引入回归 5. 风险点：列出你判断可能出问题的地方 ## 约束 - 不要写代码，不要执行命令，只输出计划 - 如果你发现需求本身有歧义，直接列出你的疑问再给计划

这个模板帮我挡住了很多次“AI 自嗨式开发”。最典型的一次，它想通过改数据库全局配置来解决一个只在特定租户出现的慢查询，如果直接动手，影响面会波及所有租户。用计划模板之后，它先把方案列出来，我一眼就看出了问题，直接驳回去让它换个思路。没有模板的情况下，这轮返工至少要浪费半小时。

5.2 自动化验证模板：提交前必跑的检查清单

第二个常用工作流是“提交前检查”。我把这个封装成了/shipit命令，执行时会依次做：

• 运行 lint 并修复风格问题
• 运行全部测试并汇总结果
• 根据 git diff 检查是否有遗漏的调试代码（比如print、console.log、临时断点）
• 检查依赖变更（如果有poetry.lock或package-lock.json的变动，会提醒我手动确认）
• 输出一份提交建议，包括改动摘要和 commit message

这个命令配置了相对严格的工具权限，允许它运行测试和 lint，但不允许它自动 commit。我吃过亏，早期让它自动提交，结果它把一份还带着 TODO 注释的代码直接推了上去，幸好只推到了本地分支。从那以后，所有自动化流程都止步于“生成建议”，最后一步永远是我自己来。

5.3 多步骤任务的分阶段模板写法

如果需求本身比较大，比如“给整个模块补充单元测试”“把旧的 REST 接口迁移到 GraphQL”，我会在模板里按阶段拆分：

• 阶段一：摸清现状，输出数据流和依赖图
• 阶段二：小步重构，每完成一步都跑测试确认不回归
• 阶段三：统一验证，跑全量测试 + lint + 类型检查

每个阶段在模板里都有独立的“完成判定标准”，AI 必须确认上一阶段的输出符合标准，才能进入下一阶段。这种做法有点像 Git 里的提交粒度控制——每次改动尽量小、可验证，不要攒一个巨型改动一次性提交。分阶段模板对 Claude Code 这种模型型 AI 特别合适，它一旦收到“做完所有事再汇报”的指令，容易在长链路任务的后半段忘掉前文的约束。

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

6.1 模板不生效：CLAUDE.md 没有被自动读取

有朋友问过我：“为什么我的 CLAUDE.md 写了，但 AI 好像没按里面的规矩来？”这个问题最常见的原因有四个：

• 文件命名不准确，Claude Code 只认CLAUDE.md，用claude.md或者CLAUDE.txt都不行。
• 文件放在子目录里，但会话的工作目录在上级目录，AI 没有往下找。
• 会话是从别的项目目录打开的，加载的是那个项目的 CLAUDE.md。
• 会话过程中手动切换过工作目录，导致上下文丢失。

排查思路很简单：会话刚开始的时候让 AI 复述一下项目规则，看它能不能说出来。说不出来，说明文件没被加载；能说出来但执行时“明知故犯”，那就是提示词的优先级冲突，比如用户级 CLAUDE.md 的规定和项目级互相矛盾。

6.2 上下文超长：模板写太多反而拖慢响应

CLAUDE.md 和命令模板加在一起，很容易把上下文撑爆。尤其是每个命令模板都写了一大段“你是资深某某某”的开场白，一次对话塞十个这种模板，AI 的上下文里全是重复的角色描述。

我的解决办法是控制模板体积：角色描述统一控制在两三句话内，把篇幅留给真正影响输出质量的“步骤”和“约束”。另一个办法是使用#注释，把模板内部的小标题写得精简，让 AI 在不相关的时候直接跳过。上下文超长还有一个表现是“AI 开始重复之前的内容”，如果你发现它在回答里反复提到同一个文件、同一个函数，基本就是上下文快撑不住了。

6.3 命令工具权限卡得太死导致任务卡住

allowed-tools这个字段限制得太严格，也会带来问题。比如我的/test命令一开始只允许Read和Write，结果 AI 发现需要先装一个测试依赖才能跑测试，命令没权限执行Bash(pip install *)，只能绕来绕去。最后我在命令里加了一条宽限规则，允许它在确认依赖缺失时执行安装命令，但强制它在执行前先输出“正在安装依赖：xxxx”这样的提示。这样既给了它必要的自由度，又保证了操作的可追踪性。

6.4 多个模板相互覆盖导致行为不一致

当用户级 CLAUDE.md 说“所有异常处理器都放全局文件”，项目级 CLAUDE.md 说“异常处理器按模块就近存放”的时候，AI 就会陷入混乱，有时候按这个来，有时候按那个来。

解决方式是在用户级模板里加一条总规则：项目级 CLAUDE.md 优先于用户级。所有项目级文件开头都写一句“本文件规则覆盖用户级默认约定”，这样 AI 在任何项目里都能正确解析规则优先级，不会再出现同一个操作在两个项目里行为不一致的情况。

6.5 模板里夹杂着过多“演示”内容导致失焦

有些模板为了展示效果，会把例子写得很长，比如在代码审查模板里贴了一段示例 diff。AI 看到这段示例 diff 之后，很容易把示例当成真实待审查内容，导致输出分析示例而不是分析实际代码。

因此我在模板仓库里定了一个规矩：示例一律放到examples/目录，正文模板里只保留占位符和指令。这样既方便复制参考，又不会被 AI 误读成上下文的一部分。

7. 模板库的日常维护与后续扩展

claude-code-templates 发展到现在，已经不只是一个配置文件集合，更像是我和 AI 协作方式的沉淀。每次遇到一个反复出现的新任务类型，我会先记录下当时的提示词，看它的核心逻辑是什么；用完之后复盘一次，哪些步骤是多余的、哪些约束没起作用，然后调整模板进仓库。这种迭代方式一开始比较慢，但积累到几十个文件之后就明显感觉到“边际收益递减、边际可靠性递增”——新模板带来的增量产出在变少，但已有模板的质量在稳步变高。

目前我还在尝试的扩展方向是 MCP 工具协议和模板的配合，比如通过 MCP 接入项目管理工具，让 Claude Code 在写代码的同时能查询需求状态、自动关联任务。这类扩展目前还在试验阶段，我自己的体会是：模板的核心价值不在于“让 AI 更聪明”，而在于“让 AI 少做无用功”。只要把信息加载、角色定义、约束边界这几件事做好，工作流就已经比大多数裸奔状态高效好几倍。

个人的最后一条建议是：模板库不要追求大而全，准确比丰富重要得多。一个只包含三条规则但每条都精确执行的 CLAUDE.md，效果一定好过一份写了五十条规则但 AI 根本无暇细读的说明书。先跑起来，再随着使用频率不断修正和删减，这才是一条走得通的路线。