WingFoil

WingFoil

AI を活用したソフトウェア開発を決定論的にするために構築された、構造化されたハーネスです。

WingFoil は重要な課題を解決します。ソフトウェアプロジェクトが大きくなるにつれて、AI エージェントは一貫性と制御を失っていきます。コンテキストが散在し、規約にずれが生じ、あるセッションでの決定が次のセッションに引き継がれません。

WingFoil は、プロジェクトのメモリ、DNA、ディレクティブを、Git で管理される構造化形式に一元化します。これにより、人間と AI エージェントが共有する信頼できる情報源を提供します。

最初の例は、docs/examples/01-first-project に記録されています。記録元は docs/examples/01-first-project/demo.tape です。この例は自身の 結果を検証し、検証に失敗すると記録を停止します。そのため、WingFoil が例と一致しなくなると記録は失敗し、 古い状態のまま残ることはありません。

---

課題

AI エージェントを使ってソフトウェアを作成すると、次第に摩擦が大きくなります。

• コンテキストの崩壊： 大きなコンテキストウィンドウやコードベース全体のスキャンは、コストがかさみ、ノイズも増えます
• 規約のずれ： 毎回説明し直さない限り、エージェントは確立されたパターンを尊重しません
• 決定事項の散在： アーキテクチャ上の決定、パターン、制約は Slack や古いドキュメントにあり、あるいはどこにもありません
• ガバナンスの不足： 人間の開発者と AI エージェントに一貫してルールを適用する方法がありません

プロジェクトが大きくなるほど、シグナル対ノイズ比は悪化します。

---

解決策

WingFoil は、プロジェクトに対する構造化された信頼できるインターフェースを提供します。

• プロジェクトメモリ — 決定事項、成果物、ドメイン知識を Git で管理
• プロジェクト DNA — モジュール、技術スタック、規約の構造マップ
• プロジェクトディレクティブ — 人間とエージェントの双方が守る、役割ベースのルール
• ワークフロー状態管理 — プロジェクトの流れ、進捗、ブロッカーを一元的に追跡・伝達
• インタラクションレイヤー — 人間向けの CLI、エージェント向けの MCP

すべてを同期させることで、同じ仕様と設定から実行した場合に、同等のソフトウェアを生成できるようにします。これが、決定論指数が測定する目標です（下記の成功指標を参照）。

---

対象ユーザー

Alex、個人開発者
AI セッションのたびに、コンテキストを説明し直す必要があります。WingFoil は関連情報を数秒で読み込むため、セッション間でコンテキストが失われることはもうありません。

Sam、コードレビュアー
AI によるコードレビューを始めたものの、まだ自信がなく、全面的な開発を任せる段階ではありません。WingFoil を使えば、品質基準を適用し、自信がつくにつれて AI の利用範囲を段階的に広げられます。

Jordan、チーム開発者
テックリードがどの規約を定めたのかわからず、エージェントはチームのルールを無視します。WingFoil は、手動で絶えず更新しなくても、指示、決定、プロジェクトの状態について全員の認識を揃えます。

Morgan、テックリード
エージェントには新しいルールを勝手に作らせるのではなく、チームのルールに自動的に従わせる必要があります。WingFoil はガバナンスを一度定義すれば、すべてのエージェントに自動で読み込みます。また、進捗とブロッカーについてチーム全体の認識を揃えます。

Casey、マネージャー
決定事項と方法論を把握する必要があります。WingFoil は監査証跡、検索可能なナレッジベース、プロジェクト状態のリアルタイム追跡を提供します。

---

主な機能

5 つの柱 — 0.3 の状況

• ✓ プロジェクトメモリ — Git 管理のドキュメント（タスク、ADR、decision-logs、バグ、仕様など）を、種類ごとのステートマシン、承認ゲート、監査証跡とともに管理します（リリース済み：作成、検索、提出、承認、却下、非推奨化、履歴；0.3 の新機能：修正、保留、作業中の上限）
• ✓ プロジェクト DNA — モジュール、技術スタック、チームと役割、リソースパスの構造化設定です（リリース済み：表示、設定、追加、更新、削除）
• ✓ プロジェクト指示 — 役割ごとのルールです。init でインストールされる 6 つの組み込みテンプレート、独自のカスタム指示、役割の割り当てに対応します（0.2 でリリース済み）
• ✓ インタラクションレイヤー — 人間とエージェント向けの CLI、読み取り専用リソースと役割ごとに 1 つのプロンプトを提供するエージェント向け MCP サーバー（リリース済み）；agent execute は、コンテキストを組み立てて事前に確認したうえで、メモリ要素に対して Claude Code または Codex CLI を起動し、実行記録を残します（0.3 の新機能）
• ✓ ワークフロー状態管理 — ワークフローを開始、進行、終了できます。次のステップとその役割、進行中のワークフロー、承認者に振り分けられる承認、チェックポイントを管理します（0.3 の新機能）。WingFoil はステップを記録して振り分け、人やエージェントがそれを実行します

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>
エージェント	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 エージェント向け

• ✓ MCP サーバー（wingfoil mcp、stdio）— DNA、Memory、ワークフローを読み取り専用リソースとして提供します。ワークフローの状態は wingfoil://workflows/-/next および wingfoil://workflows/-/status として提供され、各ロールには、そのロールの指示を埋め込んだ <role>-session プロンプトが用意されています。element と state（コミット）を指定すると、プロンプトとリソース wingfoil://session/{role}/{element}/{state} が、その要素に関するエージェントの実行コンテキストを返します
• ✓ 設計上、読み取り専用 — MCP のインターフェースにはツールがありません。変更は CLI 経由で行い、承認は approver ロールを持つ人が担当します
• ✓ docs/agents.md — エージェントがリンクから読めるドキュメントとして、同じ情報をまとめています。WingFoil とは何か、従うべきルール、すべての MCP リソースとプロンプトに対応する CLI の操作方法が記載されています

---

はじめに

インストール

npm install -g wingfoil

これにより、wingfoil バイナリがインストールされます（Node.js 22.12+ が必要です）。次のコマンドで確認してください。

wingfoil --version

クイックスタート

git の ID（git config user.name / user.email）を設定したgit リポジトリのルートで、次のコマンドを実行します。

1. WingFoil を初期化する — .wingfoil/（DNA、Memory のスキーマとテンプレート、指示、ワークフロー）を生成してコミットします。

$ wingfoil init --template Scrum

組み込みのエージェントアダプター（claude-code、codex-cli）も .wingfoil/agents/ にインストールされます。

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 エージェントを接続する — Claude Code の場合は、リポジトリのルートに .mcp.json を追加します。

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

ドキュメント

ドキュメント	対象
ユーザーガイド	インストール、DNA／Memory／指示の設定、日常的な使い方、エージェント、CI を順を追って説明します
CLI リファレンス	すべてのコマンドについて、引数、出力、終了コード、作成されるコミットを説明します
例	主なシナリオを実行して確認できるスクリプトです
AI エージェント向けガイド	WingFoil プロジェクトで作業するためにエージェントが必要とする情報をまとめています
比較	エージェント用ルールファイル、仕様駆動開発ツール、コーディングエージェント、IDE と WingFoil を比較します
ケーススタディ	WingFoil が WingFoil を開発する方法と、v0.1 および v0.2 のリリース健全性の数値を紹介します
変更履歴	各リリースでの変更内容です

---

価値提案

対象 AI エージェントをすでに利用している開発者とチーム
WingFoil は、開発プロセスを決定論的にすることを目指して構築され、その実現度を測定します
方法 メモリ、規約、指示を一元管理し、すべての関係者間で同期を保ちます

成功指標：決定性インデックス

同一の仕様と WingFoil 設定を使い、異なる AI エージェントで独立して開発を実行した場合、実質的に同等のソフトウェアが生成され、チームメンバーとエージェント全員がワークフローの状態、進捗、整合性について共通認識を保てることが期待されます。これが WingFoil の評価基準となる目標であり、すでに備わっている性質ではありません。

実質的に同等とは、振る舞いが同等であることを意味します。どちらのコードベースも同じ受け入れ条件を満たします。インデックスは次の3つの要素で構成されます。

• 入力 — WingFoil が組み立てるコンテキストは、入力が同一なら同一です。テストによって保証されます。
• プロセスへの準拠 — 実行がワークフローに従ったかどうか（形式が正しいコミット、正当な遷移、フェーズ出力の存在、ロールの遵守）を、実行のたびに測定します。
• 結果の同等性 — 2つの実行で生成されたソフトウェアの振る舞いが同じかどうかです。コードを書くのはエージェントとモデルであるため、これは測定するものであり、保証するものではありません。

---

今後の予定

0.4 — インタラクションレイヤー + 仕上げ（計画中）：進行中のプロジェクトへの WingFoil の導入（init --mode infer、dna infer、memory import、audit）、エージェントが作業を提出するための MCP ツール、参照用ワークフローテンプレート（Scrum、Kanban、Lean Inception、Trunk-Based）、CLI のヘルプ、エラー、コンソール出力の改善です。

1.0 — MVP 完了、5 つの柱すべてを統合します。

その後は、初期導入者からのフィードバックに基づいて、セマンティック検索、MCP 以外の IDE 統合、通知の振り分け（メール、Slack）、複数プロジェクト管理に対応します。

---

リリースロードマップ

WingFoil は、1.0 ですべての柱を統合するまで、リリースごとに 1 つの柱を構築します。

リリース	焦点	ステータス
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	+ プロジェクトワークフロー：ワークフローの状態、承認の振り分け、エージェントの実行	✓ リリース済み（npm の [email protected]）
0.3.1	パッチ：既存要素のワークフローへの取り込み、名前変更されたフェーズへの追従、手動チェック、ガイド付き init ワークフロー	✓ リリース済み（npm の [email protected]）
0.4	+ インタラクションレイヤーの仕上げ	計画中
1.0	MVP 完了	計画中

ドッグフーディング： WingFoil 自体の開発は 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：人間（およびエージェント）は wingfoil コマンドを使用して、メモリ、DNA、ディレクティブを管理し、ワークフローを開始、追跡、終了し、要素に対するエージェントを起動します
• MCP サーバー：エージェントは Model Context Protocol を介して接続し、メモリ／DNA を照会し、ディレクティブとその実行コンテキストを受け取り、ワークフロー定義、次のステップ、オープン中のワークフローを読み取ります
• Git バックエンド：すべての変更（メモリ、決定、ワークフローの状態）はバージョン管理され、監査できます
• 読み取り専用 MCP：MCP のインターフェースは読み取り専用です。状態の変更は CLI を介して行い、承認は approver ロールを持つ人間が行います
• ワークフローの同期：チームメンバーとエージェントは、リポジトリから推定される同じワークフローの状態（次のステップ、その役割、保留中の承認）を読み取ります

---

プロジェクトドキュメント

実装に着手する前に、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
バックログ	実装可能なタスク（インポート時点で、ストーリー 63 件 + 技術タスク 43 件）	106

すべての成果物は、docs/01_vision/07_sequencer.md に記載されたリスク順に、5 つのリリース波（v0.1 → v1.0）に割り当てられています。

---

ライセンス

MIT — オープンソースで、自由に利用できます。

---

コントリビューション

早期のフィードバックを歓迎します。GitHub Issue を開き、バグ報告または提案のフォームを利用してください。それぞれが Memory の要素（bug、decision-log、機能リクエスト用の change-proposal）として記録され、再度確認を求められることはありません。

COLLABORATION.md をご覧ください。コードではなく Memory アーティファクト（Bug / Decision-Log / Change-Proposal / ADR / Tech-Spec）を通じてコントリビューションする方法や、あなたの貢献から生成された AI 生成作業へのクレジットについて説明しています。全員が行動規範に従います。脆弱性は公開 Issue ではなく、SECURITY.md の説明に従って非公開で報告してください。

---

ご質問はありますか？

• GitHub Issues： Issue フォームからのバグ報告と提案
• ドキュメント： ユーザーガイドから始めてください。WingFoil 独自の仕様（ビジョン、USM · BDD · SARD、バックログ）は docs/ にあります
• コミュニティ： GitHub Discussions で質問や情報共有ができます

---

WingFoil：混沌ではなく決定性を目指し、AI 支援開発を統制します。