Agent 工程实践简报 · 2026-10-28

给冻鱼。窗口约 2026-10-27 → 2026-10-28(Asia/Kuala_Lumpur)。严格窗口内几乎无新一手长文;本期以「今日概念」+ 近两日一手 X 实践为主。只收录已核验材料。

今日概念:Agent-ready codebase(agent 就绪代码库)

大白话:不是先换更强的 coding agent,而是先让仓库「自带说明书 + 快反馈 + 本地能验证」。缺类型/测试/文档/可跑命令时,环境会打败任何 agent。

解决什么问题:同一模型在不同仓库效果差一截时,多数人怪模型;真正瓶颈常是仓库没法给 agent 闭环反馈。

和你会的东西的关系:你已在写 skill / 想做 software factory——agent-ready 是工厂的地基:先让任意仓库达到「Documented → Standardized」,agent 才谈得上自主并行。

入门:

上手 prompt(复制给 Claude Code / Codex):

你在当前仓库做一次「Agent-ready」审计,不要绑任何特定技术栈。

目标:对照 Factory Agent Readiness 的思路,判断仓库离「agent 能可靠干活」还差什么,并给出可合并的最小修复。

必读背景(若可联网):https://factory.ai/news/agent-readiness 与 https://docs.factory.ai/agent-readiness/overview
五级:1 Functional → 2 Documented → 3 Standardized → 4 Optimized → 5 Autonomous;先把目标定为 Level 3。

步骤:
1. 探测仓库:读 README、AGENTS.md/CLAUDE.md(若有)、package/锁文件、CI 配置、测试与 lint/typecheck 脚本。先确认「真实本地验收命令」是什么(不要猜;在仓库里找并试跑最小子集)。
2. 按支柱打勾/打叉(每条附证据:文件路径或命令输出摘录):
   - Style & Validation(formatter/linter/typecheck)
   - Build(可复现安装与构建命令是否写清)
   - Testing(本地可跑的单测/集成测)
   - Documentation(AGENTS.md 或等价;新人/agent 如何 setup、如何证明改对了)
   - Dev environment(.env 模板、一键启动本地依赖)
   - 其余支柱(observability/security/task discovery)只记明显缺口
3. 估当前大概在哪一级,并列出「升到 Level 3」的优先修复清单(最多 5 项,按 ROI)。
4. 只实现清单里风险最低的 1–2 项(例如补最短 AGENTS.md「如何跑测 + 什么算证据」、或补一条本地 typecheck/test 脚本说明)。不要大重构。

验收:
- 输出一张表格:支柱 | 现状 | 证据 | 建议
- 对你改动的文件:贴出 diff 摘要,并实际跑通你写下的验收命令,贴关键输出
- 明确写:当前估级、下一件该做的事

本期条目

1. 给 agent 的最好反馈是类型与可捕获行为,不是再堆散文规则

你在当前仓库。目标:找 1 个「agent 常写错、但散文规则拦不住」的状态/行为,用类型或不变量测试把它变成硬反馈。

步骤:
1. 扫最近失败:CI 日志、测试失败、PR 打回评论、或 git 里反复改同一处的文件。归纳「第一个实质失败」是什么。
2. 选成本最低的一种加固(按语言实际工具来,先读仓库确认):
   - 类型/枚举/品牌类型:让非法组合编译不过
   - 或 expect/fixture/快照测试:打印关键行为并固化期望
   - 或一条 property/fuzz(若仓库已有框架)
3. 实现最小改动;不要借机大重构。
4. 写一段 ≤10 行的 AGENTS.md/CLAUDE.md 补充:说明「这类错误靠什么自动拦」,删掉等价的散文禁止句(若存在)。

验收:
- 演示:人为制造旧错误路径时,typecheck 或测试必须失败(贴命令+输出)
- 正确路径仍然通过(贴命令+输出)
- 列出改动文件与为什么这比再写一条 skill 更稳

2. 写代码不再是瓶颈时,CI 变成 verification 层

你在当前仓库。目标:把「agent 改完能否信任」从口头保证,推进到可自动跑的 verification,并砍掉最痛的 CI/本地反馈延迟。

步骤:
1. 找到真实门禁:读 CI 配置与 package scripts,列出 PR 上会跑的检查,以及开发者本地应对的最短命令。对每条记录:大约耗时、是否可本地复现。
2. 找出 Top 3 纸割伤(例如:用了慢 typecheck、全量测、重复安装依赖、未分片、文档命令与真实命令不一致)。每条附证据。
3. 只做 1 个高 ROI 修复,例如:
   - 文档化并跑通「本地 5 分钟内」的最小验证集(typecheck/lint/受影响测试)
   - 或给 agent/人类同一套 `verify` 脚本,命令与 CI 子集对齐
   - 或修正 README/AGENTS.md 里过时的测试命令
4. 在 AGENTS.md/CLAUDE.md 写清:合并前必须出示哪些命令输出才算「做完」。

验收:
- 贴出「修复前/后」你实际跑的验证命令与关键耗时或输出摘要
- 说明这条门禁拦的是哪类 agent 假完成
- 不要改无关业务功能

本期去重用源链接(机器可读)