# 核心理念

把一次失败改写成能改善、能验证的环境问题。

## 代码越多，为什么返工也越多？

agent 一口气改了几个文件，功能却仍然做偏。先别急着换模型：目标错了、信息没找到、验证没覆盖，还是接口和状态本身容易出错？不同原因需要不同修复。

Figure: 四类失败与对应环境改进 ([d02-failure-sort](/diagrams/d02-failure-sort.zh.svg))

## 交付之后，维护才开始

生成速度只解释代码怎么出现，不能说明后续修改是否容易。重复实现、没人需要的分支、含糊的接口，都会让下一次改动更难判断。

先问一个具体问题：这段代码服务哪个行为？如果删掉它，哪个验收条件会失败？答不出来时，先核实需求，再决定是否保留。

> If your code sucks, your agent will too.
>
> — Matt Pocock, [source](https://x.com/mattpocockuk/status/2089336734530109837), 2026-08-17
>
> 本站译意：如果代码本身很糟，agent 的表现也会受影响。

## 给协作者一套能上手的环境

把 agent 当作需要快速熟悉项目的协作者：让它找到入口、读懂领域术语、运行应用，并看见检查结果。重复提醒「认真一点」不能补回缺失的事实。

- **目标错误** 回到[对齐](/zh/alignment-and-prototypes)，确认期望行为。
- **信息缺失** 补[文档导航](/zh/agent-documents)和领域语言。
- **验证缺口** 建立[反馈闭环](/zh/implementation-and-feedback)。
- **设计缺陷** 检查[状态与模块边界](/zh/state-and-module-boundaries)。

> **本站推论**
> 本站归纳：类型、接口、状态模型和自动检查能缩小错误空间。先找这次失败落在哪一层，再改最相关的边界；不能据此认定某种架构适合所有项目。

判断改进是否有效，要看同类输入是否被正确处理，以及合法路径能否继续工作。把失败藏起来，或者让所有请求都报错，都不算改善。

## 练习：缺配置却显示成功

一个发送表单在缺少服务地址时仍显示「已发送」。先预测：多加一句「记得检查配置」，能保证下次不出错吗？再按下面四层写出修复。

Figure: 缺服务地址仍显示已发送：复现假成功、拒绝无效配置，并检查异常与合法路径及评审证据。 ([s02-silent-success](/art/s02-silent-success.zh.svg))

### 把假成功变成可见失败

- 任务：用缺少服务地址的环境提交一次，记录错误的成功提示。
- 边界：配置无效时停止发送，给界面明确的失败结果。
- 检查：缺配置时显示错误；有效配置下仍能发送。
- 评审：附两种配置下的操作、日志和界面结果。

参考思路: 边界负责拒绝无效配置，行为检查防止成功提示回归，评审核对真实操作证据。每层都应说清自己拦住什么。

## 怎样才算完成？

交出一条可复现的失败、一处对应边界和一次通过结果。让别人指出同类错误下次在哪一层被拦住；若只能回答「agent 会记住」，反馈还不够。

再看合法请求：是否增加了难以解释的分支？是否为了一个边界错误复制了整套实现？维护成本也应进入验收讨论。

## 速查


## 来源

- [Matt Pocock · 2026-08-17](https://x.com/mattpocockuk/status/2089336734530109837)

非官方、非商业的学习整理，与 Matt Pocock 无隶属或背书关系。所引作品版权归原作者；MIT 复用内容另附版权与许可声明。

本页说明图内嵌的 CSS 片段改编自 Archify（https://github.com/tt-a1i/archify），MIT 许可，完整许可如下。

### 完整许可：Archify (tt-a1i/archify)

```text
MIT License

Copyright (c) 2026 tt-a1i (Archify)
Copyright (c) 2025 Cocoon AI

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```