企业官网建设流程全解析

最近在终端里重度使用 Claude Code，和很多人一开始的思路一样，直接对话让它改代码、写脚本、查报错。但用了一段时间我发现一个尴尬的问题：同样类型的任务，我每次都要把项目背景、目录约定、代码风格、处理偏好重新说一遍，对话一长，前面交代的上下文还会被挤掉，Claude 的表现忽上忽下。后来我开始整理一套claude-code-templates，把高频任务的提示词、约束规则、输出格式都固化成模板文件，配合 Claude Code 的命令行参数和配置文件一起用，效果直接上了一个台阶。这篇文章就把这套模板库的设计思路、实际落地方法和我踩过的坑完整分享一下，适合已经在用 Claude Code、但觉得效率还有提升空间的人参考；如果你刚听说这个工具，也能从里面找到一套可以直接抄作业的上手路径。

很多人把 Claude Code 当成一个能聊天的终端助手，聊完就关，这其实只用了它一小部分能力。它真正的价值在于可编程、可配置、可批量执行，而模板恰恰是把“可复用的工作流”变成“一键调用的标准动作”的关键。下面我从设计思路开始拆解，再给出一套能直接跑起来的配置方案。

1. 项目整体设计与思路拆解

1.1 为什么需要模板层

Claude Code 本质上是一个跑在终端里的 AI 编码代理，它不像 Cursor 那样天然绑定一个 IDE 项目，你需要自己告诉它“这个项目是什么结构”“代码规范是什么”“遇到问题优先怎么处理”。如果不做任何约束，每次对话都是从零开始的“裸聊”，结果就是：

• 同一个仓库，今天让它改接口它不知道 service 层在哪，明天让它加日志它又忘了你用的是 pino 不是 log4js。
• 长对话里早期给出的约束会被后续内容冲淡，模型开始自由发挥，产生风格不一致的代码。
• 想在多个仓库之间复用同一套规则，只能靠复制粘贴提示词，维护成本高，改一处要到处同步。

claude-code-templates解决的就是这层问题。它把“项目上下文”和“任务指令”从对话中剥离出来，变成独立的模板文件。启动 Claude Code 时，通过加载模板，让它在工作一开始就具备你对项目的全部约定，再配合具体的任务描述执行，相当于给每次会话都配了一份“项目手册 + 操作规范”。

1.2 设计原则：场景驱动、参数驱动、上下文最小化

做模板库的时候我给自己定了三条原则，缺一不可。

第一是场景驱动。模板不能为了写而写，必须来自真实使用频率。我最初只做了三类：改 bug、加功能、写测试，后来才逐步扩展出代码评审、数据库迁移、部署检查、日志分析等场景。每个模板都要回答“这个任务里 Claude 需要知道什么背景信息”和“它输出的结果应该长什么样”。

第二是参数驱动。模板不是死文本，关键位置必须留出变量接口。比如改 bug 的模板，至少要接收“bug 表现”“相关文件”“期望行为”三个参数；写测试的模板要接收“被测模块”“测试框架”“覆盖率要求”。参数设计得好，模板才能在不同任务间复用，否则就是一篇篇孤立的范文。

第三是上下文最小化。这是最容易忽略的一点。模板里塞的信息越多，模型在无关内容上浪费的 token 就越多，真正重要的约束反而容易被稀释。我的做法是：模板只保留“完成任务必需的约束”和“必须避免的坑”，其余信息通过项目根目录的CLAUDE.md加载，模板里只写一句话引用它。

提示：上下文最小化不是少写内容，而是把内容放到正确的位置。项目级信息放CLAUDE.md，任务级指令放模板，全局偏好放settings.json，三者各司其职，而不是一股脑塞进提示词。

2. 核心细节解析与实操要点

2.1 模板目录结构与文件组织

我最终采用的目录结构是这样：

claude-code-templates/ ├── README.md ├── settings.json ├── agents/ │ ├── bug-fix.md │ ├── feature-dev.md │ ├── code-review.md │ ├── test-writing.md │ ├── db-migration.md │ └── log-analysis.md ├── commands/ │ ├── explain.md │ ├── optimize.md │ └── refactor.md └── scripts/ ├── new-template.sh └── validate-template.py

agents/目录放任务级模板，对应 Claude Code 的--agent或子代理模式，每个文件是一个完整的场景指令；commands/目录放短小的命令式模板，适合在对话中输入/explain、/optimize这类斜杠命令时使用；scripts/目录放辅助脚本，用来创建新模板和校验模板格式。

这种拆分的逻辑是：长任务用 agent 模板，短操作用 command 模板。比如“修复这个接口的超时问题”属于 agent 场景，需要完整上下文；而“解释这段代码在做什么”用 command 就够，没必要加载一大堆背景。混在一起会让短任务也背上沉重的上下文负担，白白浪费 token。

2.2 模板文件语法与变量注入

模板文件本身用 Markdown 写，Claude 能直接理解。但要让模板真正“活”起来，必须支持变量注入。Claude Code 的子代理模式本身就支持类似结构化的指令文件，在调用时可以直接用claude --agent bug-fix --strategy-file之类的参数加载，也可以用环境变量、命令行参数把会话信息传进去。

一个标准的 bug 修复模板长这样：

# Bug 修复任务 ## 角色定位 你是本项目资深的后端工程师，负责定位并修复指定的 bug。 ## 背景信息 项目采用分层架构，业务逻辑在 service 层，数据访问在 repository 层，对外接口在 controller 层。请先阅读项目根目录的 CLAUDE.md 获取完整约束。 ## 任务输入 - Bug 表现：{{bug_description}} - 相关文件：{{related_files}} - 期望行为：{{expected_behavior}} ## 处理步骤 1. 先复现问题，确认触发条件。 2. 定位根因，不要只修表面症状。 3. 修改前先说明你的修复方案，等确认后再动代码。 4. 修改后补充回归测试。 ## 输出要求 - 给出问题根因分析，不超过 200 字。 - 列出修改的文件和关键 diff 片段。 - 说明验证方式，包括运行的测试命令和结果。

变量用{{双大括号}}包起来，调用模板时把具体值替换进去。这样同一个模板既能处理“登录接口超时”，也能处理“订单状态不更新”，只是参数不同，处理流程和输出标准完全一致。

2.3 CLAUDE.md、settings.json 与模板的分工

很多人配置 Claude Code 时只知道有CLAUDE.md，不知道还有个settings.json。这三个文件的分工我梳理成一张表：

我的经验是：CLAUDE.md里写“项目是什么”，模板里写“这个任务怎么做”。比如CLAUDE.md会写“本项目使用 pnpm，禁止使用 npm”，模板里就不需要重复，只引用一句“包管理命令见 CLAUDE.md”。settings.json则负责更底层的配置，比如允许 Claude 访问哪些目录、禁用哪些有风险的操作，这些和具体任务无关，但直接影响模板能否顺利执行。

注意：settings.json里如果限制了工具权限，模板里即使让 Claude 执行某个命令也会被拦下来。我遇到过模板里写了pnpm test，但 settings 只允许pnpm build，结果测试一直跑不起来。配置权限范围时一定要对着模板的常用命令过一遍，避免两者冲突。

3. 实操过程与核心环节实现

3.1 从零搭建自己的模板库

第一步不是写模板，而是先记录自己的高频任务。我建议打开 Claude Code 的历史记录，把最近两周的对话按“任务类型”归类，看看哪些任务每周重复出现三次以上。我自己的归类结果是：改 bug 占了四成，写单测占两成，剩下的是代码解释、性能优化和日志排查。没有这个数据支撑，你很容易做出一个“看着全面但用不起来”的模板库。

第二步是搭目录骨架。按上文的结构建好目录，README.md写清楚每个模板的适用场景、必填参数和调用方式。这一步很重要，模板多了之后你会有记忆负担，README 是给自己留的索引。

第三步是写第一个模板。不要贪多，先写解决你最高频痛点的那一个。我第一个写的就是 bug 修复模板，因为当时我被“让 Claude 改 bug 但改不对地方”折磨得最狠。写完之后实测一周，发现它确实把修复一次 bug 的平均往返次数从 5 轮降到了 2 轮，于是才有了继续做下去的信心。

第四步是配套脚本化。我在scripts/里放了一个new-template.sh，作用是根据交互式输入生成模板骨架文件，避免每次手敲那段结构：

#!/bin/bash # 用法: ./new-template.sh template-name "模板描述" name=$1 desc=$2 file="agents/${name}.md" if [ -f "$file" ]; then echo "模板已存在: $file" exit 1 fi cat > "$file" <<EOF # ${name} 任务 ## 角色定位 （描述这个任务中 Claude 应扮演的角色） ## 背景信息 （项目相关约定，引用 CLAUDE.md） ## 任务输入 - 输入1：{{input1}} - 输入2：{{input2}} ## 处理步骤 1. （步骤一） 2. （步骤二） ## 输出要求 - （输出格式） EOF echo "已创建模板: $file"

这个脚本本身不强，但配合一个validate-template.py就很有用了：它会扫描所有模板，检查变量{{ }}是否成对、是否包含“处理步骤”和“输出要求”两个必要章节、有没有残留的 TODO 占位符。模板库维护到 20 个以上时，人工检查已经不可靠了，脚本校验是刚需。

3.2 三类常用场景模板实例

我并不打算把全部模板贴出来，挑三个最有代表性的展开讲，覆盖面足够你举一反三。

场景一：代码评审模板

# 代码评审任务 ## 角色定位 你是具备大型项目架构视角的资深工程师，负责对指定代码变更做全面评审。 ## 任务输入 - 变更范围：{{change_scope}} - 评审重点：{{focus_points}} ## 处理步骤 1. 先读取变更涉及的完整文件，理解上下文。 2. 从正确性、架构、可维护性、性能、安全五个维度依次检查。 3. 每个问题标注严重级别：P0 阻断合并 / P1 必须修改 / P2 建议优化。 ## 输出要求 - 按严重级别分组输出问题列表。 - 每个问题给出具体修改建议，引用代码行号。 - 最后给出整体结论：通过 / 有条件通过 / 不通过。

这个模板的要点是评审维度固定、输出结构固定，避免 Claude 每次评审抓的重点都不一样。实际用下来，它产出的评审意见比自由式聊天专业很多，特别是 P0/P1/P2 分级，可以直接对接合并请求的讨论。

场景二：测试编写模板

# 测试编写任务 ## 角色定位 你是测试工程师，负责为指定模块补充单元测试或集成测试。 ## 任务输入 - 被测模块：{{module_path}} - 测试框架：{{test_framework}} - 覆盖要求：{{coverage_target}} ## 处理步骤 1. 阅读被测模块的源代码，梳理主流程和分支逻辑。 2. 先列测试用例清单，覆盖正常路径、边界条件和异常路径。 3. 按清单逐一编写测试，保证用例可独立运行。 4. 运行测试并修复所有失败项。 ## 输出要求 - 输出测试用例清单和对应断言说明。 - 列出测试运行结果和覆盖率数据。 - 对未覆盖的分支说明原因。

用这个模板时要注意，测试框架参数必须填。我试过不填框架，Claude 默认用了 Jest，但项目里实际是 Vitest，生成的测试全跑不起来。填了之后它会主动遵守项目的测试配置，包括vitest.config.ts里的路径别名和覆盖率阈值。

场景三：日志分析模板

# 日志分析任务 ## 角色定位 你是 SRE 工程师，负责从日志中定位线上问题的根因。 ## 任务输入 - 日志文件：{{log_path}} - 错误关键词：{{error_keyword}} - 时间范围：{{time_range}} ## 处理步骤 1. 先提取指定时间范围内包含错误关键词的日志条目。 2. 识别异常条目的时间分布和频率，判断是否为突发。 3. 追踪同一次请求的全链路日志，定位首个异常点。 4. 结合代码分析可能的原因，给出排查下一步。 ## 输出要求 - 按时间线整理关键日志片段，保留原始内容。 - 标注异常特征：错误码、响应延迟、依赖服务状态。 - 给出根因假设，并列出验证该假设的具体方法。

这个模板是我后来觉得最值的一个。之前让 Claude 直接“帮我看看这个日志”，它经常只给一堆没有重点的摘要，加了这个模板后它会自己按时间线串链路，输出质量和我手动排查的思路基本一致。

3.3 模板在批量任务与自动化流程中的落地

模板不止能用在单次对话，还可以结合 Claude Code 的命令行模式批量跑。举例说明：我有一个仓库需要给所有 Controller 层接口补齐参数校验测试，手写要两三天。我的做法是先在项目里跑一次测试编写模板，让 Claude 产出第一个接口的测试用例，确认风格没问题之后，再写一个批量循环脚本，遍历所有 Controller 文件，对每个文件调用claude --agent test-writing --strategy-file加载对应模板，把被测模块参数换成文件路径，跑一轮下来直接生成几十个测试文件。

整个过程里最关键的技巧是先小规模验证风格，再大规模批量执行。批量跑之前先在 2 个文件上试跑，检查输出格式是否符合项目规范，否则几十个文件生成完再发现风格不对，返工成本极高。另外，批量任务一定要加--permission-mode限制，不要让 Claude 在没有确认的情况下直接修改文件，我都是用“先输出到临时目录，人工确认后再合并”的方式，安全性会好很多。

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

4.1 模板不生效与上下文被截断

最常遇到的问题不是模板本身写错，而是模板没被加载进去。我一开始用子代理模式加载模板，但忘了看 Claude Code 的启动参数说明，有些版本对--agent的路径要求是相对~/.claude/agents/目录的，我放在项目目录里的模板根本没被识别到。排查方法是启动后第一句话问 Claude“你当前的工作模式是什么？有哪些约束？”，它复述不出来就说明模板没加载成功。

上下文被截断是另一个高频问题。模板写得太长，加上项目本身的CLAUDE.md又很长，一次会话里塞不下，模型就会丢弃最早的内容，等于模板白写了。我的经验是模板控制在 80 行以内，CLAUDE.md控制在 120 行以内，两条加起来不超过 220 行，基本能保证整个会话期间约束都在。如果确实内容多，拆成多个模板文件，按需加载，而不是合并成一个巨型模板。

4.2 变量替换失败与路径错乱

模板里的{{变量}}替换失效，通常是我在批量调用时生成的命令写错了。排查脚本里我加了--print-prompt类似的参数，先不真正执行，把替换后的完整提示词打印出来肉眼检查一遍。这一步能拦住绝大多数低级错误，比如字段名拼错、花括号没配对、路径里有特殊字符被 shell 展开等。

路径错乱的问题则要警惕shell 的变量展开和通配符。我在批量循环里直接传文件路径时，路径里如果有空格或者*，会被 shell 拆成多个参数。解决办法是写脚本时统一用引号包住所有路径变量，不要图省事裸放。代码里加双引号看起来是小细节，出问题的概率却很高。

4.3 权限配置、多用户协作与版本管理

权限配置的坑我在前面已经说过，settings.json 的权限粒度会直接让模板里的命令失效。排查思路上，如果模板执行时 Clude 报告“命令被拒绝”，去settings.json的权限数组里看一眼，看看有没有明确放行对应命令。我的做法是在 settings 里设一个“模板白名单目录”，模板里涉及的命令必须在白名单内，否则宁可拆模板也不放大权限。

多人和团队协作时，模板库要纳入版本管理，并且要有 review 机制。我自己维护的模板库用 Git 管理，新增模板必须经过两道检查：脚本校验自动检查格式，人工检查看角色描述和步骤是否符合团队当前的技术规范。团队里总有人的模板写得特别“个性化”，比如要求 Claude“不要客套”“直接用最激进的方式改”，这种语气词其实会影响输出质量，review 时我会统一收敛成中性的指令。

提示：模板库的settings.json属于全局或项目级配置，各成员本地可以覆盖。推模板代码时记得不要把自己的本地权限配置推到主干，否则别人拉下来可能被你的权限限制卡住。

5. 从模板库到个人工作流的延伸

5.1 模板与记忆文件配合使用

我实际使用中发现，模板库和 Claude Code 的记忆文件是配合关系。像项目的技术决策记录（ADR）、目录结构变化、易错点这些内容，放进CLAUDE.md之后会持续影响每次会话；而模板更偏向“动作”的复用，解决“某个任务怎么做”的问题。

举例说明，我在一个压测项目里把“压测脚本只能通过 locust 运行，不使用 JMeter”写到了CLAUDE.md里，然后在压测任务模板里只写“压测工具遵循项目约定，不额外引入新框架”。这样即使我不在模板里反复强调，Claude 也知道要用什么工具，模板体量也因此保持精简。

5.2 模板演化过程中的取舍

模板不是一成不变的。我用了一个多月后，发现 bug 修复模板里“先说明修复方案，等确认后再动代码”这个步骤极大地提高了交互轮次，原因是每次都要两端来回跑，后来把它改成了“对于改动不超过 20 行的修复，直接改并给出完整 diff；对于涉及架构调整的修改，先出方案再动代码”。这一步让我修复类任务的完成时间缩短了大概三分之一。

这里想说的是，模板迭代一定要基于真实使用数据，而不是拍脑袋。我在脚本里加了一个简单的耗时统计，每次会话结束后记录对话轮数和总耗时，定期拉出来看哪个模板的平均轮数明显偏高，就说明那个模板的指令不够明确或者约束有冲突，需要改。

5.3 适合继续扩展的方向

如果你觉得当前这套模板库已经稳定，可以考虑往上再做几层：一是把模板按项目类型分层，比如 Web 前端项目、后端服务项目、数据脚本项目各维护一套模板子目录，通过符号链接或配置文件决定当前项目加载哪一层；二是把模板库和 CI 流程打通，提交代码时自动触发“代码评审模板”跑一轮静态评审，结果直接附在合并请求里；三是把模板里的角色定位做成独立的角色文件，一套角色配置配合多个任务模板复用，减少重复定义。

我自己的下一步打算是把模板库拆成两层：基础模板层解决通用任务，项目模板层承载具体的业务约定，项目模板引用基础模板，这样跨项目复用时只同步基础层，对项目层的干扰会小很多。这个结构还在验证阶段，但如果你也遇到“换一个项目模板就全乱”的问题，可以参考这个思路试试。