Claude Code 提示词库维护：把团队指令变成可复用资产

不要把好提示词留在聊天记录里

很多团队刚开始使用 Claude Code 时，会把有效提示词贴在 Slack、PR 评论、Notion 或个人笔记里。短期看很方便，几周后就会变成问题：同一类 review 有五个版本，没人知道哪个是最新，产品页 CTA 该用哪个检查模板也说不清。最后大家又回到每天重新写 prompt 的状态。

提示词库不是“句子收藏夹”，而是一个小型运营资产。它需要版本管理、负责人、审核关卡、废弃策略和效果指标。官方的 Claude Code Prompt library 提供了可复制的模式；团队内部还要把这些模式和自己的仓库、商品页、培训流程、支持工单连接起来。相关官方文档还包括 CLAUDE.md 与 memory、Skills、Subagents 和 Hooks。

本文延续 Claude Code review 流程清单 和 前 30 分钟清单。目标是帮助商业化团队把提示词维护成能支持产品模板、付费培训和咨询交付的资产，而不是一次性经验。

先建登记表，而不是先追求完美句子

versioning 指的是版本追踪，owner 是负责人，review gate 是进入正式库前的审核关卡，deprecation 是旧版退役规则，metrics 是效果指标。初学者只要先理解这五个词，就能避免大多数混乱。

可以先把下面内容保存为 prompt-library.json。

[
  {
    "id": "review-risk-finder",
    "version": "1.2.0",
    "owner": "platform",
    "status": "active",
    "useWhen": "A pull request changes behavior, data flow, pricing, or CTA routing.",
    "inputs": ["goal", "diff", "riskAreas", "expectedTests"],
    "output": "Findings ordered by severity with evidence and smallest fix.",
    "reviewGate": "Owner approval plus one successful run on a known risky diff.",
    "deprecates": ["review-risk-finder@1.1.0"],
    "metrics": ["reuse_count", "accepted_findings", "false_positive_rate"],
    "officialDocs": [
      "https://code.claude.com/docs/en/prompt-library",
      "https://code.claude.com/docs/en/memory"
    ]
  }
]

这张表不会自动让提示词变好，但它会让提示词可管理。输出太吵时，owner 可以修改；商品页改版时，团队可以判断 CTA review prompt 是否需要小版本；培训材料交付时，讲师可以明确告诉学员当前使用的是哪个 active 版本。

每个模板只负责一个结果

常见错误是把 review、修复、测试、文档、重构、营销文案全部塞进一个 prompt。它看起来节省时间，但失败时无法判断问题出在哪里。团队库里的每个 prompt 最好只产出一个成果物。

# review-risk-finder

You are reviewing a production change for business and user risk.

Context:
- Goal: {{goal}}
- Diff or changed files: {{diff}}
- Risk areas: {{riskAreas}}
- Expected tests: {{expectedTests}}

Return findings first. For each finding include:
1. Severity
2. Evidence from the diff
3. User or revenue impact
4. Smallest safe fix
5. Verification command

If there are no findings, list what you checked and what remains unverified.

这个模板的价值在于，它提前定义了“风险”和“证据”。工程负责人可以看验证命令，产品负责人可以看收入影响，培训负责人可以把相同结构变成课堂练习。角色越清晰，Claude Code 的输出越容易被人类审查。

Use case：把提示词分给真实业务场景

Use case 1 是 PR review。不要只说“帮我看看风险”，而是传入目标、diff、预期测试和风险区域，例如支付、权限、认证、数据删除、CTA 路由。这样返回内容会更接近可修复的问题，而不是泛泛建议。

Use case 2 是 /zh/products/ 商品页维护。提示词应该检查承诺是否清楚、目标读者是否明确、购买后能得到什么、价格语言是否一致、内部链接是否有效。这个 prompt 应该由产品或营销共同负责，不能只交给工程。

Use case 3 是 /zh/training/ 培训咨询页。提示词需要识别团队痛点、现有流程成熟度、Claude Code 导入风险、培训后要交付哪些运营物。这里的指标不只是访问量，还包括有效咨询、重复 onboarding 问题是否减少。

Use case 4 是旧文章更新。Claude Code 的官方文档、命令行为和产品链接都会变化。文章刷新 prompt 应检查官方链接、内部链接、updatedDate、代码示例、截图或图解，以及是否有实际尝试后的结果。

用审核关卡控制进入 active 的条件

先定义三个状态就够了：draft、active、deprecated。draft 可以试用，active 可以进入文档、产品和培训材料，deprecated 保留迁移说明。

版本号可以简单采用语义化版本。输出格式发生破坏性变化时升 major，新增输入时升 minor，只改措辞或例子时升 patch。重点不是仪式感，而是避免团队成员以为自己在用最新版，实际却依赖旧行为。

flowchart LR
  Draft["draft prompt"] --> Owner["owner review"]
  Owner --> Gate["known-risk gate"]
  Gate --> Active["active library"]
  Active --> Metrics["monthly metrics"]
  Metrics --> Deprecate["deprecate or improve"]

known-risk gate 是很多团队漏掉的一步。每个重要 prompt 至少保留一个真实失败输入：曾经漏掉的危险 diff、坏掉的购买按钮、隐藏在日志后面的第一个构建错误、保留了旧官方链接的文章。如果 prompt 处理不了这个已知失败，它还不能进入正式库。

给 agent 明确边界

在这里可以把 agent 理解成“带着特定职责的工作担当”。官方 Subagents 文档说明了子代理可以在独立上下文里处理任务，但上下文独立也意味着任务必须窄。提示词库适合拆成三类角色：维护元数据的 librarian、用失败样例测试输出的 reviewer、批准变更的 owner。

例如可以把下面文件放到 .claude/agents/prompt-librarian.md。

---
name: prompt-librarian
description: Maintains prompt library metadata, ownership, versions, metrics, and deprecation notes.
tools: Read, Grep
---

You audit prompt library entries. Do not rewrite product copy.
Check that each prompt has id, version, owner, status, useWhen, inputs, output,
reviewGate, deprecation note, and metrics. Report missing fields first.

这个 agent 应以读取和审计为主，不要让它悄悄改商品文案或销售 CTA。需要强制阻断的规则应交给 Hooks、权限或 CI，而不是只依赖一句自然语言指令。

Pitfall：提示词库最容易坏在哪里

Pitfall 1 是命名太模糊。good-review、debug-helper、marketing-check 一个月后很难搜索。名称最好包含对象和结果，例如 checkout-cta-risk-review、build-log-first-failure、training-page-objection-check。

Pitfall 2 是只保存成功例。成功例会让 prompt 看起来比实际更强。至少保留一个失败输入，并写清“漏掉旧价格链接”“只检查了测试名，没有看实现”这样的具体问题。

Pitfall 3 是把全部规则塞进 CLAUDE.md。CLAUDE.md 很有用，但它是上下文，不是硬性策略。要阻断危险操作，应使用 Hooks、权限或 CI。prompt 负责判断框架，gate 负责执行约束。

Pitfall 4 是最后才加销售 CTA。文章写完后硬加商品链接会像广告。更自然的路径是：免费内容帮助读者先试，产品模板帮个人节省时间，培训咨询帮团队建立流程。

还有一个容易被忽略的问题：把提示词库当成工程团队内部工具，而不是商业交付的一部分。对 Claude Code 团队来说，prompt 不只影响代码质量，也影响产品说明、价格页、邮件注册、咨询表单和客户培训。如果这些场景没有 owner，最终会变成“谁有空谁来改”。更好的做法是在登记表里明确区分 engineering、product、training 三类 owner，并让每类 owner 每月只看自己负责的少数指标。

这样做的好处是转化路径更清楚。工程 prompt 证明团队能安全交付，产品 prompt 帮读者理解购买价值，training prompt 让企业客户看到导入后的流程资产。三者合在一起，文章就不只是流量入口，而是从学习、购买到团队导入的完整路径。

用脚本防止基础信息缺失

库里超过十个条目后，就应该自动检查必填字段。下面脚本可以直接用 Node.js 运行。

import fs from "node:fs";

const file = process.argv[2] ?? "prompt-library.json";
const entries = JSON.parse(fs.readFileSync(file, "utf8"));
const required = [
  "id",
  "version",
  "owner",
  "status",
  "useWhen",
  "inputs",
  "output",
  "reviewGate",
  "metrics"
];

let failed = false;
for (const entry of entries) {
  const missing = required.filter((key) => !entry[key]);
  if (!/^\\d+\\.\\d+\\.\\d+$/.test(entry.version ?? "")) {
    missing.push("version must be semver");
  }
  if (!["draft", "active", "deprecated"].includes(entry.status)) {
    missing.push("status must be draft, active, or deprecated");
  }
  if (missing.length > 0) {
    failed = true;
    console.error(`${entry.id ?? "(missing id)"}: ${missing.join(", ")}`);
  }
}

if (failed) process.exit(1);
console.log(`OK: ${entries.length} prompt entries checked`);

脚本不能替代人工判断，但能阻止没有 owner、没有版本、没有 reviewGate 的 prompt 进入销售和培训链路。

指标要少，但要能改变行为

指标	为什么看	改进动作
reuse_count	团队是否找得到并愿意用	低时改名或移动位置
accepted_findings	输出是否真的带来修复	低时收紧输出格式
false_positive_rate	是否浪费 reviewer 时间	高时具体化 riskAreas
time_to_fix_minutes	修复是否更快	要求 smallest safe fix
cta_click_rate	产品和培训路径是否改善	调整 CTA 上下文和位置

每月看一次即可。没人用、不被信任、不能支持决策的 prompt 应该废弃。小而活跃的库，比没人敢碰的大仓库更有价值。

把库连接到产品和培训

维护良好的提示词库会形成清晰转化路径。免费文章解释思路；ClaudeCodeLab 产品给个人开发者现成模板；Claude Code 培训与咨询帮助团队把 owner、review gate、hooks、metrics 和 rollout 材料落到真实仓库。

Masa 实际尝试后发现，最初保留三十多个 prompt 反而降低效率。后来按 review、debug、商品页、培训页四类整理，每类最多三个 active prompt，并保留真实失败例，团队更容易选择，也更容易改进。提示词库的价值不在数量，而在能否持续让 Claude Code 的输出变得可审查、可复用、可销售。