AI SDD 开发规范-13-仓库感知（Repository Awareness）
2025/12/27大约 4 分钟
如何让 ai 更好的 仓库感知（Repository Awareness）
这是一个已经进入“AI 编程系统工程”层级的问题。
你问的不是“怎么多喂点上下文”，而是：
如何让 AI 像一个在仓库里工作了 1–2 年的工程师，而不是一个临时读了几个文件的外包。
下面我给你一套可分阶段落地的 Repository Awareness 体系，并且会明确区分：
哪些是“立刻可做的”，哪些是“需要平台化能力的”。
一、先澄清一个关键误区
仓库感知 ≠ 上下文长度
很多人以为：
- 上下文窗口更大
- 多喂 README / tree
AI 就“理解仓库”了。
这是错误的。
仓库感知的本质是：AI 是否理解“这个仓库为什么长成这样”。
二、Repository Awareness 的 5 个层级（成熟度模型）
你可以把它当作一个能力演进路线图。
Level 0：文件级感知（大多数 AI 目前状态）
AI 能：
- 看单个文件
- 理解局部代码
AI 不知道：
- 这个文件在系统中的角色
- 为什么不能改
❌ 只能做“局部补丁”
Level 1：结构级感知（基础但必要）
AI 知道：
- 模块边界
- 分层结构
- 哪些是公共模块
最小可用手段（立刻可做）
1️⃣ 仓库结构说明文件
REPO_STRUCTURE.md
- api/
- 对外接口层，禁止直接访问 DB
- service/
- 核心业务逻辑
- infra/
- 技术实现细节2️⃣ Prompt 强制要求
在修改任何代码前，先解释该文件在仓库中的角色。Level 2：意图级感知（你已经在做）
AI 理解：
- 项目做什么
- 当前阶段目标是什么
- 为什么不做某些“正确的事”
核心文件组合
PROJECT_PROFILE.md → 为什么存在
DESIGN.md → 这次要干什么
NON_GOALS.md → 明确不干什么这是从“代码理解”跃迁到“系统理解”的分水岭
Level 3：历史与约束感知（关键跃迁）
这是 AI 编程最容易出事故、也最有价值的一层。
AI 需要知道：
- 哪些地方“看起来很烂但不能改”
- 哪些坑已经踩过
你已经有雏形，但可以进一步系统化
1️⃣ 历史包袱显性化
HISTORICAL_DECISIONS.md
- 为什么 auth 模块没重构
- 为什么 DTO 字段命名不统一2️⃣ TACIT_KNOWLEDGE.md
（你刚刚已经有完整模板）
Level 4：行为级感知（AI 开始“自我约束”）
这一层的标志是：
AI 在你没提醒的情况下，会主动避开危险修改。
实现手段不是“更聪明的模型”，而是流程设计。
关键机制
1️⃣ 改代码前强制 Scan
你已经有了：
- 风险扫描 Checklist
- 澄清触发器
2️⃣ AI 被允许拒绝执行
如果你无法确认仓库级影响，请拒绝修改并解释原因。Level 5：演化级感知（平台级能力）
这是少数团队才会做到的层级。
AI 知道：
- 仓库在“变好”还是“变坏”
- 当前是探索期 / 收敛期 / 维护期
典型能力（需要平台）
- 变更趋势分析
- 技术债密度感知
- 模块“脆弱度”评分
- 历史回滚关联分析
三、立刻可落地的 7 个仓库感知增强手段
下面是不需要平台、你现在就能用的。
1️⃣ 明确“仓库导览入口文件”
建议固定一个：
REPO_GUIDE.md内容只回答 3 个问题：
- 这个仓库是干什么的
- 哪些地方危险
- 修改流程是什么
2️⃣ 强制 AI 先“复述理解”
这是极其有效、成本极低的技巧。
在开始修改前，请先用不超过 200 字描述：
- 该仓库的整体结构
- 本次修改涉及的模块角色复述错误 = 感知失败
3️⃣ 目录级 README（比根 README 更重要）
service/README.md
infra/README.md说明：
- 允许做什么
- 不允许做什么
4️⃣ 冻结区 + 语义标记
不仅写在文档里，还体现在结构上：
legacy/
_do_not_touch/AI 对“结构信号”极其敏感。
5️⃣ “为什么存在”注释（不是“怎么用”）
坏注释：
// 校验参数好注释：
// 保留此校验是为兼容 2019 年老客户端，禁止移除6️⃣ 改代码前强制列影响面
在输出代码前，先列出：
- 直接影响模块
- 间接影响模块
- 不确定影响7️⃣ 把“禁止事项”写成第一等公民
禁止 > 建议
## 禁止事项
- 不得重构 XXX
- 不得统一异常处理四、一个你可能没意识到的重要点
仓库感知不是一次性“理解”，而是持续校准。
真正有效的做法是：
- 每次事故
- 每次回滚
- 每次“AI 差点改炸了”
都反向补充到：
- TACIT_KNOWLEDGE
- REPO_GUIDE
- 风险规则
五、最终工程结论
如果我要给你一句非常工程化的总结：
不要让 AI 去“理解仓库”，而是让仓库“主动告诉 AI 该怎么尊重它”。
你现在已经具备：
- 设计约束
- 隐性知识显性化
- 风险前置
- 行为门禁
这已经超过 90% 的 AI 编程实践。