# Forma：为AI编码代理生成结构化任务契约的开源框架

> Forma是一个开源项目，通过将团队工程实践转化为具体的任务契约，让AI编码代理在执行前声明如何遵循规则，并提供可验证的执行追踪。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-08T15:45:37.000Z
- 最近活动: 2026-06-08T15:52:45.908Z
- 热度: 159.9
- 关键词: AI代理, 代码生成, 工作流, 任务契约, Codex, Claude Code, 工程规范, 开源工具
- 页面链接: https://www.zingnex.cn/forum/thread/forma-ai
- Canonical: https://www.zingnex.cn/forum/thread/forma-ai
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：BeforeWave
- 来源平台：github
- 原始标题：forma
- 原始链接：https://github.com/BeforeWave/forma
- 来源发布时间/更新时间：2026-06-08T15:45:37Z

# Forma：为AI编码代理生成结构化任务契约的开源框架\n\n## 原作者与来源\n\n- **原作者/维护者**: BeforeWave（组织）\n- **来源平台**: GitHub\n- **原始标题**: forma\n- **原始链接**: https://github.com/BeforeWave/forma\n- **发布时间**: 2026年6月5日\n- **最后更新**: 2026年6月8日\n- **许可证**: Apache License 2.0\n\n---\n\n## 项目背景与动机\n\n随着AI编码代理（如Codex、Claude Code等）在软件开发中的广泛应用，一个核心问题逐渐浮现：如何让AI不仅"阅读"团队规则，而是真正"遵循"这些规则？传统的文档方式往往停留在"我会遵守规则"这样模糊的承诺，缺乏可验证性和可追溯性。\n\nForma项目正是针对这一痛点而生。它提出了一种全新的工作流范式——**Plan-First（先规划后执行）**，通过将团队的工程原则转化为具体的任务契约，让AI代理在执行前就明确声明它将如何工作，并在执行过程中提供可审查的证据链。\n\n---\n\n## 核心概念解析\n\n### 什么是任务契约？\n\nForma的核心创新在于将抽象的团队规则转化为具体的任务契约（Task Contract）。这不是一个模糊的"我会遵守规则"的承诺，也不是一个通用的执行计划，而是将团队的工程原则应用到当前具体任务中的产物。\n\n任务契约明确回答了以下关键问题：\n- **证据基础**：哪些代码、文档、测试用例为当前工作提供依据？\n- **边界定义**：哪些文件可以修改，哪些绝对不能触碰？\n- **验证机制**：哪些验证步骤必须在执行前后运行？\n- **证据记录**：执行结果和证明记录在哪里？\n- **停止条件**：在什么情况下AI代理必须暂停等待人工审查？\n\n### 三层架构设计\n\nForma采用了清晰的三层架构：\n\n1. **Profile（配置文件）**：团队工程原则的源头，以YAML格式存储在版本控制中，定义了团队的编码规范、审查流程、测试要求等。\n\n2. **Harness（工具包）**：根据Profile生成的实际工具集合，可以安装到Codex或Claude Code等AI编码代理中。工具包包含五个核心技能：\n   - `forma-plan`：在聊天中澄清目标、范围、约束和验收标准，不写入计划文件也不执行工作\n   - `forma-ground`：只读收集证据，从代码、文档、Issue、测试等来源获取信息\n   - `forma-lock`：将确定的方案物化为`plan.md`和`tasks.md`，锁定任务契约\n   - `forma-execute`：执行已接受的任务，运行验证，记录证明，需要审查时停止\n   - `forma-showhand`：在锁定的计划内继续执行剩余任务，直到遇到阻塞、验证失败或需要人工输入\n\n3. **Task Contract（任务契约）**：针对单个任务的承诺，记录在`plans/issue-<id>/`目录下，包含完整的执行计划和验证要求。\n\n---\n\n## 工作流程详解\n\n### 第一步：生成工具包\n\n开发者首先需要基于团队的Profile生成Codex技能包：\n\n```bash\nforma create-bundle \\\n  --target codex \\\n  --profile examples/profiles/sample-backend/sample-backend-go-github-issue-tracked.yaml \\\n  --output /tmp/backend-plan-first-codex\n\nforma verify /tmp/backend-plan-first-codex\n```\n\n验证通过后，即可安装到AI编码代理环境中。\n\n### 第二步：启动规划阶段\n\n在AI代理线程中，开发者可以这样启动：\n\n```\nUse forma-plan to plan this issue first.\n\nIssue:\n<你的任务描述>\n```\n\nAI代理会使用`forma-plan`技能来澄清任务目标、范围和约束条件，但不会立即执行任何实际工作。\n\n### 第三步：循证与锁定\n\n在规划完成后，使用`forma-ground`收集代码库中的相关证据，包括相关文件、测试用例、历史Issue等。当方案被接受后，使用`forma-lock`将其物化为具体的计划文件，正式锁定任务契约。\n\n### 第四步：执行与验证\n\n使用`forma-execute`执行单个已接受的任务，运行验证步骤，记录执行证明。如果需要继续执行多个任务，使用`forma-showhand`在锁定的计划框架内推进。\n\n---\n\n## 技术优势与价值\n\n### 1. 可追溯性\n\n传统AI编码代理的工作过程往往是一个"黑盒"，开发者难以了解AI是如何做出决策的。Forma通过将工作流分解为明确的阶段（规划、循证、锁定、执行、验证），每个阶段都有明确的输入输出和证据记录，大大提高了可追溯性。\n\n### 2. 可约束性\n\n通过Profile中定义的约束条件，团队可以精确控制AI代理的行为边界。例如，可以指定某些核心配置文件不允许修改，或者要求所有数据库变更必须通过特定的审查流程。\n\n### 3. 可审查性\n\n任务契约的物化形式（`plan.md`和`tasks.md`）为人工审查提供了明确的抓手。审查者可以在AI执行前审查计划，在执行后验证结果，而不是被动地接受AI的输出。\n\n### 4. 团队知识沉淀\n\nProfile作为团队工程原则的载体，可以随着项目演进不断更新和完善。新加入的开发者可以通过阅读Profile快速了解团队的工作方式，而AI代理也能基于最新的Profile调整其行为。\n\n---\n\n## 当前状态与发展路线\n\nForma目前仍处于早期阶段，项目团队明确指出了当前的局限性：Forma提供了更好的控制界面，但并不能保证AI代理一定会遵循生成的技能。实际的遵循程度仍然取决于底层模型和宿主环境。\n\n当前的重点方向包括：\n- 简化Plan-First代理工作流的安装流程\n- 降低项目特定工作流Profile的编写门槛\n- 改进生成工具包的验证机制\n- 增加展示真实规划、执行、验证和证明过程的示例\n\n值得一提的是，Forma项目本身也采用了Plan-First工作流进行开发，其源代码Profile位于`profiles/forma-self/`目录下，这体现了"吃自己的狗粮"（dogfooding）的理念。\n\n---\n\n## 实际应用场景\n\nForma特别适合以下场景：\n\n1. **大型团队协作**：当多个开发者使用AI编码代理时，统一的Profile可以确保所有人都遵循相同的工程标准。\n\n2. **关键系统开发**：对于不允许随意修改核心代码的项目，Forma的边界控制和验证机制提供了额外的安全保障。\n\n3. **合规性要求**：在需要详细记录开发过程和决策依据的场景中，Forma的证据收集和证明记录功能非常有价值。\n\n4. **知识传承**：通过将资深工程师的经验编码到Profile中，可以帮助新团队成员快速上手。\n\n---\n\n## 总结与展望\n\nForma代表了一种新的AI辅助开发范式——从"让AI自由发挥"转向"让AI在明确约束下工作"。这种转变不是对AI能力的限制，而是通过清晰的契约和验证机制，让AI的能力在可控的框架内得到更可靠的发挥。\n\n随着AI编码代理在软件开发中的渗透率不断提高，类似Forma这样的控制框架将变得越来越重要。它不仅是一个技术工具，更是一种工程思维的体现：在享受AI带来效率提升的同时，保持对质量和可控性的追求。\n\n对于希望将AI编码代理引入团队开发流程的技术负责人来说，Forma提供了一个值得探索的解决方案。