ask-skills

Ask Skills

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

スキルの内容を説明したり、手順を省略するよう勧めたりする前に、そのスキルの SKILL.md を読んでください。ここにある概要は、あくまで概要を把握するためのものです。

フローとは、スキルを通る経路です。多くの経路は、1 つのメインフローに沿って進み、オンランプがそこに合流します。それ以外はすべて単独で使えます。

メインフロー：アイデアからリリースまで

最も多くの作業が進む経路です。アイデアを形にしたいときに使います。

1. /grill-with-docs は、インタビュー形式でアイデアを具体化します。作業ディレクトリで作業している場合は、ここから始めてください。学んだことを GLOSSARY.md と ADR に保存するため、状態を保持できます。（作業ディレクトリがない場合は、代わりに /grill-me を使ってください。詳しくは「単独で使えるスキル」を参照してください。どちらも同じ /grilling プリミティブを実行します。grill-with-docs は記録を残すので、記録を残せるリポジトリがある場合はこちらのほうが適しています。）

2. 分岐：会話の中ですべての疑問を解決できますか？ 実行可能な答え（状態、ビジネスロジック、実際に確認する必要がある UI）が必要な場合は、プロトタイプを経由します。どちらの方向にも /handoff を使ってつなぎます（プロトタイプは独自のディレクトリに置くため、まさに /handoff の用途です。「フェーズの境界」を参照してください）。

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

3. 分岐：複数のセッションにまたがる実装ですか？

   • はい → /to-spec でスレッドを仕様書にし、続いて /to-tickets でトレーサーバレット形式のチケットに分割します。各チケットには、ブロック関係を明記します。その後、次のどちらかの方法でチケットに取り組みます。
     • チケットごとに /implement を実行し、そのたびにコンテキストを /clear でクリアします。ローカルトラッカーでは、.scratch/<feature>/tickets/ の下にチケットごとに 1 つのファイルを置き、ブロッカーから手作業で進めます。実際のトラッカーでは、依存関係がネイティブのブロックリンクになるため、ブロッカーが完了したチケットを誰でも取得できます。各チケットは自己完結しているので、最後のチケットのコンテキストは破棄できます。（「単独で使えるスキル」にある /delegate-tickets は、チケットごとにサブエージェントを 1 つ割り当て、このループを無人で実行します。）
     • /implement-spec で仕様書全体を 1 回の実行で実装します。チケットをタスクグラフとして読み込み、準備ができたフロンティア全体で実装サブエージェントを並行して実行し、すべてを 1 つの統合ブランチに取り込み、その後 /review-axes を 1 回実行します。チケットごとに進行を管理するより、ビルド全体をオーケストレーションしたい場合に使ってください。
   • いいえ → このまま同じコンテキストウィンドウで /implement を実行します。

   どちらの方法でも、/implement は内部で /tdd を進め、各チケットを実装します。赤から緑へのスライスを 1 つずつ進め、テストスイート全体を実行し、独自の差分に対してリファクタリングを 1 回行います（テストスイートが失敗した場合は元に戻します）。最後に、差分を対象とする 2 軸レビュー（標準＋仕様）である /review-axes を実行し、現在のブランチに作業をコミットします。仕様書を作らず、具体的な振る舞いをテストファーストで実装したい場合は /tdd 単独で、固定された基準に照らしてブランチをレビューしたい場合は /review-axes 単独で使ってください。/review-axes は自分の作業を対象とし、従う標準と与えられた仕様書に照らして差分を評価します。他の人のマージリクエストをレビューするのは別の作業です。「単独で使えるスキル」の /review-mr を参照してください。

   作業をプルリクエストとして出すときは、/pr で本文を整えます。変更内容を示す最小限のビジュアル、正しく動作することを示す変更前後の証拠、そして一方向または双方向のドアに関する判断を盛り込みます。モデルから呼び出されるため、エージェントは PR を作成するたびにこれを使います。

4. /retro は、ビルドが完了したとき、特にうまくいかなかったときに、振り返りを行います。セッションを読み込み、コードではなくエージェントの環境に対する改善案を提示します。ナビゲーションの手がかり、自動チェック、/review-axes が適用するコーディング規約、ステアリングファイル、ツールなどが対象です。機械的なミスは決定論的なチェックに、判断が必要なことはコーディング規約にします。次のビルドは、よりよい環境で始められます。

5. /archive-feature は、すべての実装が終わったら一連の作業を締めくくります。ローカルトラッカーでは、ファイルを確認して、すべてのチケットがすべてのチェックボックスにチェックが入った状態で ready-for-human（または done）になっていることを検証し、概要テーブルを表示します。確認を1回行うと、仕様とチケットを done にし、機能全体を git mv で .scratch/ から docs/archive/<feature-slug>/ に移動します。機能名または仕様のパスを指定するか、何も指定しなければ .scratch/ 以下のすべての機能をスキャンします。不完全な機能は、名前を指定した場合に限りアーカイブされ、仕様には未対応の項目を記した日付付きのメモが追加されます。チェックボックスにチェックを入れることはありません。「実装が終わったけれど、次はどうすればいい？」と思ったときに使ってください。リモートトラッカーには適用されません。

コンテキストの整理

ステップ1〜3はひと続きのコンテキストウィンドウで行います（グリル、仕様、チケットが同じ思考に基づくよう、/to-tickets が終わるまで圧縮したりクリアしたりしないでください）。各 /implement はチケットを基に、新しいコンテキストで始めます。振り返りの対象となるセッション内で、クリアする前に /retro を実行します。クリアした後に実行する場合は、そのセッションのログを指定してください。

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

取りかかり方

作業を生み出し、メインフローに合流する開始状況です。

• 大規模で見通しの立たない取り組み：新規プロジェクト、または1つのセッションには大きすぎる大規模な機能開発 → /wayfinder。ここで最も認知負荷の高いフローです。現在地から目的地までの道筋がまだ見えないとき、イシュートラッカー上に意思決定チケットからなる共有マップを作成し、1つずつ解決していきます。見通しが立ち、道筋が明らかになるまで、成果物ではなく意思決定を生み出します。1つのセッションで扱えるアイデアを具体化するのが /grill-with-docs だとすれば、wayfinder は1つのセッションでは扱えないアイデアのためのものです。時間がかかり、内容も密になるため、そうしたケースに限って使い、範囲が明確な機能には使わないでください。

  マップが整理されたら、引き継ぎはしますが、ビルドはしません。メインフローの /to-spec に合流し、マップ上で関連付けられた意思決定を、実装可能な計画にまとめます。その後は通常どおり /to-tickets、/implement と進みます。マップからそのまま /implement に進むと、この整理の段階を飛ばして関連する詳細が失われます。取り組みが実際には小規模だとわかった場合に限り、直接 /implement に進んでください。また、途中にある調査チケットは /research サブエージェントを通じて並列に解決されるため、調査の読み込みに時間を取られません。

コードベースの健全性

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

• /improve-codebase-architecture：時間があるときにいつでも実行し、エージェントが扱いやすいコードベースを保ちます。深化できる機会を見つけます。候補を選ぶと、メインフローの /grill-with-docs に持ち込めるアイデアが生成されます。

• /tech-debt-map：より広範で淡々とした調査を、一度に1つのモジュールについて行います。プロジェクトがどのようにモジュールに分かれているかを特定し（プロジェクトが定義していない場合は、分割自体を定義します）、レビューするモジュールを選んでもらい、それぞれが最後に調査されてからどのくらい経ったかを示します。その後、そのモジュールをあらゆる観点（アーキテクチャ、コード、ビジネスルール、保守性、テスト容易性、パフォーマンス、セキュリティ）から調査し、技術的負債マップを作成します。そこには、影響範囲に対する効果で順位付けされた、証拠に裏付けられた所見が最大10件と、3段階の段階的な計画が記載されます。これは診断であり、リファクタリングではありません。コードは変更しませんが、コミット対象のレビュー索引 docs/tech-debt/README.md は維持するため、8か月間誰にも監査されていないモジュールも確認できます。/improve-codebase-architecture が1種類の問題を探し、単一の候補について掘り下げるセッションで終わるのに対して、こちらは数週間かけて取り組み、再実行して変化を確認するファイルで終わります。その項目は /to-spec、次に /to-tickets へと引き継がれます。影響範囲が「システム全体」に及ぶ項目は、代わりに /improve-codebase-architecture に引き継ぎます。

フェーズの境界

フェーズとは、セッション内の作業のまとまりです。掘り下げ、実装、QA などが該当します。2つのフェーズの境界では5つの選択肢があり、どれを選ぶかは、この全体像の中でも特に判断が難しい部分です。

• 続行：そのまま続けます。コストも損失もありません。
• /clear：次の作業にここでの内容が関係ない場合、ウィンドウを空にします。
• /handoff：持ち運び可能な Markdown ファイルを作成します。用途は限定されており、新しいハーネス、新しいディレクトリ、同僚、またはフェーズの途中でサイドタスクを分岐させる場合にのみ使います。得られるのは持ち運びやすさです。
• サブエージェント：範囲を厳密に限定したタスクを専用のウィンドウに送り、レポートを受け取ります。
• /compact：このコンテキストを圧縮し、その内容を引き継いだ新しいセッションを開始します。ツリーの先頭ではなく末端に置かれたデフォルトの選択肢です。

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

単独

メインフローとは完全に切り離されています。

• /grill-me：/grill-with-docsと同じ、容赦のないインタビューですが、ステートレスです。ローカルには何も保存せず、GLOSSARY.mdも作成しません。作業ディレクトリにいないとき（計画、設計、文章など、配下にリポジトリがないものを練り上げるとき）に使ってください。作業ディレクトリにいる場合は、代わりに/grill-with-docsを使ってください。同じインタビューを実行し、記録も残すため、こちらのほうが間違いなく優れています。
• /grilling：インタビューの基本部分そのものです。ラウンド、フロンティア、事実の確認はエージェントの役割で、決定するのはあなたです。/grill-meと/grill-with-docsは利用方法を名付けた2つのコマンドで、/wayfinderと/improve-codebase-architectureも内部でこれを実行します。ラッパーなしでインタビューしたい場合に限り、直接使ってください。
• /prototype：設計上の1つの疑問に答える、小規模で使い捨てのプログラムです。この状態モデルはしっくりくるか、あるいはこのUIはどのような見た目にすべきか、といった問いに答えます。「使い捨て」とはコードの書き方に関する制約であって、破棄する約束ではありません。答えは実際のコードに取り込まれ、プロトタイプ自体もmainから分岐したprototype/<name>ブランチに一次資料として残し、実装イシューから参照します。メインフローのステップ2にある寄り道ですが、設計上の疑問を机上で解決しにくいときはいつでも使ってください。
• /research：バックグラウンドエージェントに調査作業を委任します。エージェントは一次資料に基づいて質問を調査し、引用元を示したMarkdownファイルをリポジトリに残します。調査中も作業を続けられます。生成されたファイルは、メインフローの/grill-with-docsに持ち込むためのものです。調査は思考を支えますが、思考に取って代わるものではありません。
• /frontend-handoff：変更がリリースされ、別のチームがそれを利用するときに使います。仕様と差分を読み、貼り付け可能なブロックを出力します。そのブロックでは、フロントエンド開発者が最初に知る必要のあることとして、判定（必須の変更／推奨される変更／変更不要）を示します。/implementの後に実行し、会議なしで「フロントエンド側で何か対応が必要か」に答えます。引き継ぐのはコンテキストのみです。フロントエンドの作業自体は、相手のリポジトリで行う別タスクです。
• /to-questionnaire：行き詰まりの原因があなたの頭の中にもコードベースにもなく、他の人の中にあるとき、その人に記入してもらう質問票を作成します。これは/grill-meの逆です。対象についてあなたにインタビューする代わりに、質問票の送付先、つまり誰に送るのか、何を返してほしいのかを聞き、情報の不足箇所に合わせて質問を作ります。返ってきた回答は、/grill-with-docsまたは/to-specの素材になります。
• /wizard：インフラのプロビジョニング、認証情報やCIシークレットの設定、使い慣れていないサードパーティのダッシュボードでの操作、単発の移行や切り替えなど、人間にしかできない手順に使います。URLを1つずつ開き、値を取得して.envとGitHubシークレットに書き込む、対話型のbashスクリプトを生成します。これにより、毎回エージェントに説明し直す手順ではなくなります。モデルから呼び出されるため、エージェントは自分だけでは越えられない壁にぶつかった時点でこれを使います。エージェントが自分で実行できるなら、そうすべきです。これは人間が本当に介在する必要がある場面のためのものです。
• /wait-what：伝わらなかったメッセージを修正するためのコマンドです。会話の途中でも、他のスキルの実行中でも使えます。エージェントは、あなたに足りなかったコンテキストを補い、GLOSSARY.mdの用語を使って、先ほどの説明を平易な英語で言い直します。事後に使えるコマンドです。事前に防ぐのが/grill-with-docsで、早い段階で共通の言葉を合意しておくことが、そもそも専門用語が飛び交うのを防ぎます。
• /traduzir：エージェントの直近のメッセージを、読めるようにブラジルポルトガル語（pt-BR）に翻訳します。これは一度限りの読解補助です。メッセージ全体が翻訳され、コードとコマンドはそのまま残り、以降の返信は英語のままです。/wait-whatが伝わらなかったメッセージを説明し直すのに対して、こちらは読めなかったメッセージを翻訳します。
• /writing-for-agents：エージェントが読むドキュメント（スキル、AGENTS.md、参照先のドキュメントなど）の書き方に関するリファレンスです。
• /review-mr：他の人のマージリクエスト（GitLab、GitHub、または2つのローカルブランチ）を対象に、バグ、セキュリティ、パフォーマンス、設計をレビューします。タスクの受け入れ基準と照らし合わせて確認し、判定（承認または変更依頼、およびその理由）と指摘事項をローカルのMarkdownファイルに書き出します。判断を下す前に、差分からは分からない点を質問します。/review-axesがリポジトリの基準と仕様に照らして自分の差分を評価するのに対し、こちらは他の人の差分を評価します。
• /delegate-tickets：新しいサブエージェントを使い、チケットを1件ずつ、順番に実装するようオーケストレーションします。各チケットで/implementの実行が必須です。/to-ticketsでチケットが作成され、すべてのチケットのビルドを、各チケット間でコンテキストを/clearしながら無人で進めたいときに使ってください。実行対象はStandardとLightのチケットのみ（Sonnet、medium effort）です。Heavyのチケット、またはDifficulty:の行がないチケットがあると、実行を停止し、自分で対応することになります。また、人間の回答が必要な手順がある場合も、先に進まず停止します。

前提条件

• /setup-skills：最初のエンジニアリングフローを実行する前に実行し、課題トラッカー、トリアージ用ラベル、ドキュメントのレイアウト、破壊的な git 操作を防ぐプロジェクトの .claude/settings.json ルールを設定します。カスタム課題トラッカーにも対応しています。
• /setup-solid：リポジトリごとに一度だけ実行する任意の手順です。CLAUDE.md に SOLID セクションを書き込み、以降のすべてのフローに適用します。アーキテクチャレベルで言語に依存せず、ボーイスカウトルールの範囲に従います。SOLID は新しいコードと、変更によってすでに触れるコードに適用されるため、コードベースは変更のたびに改善されていきます。/improve-codebase-architecture が実施すべきリファクタリングを見つけるのに対し、こちらはコードをどう書くかの基準を定めます。