亲，**这个分工抓住了本质**——一个是"行为契约"，一个是"事实地图"。比 90% 的人都想得清楚。但我得给你挑两个会让你后悔的细节，不然几个月后你会发现这两个文件又在打架。

---

## 一、先确认你对的部分

| 文件                  | 你的定位             | 我的评分   |
| ------------------- | ---------------- | ------ |
| **AGENTS.md**       | 全局约定 Agent 的行为规则 | ✅ 完全正确 |
| **ARCHITECTURE.md** | 项目的事实，模块间的关系     | ✅ 完全正确 |

这个分工对应的是计算机科学里一个非常根本的二分：

> **声明式 (What is) vs 命令式 (What to do)**
>
> ARCHITECTURE.md = 声明式，描述世界的状态
> AGENTS.md = 命令式，规定 Agent 的行动

**两者的读者交集是 AI Agent，但消费方式完全不同**：
- ARCHITECTURE.md 是 Agent 的**世界模型**（被动查询）
- AGENTS.md 是 Agent 的**行动准则**（主动遵守）

这个分层在计算机科学里有无数同构案例——数据 vs 代码、schema vs query、ontology vs rules。**你直觉上找到了一个非常稳定的抽象边界**，这是好品味。

---

## 二、但有两个会塌方的隐藏陷阱

### 陷阱 1：边界模糊地带 —— "事实"和"规则"会互相伪装

举几个真实案例，你判断该放哪：

| 内容 | 你觉得放哪？ | 正确答案 |
|------|------------|---------|
| "auth 模块只能通过 IAuthService 暴露" | ? | **ARCHITECTURE**（事实契约） |
| "改 auth 时必须同步更新 IAuthService 测试" | ? | **AGENTS**（行动规则） |
| "src/core 不依赖 src/api" | ? | **ARCHITECTURE**（事实约束） |
| "禁止 Agent 创建 utils.py 这种垃圾桶" | ? | **AGENTS**（行为禁令） |
| "本项目用 pytest，不用 unittest" | ? | **🚨 陷阱** |

最后一个就是陷阱——它**既是事实也是规则**：
- "项目用 pytest" = 事实 → ARCHITECTURE
- "Agent 写测试时必须用 pytest" = 规则 → AGENTS

**错误做法**：两边都写一份。三个月后两份漂移，Agent 看到矛盾，整个信任体系崩塌。

**正确做法**：**事实只在 ARCHITECTURE 写一次，AGENTS 用引用而不是复制**。

```markdown
# AGENTS.md
## Testing Rules
- 写测试时遵守 ARCHITECTURE.md §3 "Testing Stack" 中声明的工具栈
- 不准引入新的测试框架，必须先改 ARCHITECTURE 再改代码
```

**Single Source of Truth 原则**：事实只能有一个 owner，规则可以引用事实但不能复刻事实。

### 陷阱 2：AGENTS.md 会变成"规则垃圾桶"

这是更隐蔽的问题。AGENTS.md 这种文件**天然倾向于无限膨胀**——每次 Agent 犯一次错，人类就想加一条规则防御。三个月后你会得到：

```markdown
# AGENTS.md (3 个月后的恐怖现状)
## Rules
1. 不要直接 import requests
2. 不要在 hot path log
3. 不要用 print，用 logger
4. 不要 commit .env 文件
5. 不要改 migration 历史
6. 修 bug 前必须先写 reproducing test
7. PR 标题必须用 conventional commits
8. 不要在周五下午 deploy
... (持续到 200 条)
```

**这就完蛋了**——200 条规则放进 system prompt，**LLM 会忽略 80%**。注意力是稀缺资源，规则越多越没用。

**Linus 会问**：你这个数据结构（"规则列表"）的访问模式是什么？是 Agent 每次行动前线性扫描 200 条吗？品味问题。

### 解法：AGENTS.md 必须分层 + 限额

```markdown
# AGENTS.md

## §1 Hard Constraints (≤10 条，违反必停)
- 必须先读 ARCHITECTURE.md 再做架构变更
- 不准 commit secrets
- 不准改 migration 历史
...

## §2 Workflow (流程，不是禁令)
- 修 bug：复现 → 写失败测试 → 修 → 验证
- 加 feature：先看 ARCHITECTURE §1 决策有没有冲突
- 改架构：先改 ARCHITECTURE.md 再改代码

## §3 Style Defaults (软规则，可被 task 覆盖)
- Python: black + ruff
- Commit: conventional commits
...

## §4 Anti-Patterns (反模式，回顾用)
<!-- 这部分可以长，但 Agent 只在写代码时按需查 -->
```

**关键设计**：
- **§1 必须 ≤10 条**，超出说明你在用规则补需求漏洞
- **§2 是流程不是禁令**——告诉 Agent 怎么做，比告诉它别做什么省 token
- **§4 单独成节**，让 Agent 知道"这部分可以跳过，需要时再回来查"

---

## 三、修正后的完整分工

```
┌─────────────────────────────────────────────────────────────┐
│  ARCHITECTURE.md  (世界模型，声明式，事实)                       │
│  ├─ §1 Why: 设计决策与原因                                     │
│  ├─ §2 What: 模块边界 + 契约                                   │
│  ├─ §3 How: 关键数据流                                         │
│  └─ Glossary: 术语对齐                                         │
│                                                               │
│  读者: 人 + Agent                                              │
│  更新触发: 架构变更                                             │
│  Token 预算: 3-5k                                              │
└─────────────────────────────────────────────────────────────┘
                            ▲
                            │ 引用 (不复制)
                            │
┌─────────────────────────────────────────────────────────────┐
│  AGENTS.md  (行动准则，命令式，规则)                            │
│  ├─ §1 Hard Constraints (≤10 条)                               │
│  ├─ §2 Workflow (做事流程)                                     │
│  ├─ §3 Style Defaults (软约定)                                 │
│  └─ §4 Anti-Patterns (反模式参考)                              │
│                                                               │
│  读者: 仅 Agent                                                │
│  更新触发: 重复犯同类错误                                       │
│  Token 预算: 1-2k (§1+§2+§3), §4 不计                          │
└─────────────────────────────────────────────────────────────┘
```

**两个文件加起来 < 7k token**，能塞进任何主流模型的 system prompt。

---

## 四、还有一个你没问的问题：CLAUDE.md 呢？

既然你已经想到 AGENTS.md，迟早会撞到这个问题：**CLAUDE.md / .cursorrules / .windsurfrules / AGENTS.md 这一堆 AI 专属配置文件怎么办？**

**我的建议**：
- **AGENTS.md = 通用规则**（vendor-neutral，对所有 Agent 都成立）
- **CLAUDE.md / .cursorrules = 工具特化指令**（只放该工具独有的优化，比如 Cursor 的 `@` 用法、Claude Code 的 sub-agent 调用约定）
- **CLAUDE.md 的第一行永远是 `Read AGENTS.md first.`**

这样换工具时只改一个小文件，**核心规则永远跟着项目走**。**vendor lock-in 是技术债，规则文件层面就要防**。

---

## 五、给你的最终判分

你的分工（AGENTS = 行为规则 / ARCHITECTURE = 事实）**架构方向 100% 正确**，但需要补三个工程细节：

| 维度 | 你的方案 | 加固建议 |
|------|---------|---------|
| **边界** | ✅ 清晰 | ⚠️ 加 SSOT 原则：事实不复刻，只引用 |
| **可扩展性** | ⚠️ 可能膨胀 | ⚠️ AGENTS.md 分层 + Hard Constraints 限额 |
| **vendor 中立** | ❌ 没考虑 | ⚠️ AGENTS.md (通用) + CLAUDE.md (特化) 二级结构 |

**总分 8.5/10**——撕掉一分给"规则膨胀风险"，撕掉半分给"vendor lock-in 没考虑"。

---

## 六、留给你的最后挑战

我反复强调"AGENTS.md 引用 ARCHITECTURE.md，不复制"。但有个执行细节我没说：

**当 ARCHITECTURE.md §3 改了，怎么保证 AGENTS.md 里所有引用 §3 的规则还有效？**

提示：
- 节标题改了，引用就坏了
- 节内容改了，规则的前提可能不成立了
- CI 能检测前者，但检测不了后者

这个问题不解决，"引用而非复制"会变成**比复制更糟的腐烂**——因为你以为它保鲜了，其实它只是悄悄烂了。

想想看怎么搞。想清楚了告诉我你的方案。

> **数据结构对了，规则就少了。规则越多，说明你的事实层（ARCHITECTURE）没建好。**