Agentic Engineering
Patterns

给 Claude Code、Codex 这类 coding agent 的*可靠用法说明书*：不是 vibe coding 的爽文，而是把目标、工具、验证、harness 串成可维护工程系统。手绘风不是乱画，而是用更直觉的版式去承载严肃方法论。

wood editorial × handline serif title quote banner process bar

Agentic engineering ≠ vibe coding

Vibe Coding / Karpathy

偏原型、凭感觉、常常没有 code review，也没有完整 harness。

Agentic Engineering / Willison

面向生产：要求 review、测试、验证证据，以及能反复复用的工作流。

写代码变便宜了，写好代码并没有。

当你的直觉说"这活不值得自己做"时，可以先丢给异步 agent。最坏结果只是浪费几分钟 token；最好的结果是把本来不会做的维护工作也做了。

01 · 定目标Set goals

人在问题空间中界定边界，指出什么是对、什么是偏。

02 · 给工具Give tools

把细规格、样例、上下文与执行能力交给 agent。

03 · 验结果Verify results

必须可运行、可测试、可审查，不能只看口头描述。

04 · 写回 harnessClose the loop

把本次成功方法沉淀为系统能力，避免下次重来。

五大原则

principles

定义边界

人的职责不是替 agent 打字，而是设定目标、给工具、验结果，并把新经验写回 harness。

接受新约束

代码产出几乎免费，但好代码依旧昂贵；测试、文档、重构不该再被省掉。

囤积可复用解法

收集带可运行证明的 snippets、模板、命令与案例，逐渐组合成自己的工程武器库。

质量应上升

把任务交给 agent 后，技术债应该下降；零容忍"反正能跑"的代码味道。

严守反模式

不提交未 review 的 PR；代码必须小、可运行、有上下文，并附上测试证据。

AGENT = 通过工具循环来完成目标。能执行代码，是 coding agent 与普通聊天 LLM 的分水岭。

先懂机制 · Git · Subagent

mechanism / git / subagent

Agent 机制tool loop

LLM + system prompt + tool loop。对话越长越贵，模型又是无状态的，所以上下文是预算；复杂 debug 场景要善用 reasoning/thinking。

Git：大胆用，不必背recovery

Review changes made today：快速恢复上下文
Sort out this git mess：把混乱工作区交给 agent 整理
git bisect：用代理帮助定位回归根因

Subagent：省上下文parallel

先探索 repo，再并行修改多个独立文件；把 review / run / debug 交给更便宜的子代理，只汇报结果，不回灌冗长上下文。

Explore
先识别仓库结构

Parallel
独立任务并发处理

Expert
专项诊断后回报

测试 · 理解代码

testing / code understanding

第一道：TDDred → green

先写测试，再确认失败，再让 agent 只完成最小通过实现。

第二道：新对话跑全量测试fresh context

开新会话只做执行验证，避免 agent 被旧上下文污染，优先跑完整 test suite。

第三道：手工验收manual proof

用 python -c、curl、Playwright 或浏览器复查关键路径，留下真实输出。

Showboat： $ pytest tests/test_agent_flow.py 1 failed, 12 passed $ pytest tests/test_agent_flow.py -q 13 passed in 2.41s $ curl -I /health HTTP/1.1 200 OK

好代码标准quality bar

必须能运行，并且被证明跑过
真正解决问题，不回避错误路径
足够短小、可维护、可解释
在 YAGNI 与扩展性之间拿平衡
保留安全性与可观测性

还认知债：理解代码walkthrough