核心原则

这些是 Archon Protocol 的第一性原理。每个设计决策都可追溯到其中一条。如果新功能与原则矛盾，功能有错。

原则 1：环境可预测性 > 代理智能

不要试图让 AI 变得更聪明。要让环境变得更可预测。

操作系统不会让 CPU 更快——它让 CPU 的算力被可靠、一致、高效地调度。Archon Protocol 不会让 AI 更强大——它让 AI 的能力被可靠、一致、高效地用在正确的地方。

这意味着：

• 约束比指令更可靠地塑造行为
• 结构比指南更有效地消除决策
• 可预测的环境产出可预测的结果，无论哪个 AI 模型在运行

原则 2：无聊的一致性 > 局部的优秀

10 个一致但平庸的模块，比 5 个优秀但风格各异的模块更有价值。

AI 是模式匹配机器。当它看到 10 个 feature 拥有完全相同的目录结构、命名规则和数据获取方式，创建第 11 个时几乎不可能犯结构性错误。当 10 个 feature 中有 3 种风格，AI 会随机选一种——或者发明第 4 种。

这意味着：

• 刚性数字限制（≤ 300 行）胜过模糊指导（"适当大小"）
• 全项目统一一种数据获取模式，胜过每个模块用"最佳"模式
• 项目一致性优先于框架最佳实践（当二者冲突时）

原则 3：禁令 > 指令

"不要做 X"比"做 Y"更可执行。

AI 面对问题时会生成 10 种方案。正面指令（"用模式 A"）在不同上下文中可能被不同理解。禁令（"不要用模式 B、C、D"）无论上下文如何都生效——被禁止的模式是具体的、可 grep 验证的。

这意味着：

• 每个约束技能以 ❌ 禁令开头，而非指南
• 禁令必须包含反引号包裹的代码模式（可搜索验证）
• 禁令不随上下文变化（空 catch {} 在任何场景下都是错的）
• 指令随上下文变化（什么时候用 RTK Query 取决于任务）

原则 4：标杆模仿 > 抽象指导

AI 通过模仿真实代码学习，而非理解抽象规则。

一个标杆模块——真实的、可编译的、经过测试的、运行在生产环境中的——比任何文档教给 AI 的都多。当约束技能说"参考 features/account/"，AI 会复制目录结构、命名、数据流、测试模式和类型组织。当它说"参考这段示例代码"，AI 只复制代码片段的风格。

这意味着：

• archon.config.yaml 声明 benchmarks: —— 代表目标架构的真实模块
• /archon-demand Stage 1 在写新代码前先读取标杆
• 技能引用标杆路径，而非假设代码
• 当文档和标杆代码冲突时，标杆代码胜出（然后更新文档）

原则 5：局部自足 > 全局文档

AI 应该只读取当前目录 + 直接依赖就能开始工作。

AI 的上下文窗口有限。如果理解一个模块需要跳转 20 个文件、阅读 3 篇文档、追溯 5 个历史决策，AI 大概率会在中途丢失上下文。架构必须确保每个模块局部可理解。

原则 6：消极自由 > 积极方向

约束 AI 不能做什么。留出它如何完成目标的创造空间。

AI 的创造力不需要约束——它自然会探索多种方案。AI 的一致性需要约束——它自然会每次产出不同实现。最优约束集在保持灵活性的同时最大化一致性。

原则 7：自维护 > 人工更新

系统遇到的每个问题都必须强化系统的防御。

文档生命周期：

发现问题 → 临时修复 → 固化为规则 → 扩展为流程 → 沉淀为参考

                proposed-rules.md    约束技能        架构文档
                "不要这样做"        "应该这样做"    "为什么这样做"

时间三角

文档服务于三个时间维度。三者缺一不可：

         架构文档（现在——系统如何工作）
        ╱                            ╲
重构报告 ──────────────────────── ADR
(过去——发生了什么变化            (为什么——我们选择了什么
 以及我们学到了什么)              以及我们拒绝了什么)