Agent 设计指南
环境决定它稳不稳
改变｜提炼成七层通用配置 + F1–F14 失效清单：后续封装直接复用，持续迭代，不从零起步，质量有底。
角色｜参考最佳实践 + 四个本地 Agent 迭代账本；2026-10-22。
01 · 价值为什么值得花力气搭这层
同一个模型，有人用起来每天稳定出稿，有人每次结果都不一样——差别不在模型，在它外面那层环境。搭这层的目的只有三个，都能对应到具体的麻烦：
换成「流程必经」
换成「外部信号说好了」
搬进文件
落到业务上，判断标准很朴素：这东西能不能被别人接手。能接手，说明它的判断依据、验收方式、出错记录都在文件里，而不在你脑子里——这恰好也是增长体系里「可复制」和「靠个人」的分界线。
02 · 七层按顺序配，每层都有「默认 / 反模式」
七层不是七个可选项，是七个漏点。一个 Agent 出问题，先问「七块里缺哪块」，而不是先加一段 prompt。
配之前先定三件事，不定就别往下走：这是判断型还是程序型任务（决定工具面该少而深还是多而全）、成功长什么样、谁来判断（决定验证层）、错了代价多大、可不可逆（决定要不要沙箱和审批）。三件事没答案时，配出来的七层全是猜的。
03 · 我的实践四个 Agent 的翻车账本
下面这些不是案例故事，是我自己四个 Agent 的版本记录——每个都标了自己对应的失效编号。它们共同说明一件事：改好的那几次，改的都是装置；改坏的那几次，加的都是规则。
v1.3.6：清出 4 条模型根本无法执行的规则（比如「3 秒内让人感知」），改成它能自己检查的动作。v1.4：方向跑偏成说教口吻，改的是立场与谓语方向，不是加一条禁令。v1.4.1 又矫枉过正，把判断句收得太干净——最后补的是边界：「有支撑=金句，无支撑=空话」。
账本里最诚实的一行：所有改动只证明了「不随机崩坏」，没有证明「产出更好」。下限和上限是两件事。
第二刺眼：六维评分 6/6 pass、方向门 4/4，我读完的原话是「看不下去」。评分表全过而人读不下去，说明验收装置本身是坏的。
第三：它自编了「一百个来问价的，成交五个」写进正文，因为要求「要具体」而手里没有素材。之后加的是数字清单 + 来源准入：指不出出处就删或降级。
首份评估里 4 处数字错（67→65、3 次→35 次、52KB→43.7KB、6 条→7 条），全是它自评时报的——事实自评约等于没有评估。
最隐蔽的一条：账本写在当时的工作区，新会话 cwd 一变，实测 0 个文件。状态没跟着走，跨会话就断了。
四个 Agent 加起来，真正被修好的都是同一个动作：换装置。加规则只治「知道但没做」，治不了「不知道怎么做」，更治不了「规则互相打架」。
04 · 自查F1–F14：现象对得上，才谈修
按现象找，不按感觉找。左列是你会看到的样子，右列要换的东西——注意右列几乎全是机制，不是更严的措辞。
| 编号 | 现象 | 换什么装置 |
|---|---|---|
| F1 | 检查表全过，人读不下去；编的数字被当成证据记下来 | 外部盲读 + 来源准入 + 数字清单（无来源不许以事实口吻出现） |
| F2 | 规则写了，执行里看不到 | 改写成「动作 + 判据 + 产物」，绑在产出时点 |
| F3 | 同一类错反复出现，改一次好一次 | 规则审计：去重、删冲突、生成规则压到 ≤5 条 |
| F4 | 长文越写越散、前后矛盾 | 分段 + 进度文件 + 子 Agent 隔离 |
| F6 | 工具越多越慢越乱 | 收窄到高频 + 兜底，CLI 优先 |
| F7 | skill / 规则该触发没触发 | 前置到流程必经步，或 hook 注入；跳过必须自报 |
| F9 | 换个会话就接不上 | 初始化 + progress 文件 + git 提交 |
| F10 | 编具体数字/案例来满足「要具体」 | 取消「纯逻辑」单独通行；数字必须带来源 |
| F11 | 方向跑偏：正确但说教、自嗨 | 立场检查 + 读者位置 + 谓语方向 |
| F12 | 一轮改五处，变好也不知道为什么 | 一轮一类 + 白名单 + 账本 |
| F13 | 交付词写「完成」，但没有真实任务证据 | 交付词必须带真实任务信号与失败判据 |
| F14 | 越权、误删、越界触达 | 权限 / 沙箱 / 白名单 / 审批 |
05 · 修复顺序错了会越改越坏
固定六步：停血 → 定位 → 换装置 → 加规则 → 验收 → 记录。先关掉会造成伤害的动作（自动发布、写权限、批量删除），再对现象认一个根因、做最小复现，然后优先换机制；规则放在第四步，且一次只加一条动作型规则。
归因铁律只有一句：一次只改一处。同时改五处，即使变好也不知道是哪一处起的作用——下次换个场景，它照样崩。
停止条件同样要写死，否则会陷入无限打磨：连续两轮改动都没有外部信号改善 → 停，回目标层（很可能是目标写错了）；改动开始互相抵消 → 停，做规则审计；只剩近义词替换、没有结构变化 → 停；说不出「这版比上版多了什么事实」→ 交付上一版。
- ① 先定三件事——任务类型、成功标准与判断人、错误代价。三件事没答案，七层全是猜。
- ② 只配两层——指令（3–5 条带判据的规则）+ 验证（一个 Agent 之外能跑的检查）。一次性的问答场景配这两层就够，硬套七层是过度工程。
- ③ 出问题先查表——对现象找 F 编号，换装置，不要加规则；改完只认外部信号。
反过来也成立：单轮问答、纯生成不落地的场景，加这层只增开销。