アプリを開く

ガイド

プランを作り、図にし、エージェントに渡し、ファイルを持ち帰る。このページではその一連の流れを通して説明します。各 MCP ツールのリファレンスはドキュメントにあります。

1. プランを作る

プランは次のように整理されます。登録した時点で上の二つはすでに用意されています。

ワークスペース          メンバー、ロール、エージェントが接続に使うキー
  └─ プロジェクト       作っているもの一つと、そのプランが使う言葉
       └─ フォルダ      任意。フォルダの中にフォルダを置ける
            └─ プラン   グラフ一つ

アプリは一つの画面です。左側のサイドバーには最近があり、その下にワークスペースのすべてのプロジェクトが、フォルダやプランと一緒に並びます。プロジェクトやフォルダをクリックすると開閉し、プランをクリックすると右側に開きます。設定、メンバー、ゴミ箱も右側に開き、その間もサイドバーは横に表示されたままです。サイドバーの端をドラッグすると幅を広げられます。

プロジェクトやフォルダにポインターを合わせると、その行に新しいプランと新しいフォルダのアイコンが現れ、その中に作成できます。ツリーの一番下のアイコンでは、プラン、フォルダ、新しいプロジェクトを作成します。名前はツリーの中でそのまま入力します。プランやフォルダを別のフォルダへドラッグすればそこに移り、行のメニューか右クリックで、名前の変更、移動、共有、エクスポート、ゴミ箱への移動ができます。

最初から General というプロジェクトがあります。プランは文書ではなくグラフです。上から下へ書き進めるのではなく、要素を追加し、それらがどう関係するかを示していくことになります。

2. 図にする

ノードをいちばん手早く作るには、別のノードから始めます。ノードの右側の端子からドラッグして何もないキャンバスで離すと、離した場所に接続済みの新しいノードができ、すぐにタイトルを入力できます。Enter で確定し、Escape で取り消します。グループの中で離すと、新しいノードはそのグループに入ります。空のプランでは、タイトルブロックのノードを追加、またはキャンバスを右クリックして出るここにノードを追加で、同じように作れます。タイトルをダブルクリックすると、カードの上でそのまま名前を変えられます。

ノードをクリックすると右側にパネルが開くので、種類、ステータス、タグ、そして詳細を好きなだけ入力します。詳細はエクスポート時にそのノードの Markdown ファイルの本文になるので、きちんと書いておく価値があります。

新しく引いた線はすべてフローとして始まります。線をクリックして意味を選んでください。

  • フロー：システムが実際に動く向きです。この画面があのエンドポイントを呼び、そのエンドポイントがあのテーブルを読む、といった具合です。受け渡しのきっかけと、そこで運ばれるものを書くと、どちらも線の上に表示されます。応答は、逆向きのもう一本のフローとして表します。リストではなくシステムを描けるのは、この線です。
  • 包含：入れ物から、その中に入るものへ向かいます。エクスポート時にディレクトリになるのはこれで、グループをドラッグすると中身もすべて一緒に動きます。
  • 依存：先に存在していなければならないものを示します。何が何を呼ぶかとは別の話です。エクスポートでファイルに振られる番号の順序になります。
  • 関連：単なる関連付けで、構造は持ちません。

同じパネルで、線のきっかけや運ぶものを書いたり、線を削除したりできます。

自動レイアウトを押すと、グラフ全体を並べ直します。手でドラッグしたものは動かしません。自分で置いたノードはそれ以降固定され、固定を解除できるのは、もう一度そのノードを動かすあなただけです。

3. キャンバスを操作する

キャンバスは描画ツールと同じ感覚で操作できます。

  • 何もないキャンバスでドラッグすると選択範囲の枠が描かれ、枠に触れたノードがすべて選択されます。Shift を押しながらドラッグすると、いまの選択に追加されます。Shift、Ctrl、⌘ のいずれかを押しながらクリックすると、ノードを一つずつ選択に加えたり外したりできます。
  • 画面の移動は、マウスの中ボタンでドラッグするか、Space を押しながらドラッグするか、ホイールを回します。Shift とホイールで横に動きます。拡大・縮小は、Ctrl か ⌘ を押しながらホイールを回すか、ピンチ操作で行います。
  • 選択したものをドラッグすると、まとめて移動します。Backspace か Delete で削除します。
  • Alt/⌥ を押しながらドラッグすると、元のノードはそのままに、離した場所にコピーが置かれます。
  • Ctrl/⌘ + C、X、V でコピー、切り取り、貼り付けができます。貼り付けはポインターの位置に行われ、ほかのプランやタブにも貼り付けられます。Ctrl/⌘ + D はその場で複製します。

ドラッグ中は間隔も揃えてくれます。隣のノードとの距離が、すでにある二つのノードの間隔と同じになる位置に近づけるとそこに吸い付き、一致した間隔がピンクの寸法線で示されます。間隔が等しいノードを横一列か縦一列で選択すると、間隔ごとにハンドルが現れ、一つをドラッグするとすべての間隔が一度に変わります。間隔が揃っていない場合は、先に右クリックして間隔を揃えるを選んでください。

4. 詳細を書く

ノードの詳細はブロックエディタです。# とスペースで見出し（##、### はより小さな見出し）、- で箇条書き、1. で番号付きリスト、[] で ToDo、> で引用、バッククォート三つでコード、--- で区切り線になります。/ を入力するとすべてのブロックのメニューが開き、表、トグル、コールアウト（メモ、ヒント、注意、危険）も選べます。ブロックの横のハンドルをドラッグすると、ブロックを別の場所へ移せます。

同じ詳細に複数の人が同時に書き込め、書いている間は互いのカーソルが見えます。エージェントが書き込んだ内容も同じようにマージされます。キャンバスのカードにも見出しを含めて同じ内容が表示され、ToDo はカード上でそのままチェックできます。

エディタの外では、エクスポートもエージェントも詳細を Markdown として読みます。表は Markdown の表に、トグルは <details> ブロックに、コールアウトは Obsidian のコールアウトになるので、保管庫でも元の姿のまま開けます。

5. プロジェクトの言葉

種類とステータスはプロジェクトに属するので、同じプロジェクトのプランはすべて同じ言葉を使います。新しいプロジェクトには、ステータスとしてアイデア、計画済み、進行中、ブロック中、完了、中止が、種類として機能、タスク、決定、メモ、グループが最初から用意されています。ステータスの選択肢にはそれぞれの色が、種類の選択肢にはそれぞれの枠線が表示されます。どちらも最後に編集…があり、押すとプロジェクト設定のステータス・種類・タグが開きます。

そこで追加、名前や色の変更、並べ替えができます。各ステータスは未着手、進行中、ブロック中、完了、取り消しのいずれかの区分に属し、区分がそのステータスの働きを決めます。エージェントに次に何を勧めるか、どのフローを赤で描くか、何を進捗として数えるかは、区分によって決まります。種類ごとに枠線の形があり、作業として数えるかどうかも決められます。ステータスや種類を削除するとアーカイブされます。選択肢からは消えますが、それを使っているノードは誰かが変更するまでそのまま保持します。グループは組み込みのため削除できません。

タグはセレクトのように使えます。入力するとプロジェクトのタグが絞り込まれ、Enter を押すと強調表示されたタグが選ばれるか、一致するものがなければ固有の色を持つ新しいタグが作られます。入力欄が空のときに Backspace を押すと、最後のタグが外れます。タグのメニューからは色を変えたり、プロジェクトから削除したりできます。削除してもノードには名前が残ります。

6. エージェントを接続する

アカウント設定でエージェントを開いてキーを作成し、URL とキーを MCP クライアントに貼り付けます。マシンには何もインストールしません。サーバーには HTTP で接続します。正確な設定ブロックとツールの一覧はドキュメントにあります。

キーは、あなたがメンバーになっているすべての場所であなたとして動作します。そのため、ワークスペースがいくつあってもキーは一つで足ります。キーは一つのクライアントにだけ渡し、そのクライアントにちなんだ名前を付け、マシンの持ち主が変わるときには取り消してください。

7. エージェントに描かせる

エージェントにいつもどおりプランを書かせてから、それをキャンバスに載せるよう頼みます。エージェントは create_plan でプランを開きます。パスを渡せば、そのままフォルダに入れることもできます。

{
  "name": "create_plan",
  "arguments": {
    "title": "Billing rework",
    "folder": "Specs/Billing"
  }
}

そのあと apply_ops で描きます。まとめてアトミックに適用される一度の呼び出しで、開いているすべてのキャンバスに同時に反映されます。それ以降の変更もすべてこの呼び出しで行います。

{
  "name": "apply_ops",
  "arguments": {
    "planId": "…",
    "ops": [
      { "op": "upsert_node",
        "node": { "slug": "pricing-rules", "title": "Pricing rules" } },
      { "op": "upsert_node",
        "node": { "slug": "tax", "title": "Tax by region",
                  "kind": "decision", "status": "blocked" } },
      { "op": "upsert_edge",
        "edge": { "from": "tax", "to": "pricing-rules",
                  "carries": "rate table" } }
    ]
  }
}

何がないかに注目してください。座標です。エージェントは構造を宣言し、レイアウトはサーバーが行います。位置を求められた言語モデルは、誰も読みたくない図を描き、そのためにコンテキストまで消費するからです。また、ノードは識別子で指定されるので、同じ呼び出しを二度送っても二度目は何も変わりません。

エージェントもプロジェクトの言葉を使います。プランを読めばどんな種類とステータスがあるかがわかり、プロジェクトにない値を使うと、ある値の一覧とともに拒否されます。そのため、エージェントが勝手にステータスを作り出すことはありません。

エージェントに一つ頼んでおくとよいのは、見てわかる識別子にすることです。pricing-rules なら次のメッセージで名前として使えますが、node-7 ではそうはいきません。

8. ファイルを持ち帰る

エクスポートを押すと zip がダウンロードされます。包含関係はディレクトリに、依存の順序は各ファイル名の番号になり、どのノードも自分のフロントマターを持っています。そのため、このファイル一式はグラフの絵ではなく、グラフそのものを完全に記述しています。

plan-export.zip
├── README.md                 概要と目次
├── 01-foundation/            ほかのノードを含むノードはディレクトリになる
│   ├── README.md             …そのノード自身のメモはここに入る
│   ├── 01-ledger-schema.md
│   └── 02-pricing-rules.md   依存関係の順に番号が付く
├── 02-invoicing/
│   └── 01-render-pdf.md
├── plan.canvas               Obsidian で開ける（レイアウトもそのまま）
└── plan.json                 同じ内容を機械可読な形で

フォルダを Obsidian の保管庫に入れれば、plan.canvas が同じ図として開きます。あるいはソースコードの隣にコミットしておけば、エージェントが毎回それを読みます。それこそが、この取り組み全体の目的です。

依存関係に循環があってもエクスポートは止まりません。循環は毎回同じ方法で断ち切られ、README に報告されるので、同じプランからは常に同じファイルが出力されます。

9. ほかの人と作業する

編集はリアルタイムです。同じプランを開いている二人には互いの変更がその場で見え、同じノードの詳細に二人が同時に入力しても、上書きではなくマージされます。MCP を通して書き込むエージェントも、参加者の一人にすぎません。

共有で作成したリンクは、アカウントがなくても誰でも開いて読み、エクスポートできます。共有をやめれば、そのリンクは使えなくなります。

ワークスペースのメンバーでは、参加している人の一覧を確認し、ロール（オーナー、管理者、編集者、閲覧者）を変更し、招待リンクを作成できます。まだメール送信の機能がないので、リンクはご自身で送ってください。

10. 自分で動かす

スタック全体が AGPL-3.0 で、必要なのは Node と Postgres だけです。リポジトリをクローンし、.env.example をコピーして、Postgres を起動し、マイグレーションを適用してから実行します。正確なコマンドは README にあります。

設定はすべて環境変数で行います。また、Web アプリはサーバーのアドレスをビルド時ではなく実行時に読み込むので、一度ビルドしたバンドルがどの環境でも動きます。

まだできていないこと

いずれ出くわすことなので、率直に書いておきます。メールは一切送信されないため、招待は自分で相手に渡すリンクであり、メールアドレスは変更できません。ログインはメールアドレスとパスワードのみです。アプリ内に検索欄はなく、履歴にはすべての変更が残りますが、以前の版に戻すことはできません。

このうちどれかで困っているなら、GitHub Issuesで知らせてください。次に何を作るかに影響します。