用“最少的文件 + 最硬的约束”，让 AI 在进入仓库的前 5 分钟内，知道什么能动、什么不能动、该如何动。

你可以原样放进仓库根目录（建议文件名：REPO_AWARENESS.md），也可以按章节拆成多个文件使用。

---

Repository Awareness · 最小文件集（AI-First）

适用对象

• AI 编程（Claude / Gemini / GPT / Agent / CLI）
• 新加入的工程师
• 历史包袱较重的代码仓库

优先级声明

• 本文档优先级 高于 README
• 与 DESIGN / 代码冲突时，以本文档为准
• AI 在修改任何代码前，必须完整阅读本文件

---

一、最小文件集总览（你至少需要这些）

/REPO_GUIDE.md          ← 仓库导览（入口）
/REPO_STRUCTURE.md     ← 结构与模块角色
/TACIT_KNOWLEDGE.md    ← 隐性知识 / 禁区
/CHANGE_RULES.md       ← 修改规则与风险门禁
/DESIGN.md             ← 本次变更的精确设计（每次必有）

原则

• 文件少，但每个都是“硬规则”
• 禁止写成“介绍性文档”

---

二、REPO_GUIDE.md（仓库入口 · 必须第一个读）

目标：让 AI 在 2 分钟内知道“这是什么系统 + 最大风险在哪”

# Repository Guide

## 1. 这个仓库是做什么的
- 系统定位：
- 服务对象：
- 当前阶段（维护 / 演进 / 重构前夕）：

## 2. 当前最重要的工程目标
- 稳定性 / 兼容性 / 可预测性

## 3. 明确的非目标（非常重要）
- 不做架构升级
- 不做大规模重构
- 不统一历史风格

## 4. 高风险提示（AI 必须记住）
- 存在大量历史依赖
- 外部调用方不可完全枚举
- 看似冗余的代码可能是刻意保留

## 5. AI 行为总规则
- 修改前必须阅读 TACIT_KNOWLEDGE.md
- 触及接口 / 数据 / 并发 → 必须先澄清
- 无法确认安全性 → 拒绝修改

---

三、REPO_STRUCTURE.md（结构与模块角色）

目标：让 AI 知道“每个目录存在的理由”

# Repository Structure

## 1. 总体分层原则
- api：对外接口层
- service：业务逻辑层
- infra：技术实现层
- domain：领域模型

## 2. 目录级说明

### /api
- 职责：对外暴露接口
- 禁止事项：
  - 直接访问数据库
  - 包含业务判断

### /service
- 职责：核心业务逻辑
- 允许：
  - 事务控制
- 禁止：
  - 与 HTTP / RPC 细节耦合

### /infra
- 职责：技术细节
- 特点：
  - 允许不优雅
  - 禁止外部直接依赖

## 3. 冻结目录（只允许最小修复）
- /legacy/**
- /api/v1/**

---

四、TACIT_KNOWLEDGE.md（隐性知识 · 最重要）

目标：把“老工程师脑子里的东西”变成 AI 的硬约束

# Tacit Knowledge & Constraints

## 1. 不可变前提（Immutable Assumptions）
- 系统默认幂等
- MQ 至少一次投递
- 老客户端长期存在

## 2. 禁止触碰区域（Frozen Zones）
- auth 模块
- legacy 目录

允许：
- 修 Bug
- 加日志

禁止：
- 重构
- 改接口
- 抽象优化

## 3. 已知历史事故（必须阅读）

### INC-2021-Cache
- 修改缓存 Key 导致全量失效
- 禁止“顺手优化缓存”

### INC-2022-Timeout
- 统一超时参数引发雪崩
- 禁止统一策略

## 4. 隐式契约（代码未声明但真实存在）
- delete 实际为逻辑删除
- 查询接口允许返回旧数据

## 5. AI 行为规则
- 不得假设“代码可以随意改好”
- 不得消除“看起来多余”的逻辑

---

五、CHANGE_RULES.md（修改规则与风险门禁）

目标：让 AI 学会“什么时候该停手”

# Change Rules & Risk Policy

## 1. 风险等级定义

- L1：日志、注释、监控
- L2：内部实现，不改变行为
- L3：接口、数据、并发、缓存

## 2. AI 授权规则

- L1：允许直接执行
- L2：需说明风险
- L3：禁止直接修改，必须澄清

## 3. 必须中断并提问的场景
- 接口语义变化
- 字段含义变化
- 并发 / 缓存 / 重试逻辑

## 4. 强制输出格式

每次修改前，AI 必须输出：
- 变更目标
- 影响模块
- 风险等级
- 是否触及 TACIT_KNOWLEDGE

---

DESIGN.md（每次变更的精确设计）

目标：消灭歧义，禁止 AI 自由发挥

# Design

## 1. 本次变更目标（唯一）
- 解决什么问题
- 不解决什么问题

## 2. 输入 / 输出契约
- 输入参数：
- 输出结构：

## 3. 核心流程（逐步）
1.
2.
3.

## 4. 状态变化与不变量
- 状态如何变
- 哪些永远不变

## 5. 异常与失败处理
| 场景 | 行为 |

## 6. 风险声明
- 是否触及冻结区
- 是否依赖隐性契约

---

七、AI 强制执行提示（建议写进 CLI / Agent）

在修改任何代码前：
1. 阅读 REPO_GUIDE.md
2. 阅读 REPO_STRUCTURE.md
3. 阅读 TACIT_KNOWLEDGE.md
4. 执行 CHANGE_RULES 风险判断
5. 仅在 DESIGN.md 明确覆盖的范围内修改
如存在不确定性，请拒绝执行并提出问题。

---

八、工程级结论

Repo Awareness 不是“让 AI 更聪明”，而是“让仓库更有主权”。

这套最小文件集的价值在于：

• 把“经验”变成“规则”
• 把“感觉”变成“门禁”
• 把“不可说的东西”写成“不可违反的约束”

参考资料