隐性知识显性化模板

工程可落地、专为 AI 编程设计的《隐性知识显性化模板》。
它的设计目标不是“写说明文档”，而是：

把“只存在于人脑中的工程常识、禁忌和历史妥协，转化为 AI 可执行、可约束、可审计的显性结构。

这套模板可以直接放进仓库（建议文件名：TACIT_KNOWLEDGE.md 或 ENGINEERING_CONSTRAINTS.md），并作为 AI 执行前必读文档。

---

隐性知识显性化模板（AI-First 版）

使用原则

• 本文档用于约束 AI 与人类对代码的修改行为
• 优先级高于 README、DESIGN、代码风格规范
• 当本文档与其他文档冲突时，以本文档为准

---

1️⃣ 系统不可变前提（Immutable Assumptions）

这些前提被大量代码、下游系统或运行环境隐式依赖，改变会造成系统性风险

### 不可变前提清单

- 系统运行在单体 + 弱一致缓存模型下
- 所有接口默认允许重复调用（幂等性假设）
- DB 是最终一致性的事实源
- MQ 可能出现至少一次投递
- 存在老客户端，无法强制升级

❗ AI 行为规则

• ❌ 不允许修改或推翻上述前提
• ❓ 如修改涉及这些前提，必须先提出澄清问题并等待确认

---

2️⃣ 冻结区域 / 禁止触碰模块（Frozen Zones）

这些区域的结构和行为具有历史包袱，仅允许最小化修复

### 冻结目录

- /auth/**
- /payment/legacy/**
- /api/v1/**

冻结原因（必须填写）

• 已对接多个外部系统
• 接口行为已被文档外依赖
• 存在历史兼容逻辑，无法全面测试

允许行为

• 修复明确 Bug
• 增加日志（不改变逻辑）

禁止行为

• 重构
• 重命名
• 抽象层次变更

---

## 3️⃣ 历史事故与已知陷阱（Historical Incidents & Known Traps）

> **这是最重要的一节，也是隐性知识密度最高的地方**

```md
### 已知陷阱清单

#### [INC-2022-11-Cache]
- 现象：缓存 Key 调整后引发大规模缓存击穿
- 根因：Key 与业务参数强耦合
- 教训：禁止在未评估全量 Key 空间前修改缓存策略
- AI 风险：看似“合理”的 Key 优化会直接引爆系统

#### [INC-2023-04-Timeout]
- 现象：统一超时参数导致链路雪崩
- 根因：不同下游 SLA 差异巨大
- 教训：超时配置不得统一

❗ AI 行为规则

• 任何涉及缓存 / 超时 / 并发的修改

  • 必须先检查本节
  • 必须显式说明未触发任何已知陷阱

---

4️⃣ 隐式契约（Implicit Contracts）

代码中未声明，但真实存在的行为约束

### 接口隐式契约

- createOrder 在失败时也可能产生副作用（日志 / MQ）
- queryXXX 方法在高并发下允许返回旧数据
- delete 接口实际是“逻辑失效”，非物理删除

### 数据隐式契约

- status 字段的数值含义禁止扩展
- ext 字段允许存放任意 JSON，但不得删除历史 key

❗ AI 行为规则

• 不允许假设“无副作用”
• 不允许简化为“更纯粹”的语义

---

## 5️⃣ 非目标声明（Explicit Non-Goals）

> **防止 AI “过度优化”**

```md
### 本系统明确不追求

- 高度模块化
- 极致性能
- 架构重构
- 完美代码风格

### 当前阶段唯一目标

- 稳定性
- 可预测性
- 向后兼容

---

6️⃣ 风险分级与修改权限（Change Risk Policy）

### 变更风险等级

- L1（低风险）：日志、注释、监控
- L2（中风险）：内部实现，不改变行为
- L3（高风险）：接口、数据结构、并发模型

### AI 修改授权规则

- L1：允许自动执行
- L2：执行前必须说明风险
- L3：禁止直接修改，必须输出方案 + 澄清问题

---

7️⃣ AI 澄清触发条件（Clarification Triggers）

触发即中断执行，转为提问模式

### 必须澄清的场景

- 修改接口返回语义
- 修改缓存 / 并发 / 事务策略
- 修改字段含义或生命周期
- 修改历史遗留代码

---

8️⃣ 审计与责任声明（AI Accountability）

### AI 输出要求

- 必须列出：
  - 修改点
  - 受影响模块
  - 潜在破坏的隐性契约
- 若无法确认安全性，必须拒绝执行

---

九、如何使用这套模板（非常关键）

推荐组合方式

PROJECT_PROFILE.md      → 系统是什么
DESIGN.md               → 要做什么
TACIT_KNOWLEDGE.md      → 千万别乱动什么
GEMINI.md / AI_RULES.md → AI 必须怎么做

在 Prompt 中强制注入

在开始任何代码修改前，你必须完整阅读并遵守 TACIT_KNOWLEDGE.md。
如存在不确定性，请先提出澄清问题，不要直接改代码。

---

十、一个工程级结论

隐性知识显性化，不是为了让 AI 更聪明，而是为了让系统不再依赖“某几个人还没离职”。

参考资料