企业官网建设流程全解析

拿了“claude-code-templates”这个标题，我想说的不是那种套壳的“prompt技巧列表”，而是真正能把终端里的协作行为固化成模板的工程方法。

先说结论：claude-code 本身是一个在终端里和你一起写代码的助手，但裸跑它的时候，每次都要解释一遍项目背景、代码规范、测试要求、输出格式，效率很低。templates 的作用，就是把这类“每次都要重复交代的事”变成一套标准动作，让助手按你的套路来干活。它适合单人多项目的人，也适合想把团队开发规范真正落到执行层的技术负责人。

1. 为什么需要模板：把“反复交代”变成“默认动作”

我第一次用 claude-code 的时候，觉得它很聪明，但也有点“难带”。同一个任务，上午让它改 bug，它会先看测试再动手；下午让它改 bug，它可能上来就开干，完全不带测试。问题不是模型不行，是我没有给它一套稳定的工作方式。templates 要解决的，就是这个“工作方式不稳定”的问题。

1.1 模板的本质是行为预设，不是文档

很多人把模板当成“一段写好的提示词”，这种理解太窄了。在 claude-code 里，模板更像是一份“入职手册”：它不止告诉助手“你要做什么”，还告诉它“你在这个项目里应该怎么思考、怎么动手、做到什么程度算完成”。

举个例子。你可以在全局配置里写：

## 代码风格 - TypeScript 严格模式，禁用 any - 组件使用函数式写法，不使用 class 组件 - 提交信息统一格式: type(scope): subject

这段内容不是给开发者看的，是给 claude-code 每次启动时自动加载的“背景记忆”。它会让助手在写代码、提建议、生成提交信息时，默认往这个方向靠。这就是模板的第一个价值：把隐性的团队规范，变成每次会话都会生效的显性上下文。

1.2 模板能省下的是“沟通成本”和“返工成本”

我在一个多项目环境里工作过一段时间，每天要在三四个仓库之间切换。每个仓库的技术栈、目录结构、测试习惯都不一样。如果没有模板，我每次都要敲一大段描述，比如“这是 Python 项目，用 poetry 管理依赖，测试放在 tests/ 下，改完必须跑一条指定命令”。这种话偶尔说一次没问题，天天说就很崩溃。

用了模板之后，这些信息被固化到项目配置里。我只需要说“帮我改一下登录接口的 bug”，助手会自动带着对应的规范去理解任务。省下来的不是几秒钟的输入时间，而是避免了一系列因上下文缺失导致的返工：它不会乱建文件，不会用错依赖管理工具，不会提交一个不符合规范的 commit。

1.3 模板的价值上限取决于流程的标准化程度

这里想泼一盆冷水：如果你的开发流程本身是混乱的，模板救不了你。它做的只是“固化”，不是“创造”。我见过有人把一堆自相矛盾的规则塞进模板里，结果 claude-code 执行起来左右互搏。

所以搭建模板之前，先花时间梳理自己的流程：你希望它怎么开始任务？先看代码还是先看文档？产出物是什么格式？什么情况下应该停下问人？这些想清楚了，模板才有意义。这也是我把“流程盘点”放在整个搭建过程第一步的原因。

2. 拆解 claude-code 的模板体系：四个层级，各有分工

claude-code 的模板不是单一文件，它是一整套分层的配置体系。刚接触的人很容易只改一个文件，然后抱怨“怎么不生效”，其实是因为层级用错了。

2.1 全局配置：CLAUDE.md 和用户级设置

它会在几处自动读取 Markdown 格式的说明文件，最常见的是CLAUDE.md。你可以放在用户主目录下，比如~/.claude/CLAUDE.md，也可以放在项目根目录，比如./CLAUDE.md。

全局配置适合放“所有项目通用的偏好”。比如你习惯让助手先生成测试用例再写实现，或者你要求它在每一步里使用中文注释。全局配置不用频繁改，它是最底层的行为底色。

我个人会在全局配置里放这些内容：

• 通用编程语言偏好，比如默认使用严格类型、禁止魔法数字
• 命令执行的注意事项，比如长任务必须加超时控制
• 回答风格，比如解释问题时先给结论再给推导

2.2 项目级配置：决定“在这个仓库里怎么干活”

项目根目录下的CLAUDE.md优先级更高，它的作用是描述这个仓库特有的规则。我喜欢把它理解成“仓库的 README 伴侣”：README 给人看，CLAUDE.md给助手看。

项目级配置里我会写：

# 项目说明 这是一个 FastAPI 服务，目录结构如下： - app/ 下按模块组织代码 - tests/ 使用 pytest，数据库操作一律 mock # 任务流程 1. 修改代码前先定位相关模块 2. 修改后运行 `poetry run pytest` 3. 通过后再给出 diff 摘要

这套配置让 claude-code 进入仓库时自动带上“上下文”，不用我每次重复。如果你是一个仓库里的常驻开发，项目级配置的收益是最大的，我强烈建议先从这里入手。

2.3 命令模板：斜杠命令的定制化能力

除了配置说明，它还支持自定义斜杠命令。你可以把一些高频操作整理成.md文件，放在.claude/commands/目录下，文件名就是命令名。

比如我建了一个.claude/commands/review.md，然后在 claude-code 会话里输入/review，它就会执行我预设的代码审查流程。这里的关键理解是：斜杠命令不是“执行预先写好的文本”，而是“加载一段动态的指令让助手执行”。它可以在开头引用当前上下文、调用脚本、甚至读取用户输入。

命令模板的设计自由度很高，我后面会专门讲。

2.4 子代理与技能：更精细的分工单位

再往下，还有 subagents 和 skills 这一类更细粒度的机制。简单理解，你可以定义一些“专才”子代理，比如“测试编写专家”“性能分析专家”，它们有各自的角色说明、可用工具和行为约束。主进程接任务后，可以按需把这些子代理拉进来干活。

这套机制本质上也是模板，只是粒度更小、职责更单一。对于大型项目，用子代理能显著减少“做什么都混在一起”的上下文混乱。我在重构老项目的时候，就会专门定义一个“迁移专家”子代理，让它只负责分析旧代码、输出迁移计划，不碰其他杂事。

3. 从零搭建一套模板库：实操过程与参数设计

理论上限说完了，落到地上怎么搞？我按自己搭过几套模板库的经验，拆成五个步骤。这套方法不依赖具体项目，任何技术栈都能用。

3.1 盘点高频动作：找出真正值得模板化的操作

写模板最大的忌讳是“为了写而写”。先翻一翻你最近两周在终端里指挥 claude-code 做的事，哪些重复次数超过三次？我复盘下来，最高频的是：写 commit message、跑测试并修复、做代码审查、生成模块改动说明、排查报错。

建议做一个简单的清单，把任务分为三类：

• 高频固定型：每周至少三次，动作完全一致，值得做命令模板
• 低频但复杂型：不常发生，但操作链条长、容易漏步骤，适合做子代理或流程模板
• 一次性任务：不需要模板，临时说就行

拿这个标准筛一遍，最后沉淀下来的模板数量不会很多。我自己的库到现在也就十几个命令，但每个都真的在用。

3.2 设计模板结构：目标、输入、约束、输出缺一不可

一份好的命令模板，至少要包含四块：目标定义、输入参数、执行约束、输出格式。我见过很多不生效的模板，问题就出在“只有目标”或“只有约束”。

我在写模板时常用的骨架是这样的：

# PR Review ## 目标 以资深代码审查者的视角，审查当前分支的改动，发现逻辑错误、安全隐患和代码风格问题。 ## 输入 - 分支名: {{branch}} - 关注重点: {{focus}} ## 执行约束 1. 先 `git diff origin/main...HEAD` 拿到改动 2. 逐文件审查，不跳跃、不凭记忆 3. 每个问题都要给出文件路径和行号暗示 4. 不提出与本次改动范围无关的建议 ## 输出格式 - 概况段：改动规模、涉及模块 - 问题列表：按严重程度排序 - 建议优先级：必改、建议改、可选

这里的“目标”给方向，“输入”给参数，“执行约束”管行为，“输出格式”管成果，缺一块都会让执行结果飘忽。

3.3 理解变量与上下文传递：让模板从静态变动态

如果你只写死文字，模板很快会僵化，因为每次任务的具体目标不同。claude-code 的斜杠命令支持把用户输入的内容注入模板，格式是$ARGUMENTS。

比如我写了一个explain.md：

# 解释代码 请解释以下问题或代码段：$ARGUMENTS 说明时按三层来： 1. 这段代码的作用 2. 关键逻辑为什么要这么写 3. 潜在的问题点和改进方向

调用时只要输入/explain 这个缓存为什么过期时间这么短，助手就会把$ARGUMENTS里的内容当作具体目标来执行。这样模板是通用的，但是每次执行是定制化的。

另一个实用的技巧是利用命令行参数。在命令模板文件里可以配置allowed-tools、model等参数，也可以引用$CLAUDE_PROJECT_DIR这类环境变量。我在写模板时，会先确认项目根目录是否存在，再决定从哪里读代码，避免它在错误的路径下工作。

3.4 实操案例：一个可落地的“修复测试”命令模板

我拿实际在用的模板举个例子，它不是玩具，是解决真实痛点的。我经常遇到“测试挂了要我看看”的任务，于是建了.claude/commands/fixtest.md：

# 修复测试 ## 流程 1. 运行 $ARGUMENTS 指定的测试命令，或自动探测项目测试命令 2. 阅读失败输出，定位失败用例，找到对应源码 3. 先分析失败原因，不要直接改代码 4. 给出诊断说明，确认修复方案后实施 5. 修复后重新运行测试，直到通过 ## 约束 - 如果失败原因不明，要求用户提供更多信息，禁止瞎猜修复 - 最小化改动，不顺手重构 - 修复完成后输出一份简明报告：根因、改动文件、测试结果

这个模板看起来简单，但效果非常好。它把“看到失败就乱改”的行为控制住了。以前我指挥 claude-code 改测试，它经常改了一个断言又挂另一个，因为没有先做根因分析。模板强制它先诊断再动手，返工率明显下降。

3.5 模板的内部一致性检查

写完模板别急着用，先自己检查一遍。我喜欢用三个问题来自查：

• 如果把这个模板交给一个完全不熟悉项目的新人，他能按步骤执行吗？
• 模板里有没有同时要求两件互相冲突的事？
• 输出格式是否明确到“看一眼就知道有没有完成”？

我吃过亏：有一版模板要求“先看代码再提意见”，后面又写着“快速给出总结”，结果执行的时候它为了求快跳过了代码阅读。自那以后，我会刻意删掉模板里所有模糊的修饰词，只留明确的行为指令。

4. 模板库的管理与团队共享：目录结构、版本与命名规范

个人用模板，怎么舒服怎么来。但一旦涉及团队共享，或者要长期维护，就得引入工程化手段。这一节讲我如何组织模板库，让它不变成一堆散落各处的 md 文件。

4.1 目录组织：全局还是项目，倾向分明

我的习惯是两层分法：属于个人偏好的放~/.claude/，属于仓库规则的放项目根目录.claude/。命令模板统一放.claude/commands/，文件名即命令名。

目录结构类似这样：

~/.claude/ ├── CLAUDE.md # 个人通用偏好 └── commands/ # 个人高频命令 ├── explain.md └── commit.md 项目根目录/ ├── CLAUDE.md # 仓库专属规则 └── .claude/ ├── commands/ │ └── review.md └── agents/ └── migration-expert.md

这个结构的核心逻辑是：越靠近项目的规则越容易被具体任务覆盖，越全局的规则越稳定、越少改。我见过有人把所有规则全塞进项目级配置，结果换一个仓库就完全水土不服。

4.2 把模板库纳入版本管理

我要强调一个很多人忽略的点：模板是你工程资产的一部分，必须进 git。我会给整个~/.claude单独建一个 dotfiles 仓库，项目级模板则直接提交到各自的代码仓库里。这样改动可追溯，出了问题还能回滚。

项目级模板我建议和代码同步提交。比如这周团队决定以后新代码必须带测试，我就会把这条规则写进CLAUDE.md，和代码一起走 MR 流程。这样做有一个额外好处：历史代码对应的模板版本是当时的规范，不会因为后来规则变更导致无法复盘。

4.3 命名规范与团队协作约定

模板命名直接影响使用体验。斜杠命令是输入到终端里的，必须好记。我遵循的规范是：动词开头、不超过两个词、能表达完整动作。

举例：

• /fix修测试
• /review审查变更
• /commit生成提交信息
• /explain解释代码

团队协作时，我还会要求命令模板里的输出格式统一。不能一个人输出表格、另一个人输出大段文字。格式不统一会让大家觉得工具“不稳定”，最后弃用。

另外，模板更新要经过评审。我们团队约定：任何涉及公共命令模板的改动，都要在 PR 描述里写清楚“旧行为是什么、新行为是什么、为什么改”。否则很容易出现有人改了模板，别人还按旧习惯用，结果行为突变、一脸懵。

4.4 同步机制：让团队模板保持最新

团队里如果用同一套模板，同步是一个容易被忽视的坑。我是这样解决的：公共命令模板放在一个独立的配置仓库里，团队成员通过拉取更新来同步。同时搭配一个简单的自检命令，启动时检查本地模板和远端模板的版本号，不一致就提示。

这种做法不复杂，但能把“我模板怎么和你不一样”的沟通成本降下去。如果你只是个人使用，只需要保证 dotfiles 仓库有备份，换机器时拉下来就行。

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

我用了 claude-code 模板一段时间，踩过不少坑。这里挑几个最有代表性的问题，附上排查思路和最终解法，希望能帮你少走弯路。

5.1 模板太长导致上下文膨胀

刚开始写模板，总觉得写得越全越好。结果一段 3000 字的模板加载进去，每次对话都要占大量 token，反而让助手在无关信息里淹没了重点。

排查方法是用 claude-code 的上下文视角功能（比如/context）看当前会话加载了哪些内容。如果模板占了三分之一篇幅，就该精简了。我后来遵循一个原则：模板里只留“会影响行为差异”的信息，背景知识能不放就不放。

5.2 模板指令互相冲突

典型症状：模板写了“先写测试再写实现”，但另一个文件里写着“提高开发速度，优先完成功能”。当冲突出现时，助手的行为就变得随机，时好时坏。

我处理冲突的方法是分层定优先：命令模板 > 项目级 CLAUDE.md > 全局配置 > 默认行为。然后在模板里明确注明“如果与高层配置冲突，以本模板为准”。这也是我前面强调内部一致性检查的原因。

5.3 变量注入失败，命令不按预期执行

$ARGUMENTS这个变量偶尔会因为格式问题注入失败。比如调用/explain --detail 这段代码，如果模板里没有定义如何解析--detail，整个字符串会被当成一个参数传进去，导致行为偏差。

排查方式是先用一个极简模板做测试，只输出$ARGUMENTS的原始内容，看看它到底收到了什么。确认格式后再逐步加复杂逻辑。另外，我建议模板开头就对参数做校验，如果发现空参数，直接提示用法而不是默默执行。

5.4 助手“假装做完了”，模板里缺少完成定义

这个问题不只在模板场景下出现，但模板可以缓解它。我发现，如果模板没有定义“什么叫完成”，助手可能会在测试没跑、警告没清的情况下就说“修复完成”。

解决办法是在模板尾部加一段强制自我检查：

## 完成标准 - 相关测试已运行且通过（贴出关键输出） - 无新增的愚蠢告警 - 改动影响范围已说明 - 如果存在未完成项，明确列出，不隐藏

这个“明确列出未完成项”的约束很有效，它堵住了“假装完成”的口子。

5.5 无法复现问题时的调试手段

模板种类太多，有时候出了问题不好定位。我的调试顺序很固定：先看模板文件是否被正确加载，再看变量是否按预期注入，最后看执行日志。用--debug模式跑一次，能捕捉到助手收到什么指令、做了什么决策。大多数“模板失效”最后都定位到三个原因：文件路径不对、文件名拼错、变量格式有误。

这张表我打印出来贴在手边，出现问题时照着排查，效率高很多。

6. 模板的进阶玩法：把行为契约接入工作流

如果你已经能把基础模板玩明白，可以再往前一步：把模板当作“行为契约”，接进更大的工作流里。这里分享两个我实际用得很顺的方向。

6.1 让模板成为 CI 之外的“本地守门员”

我做的很多改动，不会每次都推上去跑 CI。与其依赖远端流水线，不如在本地就让 claude-code 按模板执行一轮检查。比如我的pre-push.md模板会做：检查 diff 里是否有调试打印、是否新增了未使用的导入、提交信息是否符合规范。这些规则原本依赖人来盯，现在变成模板内的固定检查项。

接入方法是把模板和 git hook 结合起来：push 前触发一个脚本，脚本调用 claude-code 在非交互模式下跑一遍检查，失败就阻止提交。这种方式让规范变成了工具的一部分，而不是贴在 README 里的空话。

6.2 从模板到“技能包”：跨环境复用

如果你在多个团队、多个项目里反复使用同类模板，可以考虑把它们打包成“技能包”，而不是在每个仓库复制一遍。比如“前端改版流程”包含设计审查、组件拆分、样式规范、验收清单，这些内容可以做成一份独立模板，在需要时通过一条命令导入项目。

我目前的做法是：把通用流程模板放在一个独立仓库里，按场景分目录；项目需要时，用一条安装命令把对应场景的模板软链到项目.claude/commands/下。这样既保留项目独立性，又避免重复维护多份拷贝。

6.3 保留“人工复核”的底线

最后说一条我认为很重要的经验：模板再完善，也要保留人工复核环节。claude-code 模板能做的是提高一致性和效率，它替代不了人对产品方向和技术方案的判断。我的习惯是，任何由模板自动生成的改动，我会过一遍 diff，重点看有没有“看似合理但方向跑偏”的地方。

这不是不信任工具，而是对结果的负责。把模板当成一个能力很强的初级工程师，它会按流程干活，但最终把关的人还是你。

我在实际使用中最大的体会是：模板的意义不在于“少敲几个字”，而在于让工具的行为可预期、可控制、可演进。你投入时间去梳理流程、写模板、调参数，换回来的是每次会话都稳定靠谱的产出。如果你还没开始，找一个最高频的任务，按照这篇里的结构写一份模板，用上一周，你会明显感觉到差别。