# 理念

roll 的根本立场。当设计决策争执不下时，回到这里。

## 控制

**1. 可靠性在 harness，不在模型。**
模型是黑盒。让产出可靠的是外面那层反馈闭环——设定目标、调度执行、感知结果、修正方向。这是 roll 存在的全部理由。

**2. roll 是一个按反馈闭环设计的 agent harness，不是一堆功能。**
它的形态是闭环：作动（编排）→ 传感（可观测）→ 评分（Evals = 误差信号）→ 反哺（修正下一轮）。功能要长在这个回路上，不是并列堆叠。

**3. 不打开黑盒。**
Token 级压缩、工具 schema 强制、单次推理——全部委派给下游 agent。不必建模被控对象内部，靠反馈就能控制。越界去管内层，是 roll 的范围错误。

## 真相

**4. 主干即真相。**
完成 ≡ 已合并进主干。退出码、自我声明都不算数——事后对账才算。愿望（Backlog）和真相（main）要分开，由对账协调。

**5. 上下文是持久的结构化文档，不是对话历史。**
每条工作开工前先把设计/领域/验收写成持久文档——这就是控制器对系统的模型与记忆。fresh context 之所以能成立，正因为上下文被预先补齐、落盘。

**6. 持久优先于便利。**
写在前——原子追加——退出必写终态——事件流是源不是缓存。宁可多写一笔，不可丢一次状态。

## 失败

**7. 失败要响，不偷偷自愈。**
ALERT + 通知，人决策。agent 连败不自动换人重试。一个坏 Story 不冻结其他工作，但永久中毒的 Story 不要再捞起来。

**8. 进程随时可能死，防御要覆盖每条路径。**
不假设优雅退出——SIGKILL 后重入必须能检测孤儿并安全接管；开始信号一发出，任何退出路径都必须补结束信号，兜底本身不能再依赖可能失败的操作。防御不只覆盖写入，还要覆盖删除和枚举路径——最深一课：可以拦住「写 tmp」，拦不住「按真目录枚举后删除」。

**9. 反馈必有 Goodhart 护栏。**
度量一旦被当目标就会被钻空子。所以 Evals 信号只生成「待人确认」的候选，绝不自动改动真实 backlog。自我改进的飞轮要转，但不能脱手。

## 结构

**10. 有界且可逆。**
一 Cycle 一个 Story、全新上下文、TCR 绿则提交红则回退、Feature 可整体回退、迁移可一键切回。不对大颗粒 Story 让步——拆小再跑。任何一步都要能干净撤销。

**11. 路径即身份。**
不同项目共享存储 = 污染。每个项目的运行态数据放在自己的 `.roll/loop/` 下，互不可见。

**12. 一个能力域，一个家。**
按能力域（编排/执行/工具/上下文/可观测/Evals/治理）各归其位，用类型化契约连接。能力散落在多种载体、靠文本缝合，就是不稳定与低效的根源——这是重写要根除的。

**13. 可观察契约是真相，实现怪癖不是。**
一段行为的契约是它的可观察面——入参、stdout、副作用、退出码、写的文件与事件——由冻结快照守护。踩过的每个坑固化成不变量，不在新代码里重新发现。

**14. 决策者是人——人在环上，不在环中。**
人是监督控制器与限幅器（human-on-the-loop），不是每步审批的瓶颈（human-in-the-loop）。自动化执行，但策略（merge 规则、安全阈值、路由偏好）由人设定。发布永远人点头。Loop 在人的环上跑，不是替代人。

---

## 一句话信仰

> **把 AI 当黑盒，用反馈闭环把它的产出逼向可靠；让这台 harness 自己可观测、可信赖、能自评、还拦得住自己。** 语言、框架、端都会变，这条不变。

## 反信仰（我们明确不信的）

- 不信"模型够强就够了"——再强的黑盒也需要外层闭环。
- 不信"全自动无人化"——发版与高风险决策永远留人。
- 不信"LLM 是能被经典控制器稳定的对象"——反馈闭环是设计镜头，不是字面控制数学（理论沿革见 [specs/theory-foundation](specs/theory-foundation.md)）。