# Intent-First：让AI编程助手不再"猜"的轻量级代理工作流协议

> Intent-First 是一个极简的本地代理执行协议，通过"意图→规格→计划→执行→交付物"五阶段流程，让AI编码助手在获得明确目标后自主设计、规划和构建，同时在每个阶段之间等待人工审批，从根本上解决AI代理"猜测"需求的问题。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-07T10:45:12.000Z
- 最近活动: 2026-04-07T10:51:09.994Z
- 热度: 152.9
- 关键词: AI编程, 代理工作流, GitHub Copilot, Cursor, Claude Code, 意图驱动, 软件工程, 人机协作, AI工具
- 页面链接: https://www.zingnex.cn/forum/thread/intent-first-ai
- Canonical: https://www.zingnex.cn/forum/thread/intent-first-ai
- Markdown 来源: ingested_event

---

## 问题背景：AI编码助手的"猜测"困境\n\n随着GitHub Copilot、Cursor、Claude Code等AI编码工具的普及，开发者们逐渐发现一个新问题：AI代理虽然能生成代码，但往往是在"猜测"开发者的真实意图。当你说"帮我加个登录功能"，AI可能会直接开始编码，却忽略了关键问题——这个登录是OAuth还是本地账号？需要支持哪些第三方提供商？对安全性有什么具体要求？\n\n这种"猜测"导致的结果是大量返工。AI生成的代码可能偏离需求，开发者需要反复纠正，效率反而下降。更严重的是，当项目规模扩大、涉及多个文件修改时，缺乏结构化流程的AI编码很容易陷入混乱，造成技术债务累积。\n\n## 核心洞察：瓶颈不在代码生成，而在意图捕获\n\nIntent-First 项目的创始人提出了一个关键洞察：现代AI编码的瓶颈已经从"代码生成能力"转移到了"意图捕获质量"。如果AI代理清楚地知道你想要什么，并且你已经批准了设计方案和实施计划，那么代码执行反而成为最简单的环节。\n\n基于这一洞察，Intent-First 设计了一套轻量级协议，强制AI代理在进入下一阶段前必须获得明确的阶段成果和人工审批。这不是一个框架、不是SaaS产品、也不是团队协作工具——它只是一组Markdown文件和一个Bash脚本，用于保持代理在正确的轨道上。\n\n## 五阶段工作流：从模糊想法到可交付成果\n\nIntent-First 定义了一个清晰的五阶段流程，每个阶段都有明确的输入、输出和审批节点：\n\n### 第一阶段：意图（Intent）——人写目标\n\n这是整个流程的起点，由开发者亲自撰写。在 `.intent-first/workflows/{id}/s1_intent.md` 文件中，开发者需要描述"想要什么"以及"为什么想要"，但不应该描述"如何实现"。\n\n一个好的意图文档应该回答：\n- 这个功能解决什么问题？\n- 成功的标准是什么？\n- 有哪些约束条件？\n- 优先级如何？\n\n### 第二阶段：规格（Spec）——AI设计\n\n当开发者告诉AI代理 `/wf-spec {id}` 后，AI会根据意图文档起草技术规格。这包括架构设计、接口定义、数据模型、依赖分析等。规格文档完成后，开发者需要审阅并批准，才能进入下一阶段。\n\n### 第三阶段：计划（Plan）——AI细化\n\n获得规格批准后，AI代理通过 `/wf-plan {id}` 命令创建详细的实施计划。这包括任务分解、文件修改清单、测试策略、风险点识别等。同样，需要开发者批准后才能执行。\n\n### 第四阶段：执行（Execution）——AI构建\n\n有了锁定的计划，AI代理通过 `/wf-execution {id}` 开始实际编码。这一阶段AI会跟踪进度，实时更新状态，并严格按照已批准的计划执行。如果AI发现需要偏离计划，必须获得明确批准。\n\n### 第五阶段：交付物（Artifacts）——AI文档\n\n最后，通过 `/wf-artifacts {id}` 命令，AI代理总结项目成果，记录经验教训，创建维护文档。这为未来的类似任务积累了知识。\n\n## 关键机制：阶段锁定与完整性验证\n\nIntent-First 的核心机制之一是"阶段锁定"。当开发者批准某个阶段后，AI代理会自动运行 `intent-first lock {id} {stage}` 命令，将该阶段的Markdown文件设为只读（通过操作系统级的chmod）。这意味着：\n\n- 没有IDE插件、没有Git钩子、没有代理能在未经明确操作的情况下修改已批准的阶段\n- 已锁定的阶段是不可变的，如果需要修改，必须创建新的工作流\n- 这种设计有效防止了范围蔓延（scope creep）\n\n`intent-first validate` 命令可以检测流程完整性，当文件标记为"已批准—已锁定"但实际上仍可写入时会发出警告。这种机制既提供了结构化的护栏，又保持了轻量级——就像安全带一样，目的是在AI"失火"时将其拉回，而不是构建无法逾越的监狱围墙。\n\n## YOLO模式：速度与结构的平衡\n\n对于高置信度的工作，Intent-First 提供了YOLO模式（`/wf-yolo {id}`）。在这种模式下，AI代理仍然经历所有五个阶段，但会在置信度≥85%时自动批准，仅在置信度低于阈值时暂停等待人工介入。每个自动决策都会被标记为[YOLO-AUTO]并记录在交付物中。\n\n这种模式适合：\n- 开发者已经熟悉代码库和模式\n- 任务风险较低、范围明确\n- 需要快速迭代但仍希望保持一定结构\n\n## 工具生态与兼容性\n\nIntent-First 的安装脚本会自动检测多种AI编码工具并配置相应的规则文件位置：\n\n| 工具 | 规则文件位置 | 提示词位置 |\n|------|------------|-----------|\n| GitHub Copilot | `.github/copilot-instructions.md` | `.github/prompts/` |\n| Cursor | `.cursor/rules/intent-first.md` | `.cursor/prompts/` |\n| Claude Code | `CLAUDE.md` | `.claude/prompts/` |\n| Windsurf | `.windsurfrules` | `.windsurf/prompts/` |\n| Aider | `.aider.rules.md` | — |\n| Cline/Roo | `.clinerules` | — |\n\n这种设计体现了Intent-First的哲学：无供应商锁定、无迁移成本、无配置文件维护负担。它只是一组Markdown和Bash脚本——如果它不再有用，运行 `intent-first implode` 就能完全移除。\n\n## 使用场景：何时使用Intent-First\n\nIntent-First 特别适合以下场景：\n\n**推荐使用：**\n- 涉及3个以上文件修改的功能开发\n- 架构层面的变更或重构\n- 任何"直接做"可能导致返工的复杂任务\n- 需要明确决策记录和审计跟踪的项目\n\n**可以跳过：**\n- 单行修复或简单bug修复\n- 配置文件修改\n- 快速文档编辑\n\n工作流数据（存储在 `.intent-first/workflows/`）被设计为临时的、Git忽略的，类似于聊天记录——它结构化你的过程，但不需要版本控制。当你想保留特定成果时，可以显式提交。\n\n## 模型分层策略：不同阶段的推理深度\n\nIntent-First 建议根据阶段调整AI模型的选择：\n\n- **规格/计划阶段**：使用最强可用模型（如GPT-4、Claude 3.5 Sonnet），需要深度推理、架构权衡、精确签名设计\n- **执行阶段**：使用中等模型即可，主要是遵循已锁定的计划\n- **交付物阶段**：使用轻量级模型，主要是结构化文档生成\n\n这种分层策略既保证了关键决策的质量，又优化了成本效益。\n\n## 实践价值与方法论意义\n\nIntent-First 的价值不仅在于提供了一个具体工具，更在于它提出了一种与AI协作的新范式：\n\n1. **从对话式到协议式**：不再依赖连续的对话上下文，而是通过明确的阶段文档和审批点建立结构化协作\n\n2. **从猜测到明确**：通过强制开发者先写意图文档，确保AI代理在开始编码前就理解目标\n\n3. **从模糊到可追溯**：每个决策都有记录，每个阶段都有明确的批准者和时间戳\n\n4. **从耦合到解耦**：工作流数据与代码库解耦，允许灵活采用或弃用\n\n## 局限性与未来展望\n\nIntent-First 明确承认这不是零信任安全方案——技术上AI代理仍然可以运行 `intent-first unlock`。它的目的是添加结构性护栏，帮助代理按预期工作，而不是防御恶意代理。\n\n未来发展方向可能包括：\n- 更丰富的可视化工具，展示工作流依赖图\n- 子工作流（spawn）支持，处理复杂任务的分解\n- 与CI/CD管道的集成，实现自动化测试触发\n- 基于历史数据的模式推荐\n\n## 结语\n\nIntent-First 代表了AI辅助编程工具演进的一个重要方向：从单纯追求代码生成能力，转向建立人机协作的结构化流程。在这个AI技术快速迭代的时代，它 embrace 了"轻量级、易迭代"的哲学——你可以今天采用它，如果 landscape 变化，明天就可以替换它。毕竟，它只是Markdown和Bash。\n\n对于那些厌倦了与AI代理"猜谜"、希望建立更可预测开发流程的开发者来说，Intent-First 提供了一个立即可用、零依赖、零锁定的解决方案。