别再给 Claude 模糊指令了：3 个结构化 Prompt 模板省掉 80% 的来回修改

如果你用过 Claude Code 写代码，大概率有过这种体验：它生成的代码逻辑对，但变量命名丑、没做异常处理、测试覆盖率低——然后你一句“改一下”，它改出新的问题，来回三四轮才满意。这不是 Claude 不行，是你给的 prompt 太“随性”（vibe coding）。

今天要聊的 claude-code-best-practice 项目，一天涨了近 6 万 star，核心就一句话：从 vibe coding 转向 agentic engineering。本质上就是给 Claude 一套可复用的“技能模版”（Skill），让它像一个专业工程师一样，一上手就知道你想要的交付标准。

下面我直接给你 3 个我自己正在用的 Skill 模板，复制到你的项目根目录 SKILL.md 里就能生效。每个模板都带差/好 prompt 对比，看完你就能自己改。

流程对比图：模糊指令 vs 结构化Skill的产出质量差异

1. 代码审查 Skill —— 让 Claude 自己检查自己的输出

解决什么问题：Claude 生成的代码往往只有“能跑”，缺少审查和安全意识。你需要一个边写边审的机制。

触发条件：每次 Claude 生成代码后，自动执行审查。

完整 SKILL.md 结构：

markdown
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 
# Code Review Skill
## Description
对 Claude 生成的每一段代码进行自动化审查，在交付前发现潜在 bug、安全漏洞和风格问题。

## Triggers
- 用户只差包含 "review" 或 "check" 的指令
- 生成代码块后自动触发（需在 system prompt 中声明）

## Instructions
1. 比较生成代码与项目现有编码规范（如果有 `.editorconfig`、`.eslintrc` 等则自动加载）。
2. 按优先级列出问题：安全 > 逻辑 > 性能 > 可读性 > 风格。
3. 每个问题附上修复建议，用 diff 格式给出。
4. 如果无任何问题，输出 `✅ All checks passed`。

## Constraints
- 不要修改原始生成代码，只输出审查报告。
- 最多列举 5 个最关键问题。
- 用 bullet point 列表，每条不超过 30 字。

差 prompt vs 好 prompt 对比

差 prompt（常见写法）：

text
1 
检查一下这段代码有什么问题。

结果：Claude 可能会说“看起来不错”，或者给出一通泛泛的“建议使用更安全的函数”，但你不知道优先级，也没修复方案。

好 prompt（使用 Skill）：

text
1 
请按照项目 SKILL.md 中的 Code Review Skill 审查以下代码，输出审查报告。

结果：Claude 会自动遵循结构，输出带优先级、修复 diff 的精确报告。

为什么有效：

  • 差 prompt 没有“边界”——Claude 不知道自己该多严格、多详细。Skill 用 Instructions 和 Constraints 框定了行为空间。
  • 差 prompt 没有“输出格式”——Claude 可能会写成段落，然后你还要二次消化。Skill 规定了 bullet point 和字数限制，信息密度直接翻倍。

变体用法：

  • 在 Constraints 中加入 仅检测 SQL 注入风险 即可变成安全专检 Skill。
  • 修改 max items 为 3 可提升审查速度，适合快速迭代。

2. 代码重构 Skill —— 带 Diff 输出的安全替换

解决什么问题：重构时 Claude 经常“自由发挥”改掉功能，或者只给建议不给你可运行的代码。

适用场景：需要将旧代码改写成新风格/新库，并保证行为不变。

SKILL.md 模板：

markdown
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 
# Refactor Skill
## Description
安全地将一段代码从旧风格重构为新风格，输出可直接替换的 diff。

## Triggers
- 用户指令包含 "refactor" 或 "migrate"。

## Instructions
1. 保留原始逻辑的输入输出类型和边界条件。
2. 输出代码块用 unified diff 格式（```diff），方便一键应用。
3. 如果存在破坏性变更，在 diff 上方用 WARNING 标签标出。
4. 重构完成后执行一次相同输入的单元测试（如果有测试文件）。

## Constraints
- 不得删除注释，可在原有注释基础上增加迁移说明。
- 保持同一缩进风格，不改变换行符类型。

差 vs 好

差 prompt：

text
1 
把这段 jQuery 代码改成 Vue3 组合式 API。

结果：Claude 可能会直接给你一段全新的 Vue 文件，但没说原来的 HTML 结构怎么改，你还要人工比对。

好 prompt：

text
1 
按照 Refactor Skill，将以下 jQuery 函数迁移到 Vue3 + Composition API，输出 diff。

结果：Claude 会输出类似：

diff
1 2 
- function bindClick() { $('.btn').click(handler); }
+ const handleClick = () => { /* 逻辑不变 */ };

并且会检查单元测试。

原理：差 prompt 缺少“输出格式”指令，Claude 会默认输出整个新文件，导致你没法直接 patch。Skill 中的 unified diff 约束直接解决了这个问题。另外 执行测试 约束避免了“重构成 bug”的常见失误。

变体：把迁移目标从“Vue3”改成“React 18 hooks”，只需要修改 Instructions 的第一句描述。可以做成多语言迁移 Skill。

3. 文档生成 Skill —— 从代码反推可交付的接口文档

解决什么问题：写文档是开发者最讨厌的事，但 Claude 擅长总结。问题是它总结出来的东西要么太啰嗦，要么遗漏重要参数。

适用场景：新接手项目时快速生成 README/API 文档；发布版本前补全 CHANGELOG。

SKILL.md 模板：

markdown
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 
# Documentation Skill
## Description
从代码注释、函数签名和项目中提取信息，生成结构化 Markdown 文档。

## Triggers
- 用户指令包含 "docs"、"document"、"README"。

## Instructions
1. 扫描当前文件或指定函数的所有 exports / public API。
2. 每个函数/类输出：
   - 签名（含 TypeScript 类型）
   - 参数说明（名称、类型、默认值、是否可选）
   - 返回值说明（类型、示例）
   - 使用示例（至少一个完整代码块）
3. 若文档包含示例，确保示例中的 import 路径正确（使用项目实际的包名）。
4. 输出格式为 Markdown，按字母顺序排序。

## Constraints
- 不生成任何代码修改，只输出文档。
- 示例代码必须是可执行的假代码（即不能调用真实网络接口）。

差 vs 好

差 prompt：

text
1 
给这段代码写个文档。

结果：Claude 写了一段很长的描述，但是你可能找不到每个参数的类型，也看不到代码示例。

好 prompt：

text
1 
按照 Documentation Skill，为 src/utils/format.ts 生成 API 文档。

结果：Claude 输出一个干净的 Markdown 表格，包含签名、参数、返回、示例，且示例路径用了项目实际包名，复制就能用。

为什么有效：

  • 使用项目实际的包名 这个约束非常关键。很多 prompt 忽略了上下文，Claude 会用 myLib/utils 这种假路径，而你项目实际是 @company/utils。差 prompt 没有指定，导致生成的文档无法直接复制使用。
  • 不生成代码修改 约束防止 Claude 多管闲事把代码改了。

变体：

  • 加上 只输出 CHANGELOG 条目 可变成发版日志 Skill。
  • 加上 按 Git 提交记录生成 可变成迭代总结 Skill。

如何组合使用这些 Skill？

Skill 之间可以叠用。比如：

  1. 先让 Claude 生成代码（通用 coding skill）。
  2. 自动触发 Code Review Skill 审查。
  3. 如果审查发现问题，自动调用 Refactor Skill 修正。
  4. 最后调用 Documentation Skill 更新文档。

你只需要在项目根的 CLAUDE.md 或 .claude 文件夹里放好这些 SKILL.md，并要求 Claude 按“流水线”执行即可。

markdown
1 2 
# 在 system prompt 或 CLAUDE.md 中声明流程：
After every code generation, run the Code Review Skill. If review fails with at least one critical issue, run Refactor Skill on the problematic block. Then run Documentation Skill to update API docs. Always follow the order.

这样你就从“人工来回调试”变成了“定义流程→让 AI 自动循环”。这就是 agentic engineering 的精髓：你不是在问 AI 问题，而是在设计一个能自检自修的系统。

Skill组合流水线示意图：生成→审查→重构→文档

写在最后

这个 GitHub 项目之所以一天暴涨 6 万 star，不是因为它提供了什么黑科技，而是它把很多人心里模糊的“最佳实践”变成了可读、可复制、可测试的文档。上面的 3 个模板你复制后直接放到项目根目录，下一轮跟 Claude Code 对话时就能感受到变化。

当你发现 Claude 的输出越来越接近你想要的样子——“一次过，不用改”时，你就真正理解了从 vibe coding 到 agentic engineering 的跨越。

（如果你有其他好用 Skill 模板，欢迎在评论区分享，我会整理到后续文章里。）