核心概念

Intent Engineering 为何存在、它拒绝什么、以及当意图成为稀缺资源时会发生什么变化。

瓶颈已经转移

软件工程花了数十年来优化一个约束：人工编写代码是昂贵的。设计模式、代码审查、CI/CD、微服务、敏捷：所有这些都是管理稀缺代码的系统。

这个约束已经瓦解。AI 代理现在可以以机器速度生成、审查、测试和部署代码。

新的瓶颈是意图。当代码变得廉价时，稀缺资源变成了决定构建什么、为什么重要、以及什么必须排除在外。没有这些，AI 只会生产精致的废品。

Intent Engineering 不是什么

它不是提示工程：提示工程调优单次对话，而 Intent Engineering 定义的是每次对话都继承的持久文档。

它不是设计文档：设计文档规定 How，而 Intent 文档拒绝这样做，因为技术栈、架构和时间线都是实现选择。

它不是 PRD：PRD 试图做到全面且静态，而 Intent 文档保持精简、通过探索演进，并且可以被终止。

它不是框架或工具：它是一个 markdown 文件和一种纪律。

三个层次

Intent 文档恰好有三个层次，因为人类在这里只拥有三样东西：Why、What 和 Not。其余一切都是实现选择。

Why — 存在的理由

Why 是关于价值的声明：谁的痛点重要、什么结果算成功、以及什么证据会改变你的想法。在 seed 和 exploring 阶段，它是一个赌注；在 clarified 阶段，它是一个承诺。

What — 正在构建的东西

What 是承诺的覆盖面：功能、用户流程和边界情况。它必须足够具体，让 AI 能从中派生工作，但对 How 保持沉默；"用户可以将报告导出为 PDF"属于这里，"使用 puppeteer"则不属于。

Not — 不可逾越的边界

Not 是严肃性的体现：安全约束、范围限制、质量标准、禁止的模式。没有 Not，AI 会根据你从未写下的假设来优化。

Learnings — 演进引擎

清晰通常来得很晚。一个想法起初是 seed：模糊的、脆弱的，并且以有趣的方式是错误的。前进的方式是探索。

Learnings 是带时间戳的记录，记载你尝试了什么、现实说了什么、以及什么发生了变化。

对于人类：它杜绝了事后修改历史。当项目发生转向时，原因在 Learnings 中，而不是在记忆里。

对于 AI：它承载着代码永远无法承载的上下文。代理看到的不仅是当前的形态，还有产生它的路径。

生命周期

Intent 经历四个状态：

状态	描述	该做什么
seed	仅有想法。Why 是猜测；What 和 Not 为空或模糊。	写下假设。运行第一个测试。
exploring	假设正在通过原型、研究和访谈接受压力测试。	运行实验。记录 Learnings。根据需要重写 Why/What/Not。
clarified	Why、What 和 Not 都已明确。不确定性标记已消除。	交给 AI。让它去构建。
killed	证据表明不应构建，或现有方案已经胜出。	记录原因。停止。这是一个好的结果。

最困难的转换是任何状态 → killed。启动项目很廉价；终止糟糕的项目才是判断力。

与现有概念的关系

概念	范围	与 Intent Engineering 的关系
Context Engineering	单任务、临时性	Intent 文档是所有任务之上的持久上下文。
Harness Engineering	工具和环境配置	Not 层应编译为工具规则：CLAUDE.md、linter、CI。
Spec-driven Development	功能规格说明	规格说明从 What 派生。人类不再手动编写它们。
Vibe Coding	代码生成	只有当意图足够锐利时，Vibe Coding 才能发挥杠杆作用。

自动化流水线

在成熟的流水线中，人类只触及两个节点：顶部的意图和底部的判断。

  [Intent Document]     ← Human writes and maintains
         ↓
  [Spec Generation]     ← AI derives task list from Why/What/Not
         ↓
  [Implementation]      ← AI agents write code in parallel
         ↓
  [Verification]        ← AI cross-reviews, tests, lints
         ↓
  [Deployment]          ← CI/CD automates release
         ↓
  [Feedback]            ← User data flows back
         ↓
  [Learn & Decide]      ← Human evaluates, updates intent or kills

从意图到反馈之间的一切现在都可以自动化。技术栈、架构、任务分解、验证流程、部署节奏：都是选择。不可替代的人类工作是 Why、What、Not 和 Learnings。

.gitignore 思想实验

反复追问：什么不在 .gitignore 中？——仓库中有什么是无法重新生成的？

代码是输出物，就像 node_modules 一样——AI 可以重新生成它。测试可以从 What 派生。配置和基础设施是 AI 可以做出的选择。文档可以从意图派生。剥去所有可重新生成的东西，只剩一个文件：INTENT.md。

这不是隐喻。这是逻辑终点：唯一需要人类洞察力的产物就是意图本身。其他一切都是等待发生的抽象。

Intent 是收敛，不是声明

好的意图不是一次写成的。它是通过假设 → 构建 → 验证循环收敛而来的。Learnings 部分是这种收敛的引擎——它将失败的实验转化为资产，确保同样的死胡同不会被重复探索。

Intent Engineering 不是一种文档格式。它是一种通过迭代学习快速、安全、高效地找到目的地的纪律。收敛的旅程本身就是工程。

为什么有效

约束催生清晰。Why/What/Not 消除了人们隐藏的地方：路线图戏剧、架构表演、虚假的精确。如果你无法清晰地表述意图，你就没有准备好去构建。

AI 比你更擅长 How。它拥有比任何个人工程师更广泛的实现记忆。过度指定 How 会将解决方案限制在你的局部最优。

终止也是生产力。一个有文档记录的终止不是浪费；它是偿还的不确定性。一个死掉项目的 Learnings 往往比一个已发布项目的代码存活得更久。

Intent 精度可扩展。Why 中一句精准的话会传播到任务生成、审查、测试和部署。模糊的意图放大歧义；锐利的意图放大一致性。

开始使用

在项目根目录创建 INTENT.md，只写 Why、What、Not 和 Learnings。用 (?) 标记不确定的地方，直到证据消除它。

具体操作在快速开始指南中；纪律在于拒绝将 How 偷渡进文档。

→ 快速开始指南