Agent 优先工程化
这一页只保留结论版。完整笔记见：
如果只想先抓住最重要的判断，看这页就够了。
核心结论
当代理开始承担越来越多的代码、文档和验证工作时，工程重点会从“人写代码”转向另外三件事：
- 仓库是否对代理足够可读
- 目标和约束是否写得足够清楚
- 反馈回路是否足够快、足够可验证
换句话说，人类工程师更像在设计一个让代理稳定工作的系统。
结论一：仓库要成为记录系统
如果代理会反复进入和离开仓库，关键知识就不能只停留在聊天记录里。
至少要让这些信息能在仓库中重新发现：
- 项目怎么启动
- 系统怎么分层
- 当前任务做到哪一步
- 为什么之前选了这个方案
这也是为什么 AGENTS.md、ARCHITECTURE.md、设计文档和执行计划会变得越来越重要。
结论二：AGENTS.md 应该是地图
对代理来说，最稳的入口不是一份很长的手册，而是一张能逐步深入的地图。
AGENTS.md 更适合做这些事：
- 说明工作方式和禁区
- 指向更深层文档
- 告诉代理下一步去哪里查
不适合做这些事：
- 承担全部历史知识
- 变成整站文档的复制品
- 一开始就把大量细节全部塞进上下文
结论三：可观测性本身是代理能力的一部分
很多“代理不稳定”的问题，本质上不是模型不够强，而是系统没给它足够好的反馈信号。
代理最好能直接消费这些信息：
- 日志
- 测试结果
- 页面截图或 DOM 状态
- 关键指标和追踪数据
只有这样，它才不只是“生成代码”，而是真的能验证修复。
结论四：复杂任务要有持久化计划
复杂工作不要只在对话里拆解，最好写进仓库，至少记录：
- 任务拆解
- 当前进度
- 决策理由
- 技术债和后续事项
这样下一次无论是人还是代理接手，都不用从零恢复上下文。
对当前仓库的启发
这个仓库现在还是“知识库 + 最小示例”形态，不需要一次把所有 agent-first 基础设施补满。
更现实的顺序是：
- 先保持
docs/的栏目职责清楚 - 需要代理长期维护时，再补
AGENTS.md - 示例和工程复杂度上来后，再补
ARCHITECTURE.md - 真正出现复杂任务链路后，再引入
docs/exec-plans/