AI Coding Agent 工程实践
核心判断
AI Coding Agent 的价值不是替代软件工程，而是把软件工程中可自动化的部分大幅加速。越是强的 Agent，越需要更清晰的上下文、更明确的边界、更确定的验证和更强的人类判断。
如果把 Agent 当成无人值守的黑箱工厂，它会快速生成大量代码，也会快速放大误解、重复、过度抽象和架构腐化。如果把 Agent 放进工程流程里，它可以成为高效的协作搭档：读代码、复现问题、生成实现、跑检查、整理证据、提交变更，但人仍然负责架构、风险和最终验收。
主题地图
1. 两种 Agent 观：黑箱自动化 vs 人类主导
AI Coding Agent 的两派：全自动黑箱 vs 人类主导 讨论的是最底层的立场分歧：Agent 是完全自治的软件工厂，还是工程师手里的高效工具。
这里的关键结论是：现在更可靠的路线不是“让 100 个 Agent 在黑灯工厂里连续写三个月”，而是让 Agent 在人类定义的边界内工作。人负责目标、上下文、架构和验收，Agent 负责加速执行。
2. Pi 为什么选择极简
为什么 Pi 选择极简设计 解释了 Pi 的设计哲学。它不试图把所有能力都内置到 harness 里，而是相信模型已经会使用 bash、文件系统、GitHub CLI、tmux 等通用工具。
Pi 的极简不是功能少，而是尽量减少隐藏复杂度。与其把每个能力都包装成特殊工具，不如保留透明、通用、可组合的接口，让用户通过 prompt template、extension，甚至让 Pi 自己修改 Pi 来适配工作流。
3. 日常工作流：从 issue 到 commit
Mario 的日常 AI 编程工作流 展示了一个具体流程：读取 issue、独立复现、分析根因、实现修复、人工 review diff、跑检查、更新 changelog、评论 issue、commit 和 push。
这个流程的重点不是“Agent 自动写完代码”，而是把人的注意力集中在高价值判断上：问题分析是否可信？实现是否过度？边界是否正确？而低价值的机械操作可以交给 Agent。
4. 防止代码库被 Agent 写烂
如何让 Agent 不把代码库写烂 关注质量治理。Agent 常见问题是把简单问题复杂化，生成不必要的 helper、抽象层和重复代码。功能能跑不代表系统健康，代码量增加也不代表工程质量提升。
治理思路是：架构判断不能外包给 Agent；规则不能只写在提示词里，还要落到 lint、typecheck、test、pre-commit 和 CI；任务要小，反馈要快；关键链路要人工审查。
5. 用规则、模板和扩展塑造工作流
Agents.md、Prompt Templates 和自定义扩展 说明了 Pi 如何用轻量机制承载个人工作流。
- Agents.md 提供项目规则和行为约束。
- Prompt Templates 固化高频流程，比如处理 issue 或 wrap up。
- 自定义扩展解决个人协作细节，比如 diff review、issue 状态栏、把上一条回答放进编辑器批注。
这三者对应规则、流程和工具。它们让 Agent 不只是“会写代码”，而是逐渐适配工程师的工作方式。
6. 大代码库的上下文管理
大代码库里如何管理上下文 讨论的是 context engineering。大项目里最重要的不是把所有文件塞进模型，而是让模型看到正确的文件。
如果工程师知道系统边界，就应该直接告诉 Agent 读哪些文件。如果工程师也不了解代码库，就先让 Agent 做探索分析，而不是直接实现。探索阶段可以用会话树或摘要，把分析结果带入后续实现分支，避免上下文失控。
7. Vibe Coding 后的重构
Vibe Coding 之后如何重构 以 Mario 的机器人项目为例：Vibe Coding 很适合快速做原型，但常常产生巨大文件、职责混杂和难以维护的结构。
重构的顺序不是马上让 Agent 重写，而是先恢复理解，再找边界，最后小步抽取。Agent 可以帮忙移动代码，但真正的重构判断在于：哪些职责应该分离，哪些模块边界能承载未来变化。
8. AI 编程时代的软件工程原则
AI 编程时代的软件工程原则 是对整个系列的收束：AI 让代码生成更便宜，但不会让架构、验证、上下文和责任自动消失。
软件工程在 AI 时代更重要，因为 Agent 会放大团队现有工作方式。好的工程文化会被放大成效率，差的工程文化会被放大成更大的技术债。
9. 自修改软件：工具可以被 Agent 继续塑造
自修改软件为什么因 AI Agent 变得可行 讨论 Pi 最有启发的地方：它不只是一个 coding agent，也是一个可以被自己修改的工具。
这件事的关键不是“软件获得自主生命”，而是极简核心、清晰扩展点、Git diff、测试和人工 review 共同构成了一种可控的自修改路径。工具不必一次性内置所有能力，而可以在用户工作流中逐步生长。
10. Agent 不会感到技术债之痛
Agent 不会感到技术债之痛 解释了为什么 Agent 生成代码容易让系统熵增加。人类工程师会被复杂代码库折磨，并因此推动重构；Agent 不会承担未来维护成本，所以更容易为了当前任务继续加逻辑、加分支、加 helper。
这意味着团队必须把“痛感”外部化为复杂度约束、测试、lint、review、架构边界和定期重构，而不是期待 Agent 主动还技术债。
11. 非工程师参与工程流程之后，真正稀缺的是护栏
非工程师参与工程流程之后，真正稀缺的是护栏 关注 AI 带来的组织变化：PM、设计、市场、销售都能让 Agent 生成 demo、页面和 PR。
这很有价值，但也会让原型、demo、实验代码和生产代码边界变得模糊。新的工程流程需要 sandbox、owner、分级 review 和意图说明，让非工程师能参与创造，同时把风险拦在生产系统之外。
12. 为什么 AI 时代要慢下来
为什么 AI 时代要慢下来 不是反对 AI 加速，而是反对只加速代码生成。软件交付还包括需求澄清、架构判断、验证、上线和维护。
成熟的节奏应该是：低风险、机械性、可验证的地方加速；高风险、结构性、不可逆的地方减速。否则生成越快，返工越多。
13. MCP 与 CLI 的工具集成取舍
MCP 与 CLI：AI 工具集成的两种路线 总结了访谈中关于 MCP 和 CLI 的讨论。MCP 适合企业权限、审计和平台化集成，但也会带来上下文膨胀、工具质量不稳定和可组合性下降。
CLI 更透明、更稳定、更符合 Unix 管道哲学，也更接近工程师已有工作流。实践中不需要站队，而是按场景选择最少、最透明、最可靠的工具接口。
14. Prompt Request：先审意图，再审代码
Prompt Request 比 Pull Request 更适合 AI 协作 讨论 AI 协作中的 review 前移。与其让维护者直接面对大段 AI 生成代码，不如先提交 prompt、上下文、约束和验收标准。
这让团队先审问题表达和实现意图，再由工程 owner 在正确上下文中生成或改写代码，最后才进入传统 PR、测试和 review。
一条实践主线
这组文章可以串成一条工作流：
- 先承认 Agent 不是黑箱工厂，而是人类主导下的工程工具。见 AI Coding Agent 的两派：全自动黑箱 vs 人类主导。
- 选择足够透明、可控制、可扩展的 harness。见 为什么 Pi 选择极简设计。
- 让工具通过扩展点和自修改能力适配个人工作流，而不是把所有能力塞进核心。见 自修改软件为什么因 AI Agent 变得可行。
- 把高频流程模板化，让 Agent 处理重复操作。见 Mario 的日常 AI 编程工作流。
- 当非工程师参与软件表达时，先用 sandbox、owner 和 Prompt Request 保护生产流程。见 非工程师参与工程流程之后，真正稀缺的是护栏、Prompt Request 比 Pull Request 更适合 AI 协作。
- 用规则、检查和 review 控制复杂度。见 如何让 Agent 不把代码库写烂。
- 把技术债痛感外部化为指标、测试、边界和重构机制。见 Agent 不会感到技术债之痛。
- 用 Agents.md、Prompt Templates 和扩展沉淀协作习惯。见 Agents.md、Prompt Templates 和自定义扩展。
- 面对大代码库，先管理上下文，再谈实现。见 大代码库里如何管理上下文。
- 面对 Vibe Coding 产生的混乱，先恢复理解，再逐步重构。见 Vibe Coding 之后如何重构。
- 工具集成优先选择简单、透明、可组合的接口，再按企业治理需要引入 MCP。见 MCP 与 CLI：AI 工具集成的两种路线。
- 在高风险决策点主动慢下来，避免把生成速度变成返工速度。见 为什么 AI 时代要慢下来。
- 最后把这些收束为工程原则：人负责边界和责任，Agent 负责加速执行。见 AI 编程时代的软件工程原则。
和已有主题的连接
- AI 时代我如何理解软件交付流程：这组文章可以视为它在 coding agent 场景下的展开。
- 从 Vibe Coding 到 Spec Coding：如何用 TDD 解决 AI 带来的“架构崩坏”：强调用测试和任务 review 抑制 AI 生成的架构漂移。
- TDD：测试不是补充动作，而是把需求理解和架构边界变成可验证资产。
- 重构：当 Agent 生成的代码已经形成复杂度债务时，重构仍然是恢复可维护性的核心手段。
- Agent 设计双轴框架：可以从感知、记忆、推理、行动、反思、协作、治理多个维度观察 coding agent 工作流。
- 什么才是有效 User Story：Prompt Request 本质上是在 AI 协作场景里重新强调问题、上下文和验收标准。
暂时结论
AI Coding Agent 的成熟使用方式，不是更激进地追求全自动，而是更清醒地划分责任：
Agent 负责扩大执行能力，人负责控制系统方向。
真正稀缺的不是代码生成速度，而是上下文组织能力、架构判断能力、验证设计能力和复杂度治理能力。
⚠ Switch to EXCALIDRAW VIEW in the MORE OPTIONS menu of this document. ⚠ You can decompress Drawing data with the command palette: ‘Decompress current Excalidraw file’. For more info check in plugin settings under ‘Saving’
Excalidraw Data
Text Elements
Member = Human | Agent；同一 Stage Role 可在人与 Agent 之间 handoff / takeover
Autonomous：Agent 在 Policy / Evidence Gate 内自动处理；Concern / 越界再切换
Harness Engineering / 控制机制摘要
把业务上下文、阶段状态、工具边界、质量评估、人工审批和运行证据装配成 Agent 的工作环境
Context
Memory
Story / Scenario
State
Plan
Desk Check
Tool
Pair
Q1–Q4
Evaluator
Permission
Stage Authority
Logs / Metrics
Trace
结构化上下文 · 不可变来源 · 可审查计划 · 最小权限 · 自动验证 · 人工升级 · 全程留痕
知识流贯通上下游；Evidence 组织迭代；质量四象限定义证据；Harness 保证它们可执行、可验证、可追踪
AI 扩大跨层执行带宽，让“组件内全栈”更可行
但不消除交付边界、业务上下文、质量证据与责任
Full Stack 是执行能力；Full Stream 是交付模型
Agent 视角：1 Human + N Agents 横向扩展
目标：通过多 Agent 并行扩大个人交付带宽
多 Agent 执行拓扑
Human Authority
意图 · 批准 · 合并 · 问责
Planner
方案
Builder
实现
Tester
验证
Reviewer
审查
1 : N 执行委派
能够发挥作用的受限前提
任务可切分
边界清晰 · 低耦合
结果可验证
测试 · Diff · Review
承诺：并行 Agent → 扩大执行带宽 → “一人虚拟团队”
局限：执行扩展了，Stage Authority 仍收敛到 Human
Agent 执行层 / 可横向扩展
Plan / Code × N
Tests / Review × N
Reports / Diffs × N
N : 1 汇聚
Central Human Gate / 单点授权边界
所有 Agent 的验证 · 批准 · 发布
异常处置与最终决定都汇聚于此
Agent 没有独立 Stage Assignment，权限全部回收至 Human
为什么 1 Human + N Agents 仍然走不通
• N 个 Agent 只是执行分支，Stage Authority 没有分布
• 所有输出仍汇聚为 1 人的验证、审批与异常处理
• 并行越快，Human 的上下文切换与决策负担越大
• Reviewer 仍受同一中心指挥，独立制衡不足
• 自动化无法越过 Central Human Gate，吞吐最终受单人限制
问题不在 Agent 不能负责，而在权威全部收敛到一个 Human
应将 Human / Agent 都建模为 Workspace Member
按 Stage Assignment 与 Policy 分配处理权
AI 扩展执行
→ 1 + N Agents
AI 对决策、设计、开发、Review 与测试的加速不均，局部提速反而放大等待、切换与返工
不均匀加速（示意）：需求 1.2× · 设计 1.5× · 代码 5× · Review / Test 1.3×
Product
需求决策 · 1.2×
信息 · 取舍
优先级
Agent Development
代码生产 · 5×
PR · Change · Test
×
Review /
Merge · 1.3×
Context
Gate
×
Test /
Release · 1.3×
Risk · Value
Gate
Value
Learn
上游饥饿｜成熟决策 / 设计
供给速度 < Agent 消费速度
下游拥堵｜PR / Tests 生成
速度 ＞ Review / 验证承接
歧义越晚发现，返工半径越大
需求 → 设计 → 代码 → 测试 / 发布
可观察后果
上游饥饿 · 下游拥堵
WIP / Review Age 增长
等待 · 上下文切换 · 合并冲突
晚发现歧义 → 系统返工
系统判断
局部产能 ↑ ≠ 系统吞吐 ↑
吞吐由最窄 Stage Gate 决定
Process Time 下降
不代表 End-to-end Lead Time 下降
设计目标：不再让 Agent 更快，而是让变化顺畅穿过整个团队
成熟输入 · WIP 控制 · Gate 容量 · Evidence 反馈 · Handoff
→ 右侧：多人协作交付平台
共享 Stage Board 组织多人协作；Human / Agent 按角色、权限与证据在每个阶段介入、接力与接管
1 · 谁参与 / Participants & Assignment
Human / Agent 作为同一 Member，通过 Role Slot 进入阶段
Human Members
Product · Design · Engineering · QA · Operations
Agent Members
Research · Analysis · Coding · Test · Review · Ops
Role Assignment / Access Policy
Role Slot · Capability · Authority · SoD
Lease · Escalation · Human Takeover
2 · 如何协作
Collaborative Stage Board / Human + Agent at Every Stage
按 Role Slot 进入 · 可并行 / 接力 · Evidence Gate 退出 · Handoff / Escalation
0 · Probe
Signal / Candidate
1 · Kickoff
Story Ready
2 · Understand
Scenario / Model
3 · Tasking
Approved Plan
4 · Pair
Quality / Increment
Stage State 共享当前位置 · Assignment 决定谁处理 · Evidence 决定能否进入下一阶段
3 · 如何交接
Shared Evidence & Handoff
提交、决策、版本、产物与交接都携带 Actor / Role / Stage / Revision
Shared Evidence Feed / 团队共享证据
Submission · Decision · Revision · Artifact · Concern · Handoff
下一阶段消费证据，而不是重新恢复聊天上下文
执行能力来自上方 Harness
Context · Plan · Tool · Q1–Q4 · Permission · Logs / Metrics
平台职责边界
只编排：谁在何阶段介入 · 如何交接证据 · 何时升级 / 人工接管
不重复展开：Git / CI / Runtime / Registry 等实现细节
展开为 Workspace Protocol
Design
体验判断 · 1.5×
路径 · 边界
异常状态
H · Product · Ops
A · Research · Feedback
H · Product Owner
A · Story · Context
H · Product · Design
A · Analysis · Model
H · Architect · QA
A · Plan · Test
H · Engineer · Reviewer
A · Code · Test
5 · Showcase
Accept
H · Product · QA
A · Evaluate · Explore
6 · Respond
Knowledge / Probe
H · Ops · Support
A · Observe · Probe
Element Links
tcpfZWhJ: 为什么要成为全流程序员，而非全栈程序员？
ztTkapjx: 设计流动摩擦：AI 原生团队的核心能力
vTRkeHWu: 设计流动摩擦：AI 原生团队的核心能力
HSIRFLfO: 设计流动摩擦：AI 原生团队的核心能力
aIZQFxvW: 设计流动摩擦：AI 原生团队的核心能力
IBwto6CT: 设计流动摩擦：AI 原生团队的核心能力
9EDUaxZK: 设计流动摩擦：AI 原生团队的核心能力
xp7VQXht: 设计流动摩擦：AI 原生团队的核心能力
NaEGkGV6: 设计流动摩擦：AI 原生团队的核心能力
rq21Ozgr: 设计流动摩擦：AI 原生团队的核心能力
828Fq0kW: 设计流动摩擦：AI 原生团队的核心能力
L30gbyil: 设计流动摩擦：AI 原生团队的核心能力
LFuJ3cyk: 设计流动摩擦：AI 原生团队的核心能力
1wZD3M6D: 设计流动摩擦：AI 原生团队的核心能力
wDNL1L50: 设计流动摩擦：AI 原生团队的核心能力
DJ9X2I4T: 设计流动摩擦：AI 原生团队的核心能力
luwCzLmt: 设计流动摩擦：AI 原生团队的核心能力
LMVhXyzc: 设计流动摩擦：AI 原生团队的核心能力
Fdd7t8Gi: 设计流动摩擦：AI 原生团队的核心能力
GADr5cne: 设计流动摩擦：AI 原生团队的核心能力
48GXAa2Q: 设计流动摩擦：AI 原生团队的核心能力
igGkTaHf: 设计流动摩擦：AI 原生团队的核心能力
r45ztUcC: 设计流动摩擦：AI 原生团队的核心能力
qCGoHBpp: 设计流动摩擦：AI 原生团队的核心能力
j8iqyABI: 设计流动摩擦：AI 原生团队的核心能力
gtMjQZ4z: 设计流动摩擦：AI 原生团队的核心能力
5S1JmLwZ: 设计流动摩擦：AI 原生团队的核心能力
FNmbIvPQ: 设计流动摩擦：AI 原生团队的核心能力
E14V2NiQ: 设计流动摩擦：AI 原生团队的核心能力
loRMzdEk: 设计流动摩擦：AI 原生团队的核心能力
sGW5aX6b: 设计流动摩擦：AI 原生团队的核心能力
f55W5WQP: 设计流动摩擦：AI 原生团队的核心能力
69hqoanA: 设计流动摩擦：AI 原生团队的核心能力
flowDsgR: 设计流动摩擦：AI 原生团队的核心能力
flowDsgA: 设计流动摩擦：AI 原生团队的核心能力
Irdx0IAp: 知识工程师
7szM0utd: 为什么要成为全流程序员，而非全栈程序员？
561gH4it: 设计流动摩擦：AI 原生团队的核心能力
l86KUBIE: 设计流动摩擦：AI 原生团队的核心能力
uRI2rsLT: 设计流动摩擦：AI 原生团队的核心能力
C1IDTtud: 设计流动摩擦：AI 原生团队的核心能力
2ndHpED7: 设计流动摩擦：AI 原生团队的核心能力
TVZmzjyN: 设计流动摩擦：AI 原生团队的核心能力
SsvWCuEz: 设计流动摩擦：AI 原生团队的核心能力
Yzo8DAph: 设计流动摩擦：AI 原生团队的核心能力
kCzEZTYs: 设计流动摩擦：AI 原生团队的核心能力
Ean8bBdN: 设计流动摩擦：AI 原生团队的核心能力
IdjLjwpm: 设计流动摩擦：AI 原生团队的核心能力
tt4n6J7I: 设计流动摩擦：AI 原生团队的核心能力
PoAPZV6c: 设计流动摩擦：AI 原生团队的核心能力
RdK1C4GJ: 设计流动摩擦：AI 原生团队的核心能力
vHry7joH: 设计流动摩擦：AI 原生团队的核心能力
ImfIv2hn: 设计流动摩擦：AI 原生团队的核心能力
qSK1K2yp: 设计流动摩擦：AI 原生团队的核心能力
B8kwcREp: 设计流动摩擦：AI 原生团队的核心能力
kehhMlcI: 设计流动摩擦：AI 原生团队的核心能力
jSNRDyfo: 设计流动摩擦：AI 原生团队的核心能力
U5Ea8AFo: 设计流动摩擦：AI 原生团队的核心能力
RJRtadhR: 设计流动摩擦：AI 原生团队的核心能力
flowDsgT: 设计流动摩擦：AI 原生团队的核心能力
flowDsgD: 设计流动摩擦：AI 原生团队的核心能力