ask-utarn

Utarn に質問する

すべてのスキルを覚えているわけではないので、質問してください。

フローとは、スキルをたどる経路です。ほとんどの経路は1つのメインフローに沿って進み、2つのオンランプが合流します。それ以外は単独で使うか、下層で動作する語彙レイヤーです。

メインフロー：アイデア → リリース

ほとんどの作業がたどる経路です。アイデアがあり、それを形にしたいときに使います。

1. /grill-with-docs — インタビュー形式でアイデアを磨きます。作業ディレクトリで作業している場合は、いつでもここから始めてください。このスキルは状態を保持し、学んだ内容を CONTEXT.md と ADR に記録します。（作業ディレクトリがない場合は /grill-me を使います — スタンドアロンを参照してください。どちらも同じ /grilling プリミティブを実行します。grill-with-docs は記録を残すため、記録先となるリポジトリがある場合はこちらのほうが適しています。）技術的な判断が自分ではなくエージェントに委ねられていると感じる場合は、/grill-novice を優先してください。機能要件だけを平易な簡単な英語で尋ね、何かを書く前に技術的な前提をまとめて、あなたの承認を求めます。

2. 分岐 — 会話だけですべての疑問に決着をつけられますか？ 実行可能な答えが必要な質問（状態、ビジネスロジック、実際に見る必要がある UI など）がある場合は、プロトタイプを介して迂回します。プロトタイプは専用のディレクトリに置くため、両方向の橋渡しには /handoff を使います（これは /handoff の用途そのものです — フェーズの境界を参照してください）。

   • /handoff で引き継ぎ、次にそのファイルを使って新しいセッションを開始します。
   • /prototype で使い捨てコードを作り、質問に答えます。
   • 学んだことを /handoff で元に戻し、元のアイデアのスレッドから参照します。

3. 分岐 — 複数セッションにまたがる開発ですか？

   • はい → /to-spec でスレッドを仕様にまとめ、次に /to-tickets でトレーサー・バレットチケットに分割し、それぞれにブロック関係を明記します。ローカルトラッカーでは .scratch/<feature>/issues/ の下にチケットごとに1つのファイルを置き、手作業でブロッカー優先に進めます。実際のトラッカーでは、ブロック関係がネイティブのブロッキングリンクになるため、ブロッカーがすべて完了したチケットはどれでも着手できます。チケットごとに /implement を開始し、その間に /clear でコンテキストをクリアします。各チケットは自己完結しているため、最後のチケットのコンテキストは破棄できます。
   • いいえ → 同じコンテキストウィンドウ内で、ここから /implement を実行します。

   どちらの場合も、/implement は内部で /tdd を実行し、レッド・グリーンのスライスを1つずつ進めて各課題を実装します。その後、コミット前に /code-review を実行して、差分を「標準」と「仕様」の2つの軸でレビューします。完全な仕様なしで、具体的な動作をテストファーストで作りたい場合は /tdd 単独を使い、固定された基準に照らしてブランチや PR をレビューしたい場合は /code-review 単独を使ってください。

コンテキストの管理

ステップ1〜3は、途切れずに1つのコンテキストウィンドウ内で進めてください。/to-tickets が終わるまでは、コンテキストを圧縮したりクリアしたりしないでください。そうすることで、インタビュー、仕様、チケットがすべて同じ思考の積み重ねに基づいて作られます。その後、各 /implement は新しい状態から開始し、チケットをもとに作業します。

ここでの制限は**スマートゾーン**です。これは、モデルが依然として的確に推論できるウィンドウ（最先端モデルで約150kトークン）を指します。/to-tickets の前にセッションがこの範囲に近づいた場合は、劣化した状態で無理に続けないでください。最も近いフェーズの境界で /compact を実行してから続けます（フェーズの境界を参照してください）。

オンランプ

作業を生み出し、メインフローに合流する出発点です。

• バグや要望が積み上がっている → /triage。トリアージの役割に沿ってイシューを進め、エージェントがすぐに扱えるイシューを作成します。これを後から /implement が取り上げます。

  トリアージの対象は、自分が作成していないイシューのみです。バグ報告や新たに届いた機能リクエストなど、まだ整理されていないものが対象です。/to-tickets が作成したチケットはすでにエージェントが扱える状態なので、トリアージしないでください。

  整理されていない報告が別の公開トラッカーリポジトリに届く場合、つまり、ユーザーやテスターがリリース済み製品について報告し、コードは別の場所にある場合は、代わりに /bug-tracker でそのキューを処理します（Utarn 固有の追加機能を参照）。

• 何かが壊れている → /diagnosing-bugs。難しい問題に使います。一見しただけでは分からないバグ、断続的に発生する不安定なテスト、正常な状態が確認されていた二つの時点の間に入り込んだリグレッションなどです。厳密なフィードバックループ、つまり、このバグですでに失敗する一つのコマンドを用意するまでは、原因の推測を拒みます。その後、リグレッションテストを追加して修正します。事後分析の結果、バグを封じ込める適切な境界がないことが真の問題だと分かった場合は、/improve-codebase-architecture に引き継ぎます。

• 途方もなく大きく、先が見えない取り組み――新規プロジェクトや大規模な機能開発など、1回のセッションでは大きすぎるもの → ここで最も認知負荷の高いフローである /wayfinder。現在地から目的地までの道筋がまだ見えていないとき、課題トラッカー上に意思決定チケットの共有マップを作成し、一つずつ解決します。作るのは成果物ではなく決定事項です。霧が晴れ、道筋が明確になるまで続けます。/grill-with-docs は1回のセッションで扱えるアイデアを深めるのに対し、wayfinder は1回のセッションでは扱えないアイデア向けです。時間がかかり、情報量も多いため、まさにそのような場合に限って使い、範囲が明確な機能には使わないでください。

  マップが明確になったら、引き継ぐだけで、実装はしません。/to-spec でメインフローに合流し、マップ内で関連づけられた決定事項を、実装可能な計画にまとめます。その後は通常どおり /to-tickets、/implement と進めます。マップから直接 /implement に進むと、この整理の段階が省かれ、関連づけられた詳細が失われます。取り組みが実際には小規模だと分かった場合に限り、直接 /implement に進んでください。

コードベースの健全性

機能開発ではなく、保守作業です。

• /improve-codebase-architecture — コードベースをエージェントが扱いやすい状態に保つため、時間が空いたときにいつでも実行してください。改善の機会を提示し、その中から選ぶと、メインフローで /grill-with-docs に持ち込めるアイデアが生まれます。候補を見つけるのが調査であり、選んだ候補を設計する作業台が、以下の /codebase-design です。

その下にある用語体系

他のスキルの下で実行される、モデルが呼び出す二つのリファレンスです。それぞれの用語体系の唯一の信頼できる情報源です。問題がプロセスではなく言葉にあるときは直接使うか、上記のスキルから呼び出させてください。

• /domain-modeling — プロジェクトのドメイン用語を明確にします。曖昧な用語を問い直す、複数の意味を持つ単語（3つの役割を担う「account」など）を整理する、変更が難しい決定をADRとして記録するといった作業を行います。CONTEXT.md を明確な用語集に保つために、/grill-with-docs が主に用いる規律です。
• /codebase-design — モジュールの形状を設計するための、ディープモジュールの用語体系（module、interface、depth、seam、adapter、leverage、locality）です。適切な境界に、小さなインターフェースを介して多くの振る舞いを集約します。/tdd と /improve-codebase-architecture は、どちらもこの用語体系を使います。

フェーズの境界

フェーズとは、セッション内の作業のまとまりです。調査、実装、QA などが該当します。フェーズ間の境界では、5 つの選択肢があり、どれを選ぶかは、この全体図の中でもっとも判断が曖昧なところです。

• 続行 — そのまま続けます。コストはかからず、失うものもありません。
• /clear — 次の作業にここでの情報が何も関係しない場合に、ウィンドウを空にします。
• /handoff — 持ち運び可能な Markdown ファイルを書き出します。用途は限定されており、新しいハーネス、新しいディレクトリ、同僚、またはフェーズの途中でのサイドタスクの分岐にのみ使います。これによって得られるのは、持ち運びやすさです。
• サブエージェント — 範囲を厳密に限定したタスクを独自のウィンドウに割り当て、レポートを受け取ります。
• /compact — このコンテキストを圧縮し、それをもとに新しいセッションを開始します。最初に選ぶのではなく、選択ツリーの末尾にあるデフォルトです。

順序立てられたツリー、5 つの質問、各分岐の根拠、そして一次情報のコストを考えると、まず続行を選択肢から外すべき理由については、PHASE-BOUNDARIES.md をお読みください。判断するのは境界に達したときです。フェーズの途中では、続行するか、残りをサブエージェントに分割してください。

単独で使うもの

メインフローから完全に独立しています。

• /grill-me — /grill-with-docs と同じ容赦ないインタビューですが、ステートレスです。ローカルには何も保存せず、CONTEXT.md も作成しません。作業ディレクトリで作業していないときに使ってください。計画、設計、文章など、リポジトリが関係しないものを練り上げる場合です。作業ディレクトリにいるなら、代わりに /grill-with-docs を使ってください。同じインタビューを行い、記録も残すため、こちらのほうが明らかに優れています。
• /grilling — インタビューの基本機能そのものです。ラウンドやフロンティア、事実の確認はエージェントの担当で、決定するのはあなたです。/grill-me、/grill-with-docs、/grill-novice は、この機能を使うための3つの名前付き手段です。また、/triage、/wayfinder、/improve-codebase-architecture は内部でこれを実行します。ほかの機能に包まれていないインタビューをしたい場合に限り、直接使ってください。
• /resolving-merge-conflicts — 進行中のマージまたはリベースの競合を、ハンクごとに解決して作業を完了します。行を選ぶのではなく、双方の一次情報をたどって意図に基づき解決します。--abort は実行しません。単独で使うもので、どのフローにも含まれていません。すでに競合の解決中なら使ってください。
• /prototype — 1つの設計上の問いに答える、小さくて使い捨てのプログラムです。この状態モデルはしっくりくるか、あるいはこの UI はどのように見えるべきか、といった問いに答えます。使い捨てというのはコードの書き方に関する制約であり、破棄するという約束ではありません。答えは実際のコードに反映され、プロトタイプ自体も、実装イシューから参照された、main から分岐した prototype/<name> ブランチ上の一次情報として保持されます。メインフローのステップ2にある寄り道ですが、紙の上では決めにくい設計上の問いがあれば、いつでも使ってください。
• /research — バックグラウンドエージェントに調査作業を任せます。エージェントは一次情報に基づいて問いを調査し、引用元を明記した Markdown ファイルをリポジトリに残します。調査中も作業を続けられます。生成されるファイルは、/grill-with-docs でメインフローに持ち込むものです。調査は思考の材料であり、思考に取って代わるものではありません。
• /to-questionnaire — あなたの頭の中にもコードベースにもなく、他の誰かの中にある情報が作業の妨げになっているとき、その相手に記入してもらうための質問票を作成します。これは /grill-me の逆です。テーマについてあなたに質問する代わりに、送ることについて、つまり誰に送るのか、何を回答してもらう必要があるのかを確認し、情報の不足を補うための質問を作ります。返ってきた内容は、/grill-with-docs または /to-spec に活用できます。
• /wizard — インフラストラクチャのプロビジョニング、認証情報や CI シークレットの設定、使い慣れていないサードパーティのダッシュボードの操作、単発の移行や切り替えなど、人間にしかできない手順に使います。各 URL を開き、各値を受け取って .env と GitHub シークレットに書き込む、対話型の bash スクリプトを生成します。これにより、手順を毎回エージェントに説明し直す必要がなくなります。ユーザーが呼び出す機能なので、人間が実際に関与するときに入力してください。エージェントだけで実行できるなら、エージェントが実行するべきです。まだ in-progress/ の分類にあるため、プラグインには含まれていません。使いたい場合は、直接インストールしてください。
• /wait-what — メッセージが伝わらなかったときの軌道修正に使います。会話の途中や、ほかのスキルの実行中に使うと、エージェントは、あなたに不足していた背景情報を補い、CONTEXT.md の語彙を使って、今の説明を平易な英語で言い直します。事後に使える機能です。事前の対策は /grill-with-docs です。早い段階で共通の言葉をすり合わせておけば、専門用語がそもそも出てこなくなります。
• /teach — 現在のディレクトリを状態を保持する作業スペースとして使い、複数のセッションにわたって概念を学びます。
• /writing-for-agents — エージェントが読むドキュメント（スキル、AGENTS.md、参照先ドキュメント）の書き方に関するリファレンスです。

Utarn固有の追加機能

このフォークでは、上流のルーターでは振り分けられないスキルをいくつか保持しています。メインフローのスキルと重複する部分もありますが、それぞれに合わせて調整されたワークフローで引き続き利用できます。

• /to-prd — /to-specと同様ですが、PRD形式のドキュメントを作成します。PRDという用語をすでに使用しているリポジトリ向けに残しています。
• /to-issuesと/to-issues-yes — /to-ticketsと同様ですが、プラン／仕様／PRDを、個別に着手できる垂直スライスのIssueに分割します（/to-issues-yesは、トレーサーバレットIssueとしてプロジェクトのIssueトラッカーに直接公開します）。/to-ticketsより前のスキルです。以前のIssue分割動作を使いたい場合に利用してください。
• /to-tickets-yes — /to-ticketsの「はい」を前提とするバージョンです。ブロッキング関係を付けた同じトレーサーバレットチケットを作成しますが、承認のやり取りを省略し、設定済みのトラッカーに直接公開します。分割が定型的で、やり取りなしでも問題ない場合に利用してください。
• /to-spec-yes — /to-specの「はい」を前提とするバージョンです。同じ仕様の統合と公開を行いますが、提案した境界を確認せず、合意済みとして扱います。境界が定型的な場合（既存の境界、または自分ならそこに置く境界）に利用してください。仕様の「テストに関する決定」セクションには引き続き記録されるため、その前提は明示されます。
• /setup-utarn-skills-yes — /setup-utarn-skillsのデフォルト設定を前提とするバージョンです。リポジトリ自体からすべての選択肢（リモート→トラッカー、デフォルトのトリアージラベル、モノレポの兆候→ドキュメントのレイアウト）を導き出し、確認のやり取りなしで設定を書き込みます。デフォルトのままでよい新しいリポジトリで利用してください。3つの選択肢について意見を反映させたい場合や、Jira／Linearなどのカスタムトラッカーが必要な場合は、対話型の/setup-utarn-skillsを実行してください。
• /find-mismatch — 実行時に問題を引き起こすバグを探すことに特化したコードレビューで、fallowによるJS／TSの静的解析も行います。2軸の標準／仕様レビューではなく、不整合の検出と静的チェックを特に行いたい場合に、/code-reviewの代替として利用できます。
• /work-on-issues — GitHub／GitLabのIssueを順番に取得、実装、クローズします（一度に扱うメインIssueはPRD:／feat:で始まるもの1件です）。追跡対象のIssueについて、実装→レビュー→クローズのループを一貫して実行する、エンドツーエンドのIssue処理スキルです。
• **/bug-tracker``と/init-bug-tracker** — コードのない場所に寄せられた報告を扱う、公開トラッカー向けのスキルです。/init-bug-trackerは、状態、種類、優先度、検証に加え、リポジトリから導き出したarea:*ラベルを含む、トラッカーの完全なラベル体系を作成します。また、Issueフォームを用意し、## Agent skills設定にトラッカーを記録します。続いて/bug-trackerは、対応可能なキューを一度に1件ずつ処理します。添付ファイル付きの報告を調査・検証し、タグ付けと対応中への変更を行い、分離されたサブエージェントでIssueを解決します（work-on-issuesと同様です）。さらに、解決の概要を公開トラッカーに投稿し、解決済みとしてマークしてクローズします。/work-on-issuesおよび/triage`に対応する、公開トラッカー向けのスキルです。

前提条件

/setup-utarn-skills — 最初のエンジニアリングフローを実行する前に、他のスキルが前提とするIssueトラッカー、トリアージラベル、ドキュメントのレイアウトを設定するために実行してください。カスタムIssueトラッカーも使用できます。