企业官网建设流程全解析

这两年我在终端里跟 Claude Code 打交道的时间，比跟 IDE 打交道的时间还长。从刚开始的裸对话式调侃，到后来一点点摸索出模板化的工作流，效率差距绝对不是一两倍的事。这篇文章想聊的 claude-code-templates，就是把我最近沉淀下来的模板方法论、配置文件、踩坑记录全部摊开来讲。无论你是刚接触命令行 AI 编程的新手，还是已经在团队里推广 AI 辅助开发的老手，照着这套思路搭一遍自己的模板库，会有很直观的收益。

1. Claude Code 模板到底解决什么问题

1.1 没有模板时的工作痛点

先回顾一下没有模板的时候，我是怎么用 Claude Code 的。基本上每次新开一个项目，都得花五到十分钟敲一段长长的背景说明：这个项目什么技术栈、目录结构怎么组织的、代码风格要求是什么、测试框架用哪个、接口设计遵循什么规范。这些内容说一次两次还好，问题是每个会话都得重新说，每换一个项目又得重新说。

这还不算最痛苦的。痛苦的是同一个项目里，前后几次任务的执行标准经常不一致。比如我今天让它写一个接口，它按照习惯把错误处理放在了中间件里；明天我让它加一个接口，它又换成装饰器方案。你当然可以说这是 AI 的灵活性，但对一个正经项目来说，这种随机性就是灾难。代码审查的时候看到同一套风格的接口两套写法，血压直接拉满。

还有一个隐蔽的问题是上下文浪费。Claude Code 的上下文窗口是有上限的，你前面花大量 token 去解释背景，后面留给真正代码生成、调试分析的额度就被压缩了。项目越复杂，这种浪费越致命。聊到最后它经常忘了你最开始约定的命名规范，然后又得折回去重新强调，一轮轮下来，效率远低于预期。

1.2 模板的本质：把隐性约定显性化

后来我意识到，问题的根源不在于 AI 不够聪明，而在于我从来没有把"什么是这个项目的标准"用它可以持续读取的方式表达出来。人跟人协作的时候，团队有文档、有 Code Review、有口头约定，这些都是隐性的知识传递渠道。但跟 AI 协作，尤其是 CLI 环境下的 AI，它每次会话都是"失忆"的，唯一能让它稳定记住约定的方式，就是把这些约定写进模板，让它每次启动时强制加载。

打个比方，五星级酒店的厨房里做一道招牌菜，厨师不会每次开工都靠即兴发挥。后厨有一本标准作业手册，写清楚食材产地、切配尺寸、火候分钟数、摆盘方式。AI 编程也是一回事——没有模板，它每场都是新来的临时厨师，你每次都要从头盯；有了模板，它就等于先读完你后厨的作业手册，干出来的活至少是稳定在及格线以上的。

所以我把模板定位成"项目的地基文件"。它不是帮你生成代码的魔法，而是让每一次 AI 交互都站在同一个基准线上。代码风格、架构约束、测试要求、提交流程，这些原本只存在于你脑子里的东西，全部沉淀成显性的、可版本管理、可团队共享的文件。这才是模板的核心价值。

2. Claude Code 模板的三种核心形态

2.1 CLAUDE.md：项目级记忆文件

CLAUDE.md 是 Claude Code 默认会读取的项目级说明文件，放在项目根目录下。它相当于给 AI 的一份"入职手册"。每次会话启动时，它会被自动注入到上下文中，AI 在理解你的问题之前，已经先读完了这份文档。

我在实际使用中，会在这个文件里按优先级放这几类内容：项目概述和技术栈（不要写废话，两三行说清楚）、目录结构说明（让 AI 知道该去哪里找代码）、代码风格和命名规范（这部分要具体到能执行）、常用的构建测试命令、以及项目的特殊约束（比如不要动某个文件、数据库迁移必须走特定流程）。

这里要提醒一下，CLAUDE.md 不是越厚越好。我也见过有人把它写成两千行的项目百科全书的，结果 AI 读是读了，但真正干活的时候反而被无关信息干扰。我的经验是，只放那些"不按这个规矩做就会出问题"的内容，背景知识能不放就不放。上下文窗口是宝贵的，每多一行废话，就少一分给真正任务的余地。

2.2 自定义 Slash Command

如果说 CLAUDE.md 解决的是"背景一致"的问题，那自定义 Slash Command 解决的就是"流程复用"的问题。Claude Code 支持在项目里定义自己的斜杠命令，常见的调用方式就是 / 后面跟一个命令名，比如 /test、/review、/commit。每个命令背后其实也是一个模板文件，里面写好了这个操作的标准执行流程。

我最早开始用自定义命令，是因为发现每次让它"写测试"这件事，我都要反复叮嘱一堆要求：测试文件放哪个目录、命名规则是什么、覆盖率要达到多少、边界情况怎么考虑。后来我把这些全部写进一个命令模板里，之后只需要敲 /test 加一句"测试一下 auth 模块"，它就会自动按照模板里定义的标准流程执行。

这种形态还有一个很好的使用场景，就是团队规范同步。新成员加入团队，不需要口口相传教他"我们这边提代码是怎么提的"，直接把包含 commit 命令的模板仓库拉下来，他在任何项目里敲 /commit，输出的提交信息格式自然就是符合团队规范的。

2.3 项目脚手架模板

第三种形态是把模板做成完整的项目脚手架。这跟前面的区别在于，CLAUDE.md 和 Slash Command 是在已有项目里注入记忆和流程，而脚手架模板是从零开始搭建新项目时用的一整套基础配置。

我自己会为后端服务、前端工具库、命令行工具各维护一个脚手架模板。里面除了常规的 src、tests、docs 目录，还包括预先写好的 CLAUDE.md、.claude/commands 目录、Makefile、CI 配置样例。这样开新项目的时候，不再需要从 init 一步步搭，git clone 下来就已经是一个带完整 AI 协作配置的骨架工程了。

为什么要单独做这一层？因为我发现直接复制旧项目再删改，效率反而更低。旧项目里面有太多历史包袱，迁移的时候要么漏了配置，要么带入了一堆不相关的文件。而脚手架模板每次都是精心维护的干净起点，新项目从第一天起就有正确的目录结构和 AI 协作约定，后面少走很多弯路。

3. 从零搭建模板库的完整实操

3.1 第一步：盘点你真正的固定工作流

动手写模板之前，先别急着建目录。我建议花一两个小时，把你过去一两周使用 AI 编程的对话记录翻一遍，把所有"重复出现的要求"列出来。比如你是不是每次都会说"用中文注释"、"不要改公共接口"、"测试要覆盖边界条件"——这些就是需要模板化的候选对象。

我自己当时统计下来的结果很有意思，大部分重复需求其实集中在几个固定动作上：初始化新模块、补测试、做 Code Review、写提交信息、更新文档。真正随机的、需要临场发挥的任务反而是少数。这给了我一个很强的信号：AI 编程中 80% 的沟通成本是可以模板化的，而模板化之后我能把更多精力留给那 20% 真正需要创造力的部分。

列完清单之后，再按频率和影响程度排个优先级。不是所有场景都值得做成模板的，如果一个动作一个月只碰一次，写模板反而浪费维护成本。优先处理那些高频、且执行标准容易偏离的场景。

3.2 第二步：设计模板库的仓库结构

我先搭一个独立的模板仓库，目录结构是刻意设计过的，不要随意改动。

ai-templates/ ├── claude-code/ │ ├── base/ # 通用 CLAUDE.md 片段 │ │ ├── 01-style.md │ │ ├── 02-commands.md │ │ └── 03-workflow.md │ ├── stacks/ │ │ ├── go-api/ # 按技术栈拆分的脚手架 │ │ ├── python-lib/ │ │ └── frontend-vite/ │ └── commands/ # 可复用的自定义命令 │ ├── commit.md │ ├── review.md │ └── test.md ├── scripts/ │ ├── scaffold.sh │ └── sync-templates.sh └── README.md

这个结构的核心思路，是把"通用规范"和"特定技术栈"分开。通用的代码风格、Git 流程放在 base 下，任何项目都能直接引用；而 Go 项目专属的目录约定、测试写法放在 stacks/go-api 里，跟 Python 项目互不干扰。commands 目录里的自定义命令则是跨项目通用的动作模板，单独提炼出来方便同步更新。

3.3 第三步：编写一份克制但有效的 CLAUDE.md

我把我最常用的 base 版 CLAUDE.md 核心段落贴出来，这份文件大概 60 行左右，每个项目拿到后按需微调。

# Project Overview 这是一个基于 Go 的后端 API 服务，提供用户认证和资源管理能力。 技术栈：Go 1.22 + Gin + PostgreSQL + Redis。 # Directory Layout - cmd/server：服务入口 - internal/handler：HTTP 处理层，只做参数解析和数据返回 - internal/service：业务逻辑层，核心业务规则所在 - internal/repository：数据访问层，封装数据库操作 - internal/middleware：中间件，认证、日志、恢复 - internal/config：配置读取与校验 # Code Style - 使用官方 Go 风格，gofmt 格式化 - 错误处理使用 errors.Is/As，不在业务层裸返回 fmt.Errorf - 日志统一使用 log/slog，结构化输出，禁止 fmt.Println 调试 - 接口命名遵循 Resource + Action 模式，比如 CreateUser、ListUsers # Commands - 构建：go build ./... - 测试：go test ./... -race -cover - 生成接口文档：make docs # Constraints - 不要修改 internal/repository 下的数据表结构定义，除非明确说明 - 所有新增依赖必须经过确认 - 配置变更需要同步更新 example.env

注意这份文件的写法，每一条都是"可判定的"。什么叫可判定？就是 AI 在做完之后能自己检查对错。比如"代码风格使用 gofmt"，它写完就能跑一下验证；但如果你写"代码要优雅"，它没法判断，等于白写。所有约束都应该是这种可执行、可验证的规则。

3.4 第四步：定义一条可复用的自定义命令

接下来看一下 .claude/commands 下的自定义命令。Claude Code 的自定义命令本质上就是一个 markdown 文件，里面写的是触发这条命令后 AI 应该执行的完整流程。

以我最常用的 review.md 为例，文件内容长这样：

<review> 你是一名资深代码审查者。请审查当前分支相对主干分支的全部改动。 审查步骤： 1. 先 git diff main...HEAD 查看改动范围 2. 检查是否有调试遗留代码（console.log、fmt.Println、TODO 硬编码） 3. 检查新增代码是否遵循项目 CLAUDE.md 中约定的风格 4. 检查测试覆盖情况，对未覆盖的边界条件给出补充建议 5. 按严重程度输出问题列表：阻断 > 重要 > 建议 输出格式： - 【阻断】必须修复才能合并 - 【重要】建议本期修复 - 【建议】可后续优化 注意：只输出真实存在的问题，没有问题的项不要凑数。 </review>

命令模板里的指令写得越具体，AI 的执行效果越稳定。如果你只写"帮我 review 一下代码"，它不知道 review 的标准是什么，也不知道最终该输出什么样，结果经常是给你一篇不痛不痒的总结。而上面这个模板把执行步骤、检查清单、输出格式全部固定下来，它产出的就是一份可以直接拿去开评审会的审查报告。

3.5 第五步：建立跨项目的同步机制

模板搭好之后，下一步就是让它在多个项目里跑起来。我在每个实际项目里只保留一个软链接，指向模板仓库里对应的配置，这样改一份模板，所有项目自动生效。

# 这里假设项目在 ~/work/my-service 下 cd ~/work/my-service # 创建软链接目录 mkdir -p .claude ln -s ~/ai-templates/claude-code/base/01-style.md CLAUDE.md ln -s ~/ai-templates/claude-code/commands .claude/commands

用软链接最大的好处是避免了多副本漂移的问题。如果你每个项目都拷贝一份完整模板，一个多月后每个项目里的版本一定长得不一样，有人改了 A 项目忘了 B 项目，团队协作的时候规则就越走越偏。软链接把模板仓库当成唯一事实来源，谁要调整规则，改模板仓库然后推上去就行，每个项目下次启动 Claude Code 时自动读到新规则。

4. 真实场景拆解：一个 Go 后端服务的模板配置

4.1 从脚手架生成一个干净的新项目

拿我最近做的一个 API 网关项目来举例。我没有手动 mkdir 创建目录，而是直接跑了模板仓库里的 scaffold 脚本。

~/ai-templates/scripts/scaffold.sh go-api my-gateway

这个脚本做的事其实很简单：把 stacks/go-api 目录里的骨架复制到新项目目录，然后替换掉里面的模块名，再根据模板仓库里的 CLAUDE.md 生成一份新的项目级说明文件，最后初始化 git 仓库并做首次提交。

脚本执行完，新项目长这样：

my-gateway/ ├── CLAUDE.md ├── .claude/ │ └── commands/ │ ├── commit.md │ ├── review.md │ └── test.md ├── cmd/server/main.go ├── internal/ │ ├── config/ │ ├── handler/ │ ├── middleware/ │ ├── repository/ │ └── service/ ├── tests/ ├── Makefile ├── go.mod └── example.env

注意这里 CLAUDE.md 已经包含了 go-api 技术栈的默认约定，比如目录职责说明、错误处理规范、测试要求。新项目的第一行代码还没写，AI 协作时的"背景知识"就已经齐了。

4.2 开发环节：让模板约束架构边界

开始写第一个接口的时候，我跟 Claude Code 的对话是这样的：

请在 internal/service 下实现用户注册的业务逻辑，先调用 repository 层查询用户是否存在，再创建新用户并返回。

单看这个问题，如果没有 CLAUDE.md 的约束，AI 很可能顺手就把数据库查询逻辑写在 service 里了，或者直接封装一个 ORM 调用。但因为 CLAUDE.md 里明确界定了各层职责，它知道 repository 层才是数据访问的唯一入口，所以会先在 repository 里补一个 FindByEmail 方法，然后在 service 里编排调用。

这种边界约束特别有价值。架构腐化往往就是从"这次图省事跨层调用一下"开始的，一次两次看不出问题，三个月后整个项目就变成一锅粥。模板把架构规则变成 AI 的默认行为，等于多了一个永远不用睡觉的架构评审员。

4.3 测试环节：用模板统一测试标准

项目里的测试命令模板长这样，每次让 AI 补测试，只需要敲 /test 加需求描述：

<test> 请为指定的功能编写单元测试。 要求： 1. 测试文件放在 tests/ 目录，命名格式为 xxx_test.go 2. 使用 go stdlib testing 包，不引入额外断言库 3. 每个测试函数必须包含：正常路径、失败路径、边界条件 4. 涉及 HTTP 接口的测试使用 httptest 5. 模拟依赖使用内嵌 mock 接口，不 mock 具体实现细节 6. 写完测试后运行 go test ./... -race -cover，报告覆盖率 </test>

我之前最常遇到的"AI 写测试走过场"问题，被这个模板基本根治了。过去我让它写测试，它经常只写两个 happy path 就交差了，覆盖率惨不忍睹。模板里要求的"三个路径"把测试设计的标准量化为硬性要求，它提交的测试代码明显扎实很多，我只需要偶尔补几个它理解不到位的业务边界场景。

4.4 提交与审查：让产出符合团队规范

最后看提交流程。我在模板仓库里的 commit.md 做了这样的约束：提交信息按照 Conventional Commits 规范写，且必须在提交前运行 lint、test、build 三个命令，有任何失败都不能提。

<commit> 请根据当前暂存区的改动生成提交信息。 格式要求： - type(scope): subject 的 Conventional Commits 格式 - type 可选：feat、fix、refactor、docs、test、chore - scope 使用模块名，比如 auth、gateway、config - subject 不超过 50 字符，用现在时态 提交前检查： 1. 运行 go vet ./... 2. 运行 go test ./... -race 3. 运行 go build ./... 4. 以上任一步失败，先修复再提交 </commit>

这个模板特别适合团队协作的场景。不同成员用同一个模板生成的提交信息，格式高度统一，后续回溯 git history 的时候体验极其顺畅。而且"提交前必须先通过质量检查"这条约束，相当于把 CI 的左移，很多低级问题在提交前就被 AI 自己修掉了，而不是等到流水线里报红再返工。

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

5.1 模板不生效：先分清是读取问题还是优先级问题

遇到过好多次用户跑来问"我写了 CLAUDE.md 但 AI 好像没读"，排查下来大多数情况是两种情况。一是文件路径不对，Claude Code 只读取特定位置的 CLAUDE.md，你放在子目录或者改了文件名，它自然找不到。二是文件里存在格式问题，比如手写了一些奇怪的字符或者 markdown 结构嵌套错误，导致解析中断。

还有一个优先级问题容易被忽略：如果项目里同时存在多个 CLAUDE.md（比如根目录一个、子目录一个），Claude Code 对子目录的文件的优先级更高。这本来是做模块级定制用的，但如果你不小心把通用规范放在子目录里，它在处理其他目录的任务时就读不到那些约束了。我的建议是通用规范放根目录，子目录只放该模块特有的补充说明。

5.2 上下文膨胀：模板太长让 AI 抓不住重点

模板越多越大，AI 的性能反而下降，这是我见过最普遍的错误。有一个项目方负责人把整个技术规范文档全塞进 CLAUDE.md，六个章节八千多字，结果 AI 写出来的代码反而更失真，不仅没遵守规范，连基础的功能实现都开始出现偏差。

原因是上下文窗口里塞了太多低价值信息，压缩了真正用于推理和生成的空间。模板要遵循"高频优先、规则优先、可验证优先"的原则。那些一年才用一次的配置说明、大段的背景故事、详细的历史决策记录，都不该出现在模板里面。真到了需要的时候，你可以临时把细节丢进对话里，而不是让它们长期占据上下文。

5.3 模板过度设计：为不存在的问题写模板

还有一种情况是反过来，模板做得太多太细，最后反而没人用。我见过一个团队维护了七十多个自定义命令，结果成员真正高频使用的只有四五个，剩下的绝大多数命令从创建那天起就没被触发过。

每个模板都是有维护成本的，它需要更新、需要测试、需要确保在新版本 Claude Code 下还能正常工作。一个模板如果三个月都没被用过一次，它的存在大概率只是心理安慰。我建议做减法：保留高频且标准明确的场景，其他的宁可临时现场布置，也不要急着模板化。模板库是要持续维护的资产，不是纪念品陈列架。

为了帮你自查，我把排查方式整理成了一张速查表。

我在实际维护模板库的过程中，最大的体会是：模板的本质是降低沟通熵，而不是给 AI 增加新的约束枷锁。好的模板系统，使用者甚至感受不到它的存在，只会觉得这个 AI 助手"特别懂这个项目的规矩"。而要做到这一点，靠的不是堆砌更多的模板，而是持续精简、持续对齐真实工作流。建议你先搭一个最小闭环，哪怕只有 CLAUDE.md 加两三个常用命令，跑两周看看哪些地方顺了、哪些地方还很别扭，再迭代一版，这个从实践中长出来的模板库，会比任何从网上抄回来的一整套配置都更贴合你自己的场景。