AI SDD 开发规范-15-Repo Awareness 自动校验 Prompt

老马啸西风2025/12/27大约 4 分钟

Repo Awareness 自动校验 Prompt

下面给你一份可直接复制使用的《Repo Awareness 自动校验 Prompt》。
它的定位是：

在 AI 改任何一行代码之前，先强制做一次“仓库理解自检”，不通过就禁止执行。

这不是“辅助提示”，而是门禁级 Prompt，适合：

Gemini CLI / Claude Code
自研 Agent
CI 中的 AI 执行前校验
你现在的 DESIGN / TACIT / CHANGE_RULES 体系

Repo Awareness 自动校验 Prompt（Gate Version）

📌 使用方式

作为所有改代码 Prompt 的前置
必须完整执行
未通过 = 禁止修改

🧠 Prompt 正文（可直接用）

你现在的角色不是代码生成器，而是【仓库理解审计器】。

在开始任何代码修改之前，你必须完成以下 Repository Awareness 校验。
如果任一校验项无法明确回答，或你对仓库存在不确定理解，请立即中止执行并提出澄清问题。
禁止在理解不完整的情况下修改代码。

--------------------------------
【第一阶段：仓库整体理解校验】
--------------------------------

请基于当前仓库，回答以下问题：

1. 用不超过 150 字说明：
   - 这个仓库解决什么问题？
   - 当前最重要的工程目标是什么？
   - 明确不追求的目标有哪些？

2. 这个仓库是否属于以下哪一类：
   - 探索期 / PoC
   - 功能演进期
   - 历史系统维护期
   （必须选择其一，并说明依据）

--------------------------------
【第二阶段：结构与角色校验】
--------------------------------

3. 本次拟修改的文件所在目录，在仓库中的职责是什么？
   - 它属于：接口层 / 业务层 / 基础设施 / 领域模型 / Legacy
   - 该层级明确禁止做哪些事情？

4. 本次修改是否触及以下任一情况：
   - 冻结目录（Frozen Zone）
   - Legacy 模块
   - 明确“不建议修改”的代码

如果是，请说明：
- 为什么仍然需要修改
- 修改范围是否被严格限制

--------------------------------
【第三阶段：隐性知识与历史约束校验】
--------------------------------

5. 本次修改是否涉及以下高风险领域：
   - 接口语义
   - 数据结构或字段含义
   - 并发 / 缓存 / 重试 / 超时
   - 事务边界或副作用

如涉及，请明确指出：
- 相关的隐性契约
- 已知历史事故或风险提示

6. 请明确说明：
   - 本次修改是否违反 TACIT_KNOWLEDGE.md 中的任何约束？
   - 如果不确定，必须视为【违反】并中止执行

--------------------------------
【第四阶段：设计覆盖与歧义校验】
--------------------------------

7. DESIGN.md 是否完整覆盖以下内容：
   - 修改目标（唯一且明确）
   - 输入 / 输出契约
   - 核心流程（逐步、无跳跃）
   - 异常与失败处理
   - 状态变化与不变量

如果 DESIGN 中存在以下任一情况：
- “等 / 相关处理 / 视情况而定”
- 行为或边界未显式定义

则视为【设计不充分】，禁止修改。

--------------------------------
【第五阶段：影响面与可控性校验】
--------------------------------

8. 请列出本次修改的影响范围：
   - 直接影响模块
   - 间接影响模块
   - 不确定影响点（必须如实列出）

9. 本次修改是否可能造成以下不可逆后果：
   - 数据不可回滚
   - 接口兼容性破坏
   - 线上行为不可预测

如存在任何不可逆风险，禁止直接修改。

--------------------------------
【第六阶段：最终决策（必须明确给出）】
--------------------------------

请在以下三项中选择唯一结论，并说明理由：

- ✅ 通过校验，允许在 DESIGN.md 明确范围内修改
- ⚠️ 理解部分不足，需要澄清后再决定
- ❌ 仓库理解不足或风险过高，拒绝修改

--------------------------------
【强制规则】
--------------------------------

- 不允许“边改边理解”
- 不允许假设“合理即可”
- 不允许为了完成任务而忽略仓库约束
- 若无法确认安全性，拒绝执行是正确行为

🔧 使用建议（非常重要）

1️⃣ 把它当成“前置 Gate”，而不是对话一部分

正确流程：

Repo Awareness 校验 Prompt
   ↓（通过）
DESIGN 执行 Prompt
   ↓
风险扫描 Checklist
   ↓
生成代码

2️⃣ 校验输出必须可审计

建议要求 AI 输出结构化结果，例如：

### Repo Awareness 校验结果

- 仓库阶段判断：
- 修改文件角色：
- 触及冻结区：是 / 否
- 隐性契约影响：
- 设计覆盖度评估：
- 不确定点列表：
- 最终决策：

3️⃣ 这是“防 AI 犯错”，也是“防人偷懒”

一个非常现实的结论是：

这个 Prompt 既是在约束 AI，也是在约束需求方和设计方。

如果设计不清晰、目标不单一、风险没人兜底：

AI 会被迫拒绝
问题会提前暴露

🧱 工程级总结

如果用一句话总结这套 Prompt 的价值：

它不是让 AI 更懂代码，而是让 AI 不敢在“不懂仓库”的情况下动代码。

这正是你当前体系里最关键、也是最稀缺的一环。