企业官网建设流程全解析

这几年做 AI 编程工具落地，我最常被问的一个问题是：大家都在用 claude-code 写代码，为什么别人家的 AI 像是读过整个项目的老师傅，我手底下的这个像个只会对着当前文件打字的实习生？问题通常不在模型本身，而在你根本没有给 claude-code 建立一套可复用的“工作上下文”。claude-code-templates 就是这套上下文的载体——把项目约定、代码风格、工作流、常用命令全部固化成模板，让每次新会话都从同一个高水准起点出发。这篇文章把我自己沉淀的一套模板体系完整拆给你看，适合正在重度使用 claude-code 的独立开发者、小团队，以及想给开源项目配上统一 AI 协作规范的同学。

1. claude-code-templates 项目概述：给 AI 编程助手立规矩

1.1 模板到底解决什么问题

直接说结论：claude-code 本身是一个能力很强的终端 AI 编程代理，但它默认状态下是“无记忆”的。每开一个新会话，它对你的项目一无所知，不知道你用 TypeScript 还是 JavaScript，不知道你的测试框架是 Vitest 还是 Jest，不知道你 commit 走的是 Conventional Commits 还是随便写。没有约束的情况下，AI 会倾向于给出最通用、最平均、最安全的方案——而这类方案往往不是你想要的。

claude-code-templates 的定位就是填补这个空白。通过 CLAUDE.md 这类项目指令文件、自定义斜杠命令、hooks 自动化脚本，把人和团队长期积累的工程经验“外置”到 AI 可见的文件里。你不需要每次开会话都重新念叨一遍规范，AI 启动时自动读取这些模板，天然就知道该按什么路子走。

我打个比方：没有模板的 claude-code 相当于一个能力很强但没看过员工手册的新同事。他有冲劲，但不知道你们公司的代码评审要过几道关、命名规范是什么、哪些库是禁用项。而模板体系就是那份员工手册外加一套自动化检查工具。新同事入职第一天先读手册，再看几个历史案例，配合质检脚本兜底，产出自然靠谱得多。

1.2 适合谁来参考这套模板

先说清楚适用边界，免得你踩坑。这套模板体系最适合下面几类人：

• 深度使用 claude-code 的独立开发者：一个人维护多个仓库，每个项目的技术栈、构建方式、提交规范都不一样。模板能把每个项目的上下文固化下来，切换仓库时 AI 无缝适配，不用反复解释。
• 三五个人的小团队：团队没有专职的工程效能岗，但希望 AI 辅助编码时保持统一的代码风格和接口约定。把模板放进仓库根目录，所有人共享一套规则，AI 产出的代码天然一致。
• 开源项目维护者：给仓库配上 CLAUDE.md，等于给所有用 claude-code 贡献代码的人发了一份“AI 协作说明书”。外部贡献者用 AI 改代码时，不至于把项目风格改得面目全非。

需要提醒的是，如果你只用 claude-code 做一些临时脚本、一次性实验代码，那模板反而是负担。模板的核心价值在“复用”和“一致性”，纯临时任务用不上这些，别为了规范而规范。

2. 模板体系的核心组成与设计思路

2.1 五大模板类型，各管一摊

我长期实践下来，把 claude-code-templates 拆成五个层次，每一层解决一类问题。你可以对照自己团队的现状取舍，不必一次全上。

这里面最容易被人忽略的是斜杠命令。很多人以为模板就是写一份大而全的 CLAUDE.md，其实真正让效率翻倍的是那些“一句话触发整套流程”的斜杠命令。我在实际使用中发现，一次完整的代码评审让 AI 手工执行，至少要交互五六轮，而封装成 /review 命令后，一步到位，且每次评审的维度和深度都稳定。

2.2 模板生效机制：文件优先级与读取规则

理解 claude-code 的模板加载机制，是写好模板的前提。Claude Code 在启动会话时，会按照优先级自动把多个层级的 CLAUDE.md 读进上下文，形成叠加的项目认知。

从我的实测经验来看，生效顺序大致是：

1. 用户级全局配置：位于~/.claude/CLAUDE.md，对所有项目生效。适合放个人通用偏好，比如“代码里尽量写注释说明为什么，而不是解释是什么”。
2. 项目级配置：位于当前工作目录的./CLAUDE.md，这是最常用的位置，放项目专属约定。
3. 子目录级配置：重要目录下可以放自己的 CLAUDE.md，claude-code 会按会话涉及的目录范围合并读取。比如packages/ui/CLAUDE.md专门约束组件开发规范。

这个叠加机制意味着你可以做分层设计：全局配置管“你怎么工作”，项目配置管“这个项目长什么样”，子目录配置管“某块业务有什么特殊规矩”。三层互不干扰，但共同作用在一个会话里。

实践中我见过最典型的错误，是有人把整个团队的规范全塞进用户级 CLAUDE.md。结果他给 A 项目写的东西，在 B 项目里也生效，经常出现互相矛盾的指令。正确的做法是全局只放零冲突的个人习惯，凡是跟项目绑定的内容一律下沉到仓库目录里。

3. 从零搭建自己的 claude-code-templates 库

3.1 目录结构设计与初始化

先给出一份经过验证的目录结构，你直接照着建就行：

claude-code-templates/ ├── CLAUDE.md ├── .claude/ │ ├── settings.json │ ├── commands/ │ │ ├── review.md │ │ ├── test.md │ │ ├── commit.md │ │ └── architect.md │ └── hooks/ │ └── post-tool-use-check.sh └── docs/ └── TEMPLATE_GUIDE.md

初始化时有一个容易被忽略的点：模板文件里尽量不要用绝对路径，也不要把个人本机的中文用户名写进命令示例里。团队协作时，别人 clone 下来路径就变了，模板里凡是涉及路径的地方，统一用相对路径或环境变量占位符。我早期吃过这个亏，把/Users/xxx/workspace写死在命令里，同事跑起来全部报错。

另外，.claude目录是整个模板库的核心，务必提交进 Git。可以在.gitignore里排除掉那些临时生成的文件，但命令和配置模板本身一定要版本化，这是团队 AI 协作资产的一部分。

3.2 编写 CLAUDE.md：项目公约的起点

CLAUDE.md 是整个模板体系的基石，但千万别写成万字长文。模型处理上下文有限，太长的项目公约反而稀释重点。我的经验是控制在 60 到 100 行以内，只写四类内容：

• 项目身份：一句话说清这个项目做什么、面向谁、技术栈是什么。
• 关键命令：构建、测试、lint、类型检查分别怎么跑。这是 claude-code 执行力最强的部分，写清楚命令，AI 自己就能完成“改代码→跑测试→看结果→继续改”的闭环。
• 架构红线：哪些目录能改，哪些目录要谨慎，核心数据流是什么方向。这些是 AI 最容易犯错的点，必须显式声明。
• 团队特有的命名和风格约定：比如“API 接口统一以/api/v1开头”“组件文件使用 PascalCase 命名”“禁止在业务代码里直接操作 localStorage，必须走封装的 storage 模块”。

用一份真实的片段做示例：

# Project: Commerce Admin Dashboard ## Tech Stack - Next.js 14 (App Router) + TypeScript + TailwindCSS - API calls go through src/lib/api-client.ts, never call fetch directly - Component library: shadcn/ui, do not introduce new UI dependencies without discussion ## Commands - Install: pnpm install - Dev: pnpm dev - Test: pnpm vitest run - Lint: pnpm lint - Type check: pnpm tsc --noEmit ## Architecture Rules - Business logic lives in src/features/{domain}, not inside page components - State management uses zustand stores under src/stores - Never import server-only modules into client components - Database schema changes require migration files under db/migrations

这个模板的核心在于“命令”和“红线”的紧密配合。有了明确的测试命令，Claude Code 改完代码后会自动跑测试验证，而不是把代码扔给你让你自己试。有了“禁止直接 fetch”的红线，AI 写接口调用时会自动走封装的 api-client，和团队其他代码保持一致。

3.3 自定义斜杠命令：把高频操作变成一键触发

斜杠命令是 claude-code-templates 里性价比最高的部分。每一个斜杠命令本质是一个 Markdown 文件，放在.claude/commands/下，文件名的前缀就是触发词。比如review.md对应/review，test.md对应/test。

我日常最常用的三个命令模板：

第一个是/review，代码评审命令。内容不复杂，但把评审维度固定下来：

You are reviewing code changes as a senior engineer on this team. Focus on: 1. Correctness: edge cases, error handling, async race conditions 2. Consistency: does the code match the conventions in CLAUDE.md? 3. Security: authentication, authorization, input validation 4. Performance: unnecessary re-renders, large payloads, blocking calls 5. Maintainability: naming, coupling, testability Output format: summary table, then critical issues only, then optional suggestions. Do not mention style nits that a formatter would catch.

第二个是/commit，自动生成 commit 信息。模板里明确要求 AI 先看 git diff，再对照 Conventional Commits 规范生成信息。我还加了限制：如果 diff 包含多个不相关改动，要先指出并建议拆分，而不是硬塞进一条 commit。

第三个是/test，为改动补测试。模板里写清楚测试框架、文件放置位置、 mock 手段，让 AI 补出来的测试风格和存量测试一致。

斜杠命令最容易踩的坑是“写得像需求文档，不像操作指令”。命令文件的核心是给 AI 设定执行框架和输出格式，不是描述功能。我见过有人写一个/deploy命令，里面全是“请部署到服务器”这种话，AI 根本不知道要执行什么命令、部署到哪台机器。正确的写法是给出可执行步骤，比如“运行pnpm build，通过后生成dist/压缩包，再调用部署脚本scripts/deploy.sh --env=staging”。

3.4 settings 与 hooks：行为边界和自动化兜底

settings.json 是模板体系的“保险丝”。它用来限制 claude-code 的行为边界，比如哪些工具允许自动执行、哪些操作要人工确认。我的默认配置里会开放读写权限给项目目录内的文件，但把执行 shell 命令设为“每次询问”或“允许部分命令”。

hooks 则是更高级的自动化手段，也是我强烈推荐每个团队配置的层。hook 可以在 claude-code 调工具前或调用后触发本地脚本，完成一些强制性的校验。举两个我实际部署的例子：

• 测试守卫：每次 claude-code 修改代码并尝试结束时，自动触发pnpm vitest run --related，测试不通过就把结果反馈给 AI 继续修。这比靠 AI 自觉跑测试可靠得多。
• 密钥扫描：在 AI 写入文件后扫描 diff，如果发现形如sk-、AKIA、password =等敏感模式，立即拦截并提示移除。这个 hook 救过我一次，有一次 AI 把测试用的假密钥直接硬编码进了配置文件，幸好扫描兜底拦住了。

hook 脚本的编写要注意一点：执行时间不宜太长。claude-code 的交互体验依赖响应速度，如果每次工具调用后都要跑一个 10 秒的脚本，整个会话会变得很难受。我自己的经验是 hook 只做轻量校验，重活留给 CI。

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

4.1 模板不生效，先查这四处

这是我被问到最多的问题：“我明明写了 CLAUDE.md，为什么 claude-code 视而不见？”排查顺序如下：

• 文件位置错了：CLAUDE.md 必须在当前工作目录或上级目录。如果你在/project/src下启动 claude-code，而 CLAUDE.md 放在/project根目录，大概率读不到。先确认启动目录。
• 文件名大小写：必须是CLAUDE.md全大写前缀。写成了claude.md或Claude.md都不会被识别。
• 启动目录不对：claude-code 从哪个目录启动，就以哪个目录为项目根。在错误的目录启动，项目配置自然加载不到。
• 被输出长度挤掉了：如果同时加载的上下文太多，模型可能忽略了部分规则。检查 CLAUDE.md 是否过于冗长，精简到骨干，把细节挪到斜杠命令里。

4.2 模板内容被 AI 忽略，原因多半在措辞

有时候模板加载了，但 AI 不按规则办事。问题常出在措辞模糊上。比如“代码质量要高”这种话等于没说，模型不知道你的“高”具体指什么。要写成可验证的行为：“新增函数必须附带两个以上的单测用例”“API 响应要有统一的 envelope 结构”“异步请求必须带 AbortSignal”。

另一个隐蔽原因是规则之间存在自相矛盾。全局 CLAUDE.md 说“优先使用函数式组件”，项目 CLAUDE.md 又说“这个模块必须用类组件”，模型面对冲突时只能自行判断，而判断结果往往是随机的。模板体系上线后，定期审查冲突是必要工作。

4.3 斜杠命令与内置命令冲突

自定义命令的触发词如果和 claude-code 内置命令重名，行为会变得不可预期。比如你定义一个/init，但 claude-code 本身可能对/init有默认处理。我的建议是给团队自定义命令加上统一前缀，比如/team-review、/team-commit，既避免冲突，也能一眼看出是团队独有的能力。

另外要留意斜杠命令文件里的 YAML front matter。命令文件支持description和argument-hint等元信息字段，用于在帮助列表里展示。写了 description 之后，AI 更容易理解何时该建议用这条命令，不写的命令被主动使用的概率会降低不少。

4.4 性能问题：模板太多拖慢响应

模板不是越多越好。我见过一份 300 行的 CLAUDE.md，每次会话光加载就占掉很大一块上下文窗口，留给实际任务的推理空间少了很多。控制篇幅的办法是分层：把必须时时可见的公约留在 CLAUDE.md，把那些偶尔用到的详细流程放到斜杠命令或独立文档里，让 AI 按需读取。

5. 进阶实践：让模板库真正“活”起来

5.1 模板版本化与迭代节奏

模板库本身应该当成一个真正的项目来维护。我自己的做法是用 Git 管理整个 claude-code-templates，每次修改走 commit，并且写 changelog 记录每条规则的增删原因。比如“新增：禁止在 reducer 里调用 Math.random()”，commit message 里注明是因为线上出现过一次 SSR/客户端状态不一致的 bug。这样过两个月回头看，能明白每条规矩背后都有故事，而不是一堆干巴巴的禁令。

迭代节奏建议按需驱动。团队哪块 AI 产出问题最多，就优先补哪块的模板。比如发现 AI 经常写出不符合接口约定的代码，那就在 CLAUDE.md 的“Architecture Rules”里加一条入口约束，并在/review命令里增加一个必查项。模板的价值在于解决真实痛点，不是为了凑一份漂亮的文档。

5.2 模板调优的两条独家经验

第一条经验是“让模板站在数据上说话”。不要凭空想象 AI 该遵守什么，而是先收集它犯错的实际案例。每次 claude-code 产出不符合预期的代码，顺手把问题记下来。攒两周后你会发现规律：它总是在并发处理、错误边界、命名一致性这几个地方栽跟头。针对高发问题写进模板，效果立竿见影。

第二条经验是“模板也要做 A/B 测试”。调整规则时不要一次改十几条，那样出了问题没法定位。一次只改一两条，跑几个代表性任务对比产出质量。我自己维护模板库时，对每条关键规则都保留一个“调优记录”，写清楚原先是什么、改成什么、为什么改。这个习惯帮我避开了很多回归踩坑。

这套模板体系最终要达到的状态是：你拉起一个新会话，什么都不用说，claude-code 已经知道自己是谁、项目是什么、规矩有哪些，剩下的精力全部花在真正的业务逻辑上。我在自己的几个主力仓库上跑了大半年，最直观的感受是 AI 产出的代码从“能用”进化到“像团队里的人写的”，代码评审的返工次数明显下降。如果你也在高频使用 claude-code，建议从一份 60 行的 CLAUDE.md 加三条斜杠命令开始，跑两周，再按实际坑点逐步迭代，会比任何大而全的方案都走得更稳。