WingFoil

WingFoil

用于 AI 辅助软件开发的结构化框架，旨在让开发过程具有确定性。

WingFoil 解决了一个关键问题：随着软件项目不断发展，AI Agent 会逐渐失去一致性和控制力。上下文变得分散，约定逐渐偏移，在一次会话中做出的决定也无法延续到下一次会话。

WingFoil 以结构化、由 Git 支持的格式集中管理项目的记忆、DNA 和指令，让人类和 AI Agent 共享一个唯一可信来源。

第一个示例，见 docs/examples/01-first-project，录制自 docs/examples/01-first-project/demo.tape。该示例会检查自身结果；如果检查失败，录制就会停止。因此，如果 WingFoil 的行为不再符合示例，录制会失败，而不是过时。

---

问题

使用 AI Agent 编写软件时，你会面临日益增加的阻碍：

• 上下文坍塌： 大型上下文窗口和完整代码库扫描会变得昂贵且充斥噪声
• 约定偏移： 除非每次会话都重新解释，否则 Agent 不会遵循既定模式
• 决策分散： 架构决策、模式和约束散落在 Slack、旧文档中，或根本无处可寻
• 治理缺口： 无法在人工开发者和 AI Agent 之间一致地执行规则

项目越大，信噪比就越差。

---

解决方案

WingFoil 为项目提供一个结构化、权威的接口：

• 项目记忆 — 由 Git 支持的存储，用于保存决策、制品和领域知识
• 项目 DNA — 模块、技术栈和约定的结构图
• 项目指令 — 人类和 Agent 都会遵循的基于角色的规则
• 工作流状态管理 — 统一跟踪并传达项目流程、进度和阻碍
• 交互层 — 面向人类的 CLI，面向 Agent 的 MCP

这样可以让所有内容保持同步，使同一规范和配置的两次运行能够产出等效的软件：这正是确定性指数所衡量的目标（见下文的成功指标）。

---

适用人群

Alex，独立开发者
每次开启新的 AI 会话，都得重新解释上下文。WingFoil 可在几秒内加载相关信息，不再丢失会话间的上下文。

Sam，代码审查者
你刚开始尝试用 AI 做代码审查，但还没有信心让 AI 全面参与开发。WingFoil 可让你强制执行质量标准，并随着信心增长逐步扩大 AI 的使用范围。

Jordan，团队开发者
你不知道技术负责人制定了哪些规范，而 Agent 会忽略团队规则。WingFoil 可让所有人就指令、决策和项目状态保持一致，无需频繁手动更新。

Morgan，技术负责人
你需要 Agent 自动遵循团队规则，而不是自行编造规则。WingFoil 只需编码一次治理规则；每个 Agent 都会自动加载。它还能让整个团队同步进度和阻碍事项。

Casey，经理
你需要了解决策和方法。WingFoil 提供审计追踪、可查询的知识库，以及项目状态的实时跟踪。

---

主要功能

五大支柱 — 0.3 版状态

• ✓ 项目记忆 — 由 Git 管理的文档（任务、ADR、决策日志、缺陷、规范……），每种类型都有自己的状态机、审批关卡和审计追踪（已发布：创建、搜索、提交、批准、拒绝、弃用、历史记录；0.3 版新增：修订、搁置、进行中数量限制）
• ✓ 项目 DNA — 结构化配置：模块、技术栈、团队与角色、资源路径（已发布：显示、设置、添加、更新、移除）
• ✓ 项目指令 — 按角色划分的规则：init 会安装六种内置模板，还支持自定义指令和角色分配（0.2 版已发布）
• ✓ 交互层 — 面向人类和 Agent 的 CLI；面向 Agent 的 MCP 服务，提供只读资源，并为每个角色提供一个提示词（已发布）；agent execute 会在先汇集并检查上下文后，针对一个记忆条目启动 Claude Code 或 Codex CLI，并记录运行情况（0.3 版新增）
• ✓ 工作流状态管理 — 启动、推进和结束工作流：下一步及其角色、开放的工作流、路由给审批者的审批请求、检查点（0.3 版新增）。WingFoil 记录并路由各步骤；由人员和 Agent 执行这些步骤

CLI 概览

区域	命令
设置	wingfoil init [--template Scrum|Kanban] · wingfoil mcp
DNA	wingfoil dna show [section] · dna set <path> --value <v> · dna add · dna update · dna remove · wingfoil paths [category]
记忆	wingfoil memory add --type <t> --title <t> [--set <name>=<value>] · submit <id> · approve <id> --reason <r> · reject <id> --reason <r> · amend <id> --reason <r> · park <id> --reason <r> · deprecate <id> · history <id> · search [keyword]
指令	wingfoil directive create --name <n> · directive assign --directive <n> --role <r> · directive remove <n> · wingfoil directives list [--role <r>]
工作流	wingfoil workflow list · show <name> · start <name> · next · status · finalize · end · adopt <ref> · rekey <ref> · create <name> · remove <name>
Agent	wingfoil agent execute --element <type:id> | --next · agent list · agent show <run-id>

每条命令都接受 --format console|json|yaml，并以退出代码 0（成功）、1（拒绝）或 2（命令行错误）结束；除 init 外，每条会提交更改的命令都接受 --dry-run。完整详情请参阅：CLI 参考。

面向 AI Agent

• ✓ MCP 服务（wingfoil mcp，stdio）——DNA、Memory 和工作流以只读资源的形式提供；工作流状态可通过 wingfoil://workflows/-/next 和 wingfoil://workflows/-/status 获取；每个角色都有一个 <role>-session 提示词，其中包含该角色的指令；给定一个 element 和一个 state（提交），提示词以及资源 wingfoil://session/{role}/{element}/{state} 会返回该元素的 Agent 执行上下文
• ✓ 从设计上确保只读——MCP 接口不提供工具；变更通过 CLI 进行，审批由担任 approver 角色的人类负责
• ✓ docs/agents.md ——以文档形式提供相同的知识，Agent 可通过链接阅读：WingFoil 是什么、需要遵循的规则，以及每个 MCP 资源和提示词对应的 CLI 操作

---

开始使用

安装

npm install -g wingfoil

这会安装 wingfoil 二进制文件（需要 Node.js 22.12+）。验证安装：

wingfoil --version

快速开始

在配置了 Git 身份信息（git config user.name / user.email）的 Git 仓库根目录下运行。

1. 初始化 WingFoil——搭建 .wingfoil/（DNA、Memory 架构和模板、指令、工作流），并提交：

$ wingfoil init --template Scrum

它还会在 .wingfoil/agents/ 下安装内置的 Agent 适配器（claude-code、codex-cli）。

2. 为项目命名并将自己注册为审批人——审批需要由一名担任 approver 角色的团队成员进行，并使用你的 Git 邮箱：

$ wingfoil dna set project.name --value "My Project"
{
  "key": "project.name",
  "value": "My Project"
}
$ wingfoil dna add team.members --value "Ada Lovelace" --entry-email [email protected] --entry-roles approver,developer
{
  "key": "team.members",
  "value": "Ada Lovelace"
}

3. 创建任务、编写内容并提交：

$ wingfoil memory add --type task --title "My first task"
{
  "id": "task-001-my-first-task",
  "path": "docs/memory/task/task-001-my-first-task.md"
}
$ wingfoil memory submit task-001-my-first-task
{
  "id": "task-001-my-first-task",
  "path": "docs/memory/task/task-001-my-first-task.md",
  "from": "draft",
  "to": "pending"
}

（提交前，请在文件中编写任务正文——提交时会记录该内容。）

4. 批准任务——提交会记录批准人及批准原因：

$ wingfoil memory approve task-001-my-first-task --reason "Scope is clear."
{
  "id": "task-001-my-first-task",
  "path": "docs/memory/task/task-001-my-first-task.md",
  "from": "pending",
  "to": "approved"
}
$ git log -1 --format=%B
wf(task): approve task-001-my-first-task [pending → approved]

Approver: Ada Lovelace <[email protected]> (approver)
Reason: Scope is clear.

WingFoil-Version: 0.3.0 (6ca54978a01dc29c81e395d363efcdeac8a513fd)

5. 连接 AI Agent——对于 Claude Code，请在仓库根目录添加 .mcp.json：

{ "mcpServers": { "wingfoil": { "command": "wingfoil", "args": ["mcp"] } } }

文档

文档	适用对象
用户指南	分步说明：安装、配置 DNA / Memory / Directives、日常使用、Agent、CI
CLI 参考	所有命令：参数、输出、退出代码、写入的提交
示例	主要场景的可运行、自检脚本
AI Agent 指南	Agent 在 WingFoil 项目中运行所需的信息
对比	将 WingFoil 与 Agent 规则文件、规范驱动开发工具、编码 Agent 和 IDE 放在一起比较
案例研究	WingFoil 如何开发 WingFoil，以及 v0.1 和 v0.2 的发布健康度数据
变更日志	各版本的变更内容

---

价值主张

面向 已经在使用 AI Agent 的开发者和团队
WingFoil 旨在让开发过程变得 确定，并衡量其实现程度
方式 集中管理记忆、约定和指令——使其在所有参与者之间保持同步

成功指标：确定性指数

使用相同的规范和 WingFoil 配置，通过不同 AI Agent 独立运行两次开发，所产出的软件应基本等效；同时，所有团队成员和 Agent 都应对项目工作流状态、进度和一致性保持共同理解。这是衡量 WingFoil 的目标，而非它已经具备的属性。

基本等效 指 行为等效：两个代码库都通过相同的验收契约。该指数包含三个部分：

• 输入——对于相同的输入，WingFoil 组装的上下文完全一致：由测试保证。
• 流程遵循度——运行是否遵循其工作流（提交格式正确、转换合法、阶段输出齐全、角色得到遵守）：每次运行都会进行测量。
• 结果等效性——两次运行产出软件的行为是否相同：代码由 Agent 和模型编写，因此这一点只进行测量，不作保证。

---

后续计划

0.4 — 交互层 + 打磨（计划中）：在已启动的项目中采用 WingFoil（init --mode infer、dna infer、memory import、audit），提供 MCP 工具供 Agent 提交工作，支持参考工作流模板（Scrum、Kanban、Lean Inception、Trunk-Based），并打磨 CLI 帮助信息、错误提示和控制台输出。

1.0 — MVP 完成，集成全部五大支柱。

后续将根据早期采用者的反馈推出：语义搜索、MCP 之外的 IDE 集成、通知路由（电子邮件、Slack）和多项目管理。

---

发布路线图

WingFoil 每个版本完善一个支柱，直到在 1.0 中集成全部五个支柱。

版本	重点	状态
Lean Inception · 需求	产品愿景、USM · BDD · SARD · 待办列表	✓ 已完成
0.1	项目记忆 + DNA	✓ 已发布（未发布到 npm）
0.2	+ 项目指令、记忆审批、DNA 编辑、MCP 角色提示词	✓ 已发布（npm 上的 [email protected]）
0.2.2	补丁：在仓库根目录配置、分阶段发布到 npm、首次使用问题修复	✓ 已发布（npm 上的 [email protected]）
0.3	+ 项目工作流：工作流状态、审批路由、Agent 执行	✓ 已发布（npm 上的 [email protected]）
0.3.1	补丁：将现有元素纳入工作流、跟随重命名后的阶段、手动检查、引导式 init 工作流	✓ 已发布（npm 上的 [email protected]）
0.4	+ 打磨交互层	计划中
1.0	MVP 完成	计划中

自用验证： WingFoil 使用自身管理开发工作——其配置位于仓库根目录的 .wingfoil/ 中，记忆位于 docs/04_memory/ 中。在此处执行的每个会写入 wf() 提交的动词（add、submit、approve、reject、deprecate、amend、park），都由从检出代码编译的版本运行（npm run build，然后运行 node dist/cli.js <command>）；读取命令和在 .mcp.json 中注册的 MCP 服务则运行 WingFoil 已发布的固定版本（npm run -s wingfoil -- <command>），因此其响应与用户所用版本一致。请参阅 COLLABORATION.md。

---

架构概览

┌─────────────────────────────────────────────────┐
│  Humans (CLI)        Agents (MCP Client)        │
├─────────────────────────────────────────────────┤
│           WingFoil Harness                      │
│  ┌─────────────────────────────────────────┐    │
│  │ Memory | DNA | Directives | Workflow    │    │
│  └─────────────────────────────────────────┘    │
├─────────────────────────────────────────────────┤
│         Git Repository                          │
│  (versioning, audit trail, state history)       │
└─────────────────────────────────────────────────┘

• CLI：人类（和 Agent）使用 wingfoil 命令管理记忆、DNA 和指令，启动、跟进和结束工作流，并在某个元素上启动 Agent
• MCP 服务：Agent 通过模型上下文协议连接，以查询记忆/DNA、接收指令及其执行上下文，并读取工作流定义、下一步操作和未完成的工作流
• Git 后端：所有变更（记忆、决策、工作流状态）均进行版本控制且可审计
• 只读 MCP：MCP 接口为只读；状态变更通过 CLI 进行，审批由持有 approver 角色的人类负责
• 工作流同步：所有团队成员和 Agent 读取相同的工作流状态，该状态根据仓库推断得出：下一步操作、对应角色以及等待处理的审批

---

项目文档

在实施之前，产品已通过 docs/ 下的可追溯文档流程完成全面规格定义， 将 Lean Inception 愿景逐步细化为可直接实施的待办事项（规格下沉）：

docs/
├── 01_vision/         Lean Inception — product brief, vision, personas, 8 journeys, features, sequencer, MVP canvas
├── 02_requirements/   Specification downcast:
│   ├── 01_user_story_map/   User Story Map (Jeff Patton) — journey backbone + prioritized stories, incl. edge cases
│   ├── 02_bdd/              BDD suite (Gojko Adzic) — Gherkin scenarios per feature (happy + error/edge paths)
│   └── 03_sard/             System & Architecture Requirements (Volere) — NFRs with measurable Fit Criteria
└── 03_backlog/        Operational backlog — schema-validated JSON work items, partitioned by release wave

可追溯链。 每个条目都通过各层级追溯至源头： Backlog task → SARD requirement / BDD scenario → User Story → Journey → Vision feature.

MVP 范围一览：

层级	工件	数量
愿景	用户旅程	8
愿景	MVP 功能（5 个支柱 + 通知）	66
用户故事地图	旅程文件 · 边界情况 / 中断故事	7 · 15
BDD	Gherkin 功能文件 / 场景	66 / 267
SARD	架构与 NFR 要求（可衡量的适配标准）	46
Backlog	可直接实施的任务，按导入内容计（63 个故事 + 43 个技术任务）	106

所有工件均已安排在 5 个发布阶段（v0.1 → v1.0）中，并按风险排序，详见 docs/01_vision/07_sequencer.md。

---

许可证

MIT — 开源且可免费使用。

---

参与贡献

欢迎尽早反馈。请通过 Bug report 或 Proposal 表单提交 GitHub issue：每条反馈都会被记录为 Memory 元素（功能请求对应 bug、decision-log 或 change-proposal），无需再次询问你。

请参阅 COLLABORATION.md — 了解如何通过 Memory 工件（Bug / Decision-Log / Change-Proposal / ADR / Tech-Spec）而非代码参与贡献，以及如何注明基于你的贡献生成的 AI 创作内容。所有人都必须遵守行为准则；如需报告漏洞，请按照 SECURITY.md 中的说明私下报告，切勿在公开 issue 中披露。

---

有疑问？

• GitHub Issues： 通过 issue 表单提交 Bug 报告和提案
• 文档： 从用户指南开始；WingFoil 自身的规格说明（愿景、USM · BDD · SARD、Backlog）位于 docs/
• 社区： 在 GitHub Discussions 中提问和分享

---

WingFoil：引导 AI 辅助开发走向确定性，而非混乱。