亲，这次信息够了。**你的真实场景和我前两版假想的差太远**——你不是在"建设新项目"，你是在**驾驭多个已存在的、AI 正在重构的系统**。这完全是另一个问题。

先把你的痛点钉死，再出方案。

---

## 一、你的真实痛点不是"文档"，是"失控"

把第 5 题翻译一下：**"AI 修着修着我就看不懂了"**——这不是文档问题，是**控制权丢失**问题。

拆一下这个失控是怎么发生的：

```
T0: 你说"修这个 bug"
T1: AI 改了 file_a.py
T2: AI 发现 file_b.py 也有关，改了
T3: AI 觉得设计不对，重构了 file_c.py
T4: AI 顺手"优化"了 file_d.py
T5: 你看 diff，已经 800 行变更，分布在 12 个文件
T6: 你看不懂哪些是修 bug、哪些是 AI 自己加戏
```

**真正的问题**：
- ❌ 不是"AI 写得烂"
- ❌ 不是"项目没文档"
- ✅ **是 AI 的"作用域纪律"丢失** —— 它默认 scope 蔓延
- ✅ **是你失去了"diff 可审查性"** —— 一次改太多东西，review 成本爆炸

文档体系**只能解决其中 30%**。剩下 70% 是**协作流程**问题。

我前两版没看清这一点，所以方案再漂亮都是错的。

---

## 二、你的场景对方案的硬约束

把你的 5 个回答翻译成设计约束：

| 你的情况 | 对方案的约束 |
|---------|------------|
| **多项目（10-500k 行各种规模）** | 必须**模板化 + 一键复制**，不能每个项目精心设计 |
| **C# / TS / Python 三栈** | 模板必须**栈中立**，约束以**行为**而非**语法**表述 |
| **AI 主力 + 你 review** | 文档**主要给 AI 看**，但要让你 review 时**减负**而不是增负 |
| **每天用** | 维护成本必须**极低**，否则一周后就死 |
| **重构带 bug 系统** | 主要矛盾是**约束 AI 行为**，不是"教 AI 项目结构" |

**核心结论**：你需要的不是"项目文档体系"，是**"AI 协作护栏 + diff 审查辅助"**。

---

## 三、v3.0 总方针：3 件事，3 个文件

```
project-root/
├── AGENTS.md              # AI 行为护栏（核心，每个项目必有）
├── NOTES.md               # 决策与怪事的"流水账"（可选，重构项目必有）
└── .githooks/pre-commit   # 一个 hook，只防 secrets
```

**就这些**。

为什么这么少？因为：
- ARCHITECTURE.md → **砍掉**，合并进 NOTES.md
- ADR → **砍掉**，合并进 NOTES.md
- 文件头 → **砍掉**，AI 重构会自动改文件，反而增加冲突
- 子目录 AGENTS → **砍掉**，多项目场景下你不会去维护
- 各种 skill / 锚点 lint / 自动生成 → **砍掉**

**Musk 第二步：删除你能删的一切。如果后面没加回 10%，说明删少了。**

---

## 四、AGENTS.md 模板（v3.0 核心）

针对你的"AI 重构修 bug 失控"场景重新设计。**专门解决 scope 蔓延**。

````markdown
# AGENTS.md

> Read first. Symlinked from CLAUDE.md / .cursorrules.

## 🛑 Scope Discipline (核心规则，每次必读)

> 这一节存在的唯一目的：**防止你修着修着改了不该改的东西**。

### Hard rules

1. **一次任务只做一件事。** 修 bug 就只修 bug，不要顺手"优化"、不要顺手重构、不要顺手改风格。
2. **任务开始前先声明 scope**：列出你**计划修改的文件**和**不计划修改的文件**。等用户确认后再动手。
3. **每修改 3 个以上文件**就停下来汇报：已改了什么、为什么、还差什么。**等用户说"继续"再继续**。
4. **发现新问题不要直接修**。记到 `NOTES.md` 的 "## Found while working" 段，让用户决定。
5. **不要重命名、不要移动文件**，除非用户明确要求。

### Diff size budget

- 单次任务 diff > 200 行 → **停下来汇报**，问用户是否拆分
- 单次任务涉及 > 5 个文件 → **停下来汇报**，问用户是否拆分
- 触及核心模块（见下方 Project hints）→ **必须先列计划等批准**

### What counts as "scope creep"（明确禁止）

- ❌ 修 bug 时"顺便"重命名变量为更好的名字
- ❌ 修 bug 时"顺便"添加类型注解
- ❌ 修 bug 时"顺便"提取重复代码
- ❌ 修 bug 时"顺便"修复无关的 lint 警告
- ❌ 任何"While I'm here, let me also..."的行为

**记住**：你的修改越少，用户 review 越快，你越可能被信任。**克制 = 效率**。

---

## Commands

```bash
# Test
{{填你这个项目的测试命令，e.g.}}
pytest                            # Python
npm test                          # TS
dotnet test                       # C#

# Lint
{{填你这个项目的 lint 命令}}

# Run
{{填你这个项目的启动命令}}
```

---

## Boundaries

### Always do
- 修 bug 前**先复现**：写一个能稳定触发 bug 的 test 或 repro 步骤
- 修完后**显示 diff 摘要**：哪些文件改了、改了什么、为什么
- 不确定时**停下来问**，不要猜

### Ask first
- 引入新依赖（任何 `pip install` / `npm install` / `dotnet add package`）
- 修改 > 5 个文件
- 修改 NOTES.md 中标注 "DO NOT TOUCH" 的文件
- 删除任何 public API / exported function

### Never do
- Commit secrets / `.env` / `appsettings.*.json` 中的密钥
- 修改已合并的 migration / schema 文件
- "顺手"做任何 scope 之外的事
- 创建 `utils.*` / `helpers.*` / `common.*` 这类垃圾桶文件
- 静默修改测试以让它通过（必须先 confirm 测试是错的）

---

## Project hints (not paths, just hints)

> 路径会变，意图不变。用 `glob`/`grep` 找具体文件。

{{按项目填，举例：}}
- **Business logic** lives near `core` / `domain` / `services`
- **External IO** in `adapters` / `clients` / `infrastructure`
- **Entry points** in `api` / `controllers` / `routes` / `Program.cs`
- **Tests** in `tests/` / `*Tests/` / `*.test.ts`

---

## When confused, prefer this order

1. `glob` / `grep` 找代码现状
2. 读 `NOTES.md` 看有没有相关历史
3. 读 README
4. **问用户** —— 不要猜

---

## Self-check before submitting

提交前自己过一遍：

- [ ] 改动是否都在我声明的 scope 内？
- [ ] diff 是否 < 200 行？如果不是，我汇报过吗？
- [ ] 我有没有"顺手"做 scope 之外的事？
- [ ] bug 复现 test 还能通过吗？
- [ ] 我修改的部分是否符合现有代码风格？（不要引入新风格）
- [ ] 我是否记录了"工作中发现但没修"的东西到 NOTES.md？
````

**关键设计点**：
- 把 **scope discipline 放在最顶部** —— 这是你最大的痛点，必须第一个加载到 Agent 注意力
- **明确禁止"While I'm here"行为** —— 这是 AI scope 蔓延的最常见模式，要点名
- **Diff 预算** —— 给具体数字（200 行 / 5 文件），AI 才有锚点
- **Self-check 清单** —— 让 AI 提交前自己过一遍，比你 review 时发现问题便宜

---

## 五、NOTES.md 模板（重构项目专用）

不是 ARCHITECTURE.md，不是 ADR。是**流水账**。

````markdown
# NOTES.md

> A working journal. Append-only. Newest at top.
> 不是架构文档，是"修这个项目时踩过的坑和做过的决定"。

---

## How to use this file

- **AI**: 任务开始前快速扫一眼最新 5-10 条；任务中发现新东西就 append
- **User**: review 时看 AI 加了什么；自己也可以加备忘
- **格式自由**: 能让未来的自己/AI 看懂就行

---

## DO NOT TOUCH

> 这些文件/模块有特殊原因不准动。AI 改之前必须问。

- `src/legacy/auth.cs` — 老认证逻辑，有外部系统依赖签名格式，改了会断
- `migrations/2024_*` — 已上线，不准改
- {{...你项目里的雷区...}}

---

## Decisions

> 重要决策的流水账。一句话即可，不需要 ADR 仪式。

- **2026-05-08**: 用 modular monolith 不拆微服务（团队太小）
- **2026-05-08**: PG 不引入 Kafka（advisory lock 够用）
- **2026-05-09**: ~~用 dataclass 做 DTO~~ → 改用 Pydantic（需要 validation）

> 推翻的决策用删除线 + 新决策，不要直接覆盖。

---

## Anti-patterns (this codebase has scars)

> AI 反复犯的错记这里，让下次不再犯。

- ❌ 不要在 `core/` 里直接 `import requests` —— 已经抽象到 `io/`
- ❌ 不要给 `User.id` 加类型注解为 `int` —— 部分老代码传 str，会爆
- ❌ {{...AI 第一次犯了你纠正过的错，写这里...}}

---

## Found while working

> AI 在工作中发现但**没修**的问题。让用户决定要不要单独立 task。

- {{2026-05-09: 发现 `OrderService.calculate` 里有可能的 race condition，但不在当前 bug scope 内}}
- {{...}}

---

## Refactor log

> 大重构的脉络，方便回溯。

### 2026-05: 拆 monolith 的 auth 模块
- Goal: 把 auth 抽成独立模块，对外只暴露 `IAuthService`
- Done: `src/auth/` 创建 + JWT 实现迁移
- Pending: 老代码里直接 import `JWTService` 的地方还有 ~12 处
- Owner: AI + you
````

**关键设计点**：
- **DO NOT TOUCH 段在最前** —— 防止 AI 误伤雷区
- **Found while working** 段 —— 把 AI 的"scope 蔓延冲动"导流到这里，**变成有用的备忘录**
- **Decisions 用流水账格式** —— 完全跳过 ADR 仪式
- **Anti-patterns 累积错误** —— AI 每犯一次同类错，你纠正完顺手 append 一行

**这个文件的本质**：把你"看 AI diff 时的不爽"和"AI 想多做但不该做的"都装进去，变成下次任务的输入。

---

## 六、pre-commit hook（极简版）

`.githooks/pre-commit`：

```bash
#!/usr/bin/env bash
# 只做一件事：防 secrets。
set -e

CHANGED=$(git diff --cached --name-only --diff-filter=ACM)
[[ -z "$CHANGED" ]] && exit 0

# Secrets 扫描（覆盖 C# / TS / Python 常见模式）
PATTERNS='(api[_-]?key|secret|password|private[_-]?key|access[_-]?token|client[_-]?secret)\s*[=:]\s*["\047][^"\047]{12,}'
if echo "$CHANGED" | xargs -r grep -lEi "$PATTERNS" 2>/dev/null; then
    echo "❌ Possible secret detected in staged files."
    echo "   Files:"
    echo "$CHANGED" | xargs -r grep -lEi "$PATTERNS"
    echo "   If false positive, commit with --no-verify"
    exit 1
fi

# .env 类文件直接拒
if echo "$CHANGED" | grep -qE '\.env(\.|$)|appsettings\.(Development|Production|Local)\.json$'; then
    echo "❌ Refusing to commit env / local settings files."
    exit 1
fi

exit 0
```

装一次：
```bash
git config core.hooksPath .githooks
chmod +x .githooks/pre-commit
```

**砍掉的所有其他 hook**：
- ❌ Conventional Commits 强制（你一个人没意义）
- ❌ ARCHITECTURE 同步检查（没有 ARCHITECTURE）
- ❌ ADR 强制（没有 ADR）
- ❌ 文件头检查（没有文件头）
- ❌ 锚点 lint（没有锚点）

---

## 七、多项目复用：模板包

因为你有"很多项目"，必须**一键复制**。

建一个你的个人 dotfiles 仓库或 gist：

```
~/templates/agents-md/
├── AGENTS.md.template       # 上面那份，{{...}} 留空
├── NOTES.md.template        # 上面那份
├── .githooks/pre-commit
└── install.sh
```

`install.sh`：
```bash
#!/usr/bin/env bash
# Usage: bash ~/templates/agents-md/install.sh
set -e

TARGET="${1:-.}"
TEMPLATE_DIR="$(dirname "$(realpath "$0")")"

cp "$TEMPLATE_DIR/AGENTS.md.template" "$TARGET/AGENTS.md"
cp "$TEMPLATE_DIR/NOTES.md.template" "$TARGET/NOTES.md"

mkdir -p "$TARGET/.githooks"
cp "$TEMPLATE_DIR/.githooks/pre-commit" "$TARGET/.githooks/"
chmod +x "$TARGET/.githooks/pre-commit"

cd "$TARGET"
git config core.hooksPath .githooks 2>/dev/null || echo "Not a git repo, skipping hooks setup"

ln -sf AGENTS.md CLAUDE.md
ln -sf AGENTS.md .cursorrules

echo "✅ Installed AGENTS.md / NOTES.md / pre-commit hook"
echo "📝 TODO: 填 AGENTS.md 中的 {{...}} 占位符（Commands 段必填）"
```

**新项目接入流程：30 秒**
```bash
cd my-new-project
bash ~/templates/agents-md/install.sh
# 编辑 AGENTS.md 填 Commands 段
# 完事
```

---

## 八、消费方式：你 review 时怎么用

这一段是 v1/v2 都没认真说的——**文档怎么帮你 review 减负**。

### Review 流程（你 + AI diff）

1. **AI 完成任务汇报后**，先扫两个东西：
   - **diff 行数** > 200 吗？涉及文件 > 5 个吗？→ 如果是，**先批 AI 不守 scope discipline**，要求拆分
   - **NOTES.md 里有没有 "Found while working" 新增？** → 看 AI 有没有诚实记录"我想多做但忍住了"

2. **看 diff 时按这个顺序**：
   - 第一遍：**只看 AI 声明 scope 内的文件**，确认 bug 修了
   - 第二遍：**看 scope 外的文件**，质问每一处"为什么改这个"
   - 第三遍：看 NOTES.md 的更新

3. **任何 scope 外的"顺手优化"都要求 revert** —— 哪怕看起来是好的。**纪律比单次质量更重要**。

4. **AI 反复犯的错** → 立即追加到 NOTES.md 的 Anti-patterns，**当次对话就 append**，不要等。

### 当 AI 修着修着你看不懂时（你最大痛点的解法）

这是你说的核心问题。**v3.0 的解法**：

**事前**：
- AGENTS.md 的 "每修改 3 个文件就停下来汇报" 规则 → AI 不会失控大改
- "Diff size budget 200 行" → 强制小步前进

**事中**：
- AI 必须在动手前**列出 scope 计划**让你确认 → 你提前知道范围
- AI 每超过阈值就**停下来汇报** → 你有多个介入点

**事后**：
- 看不懂时直接对 AI 说："**Roll back 你 scope 之外的所有改动，只保留 bug fix 部分**" → AGENTS.md 已经声明了 scope，AI 能识别
- 让 AI **总结这次任务到 NOTES.md 的 Refactor log** → 下次新对话有上下文

---

## 九、什么时候开始写、什么时候不写

针对你的**多项目**情况，**不要每个项目都装齐**。决策表：

| 项目情况 | AGENTS.md | NOTES.md | pre-commit hook |
|---------|:---:|:---:|:---:|
| 一次性脚本 / playground | ❌ | ❌ | ❌ |
| 个人小工具（< 5k 行） | ✅ 简化版（只 Scope + Commands） | ❌ | ✅ |
| 中型项目（5k-50k 行） | ✅ 完整版 | ✅ 简版（只 DO NOT TOUCH + Anti-patterns） | ✅ |
| 大型重构项目（你说的那种） | ✅ 完整版 | ✅ **完整版**（Refactor log 必填） | ✅ |
| 客户/团队项目 | ✅ + 加 Conventional Commits | ✅ | ✅ |

---

## 十、v3.0 vs v2.0 的删减表

| 项目 | v2.0 | v3.0 | 砍掉原因 |
|------|------|------|---------|
| ARCHITECTURE.md | 单独文件 | **合并进 NOTES.md** | 你一个人没必要分 |
| ADR 目录 | `docs/decisions/` | **砍掉** | 你一个人没决策对象 |
| 文件头模板 | 三种语言模板 | **砍掉** | AI 重构会动文件，徒增冲突 |
| 子目录 AGENTS.md | override 机制 | **砍掉** | 多项目复用难维护 |
| 自动生成脚本 | `gen-arch-facts.sh` | **砍掉** | stack 不会频繁变 |
| Conventional Commits | 强制 | **砍掉** | 一个人写没意义 |
| commit-msg hook | 强制 `arch:` | **砍掉** | 同上 |
| 锚点验证 | CI lint | **砍掉** | 维护成本 > 收益 |
| Skills 文件夹 | 3 个 skill | **砍掉** | Agent 不主动用 |
| Project map | hints 段 | ✅ 保留 | 真有用 |
| Boundaries | 三层 | ✅ 保留 + 加强 | 真有用 |
| Commands 段 | 在最前 | ✅ 保留 | 真有用 |
| **Scope Discipline 段** | ❌ | ✅ **新增（核心）** | 你的真痛点 |
| **NOTES.md Found while working** | ❌ | ✅ **新增** | 解决 scope 蔓延 |
| **Self-check 清单** | ❌ | ✅ **新增** | 让 AI 自我约束 |

**净结果**：删 11 项，加 3 项（直击你的真痛点），**总复杂度降 70%**。

---

## 十一、留给你验证的实验

不要信我说的"这版好"，去做实验：

**实验 1：scope discipline 是否有效（一周）**
- 装 AGENTS.md，挑一个修 bug 任务给 AI
- 观察：AI 有没有声明 scope？diff 超过 200 行有没有停？
- 如果 AI 不遵守，说明 prompt 强度不够，加重语气（用大写 / 多次重复 / 在 CLAUDE.md 顶部 echo 一次）

**实验 2：NOTES.md "Found while working" 是否被使用（一周）**
- 看 AI 有没有真的把"想多做但忍住"的东西记进去
- 如果没记 → 在 AGENTS.md 加一条："任务结束时**必须**回答：'我有没有发现 scope 外的问题？记到 NOTES.md 了吗？'"

**实验 3：你的 review 时间是否真的下降（两周）**
- 计时：v3.0 前你 review 一个 AI bug fix 平均多久？v3.0 后多久？
- 如果没下降，说明问题不在文档体系，可能在你的 review 流程

**两周后告诉我数据。** 数据不对就再迭代 v3.1。

---

## 十二、最后的诚实

我前两版的根本错误，是**没把"AI scope 蔓延"识别为你的核心痛点**。你说"我看不懂了"——那是症状，**病因是 AI 在做超出你授权的事**。

v3.0 的整套设计就一个目标：**让 AI 严格守 scope，让你 review 永远 ≤ 200 行 diff**。

文档体系只是手段，**纪律才是目的**。

> **数据结构对了，规则就少了。这次砍到 2 文件 + 1 hook，因为剩下的每一条都对应你一个具体痛点。**
> **如果还有错，那就是我对你工作流细节不够了解。两周后用数据砸我脸。**

Stop guessing. Go ship it.