AI Coding / Harness Engineering / Context Engineering
AI Coding 完整方法论: 从让模型写代码, 到建立受约束的工程协作系统
真正成熟的 AI Coding，不是把需求丢给模型，期待它一次性吐出正确答案，而是先把目标、边界、上下文、验证、检查点与迭代秩序写成一套稳定系统。人负责目标与裁决，AI 负责受约束地搜索实现路径，Harness 负责调度、校验、重试与收敛。只有这样，AI Coding 才会从偶尔有效的技巧，升级为可复制、可维护、可扩展的工程能力。
这篇文章既面向人类开发者，也面向 code agent 本身。对人类读者，它是一套组织 AI 协作与审查 AI 产出的工程方法论；对 code agent，它也可以被直接当作执行任务时应遵循的行为约束与工作秩序。
一、真正的问题不是“怎么让 AI 写代码”，而是“怎么让 AI 在工程边界内稳定产出”
很多人理解 AI Coding 的方式，仍然停留在“把需求说清楚，模型就会帮我把代码写出来”。这种理解只适合非常短、非常局部、几乎没有后续维护成本的小任务。一旦任务变成真实工程问题，情况立刻复杂起来：需求会含糊，代码库有历史包袱，输出要兼容现有结构，错误不能只被看见，还必须被验证、定位和修正。
因此，AI Coding 的真正问题从来不是“模型能不能写”，而是“模型写出来的东西能不能被稳定地放进一个真实系统里”。这也是为什么成熟的 AI 编程方法论，最终一定会从提示词技巧转向系统设计：需要明确的目标接口，需要可验证的验收标准，需要上下文治理，需要检查器，需要中间态，需要重试机制，需要断点恢复，需要对副作用的控制。[3][4][5]
| 把 AI Coding 理解成什么 | 典型做法 | 短期效果 | 长期结果 |
|---|---|---|---|
| 一次性生成工具 | 丢一个模糊需求，让模型直接输出代码 | 看起来很快 | 返工频繁，副作用多，难以复用 |
| 受约束的工程协作系统 | 先定义目标、边界、验证，再让模型在闭环里迭代 | 起步更严格 | 更稳定、更可控、更容易扩展 |
二、这套方法论的世界观：人负责目标与裁决，AI 负责搜索实现，Harness 负责收敛
只要把 LLM 视为一个“非常强但并不可靠的推理与生成模块”，很多方法论问题都会变得清晰。它擅长把上下文、规则和目标转译成局部实现；它不擅长替你承担系统级责任。系统级责任包括：任务拆解、状态管理、验证协议、副作用控制、何时停止、何时回滚、何时重试、何时升级为人工裁决。[3][4][6]
所以一套成熟的 AI Coding 系统，至少包含三个角色层次。第一层是人类，负责定义目标、非目标、优先级、风险边界和最终验收。第二层是 AI，负责在边界内完成分析、生成、修补、总结等局部工作。第三层是 Harness，也就是围绕模型建立的工程壳层，它负责把调用顺序、验证逻辑、错误恢复、上下文管理和中间态治理写成程序秩序。没有这第三层，AI Coding 往往会很快退化成“对话式碰运气”。从更长的思想脉络看，这种把模型视为新型软件构件、把行为目标与验证前置的视角，也可以追溯到 Karpathy 对《Software 2.0》的讨论[2]。
| 角色 | 核心职责 | 不该承担什么 |
|---|---|---|
| 人类开发者 | 定义目标、边界、成功标准、风险裁决 | 不必手工完成所有实现细节 |
| LLM / code agent | 在给定上下文与约束内完成局部推理、实现和修正 | 不应主导端到端系统秩序 |
| Harness / Orchestrator | 调度、校验、重试、记录、断点恢复、上下文治理 | 不替代人类做价值判断 |
三、5 条基础原则：所有成熟 AI Coding 系统都绕不开这几件事
如果把 AI Coding 压缩成最小行为规范，这五条原则几乎构成了通用底座。它们并不是凭空拼出来的抽象口号，而是过去两年里大量 coding agent 实践的共同收敛结果；像社区中传播很广的《andrej-karpathy-skills》这类规范，本质上也是在把“先澄清、求最简、做最小改动、围绕验证收敛”压缩成可复用的 agent 行为约束[1]。
原则 1
先想再做。假设、歧义、备选解释必须先暴露，不允许模型默默替你做决定。
原则 2
简洁至上。默认只做当前目标的最小闭环，不提前抽象，不顺手扩功能。
原则 3
精准修改。只动必须动的部分，每一行改动都要能追溯到需求或验证失败项。
原则 4
目标驱动。任务必须被翻译成可验证目标，而不是模糊愿望。
原则 5
验证闭环。任何 AI 产出默认不可信，必须进入评估、修正、再验证的循环。
原则总括
越想发挥 AI 的速度，就越要把约束、验证和边界做硬，否则速度只会放大错误。
先澄清：不让模型替你补全前提
关键词：显式假设、暴露歧义、停下来问、拒绝默选解释。
真实工程里，AI 最危险的失误往往不是语法错误，而是“理解错了你的意图，却自信地一路做下去”。因此开始实现前，必须先把假设写出来，把多种理解并列出来，把不确定点暴露出来。如果任务存在几种解释，不能让模型偷偷挑一种最顺手的。
这条原则看起来拖慢节奏，实际上是在提前消灭返工。很多“模型怎么越改越乱”的根因，并不是生成能力不够，而是起点错了。
最小方案：避免把“看起来专业”误当成“真的合适”
关键词：最小闭环、拒绝预留、禁止一次性框架化。
LLM 非常容易产生一种工程错觉：用更多层、更强抽象、更完整接口把代码包装得很“高级”。但真实需求常常只需要一个最小、直接、低副作用的实现。所谓简洁，不是写得幼稚，而是只承担当前问题所需要的复杂度。
所以 AI Coding 要把“不要添加未被要求的灵活性、不要为一次性问题做永久抽象、不要为想象中的未来场景铺路”写成硬规则。很多坏代码不是功能错，而是结构过量。
精准修改：主任务做对了，不代表副作用可以被原谅
关键词：最小 diff、范围约束、遵循现有风格、只清理自己引入的脏点。
在已有仓库里，AI 最常见的高成本错误之一是“顺手改”。它修了一个问题，同时改了相邻注释、格式、命名、结构，甚至开始清理看不顺眼的旧逻辑。最后主需求也许完成了，但 review 和回归成本大幅上升。
精准修改的标准非常简单：每一行变化都应该能直接追溯到需求、缺陷或验证失败项。凡是追溯不到的改动，默认都值得怀疑。
验证闭环：没有验证的生成，不叫完成
关键词：eval、refine、verify、通过后再继续。
把任务翻译成“可验证目标”，是 AI Coding 从聊天技巧进入工程状态的分水岭。修 bug，就先写复现；加功能，就先定义输入输出；重构，就先锁定行为不变。这样模型的输出不再只是“看起来合理”，而是被外部检查器判断“是否达标”。
一旦进入验证闭环，AI 的角色就从“写最终答案的人”，变成“不断逼近成功标准的执行者”。这是更符合工程现实的角色定位。
上下文治理：不是喂得越多越好，而是组织得越准越好
关键词：只给必要上下文、结构化摘要、长任务切片、中间态复用。
很多 AI Coding 失败，不是因为模型不会写，而是因为上下文被组织得太差。无关文件、冗长讨论、历史噪音混进来后，模型会在真正关键的信息上失焦。上下文工程的目标，不是把仓库一股脑塞进去，而是只暴露当前决策所需的材料。[5]
高质量上下文应优先是结构化的：接口摘要、约束摘要、变更摘要、风险摘要，而不是一堆原始文本。长任务则应分批推进，每一批只携带必要摘要进入下一批。
Harness：把 AI Coding 从“对话”升级成“系统”
关键词：状态机、检查器、重试、检查点、外部秩序。
只靠 Prompt 很难支撑真实工程任务。真正稳定的 AI Coding，一定要有外部程序壳层去承担秩序：什么时候读取上下文，什么时候让模型生成，什么时候运行测试，什么时候回滚，什么时候保留检查点，什么时候终止。[3][4]
换句话说，Prompt 定义的是局部推理接口，Harness 管的是整个任务生命周期。前者决定模型这一轮说什么，后者决定系统下一步做什么。
四、标准工作流：把 AI Coding 写成 7 步操作系统
如果要把这套方法论压缩成最稳定的通用流程，我更推荐把它写成 7 个固定阶段，而不是依赖临场发挥。流程越稳定，团队协作越容易统一，工具层越容易自动化，失败后越容易定位是哪个环节出了问题。
| 阶段 | 要解决的问题 | 关键产物 |
|---|---|---|
| 1. 任务定约 | 这次到底要什么，不要什么，能碰哪里 | Objective / Non-goals / Scope / Verify |
| 2. 上下文提取 | 当前决策真正需要哪些信息 | 接口摘要、约束摘要、相邻实现、未知点 |
| 3. 先计划再实现 | 多步任务怎样拆成可验证的小步 | 步骤列表和每步验证方式 |
| 4. 最小切片实现 | 一次只推进一个最小可验证单元 | 最小 diff 或最小产物 |
| 5. 局部验证 | 当前切片是否满足功能和格式要求 | 测试、lint、build、快照、断言 |
| 6. 全局一致性复查 | 与现有系统是否冲突，跨阶段是否一致 | 接口兼容性、状态一致性、风格一致性结论 |
| 7. 总结与落盘 | 如何保留可续跑、可审计、可复盘的中间态 | 变更摘要、风险摘要、检查点 |
五、任务定约是第一生产力：先把目标、非目标、范围和验收写死
很多 AI Coding 失败，一开始就埋下了种子。因为任务定义太模糊，所以模型只能靠猜；因为非目标没写明，所以它会顺手扩展；因为范围不清，所以它会误改无关区域；因为验收标准没定义，所以所有人只能凭感觉判断“差不多行不行”。
所谓任务定约，就是在开始之前把这四个维度写成显式协议。它们并不复杂，但极其高价值。协议越明确，模型的搜索空间越小，错误类型越少，验证工作越便宜。
需要再往前走一步的是：如果 AI Coding 已经进入“需要 AI 帮你继续编写提示词、agent instruction 或推理接口”的阶段，那么这里的任务定约还不够，必须继续把这些约束细化成结构化提示词与可渲染的推理接口。这个层面可以继续参考《结构化提示词设计方法论》[12]。
六、把任务翻译成可验证目标：从“看起来对”切换到“证明它对”
AI Coding 进入工程状态的关键，不在“会不会写代码”，而在“会不会把需求翻译成验证协议”。只要任务仍然停留在“修一下”“优化一下”“让它能用”这种表达层次，模型和人都会被困在模糊地带里。只有当需求被改写成可执行检查时，系统才真正开始收敛。
这也是为什么很多成熟做法会强调测试先行、快照对比、结构化断言和门禁链路。验证协议不是附属品，而是主流程的一部分。
| 原始需求 | 更好的工程化改写 |
|---|---|
| 修复这个 bug | 先写复现用例，再让复现用例通过 |
| 给接口加校验 | 为非法输入写失败用例，并明确报错结构 |
| 重构这段代码 | 保持行为不变，并证明重构前后测试一致 |
| 让页面更好用 | 先定义可观察变化，再通过截图、交互检查或指标验证 |
七、上下文工程不是“喂更多”，而是“组织得更准”
编码 agent 的上限，很大程度取决于上下文工程。上下文不是原始资料仓库，而是决策输入层。只要这个输入层被无关信息淹没，模型就会在最关键的约束、接口和风险点上失焦。[5]
真正有效的上下文治理，至少包括四件事。第一，只给当前任务真正需要的代码和说明。第二，优先提供结构化摘要，而不是大段原文。第三，把长任务拆成多个局部阶段，每一阶段只带必要中间态。第四，保留检查点和摘要，让系统可以续跑，而不必每次从零开始重新推理。
| 低质量上下文 | 高质量上下文 |
|---|---|
| 整个仓库、整个聊天记录、整个日志直接喂进去 | 只提取相关入口、接口、约束、相邻实现和未知点 |
| 堆原始文本 | 堆结构化摘要与已验证中间态 |
| 每轮都从头解释背景 | 用检查点和摘要做增量续跑 |
八、Harness 才是真正的“系统大脑”：Prompt 管局部推理，Harness 管任务秩序
很多人把 AI Coding 的主要精力放在“怎么写更强的 Prompt”上，但如果系统缺少 Harness，Prompt 再长也很难可靠。原因很简单：Prompt 只能定义这一轮推理的语义接口，它不能天然负责状态转换、异常恢复、门禁失败后的回退、检查点落盘、上下文裁剪、重试策略和并发边界。[3][4]
所以更成熟的做法，是把 Prompt 视为局部推理模块，把 Harness 视为总控。前者回答“这一轮模型应该做什么”，后者回答“系统下一步应该怎么走”。这个分工一旦清晰，整个 AI Coding 系统就不再像长对话，而更像一个可审计、可续跑、可自动化的任务流水线。
也正因为如此，AI Coding 不只是上下文管理问题，还是推理接口设计问题。尤其当 AI 已经不止在写代码，而开始帮你写 prompt、写 agent instruction、写中间推理协议时，Prompt 本身也必须被工程化，而不能继续停留在自由文本层面；这一层可以和《结构化提示词设计方法论》一起看[12]。
九、不同任务类型的最佳姿势并不一样：不要用一种工作流解决所有问题
一套方法论要真正可用，不能只讲原则，还要指导不同任务怎样落地。AI Coding 最大的误区之一，就是把所有任务都当成同一类生成问题。实际上，成熟仓库修 bug、新功能原型、大型重构、代码审查、安全敏感改动，它们的边界条件完全不同。
| 任务类型 | 推荐策略 | 核心风险 |
|---|---|---|
| 成熟仓库修 bug | 先复现，再最小修复，再跑回归 | 顺手改太多、误伤相邻逻辑 |
| 增量式功能开发 | 先定义最小闭环，再逐步扩展 | 过早抽象、顺手加配置 |
| 大重构 | 拆成一串行为不变的小步，每步独立验证 | 一次改太多，失败后无法定位 |
| 代码审查 | 聚焦 bug、回归风险、测试缺口和边界错误 | 沉迷风格意见，忽视真正风险 |
| 安全敏感代码 | 叠加专门安全检查，不接受“看起来没问题” | 模型过度自信、引入隐性漏洞 |
这也是为什么很多外部研究对 AI 编码能力的结论会显得不一致。原型类任务里，AI 往往能带来显著速度优势；而在复杂成熟代码库里，审查和修复 AI 输出的成本可能抵消甚至反超这些收益。METR 的随机对照研究就显示，针对资深开源开发者与复杂仓库任务，早 2025 年的 AI 工具让完成时间平均变慢了 19%。[8]
十、为什么这套方法论必须强调验证、审慎和零信任
如果 AI 只是偶尔答错一个事实，问题还不算大；但在代码场景里，错误往往是结构性的。模型会过度自信，会做错误假设，会在局部正确时掩盖全局冲突，会把“像工程”误当成“是工程”。微软关于代码模型过度自信的研究，以及开发者与 agent 协作研究，都说明了这一点：模型很强，但仍然远远谈不上“可被无条件信任”。[9][10]
安全面上更是如此。Veracode 的 2025 报告显示，在其测试的任务中，仍有接近一半的 AI 生成代码会包含已知安全问题。[11] 这意味着“只要模型更强就会自动安全”并不是成立前提。也正因此，零信任原则在 AI Coding 里不是保守姿态，而是必要工程纪律。
十一、最常见的反模式：AI Coding 为什么会从高效协作退化成高成本噪音
几乎所有糟糕的 AI Coding 体验，最终都能归到几类稳定反模式。它们之所以危险，不是因为偶尔会出错，而是因为一旦形成习惯，就会系统性放大模型的弱点。
| 反模式 | 问题本质 | 后果 |
|---|---|---|
| 需求含糊就直接开写 | 把澄清成本后置 | 越改越偏，返工更大 |
| 一次让 AI 改太多地方 | 失去问题定位能力 | 失败后难以判断错在何处 |
| 把“灵活性”当成高级工程 | 复杂度超前增长 | 结构噪音积累，维护变难 |
| 只有生成，没有门禁 | 把模型输出误当成完成 | 错误向后传播 |
| 上下文全量堆给模型 | 无差别输入污染关键约束 | 注意力失焦，判断漂移 |
| 让 Prompt 承担系统秩序 | 缺少外部 harness | 状态、重试、异常处理失控 |
| 顺手清理无关代码 | 范围约束失效 | review 成本和回归风险飙升 |
十二、最后的收束：AI Coding 最值钱的不是第一版代码，而是第五次迭代后系统仍然站得住
AI 让“写出第一版”变得越来越便宜，这一点几乎已经没有悬念。真正稀缺的能力，正在从“能不能写出来”转向“能不能把生成速度转化成稳定系统演化速度”。换句话说，AI Coding 时代最值钱的能力，不是 prompt 花样，不是一次性生成长度，而是把模型纳入工程秩序、让它在约束中持续产出、并让这些产出在多轮迭代后依旧可维护。
如果一定要用一句最简洁的话概括这套方法论，可以这样说：先用契约定义任务，再用上下文组织信息，再用最小切片推进实现，再用门禁闭环逼近成功标准，最后用 Harness 维持整个系统的秩序。AI 在这里不是替代工程，而是被工程化。
但当 AI 开始主动抽象、拆层、预留扩展点时，真正重要的就已经不只是“能不能生成代码”，而是“能不能谨慎识别变化点、控制依赖扩散、压住架构复杂度”。这一层更接近结构判断与架构克制的问题，可以继续参考《AI Coding 时代，理解设计模式变得更加重要》[13]。
参考文献
[1] Multica AI. andrej-karpathy-skills.
[2] Andrej Karpathy. Software 2.0.
[3] OpenAI Research Team. Harness engineering: leveraging Codex in an agent-first world.
[4] Anthropic Research Team. Effective harnesses for long-running agents.
[5] Birgitta Böckeler. Context Engineering for code agents.
[6] Dex Horthy. 12 Factor Agents.
[7] Researchers. Vibe coding: programming through conversation with artificial intelligence.
[8] METR. Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity.
[9] Microsoft Research. Do Code Models Suffer from the Dunning-Kruger Effect?.
[10] Microsoft Research. Why AI Agents Still Need You.
[11] Veracode. 2025 GenAI Code Security Report.
[12] Vortezwohl. 结构化提示词设计方法论. 面向 AI 编写提示词、agent instruction 与推理接口的结构化方法。
[13] Vortezwohl. AI Coding 时代，理解设计模式变得更加重要. 面向 AI 架构设计、变化点控制与谨慎抽象的结构方法。