wayfinder

漠然としたアイデアが生まれました。ひとつのエージェントセッションには大きすぎ、霧に包まれています。ここから目的地までの道筋は、まだ見えていません。Wayfinding は、目的地に向かって突き進むのではなく、そこまでの道を見つけることです。このスキルでは、リポジトリのイシュートラッカー上に共有マップとして道筋を描き、意思決定チケットにひとつずつ取り組みます。これらは、実行する作業を分割したものではなく、解決によって決定が下される問いです。道筋が明らかになるまで取り組みます。

目的地は取り組みごとに異なり、それを名付けることが道筋を描く最初の作業です。すべてのチケットの方向性が決まります。引き継いで反復する仕様書、計画を始める前に確定する決定事項、データ構造の移行のようにその場で行う変更などが考えられます。マップは分野を問いません。エンジニアリングの作業でも、コースのコンテンツでも、形に合うものであれば何でも対象になります。

計画し、実行しない

Wayfinder はデフォルトでは計画を行います。各チケットは決定事項をひとつ解決し、誰かが作業を始める前に決めることがなくなれば、マップは完成です。作業をそのまま実行したくなるのは、たいていマップの端まで到達し、引き継ぐ時期になった合図です。取り組みのNotesで例外を指定し、実行までマップに含めることもできますが、そうでなければ成果物ではなく決定事項を作成します。

名前で参照する

マップもチケットもすべてイシューであり、名前、つまりタイトルがあります。人が読むものすべて、説明文やマップの Decisions-so-far では、裸の ID、番号、スラッグではなく、その名前で参照してください。#42, #43, #44 の羅列では内容がわかりません。名前ならひと目でわかります。ID と URL がなくなるわけではありません。名前にリンクを付けますが、ID と URL は名前の中に含め、名前の代わりには使いません。

マップ

マップは、このリポジトリのイシュートラッカーにある wayfinder:map ラベル付きの単一のイシューで、正規の成果物です。そのチケットはマップの子イシューです。

マップは索引であり、情報の保管場所ではありません。下された決定を列挙し、詳細が記載されたチケットを示します。決定事項はひとつの場所、つまりそのチケットにのみ記載するため、マップでは内容を繰り返さず、要約してリンクするだけにします。

マップ、子チケット、ブロッキング、フロンティアクエリがどこに保存されるかは、トラッカーによって異なります。 リポジトリのエンジニア向けスキルの隣にある TRACKER.md を読み、その「Wayfinding operations」セクションで、このリポジトリにおける子イシュー、ブロッキングの関係、フロンティアクエリの表現方法を確認してください。TRACKER.md がない場合は、ユーザーから提供された情報、Git リモート、インストール済みかつ認証済みの CLI から、この実行に使うトラッカーを特定してください。どれでも特定できない場合は、ローカル Markdown トラッカーをデフォルトとして使用します。

エンジニア向けスキルのディレクトリはハーネスによって異なるため、glob で見つけてください。

ls skills/*-engineer/TRACKER.md */skills/*-engineer/TRACKER.md .*/skills/*-engineer/TRACKER.md 2>/dev/null

マップ本文

セッションごとに一度読み込む、マップ全体の概要版です。未解決のチケットは列挙しません。これらは未解決の子イシューであり、クエリで見つけます。

## Destination

<what reaching the end of this map looks like — the spec, decision, or change this effort is finding its way to. One or two lines; every session orients to it before choosing a ticket.>

## Notes

<domain; skills every session should consult; standing preferences for this effort>

## Decisions so far



- [<closed ticket title>](link) — <one-line gist of the answer>

## Not yet specified



## Out of scope

チケット

各チケットはマップの子イシューであり、トラッカーのイシュー ID がその識別子です。本文には、エージェントの 100K トークンの 1 セッションで扱える規模の質問を記載します。

## Question

<the decision or investigation this ticket resolves>

各チケットには wayfinder:<type> ラベルが付きます。値は research、prototype、grilling、task のいずれかです（チケットの種類を参照）。

3 種類では、ラベルによって HITL／AFK の軸が決まります。research は常に AFK、prototype と grilling は常に HITL です。例外は task です。どちらにもなり得るため、task チケットでは質問の下に **HITL** または **AFK** の行を記載して軸を示します。これがないと、トラッカーから軸を特定できず、後のセッションでチケットに人間が必要かどうか判断できません。

セッションは、作業を始める前に、マップを進める開発者をチケットに割り当てることでチケットを確保します。同時に進行する別のセッションがそのチケットを飛ばせるよう、割り当ては必ず最初に行います。割り当てられた人がそのまま確保者です。未割り当てのオープンチケットは未確保です。

ブロックには、トラッカーのネイティブな依存関係を使います。トラッカー独自の UI にフロンティアが視覚的に表示されるため、人間はマップを開かなくても着手可能なチケットを確認できます。ネイティブなブロック機能がないトラッカーに限り、本文の慣例で代用します。チケットをブロックするすべてのチケットがクローズされると、そのチケットはブロック解除済みになります。フロンティアとは、オープンで、ブロック解除済みかつ未確保の子チケット、つまり既知の範囲の端です。

回答は本文には含めず、解決時に記録します（マップに沿って作業するを参照）。チケットの解決中に作成したアセットは、イシューにリンクし、貼り付けないでください。

チケットの種類

各チケットは、本人の意見を述べる人間と一緒に取り組む「human in the loop（HITL）」か、エージェントだけで進める AFK のどちらかです。HITL チケットは、その場での対話を通じてのみ解決します。エージェントが人間の側まで代弁してはいけません（質問を投げかけるエージェントが自分で答えるのは、この原則に反します）。

• Research（AFK）：ドキュメント、サードパーティ API、ナレッジベースのようなローカルリソースを読み、意思決定に必要な事実を明らかにします。research スキルで解決します。ハーネスがサブエージェントに対応している場合はサブエージェントに割り当て、対応していない場合はインラインで実行します。現在の作業ディレクトリ外の知識が必要な場合に使います。
• Prototype（HITL）：議論への反応を引き出すため、低コストで粗く具体的な成果物を作って議論の解像度を高めます。概要、ラフ案、スタブ、または prototype スキルを使った UI／ロジックのコードなどが該当します。プロトタイプをアセットとしてリンクします。「どのように見えるべきか」「どのように動作するべきか」が重要な質問の場合に使います。
• Grilling（HITL）：対話です。これがデフォルトです。必ず grill-me スキルを呼び出し、進めながら分野固有の用語を明確に保ちます。ubiquitous-language の規律に従い、新しい概念が定まったらすぐに CONTEXT.md に名前を記載し、既存の用語と衝突する用語があれば必ず指摘します。
• Task（HITL または AFK）：_意思決定_を行う前に必要な手作業です。決めることも、プロトタイプを作ることも、調査することもありませんが、終わるまでは議論が進みません。API を評価できるようサービスに登録する、アクセス権を用意する、データの形を確認できるようデータを移動する、といった作業です。これは、意思決定ではなく実行を担う唯一の種類です。その役割は目的地を実現することではなく、意思決定を可能にすることにあります。エージェントだけで対応できる場合はエージェントが進め（AFK）、そうでなければ人間に正確なチェックリストを提示します（HITL）。作業の完了時に解決し、回答には実施内容と、後続チケットが依存する関連事実（認証情報の保存場所、新しい URL、行数など）を記録します。

戦場の霧

マップは_意図的に_不完全な状態にします。まだ見えていないものを描き込まないでください。進行中のチケットの先には戦場の霧があります。これから必要になりそうだとは分かるものの、まだ特定できない決定や調査の見通しです。未解決の問いに左右されているためです。チケットを解決すると、その先の霧が晴れ、仕様を定められるようになった項目が新しいチケットになります。目的地までの道筋が明らかになり、チケットがなくなるまで、一度に一つずつ進めます。

マップの未特定セクションには、そのぼんやりとした見通しを記録します。後で見直すべきだと考えられる問いや領域です。目的地へ_向かう_未発見の領域であり、ここにあるものはすべてスコープ内ですが、チケットにできるほど明確ではありません。見通せる範囲で、簡潔にも詳細にも書いてください。取り組みがどこへ向かっているのかを読む共同作業者への道しるべにもなります。

霧か、チケットか？ 判断基準は、今その問いを正確に述べられるかどうかです。今答えられるかどうかでは_ありません_。

• 問いがすでに明確ならチケットにします。作業がブロックされていて、まだ着手できない場合も同様です。
• まだそれほど明確に表現できないなら未特定にします。霧をチケット単位に細かく切り分けないでください。チケットよりも粒度が粗く、未発見の領域が見えてきたときに、一つの項目から複数のチケットが生まれることも、チケットが一つも生まれないこともあります。

未特定には、すでに決まったこと（これまでの決定）、すでに進行中のチケット、スコープ外のこと（次のセクション）は含めません。

スコープ外

霧は常に目的地へ_向かって_広がります。目的地によってスコープが定まるため、その先の作業はスコープ外です。霧ではないので、未特定にも含めません。マップに独立したスコープ外セクションを設け、_この_取り組みでは意識的に対象外とした作業を記録します。ここに分類するのは、明確さではなくスコープによります。

スコープ外の作業がチケットになることはありません。目的地で未発見の領域は尽きるため、再び対象になるのは目的地を描き直した場合だけです。その場合も、再開ではなく新たな取り組みとして扱います。

スコープ外と決めるのはスコープを定める行為であり、道のりの一歩ではありません。すでにあるチケットが目的地の先にあると判明した場合、つまりマップ作成時にスコープへ誤って含めていた場合や、解決によって明らかになった場合は、クローズします（クローズされたチケットは、未発見の領域の外にあることが明確です）。そしてスコープ外セクションに、その要旨とスコープ外である理由を一行で記し、クローズしたチケットへのリンクを付けます。実際にたどった道のりを記録するこれまでの決定には含めません。スコープの境界は、その道のりの一歩ではないからです。

呼び出し方法

3つのモードがあります。マップを作成とマップに沿って作業では、人の注意を必要としないAFKチケットを除き、1セッションで解決するチケットは1つまでです。ウルトラ・ウェイファインダーでは、HITLチケットは一切解決せず、割り当てて終了します。

未発見の領域を提示する

マップの作成でも作業でも、未発見の領域に取り組める段階に達します。そこで止めて選択肢を提示します。人に代わって選んではいけません。

未発見の領域にあるチケットをすべて名前で列挙し、それぞれの種類とHITLかAFKかを示したうえで、どれに取り組むか尋ねます。回答によってバッチが決まります。すべて、名前を指定したいくつか、あるいは件数です。人の注意とリソースには限りがあり、その上限はここからは分かりません。したがって、こちらが推測するのではなく、本人に決めてもらいます。

調査も含め、回答があるまで何も実行しません。尋ねずに調査を始めるのはコストが低く、通常は当然の選択です。だからこそ、それが予想外となる場面が一度でもあれば問題になります。

複数のHITLチケットをまとめて選ぶ回答だった場合は、ウルトラ・ウェイファインダーを使用します。

マップを描く

ユーザーは漠然としたアイデアをもとに呼び出します。

1. 目的地を決める。 grill-me セッションを実行し、ドメイン用語を磨きながら、このマップがどこを目指すのか――仕様、決定、変更――を明確にします。目的地によって範囲が定まるため、最初に決めます。
2. 未踏の領域をマップする。 今度は幅優先で再び質問します。1つの話題を深掘りするのではなく、領域全体に視野を広げ、未決定の事項と今すぐ取れる最初の手順を洗い出します。ここで不明点が何も見つからなければ――目的地までの道筋がすでに明確で、全行程が1回のセッションで収まるなら――マップは必要ありません。そこで止め、どのように進めたいかをユーザーに尋ねます。
3. マップを作成する（ラベルは wayfinder:map）。Destination と Notes を記入し、Decisions-so-far は空にして、不明点をNot yet specifiedに書き出します。
4. 今すぐ仕様を決められるチケットを作成する。マップの子イシューとして作成し、その後、2回目のパスでブロック関係を設定します（チケット同士が参照し合うには、先に ID が必要です）。設定すると、チケットが未踏の領域とブロック中の領域に整理されます。まだ仕様を決められない内容はすべて不明点、つまりNot yet specifiedセクションに残します。
5. 未踏の領域を提示する（前述）。自分で何かを実行するのではなく、回答を待ちます。回答に基づいて行動します。AFK チケットはここでサブエージェントとして実行します。research チケットは research スキルを使い、チケットからのコンテキストポインターを添えて、一時的な research/<name> ブランチに調査結果を記録します。HITL チケットは Ultra wayfinder に従い、ピアセッションとして進めます。
6. 停止します。マップ作成は1回のセッションで完了する作業であり、HITL チケットを単独で解決することはありません。

マップに沿って進める

ユーザーはマップ（URL または番号）を指定して呼び出します。チケットは任意です。チケットが指定されていない場合は、渡されたチケットではなく、未踏の領域から次に何をするかを判断します。

1. マップを読み込みます。すべてのチケット本文ではなく、概要を確認します。
2. 最初に照合します。 Decisions-so-far にポインターがないままクローズされた子チケットは、ディスパッチされたセッションによって解決されたものです。そうしたセッションにはマップへの書き込みが認められていません（Ultra wayfinder を参照）。各チケットの解決コメントをインデックスに反映し、そこから提案された不明点の具体化や範囲外との判定にも対応します。マップはインデックスです。照合されていないマップは、インデックスとして機能しなくなっています。
3. チケットを選びます。ユーザーがチケットを指定した場合は、それを使います。指定がなければ、未踏の領域を算出します。実行可能なチケットが1つなら、それを選びます。複数ある場合は、未踏の領域を提示します（前述）。ユーザーが複数の HITL チケットを選んだ場合は、Ultra wayfinder の対象となり、セッションごとに担当を決めるため、ここでの作業を続けず、そちらに進みます。それ以外の場合は、作業前にそのチケットを自分に割り当てて担当します。
4. チケットを解決します。必要に応じて詳細を確認します。関連するチケットやクローズ済みチケットの全文は必要に応じて取得し、## Notes ブロックに記載されたスキルを呼び出します。判断に迷ったら、grill-me を使います。
5. 解決内容を記録します。回答を解決コメントとして投稿し、イシューをクローズして、マップの Decisions-so-far にコンテキストポインターを追記します。ディスパッチされたセッションはコメントを残した時点で終了します。Ultra wayfinder を参照してください。
6. 新たに見つかったチケットを追加し（作成してから関連付けます）、回答によって仕様を決められるようになった不明点を具体化します。具体化した内容はそれぞれNot yet specifiedから削除し、新しいチケットとしてのみ存在するようにします。回答によって、チケット（このチケットまたは別のチケット）が目的地の範囲外だと判明した場合は、その道筋で解決するのではなく、範囲外と判定します。決定によってマップのほかの部分が無効になった場合は、それらのチケットを更新または削除します。ディスパッチされたセッションは、これらすべてを解決コメントで提案するにとどめます。
7. 不明点の解消によって未踏の領域が広がった場合は、セッションが終わる前にそれを提示します（前述）。

ユーザーはブロックされていないチケットを並行して実行する場合があるため、ほかのセッションも同時にトラッカーを編集していることを想定してください。

道筋が明確になったら、マップは完了です。次に to-tickets を実行するようユーザーに伝えます。これにより、実際のビルドをトレーサーバレット形式のスライスに分割します。この操作はユーザー自身が呼び出すものであり、あなたが呼び出すものではありません。

Ultra wayfinder — フロンティアを並行して進める

必要な機能： 人間が直接参加して会話できる兄弟エージェントセッションをディスパッチできるハーネス。サブエージェントでは代用できません。理由は以下のとおりです。ハーネスにこの機能がなければ、Ultra は利用できないことを率直に伝え、フロンティアを順番に進めてください。

ユーザーはマップと、必要に応じて取り組むチケットを添えて、「ultra wayfinder」（または「ultrawayfinder」）と入力して実行します。名前が指定されたチケットがバッチです。名前が指定されていない場合も、まずフロンティアを提示します。Ultra の実行は作業の進め方を指定するものであり、作業量を自分で選んでよいという意味ではありません。Offer the frontier を通じて Ultra に到達した場合、バッチは人間がそこで選んだ内容で確定しています。

サブエージェントではなく、兄弟エージェントセッションを使います。 サブエージェントは HITL チケットを処理できません。詰めの質問が必要なチケットやプロトタイプのチケットは、人間とのリアルタイムのやり取りを通じてのみ解決でき、サブエージェントには人間とやり取りする手段がありません。そのため、自分自身の質問に自分で答え、人間の判断が一切含まれないまま解決内容を投稿することになります。ディスパッチされた兄弟エージェントセッションは入力を待機し、人間が一つずつ参加します。これにより、希少なリソースである人間の 注意 を順番に使いながら、すべてのチケットのコンテキストを読み込んで準備しておく、並行した 状態 を実現できます。

セッションが人間の代わりになれるかどうかを決めるのはこの軸です。チケットの種類ではなく、HITL／AFK の軸でディスパッチしてください。

• HITL（grilling、prototype、HITL とマークされた task）→ チケットごとに兄弟エージェントセッションを 1 つ。
• AFK（research、エージェントが単独で進める task）→ このセッション内でサブエージェントを使います。参加する人間がいないため、兄弟エージェントセッションを使ってもメリットはなく、コンテキストの切り替えが増えるだけです。

1. マップを読み込み、フロンティアを計算します。
2. 人間が選んだセットを使います。依頼された範囲を超えて作業を振り分けてはいけません。
3. 各 HITL チケットを、以下のブリーフを添えて兄弟エージェントセッションにディスパッチします。
4. 各 AFK チケットはここでサブエージェントに処理させ、その解決内容を自分でマップに記録します。
5. ディスパッチした各セッションがチケットを取得したことを確認します。最初の書き込み前にセッションが終了すると、チケットは未取得のままフロンティアに戻りますが、人間には処理中だと伝わっています。並行処理を守る仕組みは取得だけなので、確認するのはセッションではなく取得状況です。取得されていないものは再ディスパッチするか、報告してください。
6. ディスパッチしたセットを名前で報告し、その後は停止します。

要点

ディスパッチされた各セッションには、次の4つを必ず伝えます。最初の項目が、残りを安全に進めるための鍵です。

1. あなたはディスパッチされたセッションです。 必ずこの言葉で伝えてください。セッションは Work through the map に進みますが、そうしないとステップ5に文字どおり従ってマップを書き換えてしまいます。それは絶対に避けなければなりません。
2. コマンド形式で wayfinder を明示的に呼び出します。 このスキルでは disable-model-invocation が設定されているため、wayfinder を使うように伝えるだけでは、セッションはその内容をまったく読み込みません。claim-first も含まれます。この失敗は目に見えません。セッションは開始して待機し、問題がないように見えます。（epic-runner も同じ方法で独自にディスパッチを処理します。）
3. 作業を始める前に、まずチケットを取得します。 すでに割り当て済みなら、先に誰かが着手しています。作業せずに中止し、報告してください。
4. マップとチケット、そして人間の判断が本当に必要となる最初の質問まで進めたら、そこで止まって待ちます。

ディスパッチされたセッションは、マップ本文を編集してはいけません。 通常どおり解決コメントを投稿し、課題をクローズしますが、Decisions-so-far への追記は、ロック機構のない共有ドキュメントへの読み取り・変更・書き込み操作です。そのため、同時に作業するセッションがあると、互いの変更を気づかれないまま上書きしてしまいます。そこで、セッションは提案を行います。解決内容、fog の段階付け、スコープ外の判断はすべて解決コメントに記録し、次にマップを作業するセッションが照合ステップで反映します。

AFK サブエージェントは例外です。ディスパッチしたセッションの内部で実行されるため、書き込みを行うのは常に1つのセッションだけとなり、その解決内容は通常どおり記録できます。

Claude Code でのバインディング例：

claude --bg -n "wf-<number>-<short-slug>" "/wayfinder <map> <ticket> — you are a dispatched session; <rest of brief>"

常に -n を渡してください。これがないと、セッションの行タイトルにプロンプトの生テキストが表示され、一覧が読みにくくなります。claude agents --json で確認してください。ディスパッチされたセッションは、Agent View で "Needs input" の状態で待機します（空のプロンプトで ← を押すか、claude agents を実行）。人間は → でセッションに接続します。

---

mattpocock/skills からの翻案、MIT © 2026 Matt Pocock。このファイルをコピーする場合は、この行を残してください。