企业官网建设流程全解析

刚开始用 Claude Code 的时候，我跟绝大多数人一样，直接在终端里敲一句话让它帮我写代码、改 bug。用着用着就发现不对劲：每次开新会话，它都不认识我项目的结构，不知道我的代码规范，连测试命令都要我重新说一遍。直到我认真折腾了claude-code-templates这套模板体系，才算是真正把 Claude Code 用顺了。这篇东西就是我自己在项目里沉淀下来的模板设计思路、可直接抄的配置文件和踩坑记录，希望能让你少走点弯路。

1. 为什么需要一套 Claude Code 模板体系

1.1 没有模板时的真实痛点

先说一个很常见的场景。你的项目可能是一个 Spring Boot 后端，或者一个 Next.js 前端，里面几十个目录、几百个文件。你让 Claude Code 帮你加一个接口，它默认会怎么做？它会先扫描整个项目结构，猜测哪些文件是 controller、哪些是 service，然后按照它“觉得对”的方式去改。如果项目结构和它预设的模式不一样，它就会把代码写进错误的地方，或者生成一堆和你现有风格完全不搭的代码。

这还不是最烦的。更烦的是，每个新会话都要重新交代背景：这个项目的构建命令是npm run build，测试要跑pytest，代码里日期格式必须用yyyy-MM-dd，数据库迁移文件放在哪个目录……你交代过一次，第二次开新会话它又忘了，因为对话上下文根本不共享。这个问题在团队协作里更明显——不同成员用同一个 AI 工具，出来的代码风格五花八门，review 的时候能气死人。

1.2 模板体系到底解决了什么

claude-code-templates本质上是一套“规则注入”的方案。它把项目的背景信息、编码规范、常用工作流、命令封装成固定的模板文件，放在项目目录里。每次 Claude Code 启动时会自动加载这些规则，于是它从第一句话开始就“知道”自己在一个什么样的项目里、应该按什么方式干活。

这套东西能带来几个非常直接的好处。第一是会话间的“记忆力”，你不必每次重复描述项目背景；第二是输出的一致性，同一套模板让 AI 在不同时间、不同人手里产出的代码风格趋同；第三是可复用性，新项目克隆过来，把模板目录复制进去，立刻就有了一套标准化的 AI 助手行为准则。我个人的体会是，配好模板之后，Claude Code 的可用性提升至少两个档，它从一个“偶尔聪明偶尔犯浑的对话机器人”，变成了一个真正懂你项目的协作者。

1.3 适用场景和读者画像

如果你符合下面任一情况，这套模板体系值得你花半小时配置一下：每天要开好几个 Claude Code 会话处理同一个项目的人；在团队里推行 AI 辅助编码、希望统一规范的技术负责人；维护多个项目、不想每个项目都重新调教 AI 的独立开发者。当然，如果你只是拿 Claude Code 写几个一次性脚本，那确实没必要折腾，直接对话就完了。下面说的所有内容，都是针对“把它当长期工具使”的场景。

2. 模板体系的整体设计：目录结构与分层思路

2.1 先看懂官方加载机制

动手写模板之前，得先理解 Claude Code 是怎么读取规则的。它有几个主要的配置层级：CLAUDE.md放在项目根目录，是项目级指令文件，只要在这个项目里启动 Claude Code，它就会自动加载；~/.claude/CLAUDE.md放在用户主目录，是全局级文件，所有项目都会加载；项目根目录下的.claude/commands/和.claude/agents/则用来存放自定义命令和子代理的定义。

这些文件彼此之间是叠加关系，不是替换关系。也就是说，全局规则会加载，项目规则也会加载，两者并行生效。这就给了我们一个很好的分层设计空间：全局文件放那些“不管什么项目都适用的通用偏好”，项目文件放“只有这个项目才需要的特定规则”。另外官方也支持在CLAUDE.md里用相对路径引用其他文件，比如@docs/architecture.md，这个机制可以用来拆大文件，避免一个文件塞得满满当当。

2.2 我的模板目录结构长这样

下面是我自己项目里实际在用的目录结构，你可以直接参考：

project-root/ ├── CLAUDE.md ├── CLAUDE.local.md ├── .claude/ │ ├── commands/ │ │ ├── code-review.md │ │ ├── test.md │ │ ├── commit.md │ │ ├── changelog.md │ │ └── api.md │ ├── agents/ │ │ └── backend-architect.md │ └── settings.json └── docs/ ├── architecture.md └── coding-standards.md

CLAUDE.md是核心入口，内容以“简短、高频、稳定”的信息为主，比如项目简介、常用命令、目录职责。CLAUDE.local.md是个人层面的本地规则，通常不进版本库，放一些只属于你自己的偏好，比如“回答时多用中文”“不要主动提议重构”。docs/下的两个文件是被CLAUDE.md通过@引用的大文档，放架构说明、编码规范这类低频但重要的内容，需要时再让 AI 去读，避免每次会话都消耗太多上下文窗口。

2.3 为什么这样分层

这么设计的核心逻辑是“渐进式上下文加载”。我见过很多人的CLAUDE.md写得跟百科全书一样，五千字的规范全塞进去，结果 Claude Code 每次会话的开销巨大，而且重点信息被淹没。正确的思路是：高频且短小的指令直接写在CLAUDE.md里，让 AI 每轮都看得到；低频但重要的资料放在被引用的文档里，AI 在需要的时候自己去读，用不上就不读。这就像一个团队的 onboarding 手册：新人第一天只需要知道打卡时间和工作地点，没必要把公司全套规章制度背下来。

另外要提醒一句：.claude/settings.json这个文件可以用来配置权限，比如哪些工具需要用户确认，哪些目录允许 AI 读写。我建议在多人协作项目里把需要确认的操作列进去，避免 AI 自动改了一堆不该改的文件。这个文件本身也是模板体系的一部分，别忽略它。

3. CLAUDE.md 项目指令模板：可直接抄的版本

3.1 完整模板示例

这是我从多个项目里提炼出来的一套还算通用的CLAUDE.md，你可以根据自己项目的情况增删。注意，这不是让你照抄，是为了让你看到结构：

# 项目：订单管理系统（Order Service） ## 项目简介 这是一个基于 Spring Boot 3 + MyBatis Plus 的微服务，负责订单的创建、支付回调、状态流转。前端仓库另见 order-web，本仓库只处理后端逻辑。 ## 常用命令 - 本地启动：./mvnw spring-boot:run -Dspring-boot.run.profiles=dev - 运行全部测试：./mvnw test - 运行单个测试：./mvnw test -Dtest=OrderServiceTest - 代码检查：./mvnw spotless:check - 打包：./mvnw clean package ## 目录职责 - controller/：HTTP 接口层，只做参数校验和响应封装 - service/：业务逻辑层，事务在这里控制 - mapper/：MyBatis 接口，SQL 写在对应 XML 中 - domain/：实体类与领域模型 - common/：通用工具、异常、常量 ## 编码规范 - 类名、方法名使用驼峰，常量使用大写加下划线 - controller 层统一返回 Result<T> 结构，错误码见 ErrorCode 枚举 - Service 层接口必须有实现类，禁止直接写类内实现 - 金额相关字段一律用 BigDecimal，禁止使用 double - 所有时间字段使用 LocalDateTime，禁止使用 java.util.Date - 新增数据库字段必须同步修改对应的 XML 映射文件 ## 事务与测试要求 - 涉及钱的状态流转必须在 service 方法上加 @Transactional - 每次改动必须补充或更新单元测试，覆盖率不得低于新增代码的 80% - 测试禁止连接真实数据库，使用 H2 内存库 ## 重要约定 - 修改订单状态时必须走 OrderStateMachine，禁止直接改 state 字段 - 支付回调接口是异步通知，幂等处理依赖 order_no + event_type 去重 - 日志打印统一使用 Slf4j，上下文信息放入 MDC

3.2 逐段拆解：每部分为什么这么写

开头那段“项目简介”，作用是给 AI 一个最基本的定位锚点。别小看这一句话，它能让 AI 在回答问题时自动往“这是一个订单系统”的方向靠，而不是泛泛地给一个通用方案。我见过有人在这里写了一大段业务背景，什么“本系统旨在提升……赋能……”之类，全是废话。简介控制在三到五行，说清楚“是什么、用什么技术栈、主要做什么”就够了。

“常用命令”这部分价值极高。Claude Code 经常需要自己执行命令来验证代码，如果你不告诉它构建和测试命令，它就会猜，猜错的概率相当高，尤其是 Maven 项目它总爱用mvn，而很多项目实际用的是./mvnwwrapper。把这些命令写进模板，等于是把你平时的肌肉记忆直接复制给了 AI。注意命令要写得具体，连 profile 参数、单测过滤条件都要写清楚，AI 会严格按字符串去执行。

“目录职责”那段是我的私货。很多项目的包名、目录层级并不符合主流约定，AI 默认的 Classifier 机制（根据类名猜测功能）经常会猜错。比如你的项目里有个domain包，里面全是贫血模型，AI 看到Order类可能以为它是实体，结果它其实是 DO。把目录职责写清楚之后，AI 找文件的准确率会显著提升。如果你发现 AI 总是把文件放错地方，十有八九是缺了这段。

“编码规范”和“重要约定”是保命条款。这里面写的东西，都是你实打实踩过坑、不希望 AI 再犯的错。比如 BigDecimal 替代 double，比如状态流转必须走状态机，这些规则一旦被违反，代码 review 时必然出问题。我强烈建议你每被 AI 坑一次，就往这个文件里补一条规则。一个月下来，这个文件会变成你的“AI 调教经验集”。

3.3 几个容易忽略的细节

写CLAUDE.md的时候有几个细节值得注意。第一个是不要用否定句写规则，比如“不要使用 double”，经验是 AI 对否定句的遵从度明显低于肯定句，改成“金额相关字段一律使用 BigDecimal”效果更好。第二个是规则编号的问题，如果你的规则超过十条，建议给每条加个编号，方便后面跟 AI 说“按规则 7 处理”，不然你指代不明，它又要犯迷糊。第三个是别把CLAUDE.md当成普通文档来写，它是给 AI 看的 Few-shot 上下文示例，不是给人看的说明书，所以最好用短句、祈使句、结构化列表，避免大段散文。

4. 自定义 Slash Command 实战：把高频操作做成命令

4.1 命令模板的基本格式

CLAUDE.md解决的是“每轮对话都生效的常驻规则”，但有些操作你只会在特定时刻用，比如“帮我 review 一下当前改动”“按规范生成 commit message”。这种低频高价值操作，适合做成自定义 Slash Command。Claude Code 会在启动时读取.claude/commands/目录下的所有.md文件，把它们注册成斜杠命令。格式非常简单：

--- description: 代码审查，检查当前分支的改动 argument-hint: [可选参数，比如指定文件路径] --- 你是一名资深代码审查专家。请审查当前分支相对于 main 分支的所有改动。 审查时重点检查以下方面： 1. 是否存在潜在的并发问题或事务边界错误 2. 是否有违反项目编码规范的地方（见 CLAUDE.md） 3. 是否有安全漏洞，特别是注入、越权、敏感信息泄露 4. 单元测试是否覆盖了主要逻辑分支 输出格式：先列出“必须修改”的问题，再列出“建议优化”的问题，最后给一个总体评价。

这个文件本身就是一个 prompt 模板。当你输入/code-review的时候，Claude Code 会把这段 prompt 作为执行指令，并且会把当前上下文里的文件信息自动带上。argument-hint是给用户看的参数提示，比如你可以写“指定文件或目录，不填则默认全部改动”。

4.2 我的几个常用命令模板

除了上面那个 review 命令，我再分享几个我用得最频繁的。一个是测试执行命令。直接对话里跟 AI 说“跑一下测试”，它常常会跑全量测试，慢得要死。我写了一个/test命令，让它先读取package.json里的 scripts 配置，再根据用户传入的参数只跑指定模块的测试，跑完之后还要汇总失败用例和堆栈信息。如果没传参数，就只跑和当前 git diff 相关的文件对应的测试。这个命令帮我省了大量等待时间。

另一个是/commit命令。我把它绑定到项目自己的 commit 规范上，模板里写明 commit message 的结构：type(scope): description，type 必须是 feat/fix/docs/refactor/test/chore 之一，description 用祈使句、不超过 50 个字符。AI 会先git diff和git status查看改动，再按规范生成 3 个候选 message 让我选。这样既保证了信息完整，又省去我手写提交信息的功夫。

还有/changelog命令，用来生成两个版本之间的变更记录。模板里给 AI 一个清晰的输出格式：新增、修复、变更、移除四个分组，每个分组下列出对应的 commit 标题，并标注影响范围。因为 Claude Code 能读 git log，这个命令的准确性其实相当高。最后提一下/api命令，让 AI 根据docs/api-design.md里的约定生成一个新接口的 controller、service 和测试文件，省去重复的 CRUD 劳动。

4.3 进阶：用 Bash 脚本做命令

不是所有命令都适合用纯 Markdown prompt 实现，有些需要真正执行本地逻辑。Claude Code 的命令文件支持在 Markdown 里嵌入可执行代码块，也支持直接写带 shebang 的脚本文件。我举个例子，我的/init-project命令是一个 bash 脚本，做的事情是：从模板仓库拷贝CLAUDE.md、创建.claude/commands目录、根据用户输入的项目类型生成对应的settings.json。这种“配置生成器”类型的命令，用脚本写比用 prompt 写要稳定得多。

这里要提醒一个坑：脚本文件需要可执行权限。我一开始把脚本放进去之后，怎么调用都报“command not found”，检查了一圈才发现是chmod +x没做。另一个坑是路径问题，脚本里如果用相对路径，它的基准目录是命令文件所在目录，不是项目根目录，最好在脚本开头用cd "$(dirname "$0")/../.."之类的方式固定工作目录，不然在不同项目里行为不一致，排查起来很痛苦。

5. 工作流模板：让项目启动、团队协作都有章法

5.1 新项目初始化工作流

模板体系不只能服务单个项目内的小操作，它还能帮你标准化“从零开始一个新项目”的流程。我给自己建了一个“项目脚手架”模板集，里面包含一个初始化命令和一套目录模板。新建项目的时候，我会先执行mainframe init风格的一串命令（具体看你的工具链），然后把项目类型、技术栈、包名等参数填进去，剩下的目录结构和配置文件由 AI 按模板生成。

这背后的思路是：把你自己过去两三年建项目时积累的最佳实践，固化成一堆可复用的模板文件。比如对于 Node.js 项目，我的模板里固定包含src/、src/modules/、test/、docs/这些目录，并且CLAUDE.md里写清楚了每个目录的职责边界。这样新项目的 AI 助手从一开始就有一个好骨架，不会一上来就把代码堆在根目录。

5.2 团队标准化：把模板放进 Git 仓库

如果你在一个团队里工作，模板体系的收益会被放大很多倍。我建议把.claude/目录和CLAUDE.md提交到 Git 仓库里，让每个成员 clone 之后自动拥有同一套 AI 行为准则。这比在 wiki 里写十页“AI 使用规范”有效得多——因为规则不是给人看的，是直接注入到 AI 上下文里生效的。成员自己也可以往.claude/commands/里加命令，通过 MR 合入，团队里的命令库会越用越丰富。

但在团队环境里要特别注意隐私和保密问题。.claude/目录里如果写入了敏感信息，比如内部服务地址、密钥占位符、未公开的业务规则，一旦仓库权限管控不严就会泄露。我的建议是敏感信息不要写进模板，必要的话用环境变量引用，并在.gitignore里排除CLAUDE.local.md这类个人配置文件。

5.3 子代理模板：术业有专攻

Claude Code 的.claude/agents/目录允许你定义专用子代理，每个子代理有自己的系统提示词、可用工具列表和模型配置。我个人的实践是定义了一个backend-architect子代理，它的职责是“在动手写代码之前，先输出一份模块设计文档”，包括数据模型、接口定义、依赖关系。主对话收到复杂需求时，可以让它先派子代理去思考设计，再回来写实现。这种“先设计后编码”的工作流，在改动核心模块时特别有用，能避免 AI 一上来就闷头写代码，写到一半发现方向错了。

5.4 会话启动模板：一个固定起手式

最后一个建议是给自己设计一个“会话开场模板”。我每次开始一个大需求时，会在所有对话的最前面粘贴一段固定的话：先用一句说明需求背景，再告诉 AI “在动手前先阅读 CLAUDE.md 和 docs/architecture.md，然后列出你的实施计划和需要我确认的问题，确认后再开始写代码”。这相当于给 AI 一个“元指令”，防止它一上来就自作主张。你完全可以把这段话做成一个plan命令，让它固定执行这个流程。

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

6.1 模板不生效，AI 还是瞎搞

很多人配置完模板之后发现 AI 的行为没什么变化，于是以为模板没用。根据我的排查经验，最常见的原因有三个：文件名写错了，Claude Code 只认CLAUDE.md这个名字，多一个字母少一个字母都不行；路径放错了，全局配置应该放在~/.claude/CLAUDE.md，项目配置放在项目根目录，如果放进了.claude/子目录，可能有不一样的行为；还有一个是大小写问题，在 Linux 系统上Claude.md和CLAUDE.md是两个不同文件，务必保持一致。

6.2 命令文件不显示或报 Not Found

自定义命令不显示，先检查两件事：一是命令文件是否在.claude/commands/目录下且后缀是.md或可执行文件；二是重启会话没有。Claude Code 通常在会话启动时扫描命令，启动之后新放进去的文件可能要重开会话才能识别。如果命令能显示但执行报错，大概率是 frontmatter 写错了，比如description或argument-hint的格式不对，或者脚本没有执行权限。遇到这种情况，我的排查套路是先用claude --help或官方日志看执行时的详细报错。

6.3 上下文窗口被占满，AI 越聊越蠢

模板文件太多，或者CLAUDE.md里塞了大量内容，会占用上下文窗口，导致 AI 在长对话中段开始“忘事”。我在实际使用中的感受是，CLAUDE.md的推荐量级在几十行以内，超过 200 行的项目规则建议拆到外部文档用@引用。另外，如果一轮对话实在太长，直接开新会话反而更清醒——因为模板是自动加载的，新会话并不会丢失项目背景知识，你只需要把当前任务的中间产物用文件或者git commit固化下来，新会话可以接得上。

6.4 模板和实际代码不一致的问题

这个问题在项目演进过程中几乎一定会出现：模板里写的规范还停留在三个月前，代码已经换了新风格。比如你从 MyBatis 换成了 JPA，但CLAUDE.md里还写着“SQL 写在 XML 中”，AI 就会照着旧规范给你写已经不存在的 XML 映射。解决方案没有捷径，就是定期维护模板。我现在每完成一个迭代都会扫一遍.claude/目录，把过时的规则更新掉。也可以让 AI 帮忙做这件事，专门开一个会话，让它对比当前代码风格和模板规则，输出需要同步修改的清单。

6.5 安全边界：哪些不该写进模板

最后说个安全上的经验。模板是给 AI 看的，但它也可能被输出到对话里，或者通过错误日志泄露。不要在里面写真实密码、token、内部 IP；不要写“忽略安全检查”这类僭越性指令；企业项目里的未公开业务策略，尽量用泛化描述代替具体数据。设定权限边界也很重要，比如.claude/settings.json里可以配置哪些文件目录只读，哪些工具需要二次确认，避免 AI 在无人监督时改动基础设施文件。

模板体系对我来说最大的意义，是让我从“反复给 AI 解释项目背景”的琐碎劳动中解放出来了。现在新开一个会话，我只需要说一句“帮我实现这个功能”，它就自动进入状态。这套东西没什么高深的理论，就是把该沉淀的沉淀下来，该分工的分工出去。如果你之前没用过模板，我建议从最小的CLAUDE.md开始，不要一上来就想搭一套完美体系，先把最常被 AI 搞错的三条规则写进去，用起来之后再逐步添加命令和工作流。模板是活的，它应该随着你项目和经验的成长一起迭代。