--- name: steering description: "Spec-driven plan を steering に落とす。Design合意→Tasklist合意で終了。実装は別コマンド。明示的に指定されたときはもちろん、軽度の修正でない場合（複数ファイルの編集、ステップを持つ修正）にはこのスキルを起動する" allowed-tools: Read, Grep, Write, Edit, Bash model: sonnet effort: high --- # Steering Skill ## 入力 - ユーザー入力（/plan の引数）: **やりたいこと** --- ## ゴール `.steering/.../design.md` を作って合意し、その後 `.steering/.../tasklist.md`（詳細タスク）を作って合意して終了する。 **このスキルはtasklistが完全に出来上がり合意できるまで実装しない**。 ## 注意事項 会話は日本語で行うこと。 --- ## 命名規則（固定） ディレクトリ名: - `.steering/[YYYY]/[YYYYMM]/[YYYYMMDD]-[branch]-[slug]/` ### YYYYMMDD - 実行日 ### branch - **現在のブランチをそのまま使う** - `git rev-parse --abbrev-ref HEAD` - 取得できない場合は `unknown-branch` ### slug - ユーザー入力（やりたいこと）を **英語要約**し、`kebab-case` にする（英数+ハイフン） - ルール: - 3〜8語程度を目安に短く - 冠詞は落としてよい（a/the） - 動詞＋目的語の形を優先（例: `edit-user-profile`, `add-payment-webhook`） - あいまいなら「何をするか」が伝わる最小まで（例: `profile-edit` ではなく `edit-user-profile`） ※ slug は最初に提案し、以降は **同じものを固定して使う**（途中で変えない） --- ## 成果物 - `design.md`（requirements相当を内包） - `requirements.md`（必要時のみ。design から切り出し） - `tasklist.md`（詳細タスク。実行はしない） - `discussion.md`（任意。五月雨に起こった思考過程・**実装前**設計議論の保存場所） - `implementation_review.md`（任意。**実装完了後**レビューで判明した漏れ・追加要件の収集場所） - discussion.md は実装前の設計議論、implementation_review.md は実装後フィードバック - 複数のフィードバックが揃ったら、新しい steering を起動して設計・タスク整理を行う - 整理された追加タスクは **既存の tasklist.md に追記する** - 理由: tasklist は「この機能を完成させるためのチェックリスト」。納品物は tasklist ではなく機能であり、追加要件が判明しても同じ機能の完成を目指す以上、tasklist は生き続ける --- ### discussion.md の使い方（随時） 五月雨に起こった思考過程を保存する場所。特定のフェーズには縛られず、記録の価値がある思考が生まれたときに随時追記する。 **MUST: 自動記録トリガー** - **ユーザーが論点・質問・要議論を提起した時点で discussion.md に記録する**（往復数は問わない） - **Claude が自発的に深めた議論も、2往復以上になったら記録する** - 「言われたら書く」ではなく「議題が生まれた時点で書く」。揮発を防ぐのが目的 - やってしまいがちな失敗: 「1往復で終わったから記録不要」と判断する → 往復数は記録の基準ではない - 記録タイミング: 論点が提起された直後（収束を待たず、未決定のまま記録してよい） **フィードバックループパターン（MUST）** - ユーザーからフィードバック（指摘・修正意見）を受けたとき、次の提案を出す前に現時点の提案を discussion.md にイテレーションとして記録する - 「記録して」と言われなくても自動で行う - やってしまいがちな失敗: フィードバックを受けてすぐ次の提案を出す → 提案の変遷が揮発する - 「ok」= 確定版への合意。途中フィードバック応答とは区別する - 「ok」が出た時点で決定として記録し、ネクストアクションに進む - 微修正（表現・用語調整で論旨が変わらない）はイテレーション番号を繰り上げない - 繰り上げるのは「提案の内容・方向性が変わったとき」のみ **主な用途:** - 設計前の認識合わせ（pre-design 議論）: 複数の選択肢を往復して検討した過程 - 設計中に生まれた疑問・文脈メモ: 成果物には入らないが捨てたくない思考 - こぼれ話: design.md / investigation.md / tasklist.md に収まらない判断の背景 **investigation.md との違い:** - investigation.md: 「事実を集めないと方針が決まらない」ときのファクト収集ログ - discussion.md: 「どう考えたか」の思考過程ログ（事実収集ではなく推論・議論） **エントリフォーマット（MUST）:** ```markdown ## 論点N: タイトル **提起の背景:** （既存の設計・認識の何が問題だったか・何が不確かだったか） ### 議論の変遷 #### 事象の記述 - （何が起きたか。具体的な出来事として記述する） #### 原因の追跡 - なぜ: ... - なぜ: ... - なぜ: ...（「これを解消すれば再発しない」と言えるレベルまで） #### 根本原因₀ + 提案₀ - **根本原因₀**: ... - **提案₀**: - 総論: ... - 各論: - ルール: ...（「〜のときは〜する」形式の規則本文） - 適用例: ...（ルールが当てはまるケース） #### イテレーションN（N=1,2,...） ##### 検証 - **観点**: （誰が・何を指摘したか、または何に気づいたか） - **弱点**: ... ##### 修正先の判断 - **提案レベル** または **診断レベルへの遡及**: ... ##### 根本原因N + 提案N - **根本原因N**: ... - **変更点**: （何が変わったか・なぜ変えたか） - **提案N（現時点）**: - 総論: ... - 各論: - ルール: ... - 適用例: ... **決定:** （端的な結論ステータス + 採用した提案の要点。未決の場合は「未決（理由）」） **ネクストアクション:** （この決定の結果として何をするか。SKILL.md 更新・tasklist 追加・実装など。なければ「なし」） - **MUST: 記録タイミング**: 「どのファイルのどの部分にどう変えるか」まで各論で合意が取れた状態でのみ書く - 方向性（総論）だけ合意の段階では書かない。「未決（各論を詰める）」とする - やってしまいがちな失敗: 提案の方向性に合意が取れた時点でネクストアクションに実装タスクを書く → その後に各論の議論が必要になり、ネクストアクションが実際には「あとは適用するだけ」ではなかった状態になる ``` - 「論点N」形式で連番を振る（`論点1`, `論点2`, ...）。会話中に「論点3について」と参照できるようにするため - **MUST: タイトルと提起の背景は「表面の質問」ではなく「その質問が生まれた設計上の問題」を書く** - やってしまいがちな失敗: 「〇〇は△△か？」という質問をそのままタイトルにする → 読んでも「なぜこれが問題だったか」が分からない - 正しい問い: 「この質問はどんな設計上の問題・認識のズレから生まれたか？」→ その問題をタイトルに据える - 悪い例: 「Business::Food::MealFrame は dish, meal と並列の存在か」（表面の質問） - 良い例: 「MealFrameEntry はどのドメインに帰属するか」（設計上の問題） - `提起の背景` には「既存の設計の何が問題だったか・何が不確かだったか」を書く - **MUST: 議論の変遷を省略しない**。結論だけ書いても「なぜそうなったか・何の認識のズレがあったか」が振り返れない - やってしまいがちな失敗: 「回答:〇〇」「決定:〇〇」だけ書いて変遷を省く - 特に**初期の認識が間違っていて覆った場合**は、最初の誤った認識も含めて記録する - **MUST: 各項目を1行に収めない**。思考の深さをそのまま書く。1行に収まっている項目は総論に留まっているサイン - テンプレート: `.claude/skills/steering/templates/discussion_entry.md` --- ## フロー（順序固定） ### 1) steering ディレクトリ作成 1. `[YYYYMMDD]`, `[YYYYMM]`, `[branch]`, `[slug]` を決める 2. `.steering/[YYYY]/[YYYYMM]/` ディレクトリが存在しなければ作成する - 例: `.steering/2026/202604/` 3. `.steering/[YYYY]/[YYYYMM]/[YYYYMMDD]-[branch]-[slug]/` を作成する 4. `.claude/skills/steering/templates/summary_entry.md` を参照して、対応する月の `summary.md` にエントリを追記する - `summary.md` が存在しなければ `# [YYYY]年[MM]月 Steering サマリー` のヘッダで新規作成する - タスク steering: タスクバリアントで追記。**ステータス: 未完了** - ロードマップ steering: ロードマップバリアントで追記。**ステータス: 未完了** - 親ロードマップがある場合は「**関連:** 親ロードマップ: ...」を記載する 5. `.claude/skills/steering/templates/design.md` を元に `design.md` を作成する > この時点では tasklist は作らない --- ### 2) 読み取り調査（Designの根拠を集める） - `CLAUDE.md` があれば読む - `docs/` があれば読む - **プロジェクトのコーディング規約を読む**: - `backend/docs/ai_guideline/development_standard/formatting.md` (Rubocop実行方針) - `frontend/docs/ai_guideline/development_standard/formatting.md` (ESLint/Prettier実行方針) - Grep で類似実装を探す - 類似機能 - 命名 - 例外処理 - テスト方針 - レイヤ/責務境界 - **GraphQL mutation / Command の変更・追加を含む場合（MUST）**: - 関連モジュールの README を先に読み、オーケストレーションパターンを把握する - README に記載がない場合のみ、既存の関連 resolver の実装を読む - 把握すべき観点: 「どのドメイン集約が、どのレイヤで、どう組み合わされているか」 - **コードを読んで初めて分かった知識は、次回コードを読まずに済むよう即座に doc-enricher を呼んで README に反映する** - 理由: コードを読む都度コンテキストを消費する。README にエッセンスが書いてあれば次回は読まずに済む - **UI挙動・表示に関するタスクの場合（MUST）**: - `visual-inspector` サブエージェントを使ってスクリーンショットを撮り、現状の実際の動作をファクトとして確認する - 「コードを読んだ推測」ではなく「実際に見た事実」を design.md の根拠にする - 例: ヘッダが固定されているか、スクロール時の挙動、レイアウト崩れ等 - ⚠️ Playwright ツールを直接呼び出すことは禁止。必ず `Agent(subagent_type="visual-inspector")` を使うこと --- ### 3) design.md を埋める（requirements相当をここに含める） #### MUST（design.md 記入前）: 変更・拡張する対象の既存仕様確認 設計を始める前に、以下を確認すること。 - **ルール**: 1. **現在のコードを読む**: 変更対象の現在の実装がどうなっているかを確認する（コードは Single of Truth） 2. **明示的に与えられた参照を確認する**: ユーザーが言及したデザインファイル・仕様・ロードマップ・過去 feature など、明示的に示された参照がある場合は必ず確認する 3. 確認した内容は前提として設計する。感覚・推測で上書きしない - **禁止パターン**: 与えられた参照を無視して「だいたいこういう感じ」という感覚的な判断で設計を始める - 失敗例: 「v0 デザインを参考にして」と言われていたのに確認せずにノリで枠ラベルを実装した - **適用例**: - UI コンポーネントに要素を追加する → 変更対象コンポーネントの現在の実装を読む - 「このデザインを参考に」と言われた → そのデザインファイルを確認してから設計する - ロードマップと連結した steering → ロードマップを確認する - 確認した既存仕様は design.md の `## 前提とする既存仕様` に要点を記載する --- #### この構成の思想 design.md の失敗パターンは「変更点の列挙」になることだ。変更点を全部書き終えても、「作り終わった世界がどうなっているか」の認識が揃っていなければ設計は完了していない。 - **変更点の列挙**: 「何をビルドするか」の視点。どのファイルに何を加えるかは分かる - **完成後の姿**: 「ビルドした後の世界」の視点。ユーザーが操作したとき何が起きるか、データはどう見えるか、ドメインは何と呼ぶかが分かる 変更点を全部正確に列挙しても、「誰が何を何回呼ぶか」「`assign_meal` か `set_meal_id` か」という認識がずれたまま実装が始まることは起きる。なぜなら変更点の列挙はそれを問わないから。design.md は「完成後の世界を事前に揃える」ための文書であり、変更点一覧はその補足（付録）にすぎない。 --- design.md の構成（順序固定）: ``` 1. TL;DR（2〜4文） 2. 要件（Requirements） 3. 完成後の姿 ← 中心。1〜2 は前提、4〜6 は根拠と担保 3-1. 操作フロー 3-2. データモデル 3-3. クラス・API 設計 4. なぜこの姿か（設計判断） 5. リスクと対策 6. テスト方針 （付録）変更点一覧 ← 補足。設計の中心ではない ``` --- #### 1. TL;DR 2〜4文で「何を作るか・なぜか」を示す。 --- #### 2. 要件（Requirements） - MUST/SHOULD/MAY と非目標、受け入れ基準を記載する - **MUST: ユーザー入力に以下のシグナルがある要件は、MUST/SHOULD/MAY に分類せず「要議論」として別立てにすること** - 「〜ならdropしてもいい」「大切かもしれない」などの迷い - トレードオフへの言及（「世間の潮流」「将来の恩恵」など） - 条件付きの意思（「〜だったら残したい」） - 分類（MUST/SHOULD/MAY）は議論の結果として確定するもの。議論前に勝手に格付けしない --- #### 3. 完成後の姿（MUST） 3つのサブセクションは「完成した世界を3つの異なる視点で切り取ったもの」。どれか1つが欠けると認識が揃わない。 - **3-1 操作フロー（動的な視点）**: 「ユーザーが何かしたとき何が起きるか」。フロントエンドが何を何回呼ぶか、バックエンドで何が起きるか、データがどう変わるか。これがないと mutation の引数・呼び出し順序で認識がずれる - **3-2 データモデル（静的な視点）**: 「完成後のデータはどうなっているか」。スキーマ定義だけでは整合性が確認できない。具体的な行データで「このケースは表現できるか」を確認する - **3-3 クラス・API 設計（命名の視点）**: 「ドメインは何を何と呼ぶか」。命名は「実装詳細」ではなく「ドメインが何をしているかの宣言」。`assign_meal` と `set_meal_id` では伝わる意図が全く違う。操作フローに埋め込むと「機械的実装詳細」として読まれる。独立したセクションに置くことで「命名は設計である」という位置づけを構造で示す ##### 3-1. 操作フロー（動的な視点） - ユーザー操作 → フロントエンドの呼び出し（mutation 名・引数）→ バックエンドのクラス・メソッド → データ変化 を一気通貫で示す - 典型ケースを1〜3つ、番号付きステップで示すこと - 例: ``` ① ユーザーが FrameCard をクリック ② フロントエンドが addMeal(dish_id: 5, meal: { date, meal_type }, frame_entry_id: 1) を呼ぶ ③ resolver: Meal::Usecase::AddCommand.call(...) → meals: id=10 作成 ④ resolver: FrameEntry::Usecase::FillWithMealCommand.call(meal_frame_entry_id: 1, meal_id: 10) → root.assign_meal(10) → persist ⑤ meal_frame_entries.id=1 の meal_id が 10 にセットされる ⑥ カレンダーに DishCard「スパゲティ」＋「枠: パスタ」ラベルが表示される ``` - やってしまいがちな失敗: データ例だけ書いて操作フローがない → mutation の引数・呼び出し順序で認識がずれる - 正しい判断のための問い: 「このフローを読めば、フロントエンドが何を何回呼ぶか・バックエンドで何が起きるかが、コードを読まずに分かるか？」 ##### 3-2. データモデル（静的な視点） - **新規エンティティを設計する場合（MUST）**: - `user_id` を持つか確認する - 持つ場合は、CRUD（作成・更新・削除）全体のスコープを明示する - 理由: `user_id` を持つエンティティはユーザーが能動的に管理するものであり、原則 CRUD が必要になる。「マスタ」という言葉は「静的な参照データ」を暗示し、CRUD の必要性を見落とす原因になる - やってしまいがちな行動: 「マスタテーブル」と呼んで作成のみ設計し、更新・削除を後から追加する羽目になる - **データモデルを含む場合（MUST）**: - 全テーブルが揃った状態の**具体的なデータ例**（行データ）を示すこと - 抽象的なスキーマ定義だけでは整合性の検証ができない。実際の値でデータが成立するか確認する - 典型ケースを複数示す（例: 「枠のみ登録」「枠に料理割当済」「通常の食事」） - 設計の問いに答える形で示す（例: 「同じ枠を複数日に使えるか？」→ データ例で答える） ##### 3-3. クラス・API 設計（命名は設計） 命名はコードの肝。「具体的な実装詳細を早めに決める」のではなく「ドメインが何をしているかの宣言を事前に揃える」行為。操作フローに埋め込まず独立させることで「これは設計の一部だ」と位置づけを明示する。 - **ビジネスロジックを変更・追加する場合（MUST）**: - 新設するドメインモデル・Command のクラス名を明示する - 新設するクラスに必要な public メソッド名（ドメインの行為・意図を表す動詞）を列挙する - mutation を変更・追加する場合は、mutation 名と引数シグネチャを示す - **各命名の根拠を添える**（「なぜ `assign_meal` で `set_meal_id` ではないか」など） - 目的: 実装前に命名の認識を揃え、「実装してみたら名前が合っていなかった」という手戻りを防ぐ - やってしまいがちな行動: クラス名だけ書いてメソッドは実装時まかせにする → `set_xx` / `update_xx` 系の禁止命名が実装段階で紛れ込む - 正しい命名の問い: 「このメソッド名はドメインで何が起きているかを伝えているか？`set_` / `update_` になっていないか？」 - コード例の含め方（ユーザーから求められなくても自発的に判断する）: - 以下に該当する場合はコード例を含めること: - 複数ファイル・レイヤーにまたがる変更で連動箇所が非自明な場合 - 既存パターンと異なる実装が必要な場合 - 実装後の認識ズレが手戻りにつながりそうな場合 - コード例は変更の要点が伝わる最小限でよい（完全な実装は不要） --- #### 4. なぜこの姿か（設計判断） 3. で示した完成後の姿を「なぜこの形にしたか」を示す。設計の根拠と、採用しなかった代替案の棄却理由を記載する。 - 設計選択の理由（既存パターン適合） - 代替案（最低1つ）と棄却理由 --- #### 5. リスクと対策 --- #### 6. テスト方針 --- #### （付録）変更点一覧 どこに何を足す/変えるかの列挙。実装時の参照用。 この欄は「設計」ではなく「設計から導き出されたタスクの前捌き」。変更点を全部正確に書いても、3. 完成後の姿が書けていなければ設計は完了していない。付録に置く理由はそれを構造で示すため。 --- ### 4) Designレビュー（自然言語 yes/no） - **MUST: design.md を保存する前に、「要議論」項目があればまずチャットで議論して方針を確定させること。議論が終わったら確定した分類（MUST/SHOULD/MAY または非目標）を design.md に反映する。** - **MUST: 要議論の議論内容を design.md に保存すること** - 議論して決定した内容は「事前設計議論メモ」セクションとして design.md に追記する - 保存内容: 論点・選択肢・決定理由（チャットのやり取りをそのまま揮発させない） - 目的: 実装者（未来の自分を含む）が「なぜこの設計選択をしたか」を遡れるようにする - セクション名: `## 事前設計議論メモ（揮発防止）` - design.md を保存したら、チャットで要点を短く示してレビュー依頼 - ユーザーが OK/はい/進めて 等なら次へ - 修正なら design.md を更新して再レビュー（OKまで繰り返し） - **承認キーワード強制は禁止** --- ### 5) requirements.md の切り出し（必要時のみ） - design.md 内の Requirements セクションが「長くて独立させた方がレビューしやすい」と判断した場合のみ: 1. `requirements.md` を作成 2. design.md から Requirements を移し、design.md 側は参照リンクにする ※ Requirements が短い/軽いなら切り出さない（design.md に置いたまま） --- ### 6) tasklist.md（詳細）を作る（Design合意後のみ） > ⚠️ tasklist を作る前に、以下の2パターンのどちらに該当するか判断すること。 #### パターンA: 複数のMVPに分かれる場合（親子 steering） - 判断基準: **「このフィーチャーは1つのMVPで成立するか？」** - MVP単位でなら tasklist は1つでよい（フェーズが多くても構わない） - MVPが2つ以上に分かれる、またはスコープにバリエーション（A案/B案）がある場合は roadmap - 「フェーズが多い」だけでは roadmap を選ぶ理由にならない - `.claude/skills/steering/templates/roadmap.md` を元に `roadmap.md` を作成する（`tasklist.md` は作らない） - roadmap.md はチェックボックスを持たず、フェーズと子 steering パスの一覧のみ - 各子 steering は独立して実施し、完了時に親の roadmap.md の対応箇所を更新する - **`tasklist.md` という名前にしない**（tasklist-executor が誤って拾わないよう） - 例: `.steering/2026/20260307-feature-201-apply-v0-calendar-design/tasklist.md`（過去実績） - **ロードマップ steering 作成時（MUST）**: Step 1 の summary.md 追記をロードマップバリアントで行う - 「**関連（子 steering）:**」セクションは空欄（子 steering 作成時に追記） - **子 steering 作成時（MUST）**: 以下を行う - 子 steering のエントリを対応月の summary.md にタスクバリアントで追加する（**ステータス: 未完了**、**関連:** に親ロードマップパスを記載） - 親ロードマップの summary.md エントリ内「**関連（子 steering）:**」セクションに子 steering のパスを追記する #### パターンB: 調査結果によって方針が変わる場合（investigation + tasklist） - 調査しないと実装方針が決まらない場合 - `investigation.md` を steering ディレクトリ内に作成し、調査方針を合意してから調査を進める - 調査完了後に `investigation.md` に結果を記録し、方針を確定させてから `tasklist.md` を作る - 通常の `tasklist.md`（下記）を使う。親子 steering は不要 #### 通常パターン（上記に該当しない場合） - `.claude/skills/steering/templates/tasklist.md`を元に`tasklist.md` を作成し、**詳細タスクまで**記載する（ただし実行はしない） - 要件: - **マイグレーションフェーズの原則**: - **MUST**: DB マイグレーションを含むフェーズは、必ず単独フェーズとして切り出す - **MUST**: マイグレーションフェーズの最後のタスクとして「ここで作業を停止し、マイグレーション結果をユーザーに確認する（次フェーズへは進まない）」を明示する - 理由: スキーマ変更は後続の全作業の前提になるため、ユーザーが実際に適用されたことを確認してから次へ進む - **フェーズ分割の方針**: - **MUST**: インクリメンタル開発を基本とする。各フェーズは「独立して完結・検証できる変更単位」にする - フェーズが完了したとき、そのフェーズの変更だけを DoD で検証できること - 例: 「準備 → 一覧機能（完結） → 新規作成機能（完結） → 編集機能（完結） → 品質チェック → ドキュメント」 - 横切り（レイヤ別: 実装 / テスト / 移行 など）は、独立した検証単位にならないため原則禁止 - **MUST: 各フェーズの DoD は「ユーザーが1つの操作をしたとき、何が確認できるか」の形で書く** - DoD に複数の異なるユーザー操作（作成・更新・削除・一覧取得など）が混在していたらフェーズを分割する - やってしまいがちな失敗: 「MealFrame の CRUD ができる」のように複数操作をまとめて DoD にする → 大きすぎるフェーズが生まれても気づけない - 正しい DoD の例: 「addMealFrame mutation で DB に保存できる」「一覧ページで作成した枠が表示される」 - DoDが抽象的なままレビューに進むことを禁止する。DoDが具体的でなければフェーズを書き直す - **「まとめすぎ」のサイン（フェーズを分割すべき）**: - DoD に複数のユーザー操作が混在している - DoD の確認項目が多すぎて、失敗したとき何が原因か特定しにくい - テスト・スクリーンショット確認の対象が複数のコンテキストにまたがっている - フェーズの分割軸がバックエンド / フロントエンドというレイヤーになっている（例: フェーズ1=バックエンドCRUD全部、フェーズ2=フロントエンド全部）→ 正しい軸は「ユーザーが実行できる1つの操作」 - 各タスクは "着手可能な粒度" - 順序・依存が分かる - 主要タスク or フェーズに DoD（完了条件） - **テスト作成・変更の要件**: - **MUST**: 各フェーズで実装した挙動に対応するテストを、そのフェーズ内に含める - テスト実行（green 確認）だけでなく、**テスト作成・変更**をタスクとして明示すること - 以下のケースでは必ずテストを書く/更新する: - 新しい props・挙動を追加した場合 → その挙動をカバーするテストを追加 - 既存の props・インターフェースを変更した場合 → 既存テストを新インターフェースに書き直す - バグ修正の場合 → 修正した問題を再現するテストを追加（退行防止） - 「既存テストが通れば OK」は不十分。変更した挙動が今後も担保されるテストが必要 - テストが書けない・書きにくい場合は、その理由をタスクコメントに記載する - **品質チェックフェーズの要件**: - **MUST**: プロジェクト全体のスタイルチェック（Rubocop/ESLint）を含める - 特定ファイルのみでなく、全体への影響を確認すること - これにより、新規コードが既存コードに与える影響を早期発見する - **デザイン変更を含むタスクの追加要件**: - **MUST**: UI の見た目に関わる変更がある場合、**そのフェーズのDoDにスクリーンショット確認タスクを含める** - 品質チェックフェーズにまとめるのではなく、変更を加えたフェーズで都度確認する - 品質チェックフェーズでは最終確認として改めてスクショを撮る - `visual-inspector` サブエージェント（`Agent(subagent_type="visual-inspector")`）を使ってスクショを撮り、実際の見た目を目視確認すること - ⚠️ `npx playwright` や Playwright ツールの直接呼び出しは禁止。必ず visual-inspector サブエージェントを使うこと - 確認項目の例: カラーバーの色・レイアウト・今日ハイライト・レスポンシブ崩れ - **「UI の見た目に関わる変更」の判断基準（広めに取ること）**: - 新規コンポーネント作成 - スタイル変更（CSS/Tailwind クラスの変更） - コンポーネントの props 変更（表示内容・表示条件に影響する場合） - **コンポーネントのリファクタリング**（内部構造が変わると表示崩れが起きうる） - 既存コンポーネントへの差し替え・組み込み - 「リファクタリングだから UI 確認不要」と判断してはならない。リファクタリングは表示崩れのリスクを持つ - 不確実なものは `TBD` で残し、前提・調査項目を明記 - 大きすぎるタスクとわかった場合、このsteeringではタスク分解にとどめて、個々のタスクの詳細は別のsteeringで作る - 過去やった実績: .steering/2026/20260307-feature-201-apply-v0-calendar-design のタスク --- ### 7) tasklist の自己レビュー（ユーザー提示前に必ず実施） tasklist.md を書いたら、ユーザーに提示する前に以下の観点でゼロベースで見直すこと。 - [ ] **各フェーズの DoD が1つの操作で検証できるか**: DoD に複数の異なるユーザー操作（作成・更新・削除・一覧取得など）が混在していないか。混在していたらフェーズを分割する - [ ] **各フェーズに DoD があるか**: 完了条件が明確か - [ ] **各フェーズにテスト作成・変更が含まれているか**: 実行だけでなく、変えた挙動を担保するテストが書かれているか - [ ] **UI 変更のあるフェーズにスクリーンショット確認が含まれているか**: 品質チェックフェーズにまとめていないか - [ ] **横切りになっていないか**: 実装フェーズ → テストフェーズ のような分割になっていないか - [ ] **コミット・push 前に「ユーザーに動作確認を依頼する」ステップが含まれているか**: 「完了後のアクション」の直前に動作確認セクション（ユーザーへの依頼 → フィードバック収集）が存在すること。なければ tasklist を修正する - やってしまいがちな失敗: 自動テスト・スクリーンショット確認で「動作確認済み」と判断し、ユーザー確認ステップを省略する → tasklist-executor がそのままコミット・push まで自動実行してしまう - 自動テストとスクリーンショットは「機械的な確認」。ユーザーが実際に触って確認するステップは別物として必ず残す 問題があれば tasklist を修正してから提示する。 > ⚠️ チェック項目が1つでも引っかかる場合は必ず tasklist を修正してから提示すること。 > 「だいたい合っている」で通過させてはならない。 > 特に「1フェーズに複数の異なるエンドポイント・コンポーネント変更が混在していないか」を厳しく確認する。 ### 8) Tasklistレビュー（自然言語 yes/no）して終了 - tasklist.md の要点（フェーズと主要タスク）を短く示してレビュー依頼 - OK/はい/進めて 等なら **step 9（doc-enricher + discussion レビュー）へ進む** - ⚠️ 承認を受けても step 9 を飛ばして tasklist-executor を起動してはならない - やってしまいがちな失敗: 「ok」を受けた勢いで実装に進む → step 9 が丸ごとスキップされる - 修正なら tasklist.md を更新して再レビュー（OKまで） --- ### 9) 振り返り：doc-enricher + discussion レビュー【必須・スキップ禁止】 > ⚠️ tasklist が承認されたら、実装確認（step 10）より**必ず先に**このステップを実行すること。 > 「実装に早く進みたい」という理由でスキップしてはならない。 #### 9-1) doc-enricher を起動（提案のみ → 承認があれば適用） - tasklist 合意後、`Skill('doc-enricher')` を **Phase 1（提案のみ）**として実行する - doc-enricher には以下を渡す前提で実行する: - 対象ディレクトリ（今回読み/触りが発生した範囲） - 関連ファイル（調査で読んだ/参照したファイル） - steering パス（`.steering/.../`） - doc-enricher の提案を提示し、ユーザーに自然言語で確認する: - OK/はい/適用して → doc-enricher を Phase 2（適用）で再実行（承認された変更だけ） - いいえ/やめて/あとで → 提案のみで終了 #### 9-2) discussion.md を元にしたドキュメント・スキル改善レビュー discussion.md が存在する場合、**各 discussion に対して以下の3ステップを順番に実行する**。 解決策（どこに書くか）より先に原因を特定すること。原因が曖昧なまま「このドキュメントがあれば」と考えると、症状レベルの答え（ルール追加）になりやすい。 **各 discussion に対する3ステップ:** 1. **「この議論が起きた根本原因——共有されていなかった知識の前提——は何か？」** - やってしまいがちな失敗: 議論の結論（ルール）を答えにする → 「対症療法」になる - 正しい問い: 「この議論が始まる前に、どちらかが知らなかった/共有されていなかった設計の前提は何か？」 2. **「その知識はコードを読めば分かるか？それとも読んでも分からない設計意図か？」** - コードを読めば分かる → README に設計意図として書けば次回コードを読まずに済む - コードを読んでも分からない → application_architecture.md 等の上位ドキュメントに原則として書く - 設計プロセスの問題（設計時に問うべき問いが欠けていた）→ SKILL.md に追加する 3. **「どこに書けば次回この議論が不要になるか？」** → 書く（変更は合意後） ユーザーが OK すれば適用。いいえ/あとで なら提案のみで終了 #### 9-3) このスキル定義ファイルの確認 - このスキル定義ファイルについて、変更の必要があるか確認 - 不要であれば、修正は禁止 --- ## ファインプレー即時記録の原則 型（ステップ）はメリットがあるから型化しているだけで、金科玉条ではない。 実行中にスキル改善のインサイトが生まれたとき（良い設計議論があった、新しいパターンを発見した等）は、ステップ9を待たず「今すぐ提案」してよい。 - ステップ9は全体整合性の最終確認として機能し、タイムリーな提案の代替ではない - 「あとでやる」は熱量と文脈が冷えてしまう。今の文脈が熱いうちに提案する - 「提案する」と「変更する」は別の行為。提案は今すぐ、変更は合意後 - ファインプレーを行う条件: 型の精神を理解した上で、型を守りながら型を崩さない形でのみ行う - ただし「命令無視・単なる改悪」は禁止。型を知らずに崩すのではなく、型を活かしてより良くする --- ### 10) （必要があれば）tasklistに沿って実装 > ⚠️ このステップは step 1〜**9** が**すべて完了してから**はじめて提案してよい。 > 未完了のステップがある場合は、実装を推奨してはならない。急かすことも禁止。 > **MUST: step 8（tasklist承認）を受けた直後に「実装に進みますか？」と聞くことは禁止。** > step 9（doc-enricher + discussion レビュー）を先に完了させること。 > やってしまいがちな失敗: 「ok」を受けた勢いで step 9 を省略・形骸化して「実装に進みますか？」を急いで聞く → step 9 で生まれる知識・ドキュメント改善が揮発する - ユーザに tasklistに沿って実装するか問いかける - OK/はい/進めて 等なら 次へ - そうでないならここで終了 - tasklist-executor エージェントに tasklist.md を渡して実装開始 - **MUST**: 各フェーズ・各タスク完了のたびに tasklist.md の `[ ]` を `[x]` に即座に更新すること - 最後にまとめて更新することは禁止 --- ### 11) 実装完了後レビュー（implementation_review.md） > ⚠️ このステップは実装完了後・ユーザーレビュー時に発生する。steering の通常フローには含まれない。 実装完了後にユーザーが漏れ・追加要件に気づいた場合、`.claude/skills/steering/templates/implementation_review.md` を元に `implementation_review.md` を作成し、以下の4ステップを**順序固定**で進める。 #### ステップ順序（MUST） | ステップ | セクション | 意図 | 記法 | |---|---|---|---| | 1 | フィードバック収集 | ユーザーの言葉をそのまま残す。解釈・サマリー禁止 | 言われた通りに箇条書き転記 | | 2 | 認識合わせ | フィードバックの意図・前提・決定理由を揃える | `discussion.md` と同じ「論点N」形式（提起の背景・議論の変遷・決定・決定理由） | | 3 | 設計 | 完成後の姿を示し、現状とのギャップを埋める進め方を合意する | steering の design.md と同じ思想。操作フロー中心。変更点の列挙（タスクリスト）にしない | | 4 | タスク整理 | 設計の認識が合った後に実装ステップに落とす | DoD 付きフェーズ構成。合意後に既存 tasklist.md に追記する | **各ステップの MUST:** - **セクション1（フィードバック収集）**: 解釈・言い換え禁止。ユーザーが言った原文をそのまま転記する。「〜ということですか？」と言い換えた時点でユーザーの意図が変質する。各項目に **FB-N** ラベルを付ける（FB-1, FB-2, ...）。セクション2以降の「ケース1（FB-3 修正後）」のように参照するため - **セクション2（認識合わせ）**: `discussion.md` と同じ「論点N」形式（提起の背景・議論の変遷・決定・決定理由）で書く。1往復でも省略しない。「〜で確定」の1行にすると議論の変遷が揮発する。論点の見出しには元の FB 参照を付ける（例: `### 論点1: タイトル（FB-3）`）。1つの FB から複数の論点が生まれることがあるため、参照がないと後から追えなくなる - **修正済みの FB も 論点 を省略しない**。「動作確認中に発見して即座に修正した」ケースは特に省略したくなるが、なぜそのバグが起きたか・根本原因・選択した修正方針は振り返りとして必ず残す - やってしまいがちな失敗: 「もう直したので認識合わせ不要」と判断し、論点を書かない or 1行サマリーで済ませる - 修正済みステータスは タスク整理 の `[x]` にのみ反映する。認識合わせの要否とは無関係 - **セクション3（設計）**: 「完成後のユーザー体験（操作フロー）」を中心に書く。「〇〇ファイルの△△を修正する」という形式はタスクリストであり設計ではない。正しい問い:「このフローを読めば、完成後にユーザーが何を体験できるかが分かるか？」 - **セクション4（タスク整理）**: セクション3の認識合意後にのみ着手する。整理後のタスクは既存 `tasklist.md` に追記する - tasklist は「機能を完成させるためのチェックリスト」。機能が完成するまで生き続ける - `[x]` 済みの下に新たな `[ ]` を追加することは汚染ではなく、完成に向けた正常な更新 - **やってしまいがちな失敗: 設計と同時にタスク整理を書く**。設計をユーザーに提示してフィードバックを受けていない段階でタスクを書くと、設計が覆ったときにタスクを書き直す羽目になる。設計合意 → タスク整理の順序は厳守 --- ## このスキルが “絶対にやらないこと” - 許可なくtasklist の実行 - コード変更 - テスト/CI 実行 - 自動で次工程に突入（勝手に実装開始）