--- title: "AI Agent 開発ワークフロー実践｜25 個の skill でつなぐ本流の七ステップ | TauX" description: "mattpocock/skills の 25 個の skill を、繰り返し使える一本の開発ワークフローにつなぎます。grill、spec、tickets、implement、code-review の本流の七ステップ、四つのシナリオ、31 個の落とし穴と 14 日間の練習計画。" url: "https://taux.io/ja-JP/agent-dev-workflow" locale: "ja-JP" alternates: en-US: "https://taux.io/en-US/agent-dev-workflow" ko-KR: "https://taux.io/ko-KR/agent-dev-workflow" zh-Hans-CN: "https://taux.io/zh-Hans-CN/agent-dev-workflow" zh-Hant-TW: "https://taux.io/zh-Hant-TW/agent-dev-workflow" --- # Ship with skills, not vibes — 25 個の skill を一本の開発フローにつなぐ これはツールボックスの一覧ではなく、**一本の本流に何本かの合流路を足したもの**です。曖昧なアイデアから commit にたどり着くまで、各ステップで何を打つのか、どこで立ち止まるのか、そしてどこが静かに壊れるのかを扱います。 目次 * [01 三つの土台](https://taux.io/ja-JP/agent-dev-workflow#concepts) * [02 インストール](https://taux.io/ja-JP/agent-dev-workflow#install) * [03 前準備](https://taux.io/ja-JP/agent-dev-workflow#setup) * [04 全体の地図](https://taux.io/ja-JP/agent-dev-workflow#map) * [05 本流の七ステップ](https://taux.io/ja-JP/agent-dev-workflow#main-flow) * [06 状況別インデックス](https://taux.io/ja-JP/agent-dev-workflow#situations) * [07 四つのシナリオ](https://taux.io/ja-JP/agent-dev-workflow#scenarios) * [08 既知の落とし穴一覧](https://taux.io/ja-JP/agent-dev-workflow#pitfalls) * [09 自分の CLAUDE.md](https://taux.io/ja-JP/agent-dev-workflow#claude-md) * [10 コア用語](https://taux.io/ja-JP/agent-dev-workflow#vocabulary) * [11 七つのアンチパターン](https://taux.io/ja-JP/agent-dev-workflow#antipatterns) * [12 14 日プラン](https://taux.io/ja-JP/agent-dev-workflow#plan) * [13 1 ページのチートシート](https://taux.io/ja-JP/agent-dev-workflow#cheatsheet) * [出典](https://taux.io/ja-JP/agent-dev-workflow#source) 01 ## まず押さえる三つの土台 本ページが扱うのは [mattpocock/skills](https://github.com/mattpocock/skills)（MIT ライセンス）の **1.2.3** 版、公開済みの 25 個の skill です。**この skill 群は TauX の作品ではありません**。このチュートリアルが TauX のものです。以下の判定基準、落とし穴、シナリオはすべて、公式ドキュメントと issue を読み込んだうえで書き起こした日本語の教材であり、翻訳でも転載でもありません。 この三つを先に理解しておかないと、後に出てくる skill はどれも使い方を誤ります。 ### 一、誰が呼び出せるか これは、この pack **唯一の分類軸です**。 | | User-invoked | Model-invoked | | ----------------- | --------------------------------- | ------------------------------- | | 誰が呼び出せるか | 人間が名前を打つときだけ。他の skill から呼ぶこともできない | 自分で打ってもよく、agent が自分で判断して使うこともある | | 設定 | `disable-model-invocation: true` | どちらも設定しない | | description は誰向けか | 人間（slash command の一覧） | モデル（多数のトリガー文を含む） | | 位置づけ | **オーケストレーター**：フローの進み方を決める | **規律のライブラリ**：再利用できる方法論 | 実務上の三つの帰結 * ドキュメントに「次は `/implement`を実行」と書かれていたら、それは**あなた**に打てという意味です。agent が自動で続けてくれることはありません。 * harness は user-invoked skill をモデルに渡す一覧に入れないため、agent はこれらの skill が入っていないと「思い込む」ことがよくあります。**ちゃんと入っています。そのまま打てば動きます。** * 実際に何が入っているか確かめるには `.claude-plugin/plugin.json`を見てください。そこに書かれているものが正です。 ルール自体はこうです：user-invoked は model-invoked を呼べますが、**別の user-invoked を呼ぶことは決してできません**。 ### 二、四つの役割 本流 アイデアから ship までの決まった経路：`grill-with-docs` → `to-spec` → `to-tickets` → `implement` → `code-review`。 合流路 作業を生み出してから本流に合流させます：`triage`（他人から投げ込まれたもの）、`wayfinder`（一つの session に収まらないもの）、`improve-codebase-architecture`（定期点検から題材が出てくるもの）。 単独 いつでも呼び出し、使い終わったら離れます：`prototype`、`research`、`diagnosing-bugs`、`resolving-merge-conflicts`、`wizard`、`handoff`、`teach`、`to-questionnaire`、`wait-what`、`grill-me`。 語彙層 フローを持たず、正確な用語だけを提供し、他から借りられます：`codebase-design`（モジュールの形）、`domain-modeling`（ドメイン言語）、`writing-for-agents`（agent に読ませるドキュメント）、`grilling`（インタビューのプリミティブ）。 もっとも誤用されやすい語彙層 これらには**フローがありません**。たとえば `codebase-design` に「始めよう」と言うと、agent は独自のフローを勝手に発明し、頼んでもいないものをリファクタリングして 100k token を燃やします（登録済みの issue 449）。語彙層は「**driver skill が上、語彙層が下**」という形で走らせます。 ### 三、Phase boundary 一つの session の中の一区切りの作業を **phase**と呼びます（インタビュー、実装、QA…）。「自分の context をどうするか」という問いが**成立するのは二つの phase のあいだだけです**。phase の途中に選択肢はなく、続けるか、残りを subagent に投げるかしかありません。 | 優先順位 | 選択肢 | 選ぶタイミング | | ---- | -------- | ------------------------------------------------------------------------------------------------ | | 1 | 続ける | 次の phase がこの phase の生の発言を必要とする、または smart zone にまだ余裕がある場合。一次資料を保てる唯一の選択肢なので、**まずこれを排除してから**ほかを考える | | 2 | clear | この先の内容はすべて捨ててよい。いちばん安いが、判断を誤れば一方通行 | | 3 | handoff | 何かを**引っ越し**させる必要があるとき：harness を変える、ディレクトリを変える、同僚に渡す、途中で見つけた支線を切り出す | | 4 | subagent | タスクの範囲が十分に締まっていて、自分がいなくても走り切れる | | 5 | compact | どれにも当てはまらない。第一候補ではなく最後の受け皿だが、実務ではここに落ちることがいちばん多い | よく取り違えられるのが二つあります：`handoff` は「ウィンドウをまたぐ汎用の橋」ではありません。それが買うのは**可搬性だけです**。`compact` はツリーの底であって最初に手を出すものではありません。三つが守るものは違います——compact が守るのはあなたの**意図**、clear は何も守らず、handoff が守るのは仕事の**移動できる力**。そしてこの三つはいずれも、会話（一次資料）を要約（二次資料）に変えてしまいます。 02 ## インストール：二つの道から一つを選ぶ 二つのインストール方法は、二つの哲学を表します。**両方入れると、すべての skill が二重になります。** ルート A — 購読 ``` claude plugins install mattpocock-skills ``` または session 内で `/plugin install mattpocock-skills`と打ちます。すでに公式 marketplace にあるので、ソースを先に追加する必要はなく、更新も自動で届きます。**代償：読み取り専用で、手を入れられません。** ルート B — 手を入れられる版 ``` npx skills@latest add mattpocock/skills ``` どの skill を入れるか、どの agent に入れるかを聞かれます。**必ずチェックすべきなのは `setup-matt-pocock-skills`。**ファイルは「自分が所有する普通のファイル」として repo に書き込まれ、自由に変更できます。更新したいときは自分で `npx skills update`。 ルート B の落とし穴 手で書き換えた `SKILL.md` **は `npx skills update` によって上書きされます**。長期にわたって効かせたい振る舞いは、自分の `CLAUDE.md` / `AGENTS.md`（詳しくは [第 09 節](https://taux.io/ja-JP/agent-dev-workflow#claude-md)）に書くか、呼び出すたびに口に出して伝えてください——skill ファイルは書き換えないこと。 beta を試したい人へ ``` npx skills@latest add mattpocock/skills --skill= ``` plugin ではこれらは手に入りません。執筆時点の in-progress bucket には `loop-me`、`writing-beats`、`writing-fragments`、`writing-shape`、`claude-handoff`、`setup-ts-deep-modules`があります——ドキュメントページはなく、いつ変わっても消えてもおかしくありません。plugin に入らない misc bucket もあります：`git-guardrails-claude-code`（hook で危険な git コマンドを止める）、`setup-pre-commit`、`migrate-to-shoehorn`、`scaffold-exercises`。 03 ## 前準備、repo ごとに一度 `/setup-matt-pocock-skills` は、すべての engineering skill の**前提条件であり、フローの一ステップではありません**。 | 決定事項 | 先に提案してくるもの | 実際に聞かれる条件 | | ---------------- | -------------------------------------------- | --------------------------- | | Issue tracker | git remote から推測 | 毎回聞かれる——唯一の本物の選択 | | Triage の label | 標準の五つの名前をそのまま使う | triage を入れた場合のみ聞かれる | | Domain ドキュメントの配置 | 単一 context：root に `CONTEXT.md` と `docs/adr/` | monorepo のシグナルを検出したときだけ聞かれる | Tracker の四つの選択肢：**GitHub**（要 `gh`）、**GitLab**（要 `glab`）、**Local markdown**（`.scratch//`、remote すら不要）、**Other**（作業フローを説明する文章を自分で書く）。 Local markdown は**代替案ではなく一級市民です**：一人プロジェクトで remote がなくても完全にサポートされます。ただし GitHub を使うプロジェクトで local markdown を併用しないでください。両者は代替であって重ねるものではありません。 「Other」もプレースホルダーではありません——Jira、Linear、Azure DevOps が動くのはこれのおかげです：自分が作業フローを説明すると、その言葉をそのまま `docs/agents/issue-tracker.md`に書き込み、下流の skill はその文章どおりに動きます。だからこそ**この一式は GitHub に縛られていません**し、tracker を変えるために skill ファイルを書き換える必要も永遠にありません。 ### 必ず知っておきたい三つの落とし穴 一、label は作ってくれません `triage-labels.md` は「対照表」にすぎません。新しい GitHub repo にはそれらの label がそもそも存在せず、貼ろうとすると失敗します。まず自分で一度作ります： ``` gh label create needs-triage gh label create needs-info gh label create ready-for-agent gh label create ready-for-human gh label create wontfix gh label create bug gh label create enhancement ``` 使うのが `wayfinder` なら、あと五つも先に作っておく必要があります（`gh` は存在しない label に当たると即失敗します）：`wayfinder:map`、`wayfinder:grilling`、`wayfinder:prototype`、`wayfinder:research`、`wayfinder:task`。 二、見ているのはファイルの有無で、どの harness を使っているかではありません Codex を使っているのに repo に `CLAUDE.md`が残っていると、 `## Agent skills` の節が、Codex には永遠に読めない場所に書かれます。対処は手動で `AGENTS.md`へ移すか、 `AGENTS.md` を本体にして、`CLAUDE.md` にはそこを指す一行だけを置くことです。 三、skills を更新したらもう一度走らせてよい シードのテンプレートは版が変わるので、古い `issue-tracker.md` は新しい skill と噛み合わないことがあります。下流の挙動が怪しくなったら、走らせ直すのがいちばん安い直し方です。 ### 成功したかどうかの見分け方 * `docs/agents/issue-tracker.md` と `domain.md` が存在します（triage を入れていれば `triage-labels.md`） * 自分の harness **が本当に読む**指示ファイルに次の見出しがあります： `## Agent skills` * その後は `/to-tickets` が issue の置き場所を聞いてこなくなり、`/triage` は label を「貼る」のであって「発明」はしません * **skill ファイル自体は一文字も変わっていません。**setup が何かの `SKILL.md`を書き換えていたら、それは事故です 04 ## 25 個の skill、全体の地図 「ハード依存」の列が実戦での要点です——**依存が入っていなければ、skill は静かにただの即興へと退化します。** | Skill | 呼び出し元 | 役割 | 一言で | ハード依存 | | ----------------------------- | ----- | ------ | ------------------------------------------------------ | ------------------------ | | setup-matt-pocock-skills | User | 前準備 | repo ごとに一度実行。tracker、label、ドキュメント配置を設定 | — | | ask-matt | User | ルーター | 状況を書けば、どの並びを打てばよいかを教えてくれる | この pack の skill しか知らない | | grilling | Model | プリミティブ | ラウンドごとに進むインタビューエンジン。他の grilling はすべてこの上に建つ | — | | grill-me | User | 単独 | ステートレスなインタビュー。repo は不要、主題はコードでなくてよい | grilling | | grill-with-docs | User | 本流の先頭 | 同じインタビューに加えて codebase を読み `CONTEXT.md` と ADR を書く | grilling、domain-modeling | | wayfinder | User | 合流路 | 一つの session に収まらない大きな仕事を、decision チケットの地図として描く | tracker | | to-spec | User | 本流 | 会話を一つの spec に収束させて tracker に登録。もうインタビューはしない | tracker | | to-tickets | User | 本流 | spec または会話を tracer-bullet チケットに切り分け、ブロッキングエッジを宣言 | tracker | | implement | User | 本流 | チケットどおりに作り、内部で tdd を駆動、締めくくりに code-review を走らせて commit | tracker（チケット由来の場合） | | tdd | Model | エンジン | red-green。**事前に合意した seam** の上にだけテストを書く | codebase-design | | code-review | Model | 本流の末尾 | ある固定点に対する diff を Standards と Spec の二軸で審査 | tracker（Spec 軸） | | triage | User | 合流路 | **他人**が投げ込んできた issue を状態機械に通す | tracker、label | | improve-codebase-architecture | User | 合流路 | codebase を走査して「モジュールを深化させる」機会を探し、HTML レポートを出す | — | | prototype | Model | 単独 | 使い捨てのコードで**一つ**の設計上の問いに答える | — | | diagnosing-bugs | Model | 単独 | 難しい bug と性能リグレッションの六段階診断。red loop ができるまでは推測しない | — | | research | Model | 単独 | バックグラウンドの agent が一次資料を読み、引用付きの markdown を残す | — | | resolving-merge-conflicts | Model | 単独 | hunk ごとに「意図」に沿って衝突を解決し、検査を走らせ、merge を完了する。決して諦めない | — | | wizard | Model | 単独 | 対話型の bash script を生成し、人間にしかできない手順を案内する | 実行時に `gh` | | codebase-design | Model | 語彙層 | モジュール、インターフェース、depth、seam の正確な用語と四つの原則 | — | | domain-modeling | Model | 語彙層 | ドメイン言語を能動的に築き磨き、その場で書き込む `CONTEXT.md` と ADR を書く | — | | handoff | User | 単独 | 現在の会話を、持ち運べる引き継ぎドキュメントに圧縮する | — | | teach | User | 単独 | 現在のディレクトリを、session をまたぐ学習ワークスペースに変える | — | | to-questionnaire | User | 単独 | 「他人しか知らない」決定を一枚の質問票にする | — | | wait-what | User | 単独 | 直前の説明が腑に落ちないときに打つと、agent が語り直す | — | | writing-for-agents | Model | 語彙層 | agent が読む文書（skill、指示ファイル、spec、prompt）の指針 | — | 覚えておきたい二つの分岐 * **prototype への分岐**：インタビュー中に「言葉にできない、見ないと分からない」問いに当たったら、いったん止めて prototype を作り、見てから一行で答える。 * **spec と tickets が割に合うのは session をまたぐときだけ**。単一の context window で収まる変更なら、そのまま `grill-with-docs` から `implement`へ進み、間の二歩は飛ばします。 05 ## 本流の七ステップ、順を追って 通しの事例 社内ツールの repo（Next.js と Postgres）に「契約期限リマインダー」を足したい——30 日以内に期限が来る契約を一覧し、担当者にメールを送り、管理画面に赤い点を出す。schema、API、UI、メール送信にまたがり、幅として十分で、フル工程を通す価値があります。 ### Step 1 — 曖昧なアイデアを問い詰めて決定に変える ``` /grill-with-docs 契約期限リマインダー機能を追加したい ``` きれいな会話を一つ開き、**plan mode を切ります**。plan mode は agent に計画を早く出させようとしますが、それは「問いの中に留まる」ことのちょうど逆です。 何が起きるか codebase を読んだうえで、**ラウンドごとに**質問してきます。各ラウンドはその時点の **frontier**——前提条件がすべて解決した問いをまとめて一度に聞くので、宙に浮いたままの問いを聞かれることはありません。形式は固定で、番号つきの見出し、本文、一行の推奨回答。13 問なら通常 3 ラウンド、46 問を 4 ラウンドに分けるのもごく普通の一回です。 どう答えるか ``` 1 はい 2 二つ目 3 いいえ。うちの契約に一部解約はありません 4 分かりません ``` **最大の失敗モードは受け身です。**「同意」と四十回答えれば、agent が書いてあなたが頷いただけの計画ができます——長いので生産的に感じます。でも実際には何も決まっておらず、結果は自分で稼いでいない確からしさをまとっています。能動的とは、こういうことです。必要な精度より浅く問われたら**押し返す**、範囲が漂っているなら**口に出す**、本当に分からないなら「分かりません」と答える。これは本物の答えです。 grillable vs ungrillable 「一枚の長いフォームか、三ページか」「このインタラクションはどんな感じであるべきか」——こうした問いは**話しても出てきません**。反応できる何かが要ります。ぶつかったら、いったん止めて prototype を作り、見てから一行で答える。ungrillable な問いを押して話し続けるのが session の爆発する主因です。agent は言い換えて聞き続け、あなたは推測を重ね、範囲は不確かさを埋めるために膨らみます。 | 何が片づいたか | どこに残るか | | ------------------------------------------------ | ------------------------------------------- | | 一つの**用語**——このプロジェクト固有の言い方 | `CONTEXT.md`、**その場で書き込む**。最後にまとめて出すのではありません | | 一つの**元に戻しにくく、context がなければ意外に映り、本当にトレードオフがある**決定 | `docs/adr/` の下に置く一件の ADR | | ほかに決めたことすべて | 会話の中だけ。ほかのどこにもありません | 三行目の意味 問い詰めて出した**ものの大部分は、この context window の中にしか存在しません**。だから clear もしない、compact もしない。同じ会話の中でそのまま `/to-spec`。 `CONTEXT.md` は**用語集であり、用語集でしかありません**——実装の詳細も、spec も、下書きも入れません。ADR は三つの条件が同時に成り立つ必要があるので、**ほとんどの session は ADR を 0 件しか出しません。それは設計どおりです**。 このステップでは**手持ちで最良のモデル**を使います。grilling が食うのはモデル自身の「システムはどう壊れるか」という直感です。実装の段階はむしろ context を食うので、もっと安いモデルで構いません。 ### Step 2 — 決まったことを、生き延びる文書に変える `/to-spec`、**同じ会話の中で。新しい会話を開かないこと**。 これは**あなたにインタビューしません**。ここまで来れば決めるべきことは決まっているので、これは「総合」です——会話、codebase、`CONTEXT.md` と ADR から整理します。 spec は決定の記録であって、決定の現場ではない これが存在する理由は context window が終わるからです。いま問い詰めて出したものはすべて、まもなく捨てられる会話の中にあります。spec はその会話の生き残りです。だから何も検証しないし、何も決めません。**spec の中に、あなたが言っていない一文があれば、それは欠陥です。** まず seam をあなたと確認する 一文字も書く前に、この機能をどの **seam**（テストが振る舞いを観察する公開の境界）の上でテストすべきかを草案にして、あなたに聞いてきます。新しく開くより既存の seam を好み、取れるかぎり**いちばん高い**ところの seam を取ります。理想の数は変更全体で一つだけです。この「事前に合意した seam」は下流へそのまま伝わります：`tdd` は事前に合意した seam の上にだけテストを書き、`code-review` は合意していない seam が使われていないかを確認します。**だからこのやり取りは真面目に答えてください。実装の段階に先送りしないこと。** | いまどこにいるか | 何を走らせるか | | ------------------------------------- | ------------------------------ | | まだ何も決まっていない | まず `grill-with-docs` | | 決まっていて、しかも**一つの context window で終わる** | そのまま `implement`、**spec を飛ばす** | | 決まっていて、仕事が複数の session にまたがる | `/to-spec`、そのあと `/to-tickets` | | wayfinder の地図を片づけ終えたところ | `/to-spec #` | よくある落とし穴 * **`ready-for-agent` ラベルの誤解**：spec にこれが貼られ、意味は「もう triage は要らない」です。つまり**入場資格であってチケットではありません**。しかし、このラベルを監視する無人の agent がいると、その違いが分からず、spec 全体を一気にやりきろうとします。対処は、その agent の prompt で parent spec を明示的に除外するか、 `/to-tickets` の実行が終わったらラベルを外すことです。 * **リファクタリング型の作業はテンプレートに合わない**：テンプレートは user story に寄りすぎていて、アーキテクチャの作業を当てはめると「誰も要求していない物語」になります。代わりに implementation-decisions と testing-decisions の二つの節に頼り、長く効くアーキテクチャの決定は ADR の形で `grill-with-docs` の側で固めます。 * **重複は調べません**：同じ issue が既に立っていないか tracker を検索することはなく、従っている ADR をリンクすることもありません。よく触る領域は自分で先に検索しておきます。 * **spec が大きすぎると切り詰められます**：巨大な spec は tracker issue がきれいに返せる量を超え、しかも戻れるローカルの控えもありません。`/to-spec` と `/to-tickets` の間では clear も compact もしないでください。 ### Step 3 — tracer bullet に切り分ける `/to-tickets`、同じウィンドウで。あるいは `/to-tickets #`。計画が会話の中にあるだけで spec になっていなくても構いません。会話をそのまま読みます。 | | 水平スライス（誤） | 垂直スライス（正） | | -------------- | ------------------------------------------ | -------------------- | | チケット 1 枚が届けるもの | 変更の**1 つの層**（schema を全部で 1 枚、API を全部で 1 枚） | 1 本の細い道が**すべての層**を貫く | | 着地したあと | すべての層がそろうまで何も動かない | それ単体で demo できる | | 受け入れ条件 | 別のチケットが持つ作業まで手を伸ばさざるを得ない | 自分が持つものだけを評価する | これは最も破られやすいルールであり、**代償は実測されています**：あるチームは層ごとに切ったチケットを 26 枚使いました（corpus、producer、aggregator、selector）。平均で**チケット 1 枚を閉じるのに agent を 20 回走らせました**。そのうち約四分の三は手戻りです。チーム自身の振り返りは、あらゆる種類の失敗を、実装の品質ではなく水平スライスに突き当てています。 やるべきチェック チケット 1 枚ごとに、ひとこと問いかけます——**「これが終わったら何を demo できるか？」**答えとして**振る舞い**を挙げられないなら、それは水平スライスです。チケットごとに demo path を 1 行足す人もいて、モデルを垂直分解のほうへ押せると報告されています。 発行の前に **Prefactoring**：まず「変更を容易にしてから、その容易になった変更を行う」という作業を探し、いちばん前に並べます。そのうえで、**番号付きのリストを渡して詰問してきます**：粒度は適切か、ブロッキングエッジは本物か、統合すべきものや分割すべきものはないか。**承認するまで、tracker には何も入りません**——この詰問ステップこそ、押し返す場所です。 広域リファクタリングだけが例外 tracer-bullet のルールを破る形が一つだけあります——**単一の機械的な変更でありながら、影響範囲が codebase 全体に及ぶもの**（フィールド名を一つ変える、共通の型を一つ差し替える）です。一度の編集で数千の呼び出し箇所が壊れ、緑のまま着地できる垂直スライスは存在しません。expand–migrate–contract で進めます：**Expand**——新しい形を古い形の隣に足すだけで、何も壊しません。**Migrate**——影響範囲に沿って呼び出し箇所をバッチに分けて移します。1 バッチが 1 チケットで、いずれも expand にブロックされ、古い形が残っているので CI は緑のままです。**Contract**——呼び出し元がなくなってから古い形を削除します。すべての migrate バッチにブロックされます。 よくある落とし穴 * **3 行の変更が 12 枚のチケットに切られる**：分解しすぎることが最もよくある摩擦です。詰問ステップで統合するように言ってください。もっと根本的な答えはこうです——変更全体が一つの context window に収まるなら、**そもそもこの skill は要りません**。 * **GitHub で sub-issue として作られない**：既知で未修正です（issue 554）。Codex ではさらに深刻です。`gh` は v2.94 からネイティブ対応しています—— `gh issue create --parent` と `gh issue edit --add-sub-issue`。 * **「Blocked by」が本文にしか書かれない**：同種の問題です（issue 513）。GitHub にはネイティブの `gh issue create --blocked-by`があります。ブロッカーが先に発行されるので、番号は作成の時点で必ず手に入ります。 * **受け入れ条件が何も評価していない**：一つひとつについて「どんな観察がそれを偽だと示すか」を挙げ、開始時点の commit で赤になることを確かめます。 * **チケットを出し終えた、そのあとは？**自動の割り当てはありません。ボードを見て、未完了のブロッカーを持たないチケットが何枚あるかを数え、その数だけ agent session を開きます。**チケット 1 枚につき真新しい context を一つ、あいだで clear。** ### Step 4 — チケット 1 枚に session 1 つ ``` /implement https://github.com/you/repo/issues/12 ``` なぜ完全な reference を書くのか `/implement #2` の `#2` は**「agent から見えるあらゆる番号付きリスト」**に対して解決されます——新しい session ではそれが todo ファイルや checklist かもしれず、自分が設定した tracker とは限りません。しかも解決の仕方は自信満々で、**fail-closed になりません**。だから間違っていてもすぐには気づけません。完全な URL か `owner/repo#2`を渡し、タイトルを読み上げて確認させてから始めさせます。 1 回の run の五つの拍 1. ticket か spec を読み、seam を導き出す 2. 事前に合意した seam の上で `tdd`を回し、一度に red-green スライスを一つ 3. こまめに typecheck し、途中は単一のテストファイルを走らせる 4. 仕上げに完全なテストスイートを 1 回走らせる 5. 最後に `code-review`を走らせ、そのあと commit する先は**現在の branch** 絶対にしないこと **計画を開き直すことは決してありません。**インタビューもなく、確認のラウンドもなく、別のやり方を提案することもありません。上流で決まったものが入力であり、その仕事はそれを一つの commit に変えることだけです。これこそが、「新しい agent に『これをやって』と打つ」こととの違いです——後者は作りながら設計をやり直します。 | 症状 | 説明 | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 走り終わったのに、チケットが開いたままで受け入れ条件にチェックが入らない | **正しく、想定どおりです。**implement には締めくくりのステップがなく、commit で止まります。**チケットは自分で閉じます**——これは依存の連鎖でいちばん強く噛みつきます。frontier の定義は「ブロッカーがすべて閉じている」なので、誰も閉じなければ、着手できるチケットは永久に現れません | | すべてのチケットを一度に、並行で走らせられますか？ | **できません。**同じ checkout で複数の implement を並行させるのは「非対応」よりたちが悪く、一つの午後のうちに、別の session の commit に amend が当たる、stash が消える、commit が違う branch に落ちる、といった現場報告があります。コミュニティの workaround は worktree ですが、stash は依然として共有です | | PR を開けますか？ | 組み込みではありません。現在の branch に commit し、branch を切ってくれることもありません。呼び出しの時点で上書きする人もいます | | code-review が私の変更を見ていないと言う | 審査するのは `diff ...HEAD`、**staged と working tree は除外します**。implement は commit の前に review を走らせるので、途中の commit が既にあるのでない限り、その diff には何もありません。**先に commit してから review** | | チケット 1 枚で 150k token 燃える | たいていは使い方の誤りではなく、チケットが大きすぎるせいです。1 回の run は codebase の探索、seam ごとの red-green、完全なスイート、review を含むので、100k token を超えるのは普通です。**てこは上流にあります**：新しいウィンドウ一つに収まるところまでチケットを調整します。1 枚が何度も溢れるなら分割することであって、effort を上げることではありません | 組み込みのあの review を**あえて使わない**人もいます——コードを書いた agent が自分のコードを審査すれば、自分の解法をひいきします。きれいな session で固定点に対して別途 `code-review` を走らせるのは、理にかなった代替策です。 ### Step 5 — red-green エンジン `tdd` は**参考資料であって、ドライバーではありません**：ループのルールを握っているだけで、session を回すのは別の誰かです（あなた、または `implement`）。 Red-green 失敗するテストを書き、それをちょうど通すだけのコードを書きます。次のテストを先回りして書きません。**refactor フェーズはありません**——2026 年 6 月に削除されました。agent がほとんど実行しないうえ、review と implementation は session を分けたほうが結果がよいからです。リファクタリングは code-review の担当です。 Vertical slice 一つの seam、一つのテスト、一つの最小実装、そして繰り返し。最初の cycle が tracer bullet で、一本の道が端から端まで通ることを証明します。逆は、テストを全部書いてからコードを全部書くやり方です——それが検証するのは**想像上の**振る舞いであり、ユーザーがすることではなく物の形を確かめているだけで、しかも実装を理解する前にあなたを一つのテスト構造に縛りつけます。 Pre-agreed seam ルールは絶対です：**確認していない seam には、テストを書かない。**チェーン全体では seam を `to-spec` の段階で合意しておきます。単独で呼び出したときは、その場で直接聞いてきます。 | アンチパターン | 現れ方 | | ---------------------- | -------------------------------------------------------------------------------------------- | | Implementation-coupled | 内部関数の名前を変えただけで振る舞いは同じなのに、テストが壊れる。自分の内部協力者を mock する、呼び出し回数をアサートする、インターフェースではなくデータベースのクエリで検証する | | Tautological | 期待値がコードと同じやり方で計算されているので、テストは必ず通る。**期待値は別のところから来なければならない**：既知の正しいリテラル、手で計算した例、spec | | Horizontal slicing | 実装より先にテストがまとめて着地している | **Mock を使うのはシステム境界だけ**：外部 API、時間、ランダム性。ファイルシステムやデータベースのこともあります。**自分のモジュールを mock してはいけません。** よくある落とし穴 * **「どの test seam にするか聞かれても、まったく分からない」**：いちばん多い摩擦です（issue 607）。プロンプトは候補の seam を名前で並べるだけで、それぞれが何をとらえ何を取り逃すかを言いません。**agent にトレードオフを聞き返す**：component 層の seam が取り逃すもののうち integration seam がとらえるものは何か、どれだけ遅くなるか。チェーン全体が `to-spec` の段階で seam を決めておく理由も、まさにこれです。 * **テストより先に実装を書く**：起こります。skill は「それと共に生きる」書き方であって、agent に 100% 守らせる指示は存在しません。あるスライスで本当に厳密さが要るなら、走らせながら見ていてください。 * **先にブラウザテストを書いて堂々巡りする**：agent が Playwright を先に書き、まだ存在しない機能に対して何度も走らせ、最後に「テストが壊れている」と結論した、という報告があります。repo の指示ファイルに宣言してください：browser テストは、振る舞いが動くようになってから書く。 * **ほかのチケットのことを知らない**：一枚のチケットに対して走らせると、兄弟チケットに属する作業を嬉々として提案してきます（issue 129）。spec を ticket と一緒に渡すと役に立ちますし、最初からチケットを正しく切っておくともっと役に立ちます。 ### Step 6 — 二軸レビュー ``` /code-review main ``` **固定点はあなたが与える必要があります**。与えなければ、勝手に推測せずに聞いてきますし、ref が解決すること、diff が空でないことを確かめてから sub-agent を生成します。 | | Standards | Spec | | ------------ | ---------------------------------- | -------------------------------------- | | 問い | 正しくやれているか？ | やっているのは正しいものか？ | | 何を読むか | repo 自身が文書にした規範と、内蔵の smell 基準 | 出どころの issue または spec | | 何を報告するか | 明文の違反（ハードな失格になりうる）と smell（つねに判断もの） | 欠落または一部しか実装されていない要件、スコープの膨張、誤って実装された要件 | | 所見ごとに引用すべきもの | 規範ファイルと条項、または smell 名と hunk | spec のその一行 | 二つの軸は**それぞれ別の sub-agent で走り**、互いの推論が見えません。報告の最後には「軸ごとの最悪の所見」を挙げ、そして**軸をまたいだ総合優勝を選ぶことは拒みます**——一つの変更が片方の軸は通り片方の軸は落ちうるからです：慣例をすべて守りながら間違ったものを作ったコードは Standards を通り Spec で落ち、チケットどおりに作っても repo の慣例を壊すコードはその逆になります。**混ぜた裁定は、通った軸に落ちた軸をかばわせてしまいます。** Smell 基準は Standards の下に敷かれた床です：Fowler『Refactoring』第 3 章の 12 個の code smell。どれも「かもしれない」というヒューリスティックな札であって決して硬い違反ではなく、しかもすべて「それは何か、どう直すか」の形で書かれているので、所見があなたのところに届くときには、**すでに動作が一つ付いています**。あなたの linter がすでに扱っているものは、二つの軸とも飛ばします。 よくある落とし穴 * **同名の組み込みコマンドと衝突する**：最も多く報告されていて、未修正です。組み込みのほうは「diff から bug を探す」もので、こちらは規範と spec への適合です。両方入れるとどちらかが勝ち、どちらが勝つかはインストールのしかた次第です。 * **sub-agent がまた自分を呼び、agent がどんどん増える**：複数の人が複数の harness で再現していて、一度は 50 個以上に達しました。fork での直し方は、二つの sub-agent brief にそれぞれ一行入れることです：「code-review を呼び出したり追加の agent を生成したりせず、このレビューを直接実行すること」。**無人で走らせるときは、agent の数を見ていてください。** * **コードを書いたのと同じ session で走らせるべきか？**新しいほうを勧めます。うまい言い方をした人がいます：**同じ context で自分をレビューするのは、slash command 付きの確証バイアスです。** * **所見は信じてよいか？**確かめずには信じられません。sub-agent の出力は**証拠ではなく仮説です**。二つの報告をまとめますが、一件ずつファイルに戻って検証はしないので、引用が別の場所を指したり影響を誇張したりすることがあります。所見ごとの引用を見てから動いてください。 * **なぜ走らせるたびに新しい問題が出るのか？**変更は新しい面をつくりますし、判断ものの半分は決定的ではありません。**収束の保証はありません。**一回の pass を手がかりの一覧とみなし、明文の規則に裏づけられたものを片づけて、そこで止めてください——「きれい」になるまで走らせてはいけません。そうはなりません。 ### Step 7 — 締めくくりとループ チケット一枚のループ： 1. clear context 2. `/implement `（`tdd` の実行はこの中で回る） 3. commit 4. `/code-review `、クリーンな session で 5. チケットを手で閉じ、受け入れ条件を突き合わせる——**implement はこれをやってくれない** 6. frontier から次のチケットを取り、第 1 歩に戻る リズム * **毎日**：本流。チケット一枚につき session 一つ、あいだで clear。 * **数日おき**：`/improve-codebase-architecture`、構造の負債を新しい課題に変えて本流へ戻す。 * **inbound の仕事があるとき**：`/triage`。外部からの報告がないプロジェクトでは、開くことはほとんどない。 * **技能を補いたいとき**：`/teach`、専用のディレクトリを一つ作る。 忘れないこと チェーン全体で唯一**誰も代わりにやってくれない**ことが、**チケットを閉じて受け入れ条件を突き合わせること**です。implement は commit で止まります。依存の鎖を先へ進めるには、あなたがチケットを閉じるしかありません——さもないと frontier に新しく着手できる項目が出てきません。 06 ## 状況別インデックス、どんなときにどれを取るか 本流以外の skill は、どれも「特定の状況でだけ逸れていく」ものです。ここでは**あなたの状況**で並べます。 単独 — prototype ### この問題は議論では決着しない これが書くのは**一つの問いに答えるための使い捨てのコード**です。問いが先に来て、あとに来るすべての形を決めます。間違った問いに答える prototype は、どれだけ見栄えがよくても純粋な無駄です。「使い捨て」は、**どう書くか**への制約であって、「必ず破棄する」という約束ではありません：テストなし、動く以上のエラー処理なし、抽象化なし、永続化なし。 二つの分岐で、返ってくるものは大きく違います。「このロジックや状態モデルは正しく感じられるか？」には**共有できる単一の HTML ファイル**が返ってきます——state panel、free-play ボタン、タブ式のナビゲーションを備え、すべて領域の言葉でラベルづけしてあるので、デザイナーや領域の専門家にそのまま渡して自分で感じてもらえます。裏のロジックは DOM に触れないきれいな純モジュールで、検証できたらそのまま本番のコードへ引き上げられます。「これはどう見えるべきか？」には**同じ route 上に並ぶ、大きく異なる複数の UI バリアント**が返ってきます。フローティングの下部バーで切り替えます。バリアントが食い違うべき場所は色ではありません。**構造**です——軽く調整しただけの card grid が三つ並んでも、それは壁紙であって prototype ではありません。 **それを「堅牢化」していると気づいた瞬間、もう prototype を作ってはいません**——テストを足す、本物のデータベースにつなぐ、「あとで必要になるかも」のために一般化する。そういうことです。 **成果物をどう扱うか**：答え（裁決と、それが解決した問い）は耐久性のある場所に置きます——commit message、ADR、実装 issue。prototype 自体は消しませんが、main にも入れません。commit 先は `prototype/` branch、**決して merge しません**。実装 issue にポインタを一つ残します。 **落とし穴**：本当は実装すべき場面で、agent は prototype を勧めてきます——命名の問題で、流れに不慣れな agent には「チケットができたあとの当然の次の一歩」と読めてしまうのです。それからもう一つ。**app 全体を prototype しないこと**：自然な停止点がなく、惰性でそのまま製品になり、「テストもエラー処理もない」コードがそのままユーザーの前に出ます。 単独 — research ### 外部の事実が判断を止めている それが素材にするのは**一次資料**だけです（公式ドキュメント、ソースコード、仕様、ファーストパーティの API）。どの主張も、答えを持っているその出所まで遡ります。**会話の中では答えてくれません**——出力は一つのファイルで、どの主張にもリンクが付きます。決め手は、読む部分をどこで走らせるかです。**バックグラウンド agent**。 **research は委任した足仕事であって、外注した思考ではありません。** **落とし穴**：自分自身の二つ目を生んでしまいます（issue 530）——skill は呼び出し側にバックグラウンド agent を立てろと言うだけで agent の種類を縛らないため、立ち上がるのは同じツールと指示を握った汎用 agent で、それがまた一つ立ち上げます。ある人の計測がこれです。**単一の research タスクが、三回の重なった実行で約 450k token を燃やしました**。重複したほうは三十分後、完全に視界の外で終わっていました。**呼び出したらバックグラウンドタスクの一覧を見て、重複を止めてください。** もう三つあります。逆向きの失敗——グローバルな指示がさらなる委任を禁じている場合、バックグラウンド agent は丁重に断り、skill は静かに何もしません。「信頼度の高い出所」はモデル自身の判断で、allowlist はありません。実際に効く緩和策はこれです。**引用を二つ三つ、無作為に追いかけること**。そのもの自体ではなく「そのものの要約」に着地していたら、その実行は失敗です。**停止基準がありません**。範囲はこちらの責任です——一つの API、一つの挙動、一つのバージョンについての主張のほうが、「research X」よりはるかに良いものが返ってきます。 **research ファイルは ADR ではありません**：ADR は残し、research ファイルは使い終わったらアーカイブするか削除します。古くなった research ファイルは無いより悪く、以後の repo 読み取りを汚染します。 単独 — diagnosing-bugs ### 何かが壊れた、理由が分からない 六つのフェーズ：repro を作る、最小化する、仮説に順位をつける、プローブを仕込む、リグレッションテスト付きで直す、片づける。 **「タイト」なフィードバックループができるまで、agent に理論を立てさせません。**名前の付いたコマンドが一つ、**すでに一度走らせてある**、この bug では赤で、直せば緑になる。bug 報告を渡された coding agent の既定の振る舞いはコードを読んで推測することですが、この skill はそれを塞ぎます。**赤にできるコマンドがなければ、Phase 2 はありません。**その gate こそが、この skill の価値のすべてです。 **ループが「ある」ことは目標ではなく、「タイト」であることが目標です**：速い（秒単位）、決定的（毎回同じ裁定）、鋭い（「crash しなかった」ではなく、正確な症状を断言する）、agent が無人で走らせられる。30 秒かかって flaky なループは、無いのとたいして変わりません。断続的に出る bug では、目標はきれいな repro ではありません。**再現率を上げること**です——トリガーをループさせる、並列化する、負荷をかける、sleep を注入する。 ループの作り方の階段、好ましい順 1. bug に到達できる seam に置いた、失敗するテスト 2. dev server に対する curl か HTTP script 3. fixture 入力を与えた CLI 呼び出しと、既知の良好なスナップショットとの diff 4. DOM、console、network を断言する headless browser script 5. キャプチャの再生（保存した request、payload、event log） 6. 使い捨ての harness（システムの最小の部分集合、関数呼び出し一回） 7. property または fuzz のループ、「たまに出力が間違う」向け 8. そのまま `git bisect run` に渡せる bisect harness 9. differential loop（同じ入力で、旧版と新版を突き合わせる） 10. human-in-the-loop の bash script、最後の手段 | Gate | 真でなければならないこと | | ----------- | ---------------------------------------------------------------------- | | Phase 2 に進む | 名前の付いたコマンドが一つ、**すでに走らせてあり**、出力も貼ってあり（機微な値はマスク済み）、この bug で赤になるもの | | Phase 3 に進む | repro が再現し、**かつ**最小化されていること——残った要素は一つひとつが効いていること | | Phase 4 に進む | 順位をつけた反証可能な仮説が 3 から 5 個、それぞれ予測を明示し、どれかを試す前に必ず先に見せること | | Phase 5 に進む | プローブが特定の予測に対応し、変数は一度に一つ、どの debug log にも grep できるタグが付いていること | | 完了 | 元の repro がもう再現せず、計測の仕掛けはすべて撤去され、**当たっていた仮説が commit message に書かれていること** | **落とし穴**：直接の答えだけが欲しい軽い質問でも発動してしまいます——いちばん多く報告されている問題です（issue 578、四人が同じ形を報告）。「診断せずに直接答えて」とはっきり言うか、この skill の model invocation を切ってください。**「性能の問題がどこにあるか」を探すのには使えません**。診断できるのは、すでに名前を言える失敗です。それに**修正を書く前に立ち止まって聞いてはくれません**。人間のチェックポイントは Phase 3 だけです。 単独 — resolving-merge-conflicts ### merge か rebase の衝突で詰まっている これは**衝突をテキストの問題として扱うことを拒みます**。hunk に手を触れる前に、両側を**一次資料**まで遡ります——commit message、PR、元の issue——ですから、選んでいるのは**二つの意図**の間であって、二つのテキストの塊の間ではありません。両立できるところでは両方を残します。本当に両立しないときは、この merge の明示された目標に合うほうを選び、そのトレードオフを言葉にします。衝突を取り繕うために新しい振る舞いを発明することはありませんし、**途中で投げ出しません**：merge は必ず完了した commit まで運ばれます。 repo 自身の自動化された検査を見つけ出し、commit の前に走らせもします——merge は git のなかで、「二つの branch を同時に満たしているのに、どちらの側のテストも通らない」ものが最も生まれやすい場所だからです。 **追加の実務知識**：衝突を避けるために並行タスクのあいだで「ファイルを分け合う」のはやめてください。得られるものよりコストのほうが高くつきます。守る価値のある唯一の規律はこれです。**大きなリファクタリングを先に済ませる**。worktree で並行して進めるときは、**merge して戻すのは、その変更を書いた session がやるのがいちばんです**。意図を知っているのはその session だけだからです。全員の衝突をまとめて最後の agent に batch で渡すのは、この skill が苦労して組み立て直そうとしているものを、ちょうど捨てる行為です。 合流路 — improve-codebase-architecture ### codebase が腐っていく codebase をスキャンして**深化の機会**——浅いモジュール（インターフェースが、それが隠しているものとほぼ同じくらい複雑なモジュール）を深いモジュールに変えられる箇所——を洗い出し、HTML レポートにまとめ、選んだ候補に対して grilling を行います。 **コードは決して変更しません。**run 全体が生み出すのは「HTML ファイル 1 つと対話 1 回」です。リファクタリングそのものは後で別の session で、通常の構築フローに乗せます。これが、**リファクタリングツールではなく点検である**ということの意味であり、「まだ手を付ける準備ができていない」codebase に対して走らせる価値がある理由でもあります。 **フィルターは二つ**：*deletion test*——このモジュールを削除したと想像したとき、複雑さはより小さなインターフェースの背後に**集約**されるのか、それとも各呼び出し側へ**拡散**するのか。「集約」になるケースだけがカードになります。また、領域を指定しない限り、直近の commit 履歴を先に読み、スキャンを**いま動いている**パスへ寄せます——誰も触っていないコードの深化は、あなたが永遠に実行しないリファクタリングです。 強度ラベルは三段階：**Strong**（deletion test を明確に通過し、摩擦も実在する。真剣に見る価値あり）、**Worth exploring**（筋は通るが、見返りはコードがこの先どこへ向かうかに左右される）、**Speculative**（網羅性のために挙げてあるだけで、大半は安心して無視できる）。 | 場面 | 使い方 | | ------------- | ------------------------------------------------- | | 定期メンテナンス | 数日おき、または空き時間に走らせ、機能と機能のあいだで構造が腐るのを防ぐ | | 大きな案件の前 | spec に向けて「この変更をやりやすくするには？」と聞く。**これが最も効く prompt** | | Brownfield 監査 | 大規模で構造のない vibe-coded な repo に走らせ、実際どんな形をしているのかを見る | | Legacy のテスト作業 | まずこれで足りない seam を洗い出し、そのうえでテストしにくいコードにテストを書く | **落とし穴**：「一つのアイデアのために一時間も問い詰められた」が最も声の大きい不満です——呼び出すときに「**問い詰めないで、そのままレポートをください**」と伝えてください。レポートを開いてもスタイルも図もないのは、外部リソースを CDN から読み込んでおり、ブロックされても静かに失敗するので agent からは見えないためです（agent はそのページを描画しません）。**inline CSS と手書きの SVG を使うよう指示します**。session 一つにつき候補は一つです。**この skill が「あなたの codebase に問題はない」と言うことはまずありません**——全部が Speculative のレポートというのは、何も見つからなかったことを、それが知っている唯一の方法で伝えているだけです。 合流路 — triage ### 他人から issue が大量に投げ込まれる **自分が作成していない issue にだけ使います。**生の bug 報告、外から来た feature request、突然現れた外部の PR。`to-tickets` が産出するチケットは構造上すでに agent-ready であり、それらに triage を走らせても、うまくいって無駄骨です。この skill は**提案して待ちます**：分類と状態の判断を理由とともに伝え、指示があるまで何も適用しません。 triage された項目はどれも、最終的に**分類の役割ちょうど一つと状態の役割ちょうど一つ**を持って終わります。分類は二つ、bug と enhancement。状態は五つ：`needs-triage`（評価が必要なもの）、`needs-info`（報告者待ち。返信があれば needs-triage に戻る）、`ready-for-agent`（完全に仕様化され、agent brief が付いている）、`ready-for-human`（同じ brief に「なぜ委譲できないか」を加えたもの）、`wontfix`（クローズ、理由は記録済み）。 `wontfix` は三種類あり、その違いは重要です。なぜなら**知識ベースに書き込まれるのは一種類だけ**だからです：すでに実装されているものは、それが存在する場所を指すコメントを残し、out-of-scope には**書きません**（それは作られた機能であって拒否された機能ではありません。書き込むと重複チェックを汚染します）。拒否した bug は丁寧に説明してクローズします。拒否した enhancement は out-of-scope ディレクトリにファイルを一つ書き、クローズのコメントからリンクします。そのディレクトリは**拒否された概念一つにつき markdown 一つ**（issue 一つにつき一つではありません）であり、triage は何かを評価する前にディレクトリ全体を読み、**キーワードではなく概念で照合します**。 **brief を書く前に検証します**：bug は報告者の手順どおりに再現し、PR は checkout して関連するテストを走らせ、そのうえで三つの結果のいずれかを報告します——確認済み（コードパス付き）、再現できない、試すには詳細が足りない（これ自体が最も強い needs-info のサインです）。すべては **agent brief** を良くするためであり、その brief は**正確さより耐久性**を旨として書かれます：型、シグネチャ、振る舞いの契約を書き、**ファイルパスと行番号は決して書きません**。issue は何週間も放置されることがあり、その下でコードは動き続けるからです。 **落とし穴**：label は自動では作られません。状態が五つでは**足りない**というのが最もよく挙げられる不足です（blocked、deferred、implemented はいずれも要望がありますが、どれも ship されていません）。**backlog 全体に一度に放って走らせないでください**——「注意が必要なものを見せて」というパスは、選ぶための安価なリストです。一度に二十個の issue を回すと、agent はそれを静かに証拠の土台として扱ってしまいます。そのうえこの skill が返すのは、**issue の本文だけでコメントは返しません**。 合流路 — wayfinder ### この案件は session 一つに収まらない この skill が引き受けるのは、**agent session 一つには収まらないほど大きな**案件です——**目的地**は言えるのに、まだ経路が見えない。それを tracker 上の共有された一枚の**地図**として描きます。地図は decision チケットで構成され、一度に一枚ずつ解いて経路がはっきりするまで進めます。 **計画はしますが、実行はしません。**各チケットは「解決すると決定が出る」問いを一つ抱えているのであって、実行すべき構築の一片ではありません。地図が完成したと言えるのは：**誰かがこれを作り始める前に、決めるべきことが何も残っていない状態です。**このルールは agent が最もよく破ります。 これと `grill-with-docs` の境界は **session の数であって、プロジェクトの大きさではありません**：一つの会話に収まるなら grilling（安くて質も良い）。収まらないときだけ wayfinder です。**範囲がはっきりしている機能に wayfinder を持ち出すのは、よくある間違いです。** **地図に載る四つのもの**：*Destination*——行き着いた先がどんな姿か。それを**どのチケットよりも先に名付けます**。*Decisions so far*——クローズしたチケット一枚につき一行、それぞれ詳細が実際に住んでいる場所へリンクします。*Not yet specified*、つまり**戦争の霧**——来ることは見えていても、まだ正確に言い表せない決定です。判定基準は**その問いをいま正確に言えるかどうか**であって、答えられるかどうかではありません。*Out of scope*——目的地の外だと判断した作業です。クローズし、決して卒業させません。地図は**保管場所ではなく索引**であり、決定はそれ自身のチケットの中にだけ生きています。 **Frontier** は「開いていて、ブロックされておらず、まだ引き受けられていない」チケットのことです。session は作業を始める前にチケットを自分に assign して引き受けるので、assignee がそのまま引き受けの印です。チケットは**常に名前で呼び、裸の番号は使いません**——issue 番号がずらりと並んだ壁は、文章の中では読めません。 | タイプ | モード | 使いどころ | | --------- | ----- | ---------------------------------------------------------------- | | grilling | HITL | デフォルト。話し合いで問題をはっきりさせられる場合 | | prototype | HITL | 「これはどんな形であるべきか」——話し合いでは決まらない問い。成果物はチケットから asset としてリンク | | research | AFK | 作業ディレクトリの外にある事実が意思決定を止めている場合。地図を描く時点で発射し、並行で焼き切る | | task | どちらでも | 決めることは何もないのに、**手作業**が一つの決定を止めている場合——権限の付与、サービスの登録、形が見えるようにデータを移す | `task` は「決める」ではなく「やる」唯一のタイプであり、存在理由は**ある決定のブロックを外すこと**、**目的地を届けるための一部になることは決してありません**。実務でもっとも間違えられるタイプです：agent がこれを実装ステップだと思い込み、地図の中でプロダクトコードを書き始めます。`research` は「1 session につきチケット 1 枚」の唯一の例外です。 **致命的な落とし穴が三つあります。**一つめは、**wayfinder の session の途中で agent が本番コードを書き始める**——最も多く報告されている失敗です。「計画はするが実行はしない」という既定値は地図の Notes で上書きできますが、 **Notes を書くのは agent 自身**です。したがって、制約とその免除が「制約される側」の所有する同じファイルの中に同居することになります。あるユーザーは、agent が「この地図は実行を伴う」と自分の Notes に書き込み、あとの session でそれを自分への許可として読み戻し、本番サーバー上で作業を始めるのを目にしました。二つめは、**地図が空になったあとも必要なのは `/to-spec` と `/to-tickets`**——decision チケットは地図が閉じるときにすべて閉じられ、残るのは「リンクされた決定で埋まった地図」であって、それは構築計画ではありません。三つめは、**grilling のチケットを並行して走らせてはいけません**。二つの session は context を共有しないため、片方でついさっき答えた質問を、もう片方でまた聞かれることになります。 実測された報告がもう一つあります：**「27 枚のチケットを描いて、13 枚目まで進んだところで残り全部が意味をなさなくなった」**。対抗策は二つ。地図の範囲を**境界のある目的地一つ**に絞ること（きちんと定義された epic のほうが、漠然とした「V1 を実装する」よりはるかにうまくいきます）、そして**積極的に prototype すること**。著者の言い方では、wayfinder は「prototypemaxxing」であって「planmaxxing」ではありません。 単独 — handoff ### 何かを移す必要がある 現在の会話を一つの**引き継ぎドキュメント**に圧縮します——ワークスペースではなく OS の一時ディレクトリに書き出される markdown ファイルで、まっさらな agent がそれを読めばそのまま引き継げます。 **これが買っているのは可搬性であって、圧縮ではありません。**そのぶん、聞こえるよりずっと狭い用途になります：ファイルが要るのは、仕事が**動く**ときだけです。トリガーは四つ——harness を替える、別のディレクトリや repo に移る、仕事を同僚に渡す、phase の途中で見つかった支線を分岐させる。 **最も飛ばされがちな使い方は分岐です。**自分は自分の session に留まったまま、蓄積した context の複製を、並行して働く二人目の agent に渡します。prototype の脇道はまさにこう使います：深い設計の会話の最中に、走らせてみないと決着しない問題にぶつかり、しかも苦労して積み上げた thread をその調べものに費やしたくない——prototype の session に handoff し、答えを受け取り、それを持ち帰って、元の thread で引用する。**二回の横断、生きた会話は一つ、話し直しはゼロ。** 何が旅をするか：ドキュメントは生きた thread（いま何が飛んでいるか、なぜか、次は何か）と、推奨する skill を一組携えていきます。秘密は書き出す前にマスクされます。すでに書き留められているものは、意図的に**一切**持っていきません——spec、計画、ADR、issue、commit、diff はすべてパスか URL で参照し、決してコピーしません。 **落とし穴**：ファイルは一時ディレクトリにあり、パスは長く OS ごとに違うので、**パスを尋ねて書き留めてから先へ進む**こと。session をまたいで temp を消す環境もあるので、次の session がすぐに始まらないなら、自分で永続的な場所へコピーしておきます。次の agent への渡し方は**パスを指す**ことです。要約を shell コマンドに貼り込んではいけません——特殊文字を含む要約は壊れますし、典型的な失敗は**黙って切り詰められること**です。「what は拾うが why は拾わない」というのは公正な批判なので、**「次の session は何のためか」をパラメータとして渡す**とよいでしょう。そして、検証されていない思い込みが事実として書き留められていないか注意してください。 単独 — to-questionnaire ### 答えは他人の頭の中にある 自分ひとりでは決められない決定を、一通の**質問票**に変えて、足りないピースを握っている人に渡します。 **それが問い詰めるのは「今回の送付」であって、主題ではありません。**主題についてあなたを問い詰めても、ここでは意味がありません——主題を知らないことこそが、他人に書いて送る理由なのですから。そこで、必ず答えられる二つのことだけを尋ねます：**誰に宛てるのか**（相手の役割、専門、あなたとの関係。これで語り口と、ドキュメントがどれだけ context を自前で持つべきかが決まります）と**何を持ち帰る必要があるのか**（自分では決着させられない具体的な決定や事実。これが成果物を測るチェックリストになります）。そのあとはすべて起草です。 ドキュメントの形：一行の purpose と、「あなたの頭の中に一度も入ったことのない人」に向けた短い context。質問は**重要なものから先に**並べ、主題ごとにまとめる。**一問に一つの考えだけ、複合質問は絶対に作らない**。**「わかりません」と答えてよいと明示する**——フラグの立った不確かさは役に立ち、事実のように読める自信ありげな推測は役に立ちません。最後は catch-all を一つ。 これは意図的に**一切**分岐せず、**一切**複数の宛先を取りません。三人が三つの答えを握っているなら、三回走らせます。最もよくある使い方は、行き詰まった grilling です：**同じ会話の中で**走らせます——ingest の段階を持たないこの skill が grilling のあとで働くのは、その session がすでに context に入っているからにほかなりません。 単独 — wait-what ### いまの説明が腑に落ちない agent が、いま言ったばかりのことを**もう一度売り込み直します**：足りなかった context を補い、平易な言葉で書き、あなたのプロジェクトの `CONTEXT.md` にある語彙を使います。 **この skill はたった三行で、それは未完成の草稿ではなく設計です。**冗長さと戦う skill は、長くなることで失敗します：四百行の「簡潔にせよ」を読んでも、モデルはやはり冗長になります。モデルが読み取るのは、訴えの中身ではなく分量だからです。 **名前がそのまま仕組みです。**先頭に来る語は *wait*。「もっと簡潔に」は **agent の出力**についての指示で、モデルは「言葉を削る」ことで従い、その結果あなたはもっと迷子になります。*wait* が指すのは**あなたの状態**です：「理解はここで失敗した」と言っているのです。「短くして」と言われた agent は電報を書きます。「待って、置いていかれた」と言われた agent は**戻って説明し直します**。流行している言い回しはどれも出力を名指ししていて、モデルは短いだけで明確にはならない語り口へと過剰修正します。**聞き手を名指しすれば、両方の半分がそろって手に入ります**：より少ない言葉、**そして**あなたに欠けていた前提。 意図的に「説明し直すのは**それ**」と言い、「直前のメッセージ」とは言いません——あなたを置き去りにしたものはたいてい一段落より大きく、どこまで戻るかは agent が決めます。本当の解毒剤は、あらかじめ共有言語を作っておくことです。wait-what が直せるのは、すでに起きてしまった一件だけです。 単独 — teach ### 何日もかけて何かを学びたい これを実行したディレクトリを常設の学習ワークスペースに変え、一連の**自前のスタイルを持つ短い HTML レッスン**で、複数の session にまたがって一つの主題を教えます。 **モデルがすでに知っていることからは教えません。**parametric knowledge は信用できないものとして扱われます：教える前に、まず信頼度の高い資料を探し、資料ファイルに記録し、どのレッスンでもそれを引用します。そして**状態を持ちます**——mission、資料、レッスン、学習ログはすべてファイルとしてディレクトリの中に住んでいます： | パス | 入るもの | | ----------------- | ------------------------------------------------------------ | | MISSION.md | なぜこれを学ぶのか。ほかのすべてがこれにぶら下がります。これが無ければ、まずそれが存在するまであなたにインタビューします | | RESOURCES.md | 厳選された出典。Knowledge と Wisdom（コミュニティ）に分かれます | | lessons/ | 番号付きのレッスン——教える単位の主役 | | reference/ | 圧縮されたチートシート、アルゴリズム、用語集——**実際に読み返すことになる**ドキュメント | | learning-records/ | ADR 形式の「何を確かに学んだか」の記録。次に何を教えるかを決めるのに使います | | assets/ | 再利用できる部品——最初のものは共有 stylesheet——レッスンが同じ一つの講座に見えるようにします | | NOTES.md | あなたが述べた教え方の好み | 中心にある考えは **storage strength**（長期の保持）であって、 **fluency**（その場の思い出せる感じ。読んでいるあいだは習熟したように感じられ、一週間後には消えています）ではありません。それは**望ましい困難**を使って前者を作ります。知識が先です（この段階では難度は敵であり、理解に必要なワーキングメモリを食います）。技能はそのあと、タイトなフィードバックループで鍛えます（この段階では難度は道具です）。**レッスンはめったに読み返されませんが、リファレンス文書は読み返されます**——ですから、一つのレッスンの圧縮されたエッセンスはリファレンスのディレクトリに属するのであって、それを導入したレッスンの中に埋めるものではありません。 **落とし穴**：ファイルが間違った場所に書き込まれることがあり（issue 377、あるユーザーのレッスンがグローバルの skill ディレクトリに書き込まれました）、**最初にディレクトリ名をはっきり言ってください**。**小テストの正解が必ず最初の選択肢になります**（複数のモデルで確認済み、未修正。あるコントリビューターは 9 レッスン 33 回すべてが A だったと報告しています）。**能力評価のステップがありません**。最初のメッセージで、自分の既存の知識とギャップを伝えてください。**間隔反復のスケジュールもありません**。復習したければ自分から頼んでください。 コードのためだけではありません——記録では、コード以外の用途のほうが大きな割合を占めます。コードの中では、いちばん強い用途はゼロから言語を学ぶことではなく、**見知らぬ codebase や新しいチームの技術スタックの中で方向をつかむこと**です。著者はきれいな組み合わせを一つ挙げています。問い詰められている最中に分からないものに当たったら、**grilling を止めて学びに行かないでください**——学習ワークスペースへ handoff し、そこで学び、戻って続きをやります。 単独 — wizard ### 人間にしかできない手作業の手順がある それは**対話型 bash script**を生成し、人間を一歩ずつ手作業の手順に沿って導きます——サードパーティサービスをつなぐ、一度きりの移行を走らせる、プロジェクトを状態 A から状態 B へ移す。 **agent が script を書きますが、それを実行することは決してありません。**実行するのは自分のマシンの上です。ですから wizard は、それに従って進める手順書ではありません——それは**プロセスを駆動し、状態を保持するプログラム**であり、あなたの担当はクリックとペースト、そして Enter を押すことです。Stage は「一つの画面に一つの集中したタスク」で、script は stage の間でターミナルをクリアします。 **script を書く前にまず scoping**：それは何も知らないまま尋ねるのではなく、あなたの repo を読みます——環境ファイル、compose ファイル、framework config、そして CI 設定の中のすべての secret と変数参照。そのどれもが wizard の出さなければならない値です。そのうえで順序づけた stage の一覧を出して確認を取り、そのあとで初めて各 stage を人間がたどる正確な経路に対応づけます。今の UI がどうなっているか分からないときは、あなたに尋ねるか文書を調べるのであって、**クリックを発明したりはしません**。 template がすでに UX を解決しています：進捗、確認ゲート、クロスプラットフォームでの URL の起動、secret の伏せ字入力、環境ファイルへの冪等な書き込み、CI secret の書き込み、そして「何をスキップしなければならなかったか」の締めくくりの要約。**固定ライブラリの半分はどの wizard でも同じで、決して手で直しません。一貫性こそが要点です。**wizard を書く agent はそれをエンドツーエンドで実行せず、静的な検証に切り替えます。**最初に実行するのはあなたで、その一回がそのままテストです**。 **落とし穴**：**途中で前のステップに戻れません**。3 つ目のステージで打ち間違えたら中断して走り直しです（走り直しは安く、環境ファイルに書き込み済みの値はデフォルトとして戻ってきます）。プロンプトでは**矢印キーに bug があり**（issue 741）、backspace は効きます。サードパーティサービスの状態を調べに行くことはしません。**API key はモデルの context に入りません**——ただし scoping のときに key をチャットへ貼り付ければ、それは貼り付けた他のどんなテキストとも同じく context の中にあります。 語彙層 — codebase-design ### モジュールはどんな形であるべきか これはモジュールを設計するときに使う言葉を固定し、一つひとつを正確に定義して、**ゆるい代替語を禁じます**。そして、そこから導かれるいくつかの原則を述べます。 | 用語 | 意味 | 使わない語 | | --------- | ----------------------------------------------------------------------------- | ---------------------- | | Module | インターフェースと実装を持つものすべて。**意図的に規模とは無関係**——一つの関数、一つの class、一つの package、層をまたぐ一つのスライス | unit、component、service | | Interface | 呼び出し側が正しく使うために知っていなければならない**すべて**：型シグネチャに加えて、不変条件、順序の制約、エラーモード、必須の設定、性能特性 | API、signature | | Depth | インターフェースにかかるてこ。**深い**：小さなインターフェースの背後に大量の振る舞い。**浅い**：インターフェースが実装とほぼ同じくらい複雑 | — | | Seam | そこを編集しなくても振る舞いを変えられる場所。インターフェースの**位置** | boundary | | Adapter | ある seam の上で、あるインターフェースを満たす具体的なもの。名前が指すのは**役割であって素材ではない** | — | | Leverage | 呼び出し側が depth から得るもの：インターフェースを一単位学ぶごとに、より多くの力が手に入る | — | | Locality | 保守する側が depth から得るもの：変更、bug、検証が一か所に集まる | — | Depth **は意図的に**「実装の行数をインターフェースの行数で割ったもの」とは定義されていません——その指標は、実装をより肥大化させることに報いてしまうからです。ここで使うのは depth-as-leverage です。 **四つの原則**：depth はインターフェースの性質であって、実装の性質ではありません。**deletion test**——このモジュールを削除して複雑さが消えるなら、それは pass-through。複雑さが N 個の呼び出し側に再び現れるなら、それは稼いでいるということ。**インターフェースこそがテスト面**であり、その外側まで測りたくなったら、それはモジュールの形が間違っているということです。**adapter が一つなら仮説上の seam、adapter が二つあって初めて本物の seam**。 **落とし穴**：**これを driver として使わないでください**（issue 449）。「続けて未解決の事項を進めて」と言われると、agent は見つけられるうちでいちばん動作らしいものをつかみ、前の session ですでに読み込んだコードを探索し直し、長く走ってからようやく何かを尋ねてきます。**driver となる skill を名指しして、これはその下に置いてください。** 語彙層 — domain-modeling ### 言葉がぶつかっている これは設計を進めるのと同時に、プロジェクトの **ubiquitous language**を作り上げ、磨いていきます——用語集と衝突する言い回しに異議を唱え、曖昧な言葉を使ったときに正確な言葉を引き出し、具体的なシナリオで一つの関係を境界がはっきりするまで圧力テストします。 **これは能動的な規律であって、受動的なものではありません。**ただ `CONTEXT.md` を読んで語彙を借りるのは、どの skill にもできる一行の習慣です。これは**モデルを変えている**ときに使うものです。これが、**あなたを中断させる**理由です：用語が決着したその瞬間に、会話の途中で `CONTEXT.md`へ書き込みます——バッチ版は一回の session の**要約**であるのに対し、リアルタイム版はその session の**実際の成果物**。 成果物は二つ、基準も二つ。`CONTEXT.md` に入るのは**用語**（あるものが何であるか、一〜二文）です。書き込みのしきい値は「曖昧な言葉が正式な用語になったとき」、タイミングはリアルタイムです。**決して入らないのは**実装の詳細、spec、走り書き、一般的なプログラミングの概念です。ADR に入るのは**一つの決定**（一〜三文：context、選択、理由）です。書き込みのしきい値は**三つすべてに当てはまること**——逆転が難しいこと、context がなければ意外に感じること、実際のトレードオフの結果であること——であり、しかも提案であって既定ではありません。 **本当に覚えておくべきなのは `CONTEXT.md` のあのルールです**。実戦で壊れるのがそのルールだからです：**それは用語集であり、用語集でしかありません。**放っておくと、モデルは「CONTEXT.md に書き込む」を「与えられた答えをすべて永続化してよい」という許可として受け取り、ファイルは走り続ける spec になってしまいます——**これはこの skill でいちばん多く報告されている問題で、複数のモデルにまたがっています。** **この skill の効きを実感できる動き**：何かがどう動くのかをあなたが述べると、それはコードを調べて矛盾を並べて見せます——「あなたのコードは Order 全体をキャンセルしていますが、いま部分キャンセルができると言いました。どちらが正しいのですか？」こうして、どちらか一方が変更される前に、言語とコードは**声に出して揃う**ことを強いられます。**制限**：交差参照するのはコードと commit 済みのドキュメントだけで、**あなたの issue tracker は検索しません**。ですから、数か月前にクローズされた issue の中で議論し尽くして意図的に決着させた命名の衝突が、新しいものとして持ち出されます。 **落とし穴**：`CONTEXT.md` が 500 行以上に膨らむ——**サイズは症状であって病気ではありません**。そのまま、簡潔にして実装の詳細を取り除くよう指示してください。ファイルが本当に引き締まっているのに、読者が同時に頭へ入れたくない二つの領域をなお含んでいる場合にだけ、分割を検討します——**肥大したファイルを分割しても、肥大したファイルが複数できるだけです**。**自動トリガーはこの skill の最も弱いところです**：grilling を一通り走らせても `CONTEXT.md` の中身がまったく変わっていないなら、まさにそれが起きています。名指しで指示してください。**人のレビューを経ていない、agent が書いた用語集は、無いよりも悪いものです**：自信ありげに響く言い伝えになり、後続の session に真実として扱われます。 語彙層 — writing-for-agents ### agent に読ませる文書を書きたい skill、指示ファイル、spec、runtime prompt、README——agent が読むものならすべてです。包装は違っても、書き方は同じです。 **この skill の既定の動きは削除であって、説明ではありません。**agent に別の agent 向けの指示を書かせると、字数の大半はモデルがすでに知っていることの説明に消えます。**そのどの一行も no-op です**：context の対価を払いながら、行動を何ひとつ変えていません。この参考資料はそれを見つけ出すためのレンズです。だからこの skill が値を返す相手は、白紙のファイルだけではありません。**すでに手元にある文書**に対しても、少なくとも同じだけの価値を生みます。 **負担は二種類あります。***Context load* は、常時ロードされる材料が agent のウィンドウの中で払わせるコストです。指示ファイルの一行、skill description、トリガーされるかどうかに関係なく毎 turn context に居座るもの、そのすべてです。*Cognitive load* のほうは**あなた**にかかるコストです。どの文書が存在し、いつどれに手を伸ばすか——索引はあなた自身です。**これは最小化すべきコストではなく、人間が主導権を握るための値段です。**この二つが腑に落ちれば、書くときの判断の大半は、同じ取捨を場所を変えて行うだけになります。 **五つのてこ**：*Context pointer*（context の中にあり、context の外の材料を名指しし、「いつ取りに行くか」まで符号化した参照。agent がどれだけ確実にそこへ手を伸ばすかを決めるのは、pointer の**言葉づかい**であって、その参照先ではありません）、*Information hierarchy*（「ファイル内の手順」から「ファイル内の参考」へ、さらに「pointer の先に置いた参考」へと上がる梯子）、*Completion criteria*（防ぐのは**早すぎる完了**、その防衛線です）、*Leading words*（モデルの事前学習にすでにある圧縮された概念。錨は二度下ろします——body では実行のために、pointer ではトリガーのために）、*Pruning*（単一の真実の源、関連性、そして一文ずつ当てる no-op test）。 **no-op test は行動で測るもので、美意識で測るものではありません**：その一行を消して、agent の行動が変わるかを問います。通らなかった文は、**丸ごと削る**——言い換えるのではありません。意見が割れたときは、**その文書を走らせて**決着をつけます。議論はしません。判定基準は、文書が良くなると同時に短くなること、そして残りの少なさに驚くこと。もうひとつ、**同じことが二度書かれていない**こと（重複は「この文書は一度も試されていない」ことの最も確かな徴候です）。 単独 — grill-me ### アイデアはあるが、まだ形になっていない この skill が手に取るのは**ゆるいアイデア**です。それを材料にインタビューし、あなたがそれに踏み切れるようになるまで続きます。練り上げた計画がなくても始められます——**その計画を作ることこそが、この session の目的です**。そしてこの skill は**無状態**です。ファイルも書かず、作業場も残しません。残るのは、頭の中にある、より鋭くなった版だけです。題材はコードでなくてよく、repo も要りません。 **plan mode は切ってください。**これは agent に早く計画を出せと急かすもので、「問いの中に留まる」ことの正反対です。 **うまく回っているときの姿**：あなたが何かに異を唱えます——**一度も押し返さなかった session は、そもそも要らなかった session です**。質問は長い点滴ではなく「数回のラウンド」で届き、後のラウンドは前に言ったことの上に明らかに積み上がります。ある問いが、ずっと暗黙のうちに下していた決定を掘り返すので、予想しなかった場所にたどり着きます。終わるころには、どの選択もその場にいなかった人に向かって弁護できます。 **ラウンドを数えて、質問を数えないでください。**46 問を 4 ラウンドに分けるのは普通の一回です。200 問は範囲が大きすぎるという意味で、長すぎる session は **dumb zone**——つまり context window が埋まりすぎて質問の質が落ちる領域——へ漂っていきます。問い詰めが終わって腹が決まったら、**新しい session を開かないでください**。その会話の context こそが価値です。 ルーター — ask-matt ### どれを使えばいいのか分からない これは**勧めて、そこで止まります**。grill もせず、spec も書かず、ファイルも開かず、名指ししたばかりの skill を代わりに起動することもしません——手に入るのは「次に何を打つか」だけで、打つのはあなたです。渡してくる思考の単位は **flow**：単一の skill ではなく、skill を**貫く**一本の道筋のことです。 **知っておくべき正直な限界。**これは**手書き**の地図で、repo に遅れますし、この pack の skill しか知りません。しかも**「skill の半分は入っていない」と言ってきます**——既知で未修正です。routing される skill の大半は user-invoked で、harness はそれらを agent に注入する一覧に載せません。agent はその一覧を完全なものとして扱い、存在しないと報告します。**それらは入っています。** さらに、この skill は**他の skill の挙動を誤って説明することがあります**：skill 本体ではなく、自分が持つ一行の要約から答えるからです。ある詳細な報告では、単一の session の中で三回それが起きており、「thread を spec に変えるもの」という大雑把な印象だけで `to-spec`を飛ばすよう勧めた例も含まれていました。その `SKILL.md` ファイルは一度も開かれておらず、代償として本物の seam チェックが一回抜け、切り出したチケットは作業量を過小評価していました。**他の skill について効いている断言をしてきたら、まず開かせてください——その `SKILL.md`。** **位置づけ**：ask-matt はこの一式の上に立つ **secondary source**です。router と `SKILL.md` が食い違ったときは、`SKILL.md` のほうが正しいです。 07 ## 四つの完全なシナリオ 本流のシナリオは [第 05 節](https://taux.io/ja-JP/agent-dev-workflow#main-flow)にあります。ここでは、それ以外で最もよくある四つの状況を挙げます。 ### シナリオ A — 本番環境で断続的に出る 500 **状況**：顧客から「ときどき送信すると 500 が返る」と報告があり、自分では再現できません。 1. 他人からの報告なので、まず合流路に乗ります：`/triage`。報告者の手順で再現できますか。できなければ `needs-info`、あるいは今すぐ追うと決めます。 2. 今すぐ追うと決めたら、**session を開き直します**：`/diagnosing-bugs`、そして「まず赤くなるループを作ってくれ」と明言します。 Phase 1 だけが本当の関門で、見張るべきもそこだけ まず渡してもらうのは、**すでに実行済みで、出力が貼られていて、この bug で赤くなる**コマンドです。断続的な bug では、目標はきれいな再現ではなく**再現率を上げること**。**赤いコマンドがないうちは、Phase 2 に進ませないでください。**推測を始めたら引き戻します。 この先は機械的です：最小化（残った要素はどれも、なぜ効いているのかを言えること）、3 から 5 個の順位づけされた反証可能な仮説（**唯一の人間のチェックポイント**）、タグ付きのプローブを埋めること、**修正より先にリグレッションテストを書くこと**、後始末、そして当たった仮説を commit message に書くこと。 **知っておくべき分岐がひとつ**：そのリグレッションテストを置く正しい seam がないとき、この skill はそう言うべきで、偽の安心を与える浅いテストを書くべきではありません——**「seam がない」こと自体が発見です**。渡す先は `improve-codebase-architecture`。 ### シナリオ B — 誰も片づけていない legacy repo を引き継ぐ **状況**：八年目のプロジェクトに入ったばかり、あるいは vibe-coded な repo を引き継いだところです。ADR もなく、領域言語もなく、設計原則もありません。 1. **初日**：`/setup-matt-pocock-skills` で tracker と文書の配置を整えます。 2. **初日**：`/grill-with-docs`で、この既存の repo を `CONTEXT.md` を通して立ち上げてもらいます。覚悟すべきは**とても長い**インタビューです（ファイルが形になるまで 50 問以上かかったという報告もあります）。しかも能動的に舵を取ってください——この skill はコードを読み、見つけたものについて質問してきますが、**「コードにすでにある言葉のどれが正しい言葉か」を決めるのはあなたです**。 3. **二日目**：`/improve-codebase-architecture`を呼び、開口一番「問い詰めないで、まずレポートをください」と伝えます。**すべてが Speculative なら、実際には何も見つけられていないということです**。Strong の候補を一つ選びます。 4. **二日目**：候補は一度に一つ。その候補について grilling させ、成果物は diff ではなく「決定」です。そのあとに `to-spec`、`to-tickets`、`implement`。 5. **その後**：数日おきにアーキテクチャ点検をもう一度回して、メンテナンスとします。 なぜこの順番なのか 先に共通の語彙を作っておくと、アーキテクチャ点検の出力は格段に良くなります——候補が「Order intake モジュール」のような**あなたたちの名詞**で語られ、「FooBarHandler」ではなくなります。 **正直な期待値**：本当に収拾がつかなくなったプロジェクトでは「少しは助かったが、それでも足りない」という報告があります。八年もの legacy codebase では、モデルが同じ場所を堂々巡りするのを見た人もいて、一方で同じ skill が整った repo ではきれいな図を出してきます。**いまのところ、このケースを専門に扱う skill はありません。** ### シナリオ C — 大規模なグリーンフィールド案件 **状況**：新しいプロダクトモジュールをゼロから作る。道すじはまったく見えておらず、一回の対話で話しきれるものでないのは明らかです。 1. まず五つの `wayfinder:` label があることを確認します（存在しない label があると `gh` コマンドがそのまま失敗します）。 2. `/wayfinder`。最初にやるのは、**destination の命名**です。問われるのは「地図全体の目的地」であって、この session の目的地ではありません。**範囲は境界のはっきりした一つの epic まで絞ります**。「V1 の実装」ではいけません。 3. 幅優先の grilling を一度おこない、Destination、Decisions so far、霧、Out of scope を描き出します。霧とチケットを分ける判定基準は**その問いを「いま」正確に言えるかどうか**です。冒頭の grill で霧が一つも見つからなければ、「これは地図が要らないほど小さい」と言って止まるべきです。 4. research チケットは地図を描いている最中に発射され、並行で燃やします。ほかのチケットは**一度に一枚だけ**。自分に assign して引き受けます。 5. 一枚解くごとに、resolution のコメントを貼り、チケットを閉じ、地図に一行残して、そこで**止まる**。前方の霧を晴らし、いま言葉にできるようになったものを新しいチケットへ卒業させます。 6. 地図が空になったら：`/to-spec #`（渡すのは**メインの地図**で、個別の decision チケットではありません）。そのあとに `/to-tickets`、`/implement`。 **三つの致命的な落とし穴**は [第 06 節](https://taux.io/ja-JP/agent-dev-workflow#situations) の wayfinder の項目にすでに挙げてあります：agent が本番コードを書き始める、そして `to-spec`を飛ばさない、grilling チケットを並行で回さない。 ### シナリオ D — コードとまったく関係のない意思決定 **状況**：ビジネス上の判断を考えている——新しい製品ラインを立ち上げるか、提案の価格をどう決めるか、記事の論証の骨組みをどう組むか。 1. きれいな対話を一つ開きます（**どの repo の中にいる必要もありません**）。plan mode を切って、 `/grill-me`。 2. 一巡ずつ答え、番号を振ってまとめて返します。浅すぎる問いは押し返し、範囲がずれてきたら言葉にします。**「わかりません」は本当の答えです**。 3. 「実物を見ないと答えられない」問いに当たったら、それは ungrillable です。コード以外の場面ではたいてい、一枚の下書きを先に作る、一枚の表を先に計算する、顧客を一人先に捕まえる、のいずれかになります。 4. 「答えが他人の頭の中にある」問いに当たったら、**同じ会話の中で** `/to-questionnaire`。それをその人に送り、答えが返ってきたら次の一巡を開きます。 5. これはステートレスです：ファイルを書かず、ワークスペースも残しません。残るのは、あなたの頭の中にある、より鋭くなった版だけです。 08 ## 既知の落とし穴一覧 「最初に目にする症状」の順に並べています。**重大**は、お金か時間を無駄にするという意味です。 | 症状 | どの skill | 重大 | 対処法 | | ------------------------------------ | ----------------------------- | -- | ------------------------------------------------------------------------------------------ | | agent が一部の skill は入っていないと言う | ask-matt など | — | user-invoked skill はモデルの一覧に載りません。**入っているので、そのまま打てばよい**。正となるのは `.claude-plugin/plugin.json` | | `gh` が label は存在しないと言う | triage、wayfinder | — | setup **は label を作りません**。自分で `gh label create` を一度実行します | | インタビューが質問を一度に全部出し、推奨の答えもない | grill-with-docs | — | grilling か domain-modeling が読み込まれていません。**agent に「どの skill を読み込んだか」と聞く** | | インタビューは良いのに `CONTEXT.md` が変わらない | grill-with-docs | — | domain-modeling が読み込まれていません。名指しで呼び出します | | `CONTEXT.md` が 500 行以上に膨れ上がる | domain-modeling | — | 実装の詳細を吸収しています。簡潔にして実装の詳細を取り除くよう直接命じます | | spec の読み込みが途中で切れ続ける | to-spec → to-tickets | 重大 | 二つのステップの間では、**clear も compact もしない**。同じウィンドウで最後まで回します | | 3 行の変更が 12 枚のチケットに切られる | to-tickets | — | 詰問ステップでまとめるよう指示します。本当に小さいならそのまま implement して、これは使いません | | レイヤーごとに一枚のチケットに切られる | to-tickets | — | チケットごとに「終わったら何が demo できるか」を聞き、振る舞いを答えられないものが水平スライスです | | sub-issue にならず、blocked-by が本文に書かれるだけ | to-tickets | — | 既知の未修正です。あとから自分で `gh issue create --parent`、`--add-sub-issue`、`--blocked-by` | | 受け入れ条件が着手前にもう通っている | to-tickets | — | 一条ずつ「どんな観察がこれを偽だと示すか」を聞き、開始時の commit で赤になることを確かめます | | `/implement #2` がまったく無関係なことをする | implement | 重大 | `#2` は「見えている番号つきリストなら何でも」に対して解決されます。**完全な URL を渡し、タイトルを読み上げさせる** | | 終わってもチケットは開いたまま、受け入れ条件にチェックが入らない | implement | — | 想定どおりの動きで、締めくくりのステップがありません。**手でチケットを閉じる**と、依存の連鎖がようやく前に進みます | | code-review が私の変更を見ていないと言う | implement、code-review | — | HEAD との diff を取るので、commit していないものは入りません。**先に commit してから review** | | implement を並行で何本も回すと git の状態がおかしくなる | implement | 重大 | 同じ checkout では対応していません。worktree を使いますが、stash は共有のままです | | 組み込みの code-review と名前がぶつかる | code-review | — | 組み込みのほうを外すか、fork して別名にします | | review の sub-agent がさらに agent を生む | code-review | 重大 | 既知の未修正で、一度は 50 個以上まで増えました。**無人で回すときは agent の数を見張る**。fork には再生成を禁じる一行を足します | | review が回すたびに新しい問題を見つける | code-review | — | 収束する保証はありません。手がかりの一覧として扱い、明文のルールに裏づけられたものだけ直して、そこで**やめる** | | research が 450k token を焼く | research | 重大 | nesting bug（issue 530）で、自分自身をもう一つ生みます。**呼び出したあと、バックグラウンドのタスク一覧を確認する** | | 一言の答えがほしいだけなのに、再現環境を作りにいく | diagnosing-bugs | — | 「診断せずに直接答えて」と言うか、その model invocation を切ります | | テストより先に実装を書く | tdd | — | 起こります。skill はこの点を抱えたまま生きています。あるスライスで厳密にやりたいなら、見張りながら回します | | 先にブラウザテストを書いて堂々巡りする | tdd | — | repo の指示ファイルで宣言します：browser テストは振る舞いが動いたあとに書く | | アーキテクチャのレポートを開いてもスタイルも図もない | improve-codebase-architecture | — | 外部 CDN が遮断されています。inline CSS と手書きの SVG を使わせます | | 一時間問い詰めてくるだけで選択肢をくれない | improve-codebase-architecture | — | 呼ぶときに「問い詰めないで、そのままレポートをください」と言います | | 語彙層に「開始」と言って 100k token を焼く | codebase-design | 重大 | これには流れがありません。**driver となる skill を名指しし、その下に座らせる** | | wayfinder の agent が本番コードを書き始める | wayfinder | 重大 | Notes は「計画のみで実行しない」を上書きでき、その Notes は agent が書いています。**先に Notes を読む** | | 27 枚のチケットのうち 13 枚目まで来たら全部が的外れ | wayfinder | — | 範囲を境界のある一つの epic に絞り、積極的に prototype します | | grilling が一問ごとに三段落で、疲れる | wayfinder、grilling | — | reasoning effort を下げ、グローバルの指示ファイルに平易な一文を足します。**未解決** | | handoff のファイルが消える | handoff | — | 一時ディレクトリは消されます。**パスを聞き、必要なら自分で永続する場所へコピーする** | | コースがグローバルの skill ディレクトリに書き込まれる | teach | 重大 | issue 377。**ディレクトリ名をはっきり伝え、第一課がどこに落ちるかを先に確かめる** | | 小テストの正解がいつも A | teach | — | 既知の未修正です（33 回すべて的中）。位置には意味がないものとして扱うか、render のときにシャッフルする部品を求めます | | wizard で打ち間違えて一つ前に戻りたい | wizard | — | 戻る手段はありません。中断して回し直します（保存済みの値が既定値になります）。方向キーには bug があるので backspace を使います | | 自分で書き換えた `SKILL.md`。更新後に消えた | すべて | 重大 | `npx skills update` が上書きし、plugin は読み取り専用。**長期的な振る舞いは自分の指示ファイルに書く** | 09 ## 自分の指示ファイルに入れるとよいもの これは「公式の経路でカスタマイズする」やり方です——**skill のファイルを書き換えると上書きされますが、ここは上書きされません**。全体をそのままコピーして構いません。貼り先は自分の `CLAUDE.md` か `AGENTS.md`。 ``` ## Agent behaviour - When grilling, ask one question at a time. - Do not start implementing without my explicit permission. - Browser and end-to-end tests are written after the behaviour works, never as the first red test. - Keep questions and recommendations short. One paragraph maximum per question. - When a skill asserts something about another skill's behaviour, open that skill's SKILL.md before acting on it. - code-review sub-agents must not invoke /code-review or spawn additional agents; perform the review directly. ``` 各行が防いでいるもの * **一度に一問**：一問ずつのリズムに戻します。読むのが遅い人、第二言語で読む人、集中の足場が要る人におすすめです。 * **許可なく実装を始めない**：grilling が frontier を空にしたあと勝手に作り始めるのを防ぎます。弱いモデルや低い effort のときに起こります。 * **ブラウザテストは最後に書く**：tdd が先に Playwright を書いて堂々巡りになるのを防ぎます。 * **質問と提案は短く**：wayfinder と grilling の冗長さを和らげます。 * **まず開くのは、主張の対象になっている `SKILL.md`**：ask-matt が自分の要約で別の skill を誤って説明するのを防ぎます。 * **review の sub-agent はさらに agent を生成しない**：暴走する fan-out を防ぎます。fork したユーザーが実測で効果を確かめた一行です。 10 ## 中核の用語 これらの語は skill 群に共通する言語です。**意味が取れなければ、skill の出力も読めません。** | 用語 | 語義 | | ------------------------------ | ------------------------------------------------------------------------------------------ | | Seam | そこを編集しなくても振る舞いを変えられる場所。テストは seam の上に載る。seam はインターフェースの**位置** | | Pre-agreed seam | コードを書く前に合意しておいた seam。テストが長持ちする理由——下の実装を書き直してもテストはそのまま | | Tracer bullet | すべての層を貫く細いが完全な一本の道。落ちた瞬間から単独で demo できる | | Vertical / horizontal slice | 垂直は一本の道がすべての層を貫く（正しい）。水平は一度に一層（誤り、最もよくある失敗） | | Deep / shallow module | 深いほうは小さなインターフェースの後ろに大量の振る舞い。浅いほうはインターフェースが実装とほぼ同じ複雑さ | | Deletion test | このモジュールを消したと想像する：複雑さがより小さなインターフェースの後ろに**集約**、これは残す価値がある。それとも呼び出し側に**拡散**、それなら pass-through | | Locality / Leverage | Locality は保守する側が得るもの（変更が一か所に集まる）。Leverage は呼び出す側が得るもの（インターフェースを一単位学ぶごとに得られる能力が増える） | | Design tree / Frontier / Round | 設計ツリーは決定にぶら下がる決定。frontier は前提条件がすべて解決済みの決定の集合。1 round は frontier 全体を一度に問い切ること | | Grillable / ungrillable | 話し合いで詰められる問い。対して、反応する対象が要る問い（後者は prototype へ） | | Fog of war | wayfinder の地図上で「来るのは見えるが、まだ正確に言葉にできない」決定 | | Decision ticket | wayfinder の単位：一つの問いを抱えるもの（解決すると決定が出る）。これは**決して**実行するビルドのスライスではない | | Destination | wayfinder の地図一枚全体の終着点の姿。地図を描く最初の一手はそれに名前をつけること | | Spec / Ticket | spec は目的地とそれを固定する決定（残す）。ticket はそこへ至る実行の手順（使ったら捨てる） | | Primary / secondary source | 一次資料は対話そのもの、commit、公式ドキュメント、ソースコード。二次資料はあらゆる要約。**食い違ったら一次資料を採る** | | Context pointer | context の中にあって、context の外の材料を名指しし、「いつ取りに行くか」まで書き込んだ参照 | | Progressive disclosure | ある分岐だけが必要とする参考資料を pointer の後ろへ移し、主ファイルを読める状態に保つこと | | Context load / Cognitive load | 前者は常時読み込まれる材料がモデルのウィンドウで払うコスト。後者は「どんな文書があり、いつ使うか」を**あなた**が負うコスト | | No-op | 消しても agent の振る舞いが変わらない一行。context を払っているのに何も変えていない | | Leading word | モデルの事前学習にすでにある圧縮された概念（tight、red、tracer bullet）。agent はそれを使って考える | | Storage strength / fluency | 長期の保持。対して、その場での思い出しやすさ（後者は読んでいる間は習得した気になり、一週間後には消える） | | Smart zone / dumb zone | context window にまだ余裕がある状態。対して、品質が落ちるほど埋まった状態 | | HITL / AFK | 人間がループの中にいる（生きたやり取りでしか解けない）。対して、その場にいなくても走り切る | | Phase boundary | 二つの作業の間。「自分の context をどうするか」を問うべき唯一の場所 | | Expand–migrate–contract | 広域リファクタリングの三段階：新しい形を古い形の隣に足す、呼び出し箇所を小分けに移す、呼ぶ人がいなくなってから古いほうを消す | 11 ## 七つのアンチパターン この仕組みが最もよく壊れる使われ方です。 1. **受け身の grilling。**「同意」と四十回答えた末に出てくるのは、agent が書いてあなたが頷いただけの計画です。**一度も押し返さなかった session は、必要のなかった session です。** 2. **to-spec と to-tickets の間で clear や compact をする。**問い詰めて引き出したものの大半は、その context window の中にしかありません。ここで切ると、spec はあなたが本当に決めたことを静かに取りこぼします。 3. **自分で生成したチケットに triage をかける。** `to-tickets` が出すチケットは構造上すでに agent-ready です。triage は**他人**が投げ込んできた仕事のための合流路です。 4. **範囲がきちんと切れている機能に wayfinder を持ち出す。**判定基準は **session の数**です。一つの対話に収まるなら使うのは `grill-with-docs`。そのほうが安く、質も上です。 5. **語彙層をドライバーとして使う。**たとえば `codebase-design` か `domain-modeling` に「始めよう」と言うと、agent は自分で流れを発明し、大量の token を燃やします。driver を名指ししてください。 6. **review をコードを書いたのと同じ session で走らせる。**同じ context で自分を審査するのは review ではなく、slash command を付けた確証バイアスです。 7. **カスタマイズのために `SKILL.md` を書き換える。**更新で上書きされますし、plugin でのインストールはそもそも読み取り専用です。長期的な振る舞いは自分の指示ファイルに書いてください。 もう一つ、メタなアンチパターン これを「流れがあるから考えなくていい」と受け取ること。作者が README で取っている立場は逆です——**流れを引き受けてしまう**たぐいのやり方は、助けてくれる代わりにあなたの制御を取り上げ、流れ自体の bug を直しにくくします。この skill 群は意図して小さく、書き換えやすく、組み合わせられるように作られています。**出力の品質は、問いの数ではなく、あなたの答えの品質に追随します。** 12 ## 14 日間の学習プラン 1 日あたり 30 分から 60 分ほど、対象は**自分の本物のプロジェクト**。 | 日 | やること | 合格の目安 | | -- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- | | 01 | [三つの土台となる考え方](https://taux.io/ja-JP/agent-dev-workflow#concepts)に目を通す。plugin か skills.sh を入れる（**どちらか一方**）。repo を一つ選んで setup を走らせる。label を作る | `docs/agents/` に三つのファイルがある。指示ファイルには `## Agent skills` | | 02 | `/grill-me` で**コード以外**の決定を問い詰める。「押し返す」を意識して練習する | 押し返しが 3 回以上。その場にいなかった人に対して、どの選択も弁護できる | | 03 | `/grill-with-docs` で、既存の repo に小さな機能ひとつ分のインタビューをかける | `CONTEXT.md` が進行中に一行ずつ育つ。ADR は 0 から 1 本 | | 04 | 同じ対話のまま進む先は `/to-spec`。seam と out-of-scope の二節をしっかり読む | spec の中のどの決定も、自分が下した覚えがある | | 05 | 同じウィンドウのまま進む先は `/to-tickets`。詰問ステップでチケットごとに「何を demo できるか」を聞く | どのチケットも振る舞いを demo できる。一番上のチケットにブロッカーがない | | 06 | `/implement` で最初のチケットをやる（**完全な URL**）。trace を最後まで見る | trace の中に `tdd` の呼び出しが見える。commit まで到達する | | 07 | 新しい session で走らせるのは `/code-review main`。引用を一つずつ追う | 分かれた二つのレポート。**発見を少なくとも一つ却下している** | | 08 | `codebase-design` の用語集を読み、流れではなく辞書として扱う | 設計の対話に component、service、boundary が出てこなくなる | | 09 | 「話し合いでは詰められない」問いに当たったら、走らせるのは `/prototype` | 共有できる HTML ファイル一つ、または構造的に異なるいくつかのバリアント。答えは一行 | | 10 | 本物の bug に対して走らせるのは `/diagnosing-bugs`。Phase 1 の gate を注視する | **最初の理論より先に、赤いコマンド出力を見ている** | | 11 | `/improve-codebase-architecture`（「まずレポートを」と言うのを忘れずに）。Strong の候補を一つ選ぶ | HTML のレポート。候補が一つ、問い詰められて決定になっている | | 12 | `/handoff` で「分岐」を一度練習する。主の対話は残したまま、並行する session を一つ開く | 元の session はその場に残る。新しい agent は説明し直さなくてもすぐ着手できる | | 13 | 練習するのは `/wait-what` と `/to-questionnaire`。そして [第 09 節](https://taux.io/ja-JP/agent-dev-workflow#claude-md) の内容を指示ファイルに書き込む | 言い直しが「より短く、より明確」になる。質問票はそのまま送り出せる | | 14 | 本当に大きすぎる仕事を一つ選んで走らせるのは `/wayfinder`。範囲を境界のある epic まで絞る | destination がどのチケットよりも先に書き出されている。開いているチケットはどれも一つの問いとして読める | そのあとのリズム：本流は毎日、アーキテクチャの点検は数日に一度、`/teach` は技能を補う必要が出たときに専用のディレクトリを開きます。 13 ## 1 ページのチートシート repo ごとに一度 * `/setup-matt-pocock-skills` — tracker、label とドキュメントの配置 本流（アイデアから ship まで） * `/grill-with-docs` — repo あり、単一の session で話し切れる * `/to-spec` — session をまたぐときだけ必要。同じウィンドウで、clear しない * `/to-tickets` — tracer bullet に切り分け、ブロッキングエッジを宣言。同じウィンドウ * `/implement <完全な ticket URL>` — 1 チケットに 1 session、あいだで clear * `/code-review ` — きれいな session で走らせる。先に commit 合流路 * `/triage` — 他人が投げ込んできた issue * `/wayfinder` — 一つの session に収まらない。clear のあと戻る先は `/to-spec` * `/improve-codebase-architecture` — 数日に一度の構造の点検 いつでも * `/grill-me` — repo なし、ファイルなし。テーマはコードでなくてよい * `/prototype` — 話しても決まらない設計の問い、一度に一つ * `/research` — 外部の事実。バックグラウンドで走らせ、二つ生まれていないか確認 * `/diagnosing-bugs` — 難しい bug。赤いループができてから推測 * `/resolving-merge-conflicts` — すでにコンフリクトにはまっている * `/wizard` — 人間にしかできない手作業の手順 * `/handoff` — 引っ越させるものがある、または枝を分岐させる * `/to-questionnaire` — 答えが他人の頭の中にある * `/wait-what` — さっきの部分が分からなかった * `/teach` — 何日もかけて一つのテーマを学ぶ * `/ask-matt` — どれを使うか分からない。提案して止まる 語彙層、ドライバーとして使わない `codebase-design`、`domain-modeling`、`grilling`、`writing-for-agents` Phase boundary の五択、上から順に判断 継続 → clear → handoff → subagent → compact 出典 ## このチュートリアルは何にもとづいて書かれたか もとにしたのは [mattpocock/skills](https://github.com/mattpocock/skills) plugin **1.2.3 版**（公開済みの 25 個の skill）です。その repo の `README.md`、`CONTEXT.md`、25 本の公式 skill ドキュメント、`.claude-plugin/plugin.json` と `CHANGELOG.md` を読んだうえで整理し、書き直しました。この repo は **MIT** ライセンスで公開されています。 **本ページは TauX が独自に書き下ろした日本語のチュートリアルであり、公式ドキュメントの翻訳でも転載でもありません。**skill そのもの、その名称、その挙動は原作者に帰属します。本ページの構成、判定基準、訳語、そしてすべての論評は TauX が書いたものであり、**原作者の立場を代弁するものではありません**。 本文中の issue 番号はすべてその repo の issue で、**執筆時点では多くがまだ開いています**。これは二つのことを意味します。落とし穴は本物であり、そしてすでに直っているかもしれない、ということです。**動かしてみて妙なことが起きたら、まずその repo で症状を検索してください**——固定で書き込まれた落とし穴の一覧にとって最良の結末は、いつの日かそのすべてが期限切れになることです。 バージョン表記はここでは飾りではありません。この skill 群は変化が速く（`to-prd` は v1.1 で改名されて今は `to-spec`、`tdd` の refactor 段階は 2026 年 6 月に削除されました）、**バージョン番号のないチュートリアルでは、どの部分がまだ有効なのか読者には判断できません**。 ## このワークフローを自分のチームに組み込みたい方へ ツールは公開されています。難しいのは、すでにある tracker、規範、納品のリズムにつなぎ込むところです。そこは私たちがやってきました。 [相談を予約する](mailto:hello@taux.io) [企業向け AI 導入と社内研修を見る](https://taux.io/ja-JP/ai-smart-work)