你的团队可能还在 Confluence 里堆积如山的技术文档，但新一代工程师已经不再去那里查东西了。

他们打开 ChatGPT 或 Claude，直接问。因为更快、更准、更符合上下文。

问题是：AI 的回答是基于通用训练数据的，不是基于你们团队的私有知识。 它不知道你们的编码规范、不知道你们的架构约束、不知道你们的业务规则。所以它给出的代码和建议，经常跟你们的实际情况格格不入。

解决方案不是禁止工程师用 AI，而是把团队知识从静态文档转向动态 Prompt 工程库。这篇讲怎么做。

---

一、为什么传统知识管理失效了

失效 1：文档写得越多，读得越少

技术文档有一个经典悖论：

• 不写文档，新人没法上手
• 写了文档，没人看，因为太长、太旧、太难搜
• 文档越厚，维护成本越高，过期的速度越快

我见过很多团队的 Confluence 里有几百页文档，但工程师遇到问题时第一反应是问同事或问 AI。文档成了摆设。

失效 2：AI 无法理解你们的文档结构

你把架构文档喂给 AI，它确实能读。但：

• 它不知道哪部分文档是权威的，哪部分已经过时
• 它无法把分散在多个页面的信息整合成一个连贯的解决方案
• 它不能判断文档里的代码示例是否跟你们当前的代码库版本兼容

AI 处理文档的能力远不如人类想象的强。尤其是当文档之间存在矛盾、缺失、或者隐含的假设时。

失效 3：知识在对话中流失

最可怕的一点：团队里最有价值的知识，不在任何文档里。

它在 Slack 的对话里、在代码评审的评论里、在工程师和 AI 的私聊记录里。这些信息：

• 没被记录
• 即使记录了也没人整理
• 即使整理了也跟不上系统变化的速度

结果是：同一个问题，团队反复问 AI，AI 反复给不准确的答案，工程师反复手动修正。知识没有积累，只有重复劳动。

---

二、Prompt Registry：新的知识容器

核心定义

Prompt Registry 是一个经过结构化组织、版本控制、持续迭代的 Prompt 模板库。每个模板都封装了团队在特定场景下的最佳实践、约束条件、上下文知识和质量要求。它是 AI 时代的「可执行文档」。

跟传统文档的区别：

维度	传统文档（Wiki/Confluence）	Prompt Registry
形式	静态文本、图片、代码块	可执行的 Prompt 模板，带变量插槽
消费方式	人读	AI 执行，人审结果
更新机制	手动维护，容易过期	与代码库联动，失败时触发更新
知识密度	低（大量解释性文字）	高（直接封装约束和上下文）
可验证性	低（无法自动验证正确性）	高（输出可通过测试验证）

Prompt Registry 的构成

一个完整的 Prompt Registry 包含以下层级：

1. 元上下文层（Meta-Context）

描述整个团队/项目的通用约束：

• 技术栈和版本（Python 3.11、Django 4.2、PostgreSQL 15）
• 编码规范（PEP 8 + 团队自定义规则）
• 架构原则（微服务？单体？事件驱动？）
• 安全红线（哪些库不能用、哪些操作必须人工审批）

这一层通常由一个 meta-context.md 文件管理，每次调用 AI 时自动注入。

2. 领域模板层（Domain Templates）

按业务领域组织的专用 Prompt：

• payment/generate-refund-logic.prompt：生成退款逻辑的 Prompt，内含幂等性要求、并发控制约束、对账规则
• auth/generate-permission-check.prompt：生成权限检查的 Prompt，内含 RBAC 模型定义、性能约束
• recommendation/generate-coldstart-strategy.prompt：生成冷启动策略的 Prompt，内含业务目标、数据约束、A/B 测试要求

3. 任务模板层（Task Templates）

跨领域的通用任务 Prompt：

• tasks/generate-unit-tests.prompt：生成单元测试的标准 Prompt（带覆盖率要求、边界条件清单）
• tasks/generate-api-docs.prompt：生成 API 文档的 Prompt（带 OpenAPI 规范要求）
• tasks/security-review.prompt：让 AI 自查代码安全问题的 Prompt（带 CVE 检查清单）

4. 反例层（Anti-Patterns）

记录 AI 在该团队/领域最容易犯的错：

• anti-patterns/payment-race-conditions.md：AI 经常忽略的支付并发问题及正确做法
• anti-patterns/auth-caching-mistakes.md：AI 在权限缓存上的常见错误

这一层是最被低估的。知道 AI 哪里容易翻车，比知道 AI 哪里能干更重要。

---

三、怎么从零搭建 Prompt Registry

步骤 1：选一个「痛点场景」开局（第 1 周）

不要试图一次性覆盖所有场景。选一个团队最痛苦、重复最多的任务：

• 生成 CRUD API（如果团队还在手写大量 CRUD）
• 生成单元测试（如果测试覆盖率长期低于 60%）
• 重构遗留代码（如果有大量技术债务需要清理）

针对这个场景，写出第一个 Prompt 模板。

步骤 2：写出第一个「黄金 Prompt」（第 1-2 周）

黄金 Prompt 的标准：

• 上下文完整：包含足够的信息让 AI 理解约束，但不至于 token 超限
• 输出可验证：AI 的输出必须能通过某种方式验证（编译、测试、lint）
• 可复用：同样的 Prompt 给不同的输入，都能产生符合预期的输出
• 可迭代：当发现 AI 输出有问题时，能在 Prompt 里找到明确的改进点

一个黄金 Prompt 的结构：

【角色】你是一名擅长 [技术栈] 的资深工程师，熟悉 [架构原则]。
【任务】请根据以下需求生成 [具体输出]。
【约束】
- 必须遵循 [编码规范]
- 必须使用 [依赖版本]
- 必须处理 [边界条件]
- 禁止 [安全红线]
【上下文】
- 相关代码：[当前代码片段]
- 依赖接口：[接口定义]
- 数据模型：[Schema]
【输出格式】
- 代码块使用 [语言] 标注
- 关键决策点在注释中说明
- 生成对应的单元测试
【验证标准】
- 代码必须通过 [lint 规则]
- 测试覆盖率必须达到 [百分比]

步骤 3：版本控制 + 代码化（第 2-3 周）

Prompt Registry 必须跟代码库一样管理：

• 放在 Git 仓库里，跟项目代码同库或子模块
• 每个 Prompt 文件都有版本历史，变更要 PR Review
• 引入自动化测试：用固定输入跑 Prompt，验证输出是否符合预期

示例目录结构：

prompts/
├── meta-context.md          # 元上下文
├── domains/
│   ├── payment/
│   │   ├── generate-refund.prompt
│   │   └── anti-patterns.md
│   └── auth/
│       ├── generate-permission-check.prompt
│       └── anti-patterns.md
├── tasks/
│   ├── generate-unit-tests.prompt
│   └── security-review.prompt
└── tests/
    ├── test_payment_prompts.py
    └── test_auth_prompts.py

步骤 4：集成到工作流（第 3-4 周）

Prompt Registry 必须「长在」工程师的工作流里，而不是独立存在：

• IDE 插件：在 Cursor/VS Code 里集成 Prompt 选择器，右键选「用 payment/refund Prompt 生成」
• CI 集成：PR 提交时自动用对应领域的 Prompt 跑安全审查，结果贴在 PR 评论里
• Slack Bot：工程师在 Slack 里 /prompt payment/refund，Bot 自动调用 AI 并返回结果

步骤 5：建立反馈闭环（持续）

Prompt Registry 不是写一次就完事的，它必须持续进化：

• 输出质量看板：记录每个 Prompt 的首次通过率、返工率、生产缺陷归因率
• 定期 Prompt 审计：每月选一个 Prompt，用最新的模型重新跑，看输出质量是否退化
• 缺陷回溯：如果 AI 生成的代码出了生产 bug，必须回溯到对应的 Prompt，分析是 Prompt 缺陷还是模型局限

---

四、常见坑和避坑指南

坑 1：Prompt 写得太啰嗦

很多人以为 Prompt 越长越详细，效果越好。实际上：

• 太长的 Prompt 会稀释关键约束，AI 反而抓不住重点
• 上下文窗口有限，啰嗦的 Prompt 会挤占代码空间

避坑：用「结构化 + 关键词」代替自然语言描述。清单比段落有效。

坑 2：一个 Prompt 想覆盖所有场景

「通用生成代码 Prompt」是陷阱。不同场景需要的约束完全不同。宁可维护 20 个专用 Prompt，也不要 1 个万能 Prompt。

坑 3：不测试 Prompt 的稳定性

同一个 Prompt，同一个模型，两次运行可能输出不同的代码。如果不做稳定性测试，你的「黄金 Prompt」可能某天突然翻车。

避坑：对关键 Prompt 做「N 次运行一致性测试」——跑 10 次，检查输出是否都在可接受范围内。

坑 4：Prompt Registry 变成另一个没人维护的文档库

如果 Prompt Registry 没有集成到工作流、没有反馈闭环、没有 ownership，它就会变成 Confluence 2.0。

避坑：指定专人负责维护（可以是轮流制），把 Prompt 质量纳入团队绩效考核。

---

写在最后

知识管理的本质没有变：让团队的经验可积累、可复用、可进化。

变的是载体。以前是文档，现在是 Prompt。以前是给人读的，现在是给 AI 执行的。

Prompt Registry 不是技术炫技，而是组织能力的工程化。它把散落在各个工程师脑袋里的隐性知识，转化成可被 AI 理解、可被团队共享、可被持续改进的显性资产。

谁先建好这套系统，谁就在 AI 时代的工程效率竞赛里领先一个身位。

---

你们团队有维护 Prompt 模板的习惯吗？还是用 AI 全靠个人发挥？欢迎交流。