design-code-implement

コード実装の設計

何を作るかがすでに決まっているものについて、どのように作るかを決めます。並列サブエージェントを使ってリポジトリの実際のアーキテクチャ上の慣例を調査し、新しい要件とそれらの慣例が衝突する箇所を明らかにして、ユーザーが選べる少なくとも3つの方向性を提示します。

このスキルでは、本番コードは作成しません。方向性が選ばれ、記録された時点で終了します。

1. 入力を確認する

ファイルパス、前段のスキルからの引き継ぎ、会話中の文章など、どのような形で要件が提示されても受け入れます。ファイルを要求してはいけません。ユーザーが示した内容を読み、求められている結果を1文で言い換えてください。少しでも曖昧な場合は、確認を取ってください。

リポジトリ、ランタイム、ツールから判明する事実をユーザーに尋ねてはいけません。

2. 調査範囲を決める

§1で確認した要件に基づき、調査する観点は自分で決めてください。まず偵察用のサブエージェントを送ってはいけません。また、観点のリストについてユーザーの承認を求めてはいけません。リポジトリの実態を見る前にユーザーがそれを判断することはできず、観点が誤っていれば、レポートを見た時点で明らかになります。

観点のリストには、次の制約があります。

• 必ずドメイン用語を含めること：既存の概念が何と呼ばれているか、また、要件によってコードベースに存在しない用語が持ち込まれるかを調べます。
• アーキテクチャ上の慣例に限ること：レイヤーの分け方、エラーの伝播方法、データの入出力方法、テストの配置、既存の接続点を調べます。表層的なスタイル（命名規則、ファイル配置、フォーマット）は除外してください。リンターや近接するコードから分かることであり、キャメルケースを理由に実装の方向性を変える人はいません。
• サブエージェントは最大5つまで。それ以上必要と思われる場合は、観点を統合してください。8つのアーキテクチャ上の観点にまたがる要件は、設計に入る前に分割してください。
• 影響範囲を限定すること。要件が触れる領域と、git log --onelineで確認できる最近の変更が集中している箇所だけを調べます。リポジトリ全体を網羅的に調査してはいけません。無関係な慣例は、実際の衝突を見えにくくします。

3. 調査を割り当て、報告を集める

すべてのサブエージェントに、同じツールの優先順位を伝えてください。

• コードベースのナレッジグラフMCPが利用できる場合は、まずそれを使います。リポジトリがまだインデックス化されていない場合は、インデックス化を完了させてください。
• それ以外の場合は、リポジトリを認識したナビゲーションツールを優先してください。
• 文字列リテラル、設定、スクリプト、コード以外のファイルを調べる場合、または上記のツールが古い情報を返すか適用できない場合は、組み込みの検索機能を使ってください。

各サブエージェントには、各調査結果について次の3項目だけを報告するよう求めてください。

1. 既存の慣例 — この観点について、リポジトリですでに行われていること。
2. 根拠 — ファイルと行番号（path/to/file.ts:42）。パスのない主張は使用できません。
3. 衝突点 — 新しい要件がその慣例と衝突する箇所。衝突がない場合は、その旨を明示してください。

この作業の要点は、衝突点を見つけることです。衝突のない慣例は背景情報にすぎません。実装の方向性は、衝突点から導き出されます。

4. 方向性を提示する

継承すべき要件に関して、既存の規約が見つからなかった場合は、その旨を伝えて終了します。このスキルには、方向性の根拠にできるものがありません。方向性は提示しないでください。

最低3つの方向性を会話の中で順番に提示し、それぞれが比較される前にユーザーが内容を把握できるようにします。

• 方向性1は常にベースラインです。既存のすべての規約に従い、新しい接点を設けず、最も保守的な方法を取ります。提示にほとんどコストがかからず、他の方向性と比較する基準になります。これがなければ、ユーザーは追加コストに見合う価値があるか判断できません。
• 方向性2と3は、報告された緊張関係から導きます。テンプレートから作ってはいけません。方向性にあらかじめ制約を割り当てず、リポジトリに実際にある摩擦に応じて違いを決めます。

各方向性には、次の4項目を必ず含めます。

1. 位置づけ — 1文。
2. 影響範囲 — 対象となるファイルと接点。
3. コスト — 具体的に何が必要になるか。
4. この選択が適切でない場合 — この方向性が誤りとなる条件。

4つ目の項目は必須です。これにより、率直な判断を促します。失敗条件のない方向性は、十分に検討されていません。

最後に推奨案を示します。選ぶ方向性と、その決定要因となる緊張関係または要件を伝えてください。選択権はユーザーにあります。

緊張関係を踏まえても実質的な方向性を3つ提示できない場合は、その旨をはっきり伝えます。既存の規約によってすでにアプローチが決まっていると報告し、終了してください。作為的な違いでリストを水増ししてはいけません。実質的な選択肢と、作り上げた選択肢を見分けられないユーザーは、どの選択肢も信頼しなくなります。

組み合わせも可能です。 ある方向性の全体像に、別の方向性のエラー処理を組み合わせたいとユーザーが望む場合は、そのようにします。そのうえで、組み合わせた方向性をすべて言い直し、何かを書く前に確認を得てください。双方が異なる意味で理解している組み合わせは、何も組み合わせないより悪い結果になります。

5. 決定を記録する

design.md を作成します。

配置場所：作成前に、ユーザーに保存先を確認します。

内容 — references/template.md に沿って、実施することだけを記載します。

• 選択した方向性を、文章ではなく図で示します。
  • コンポーネントをまたぐ各フローについて、トリガーごとに1つの ASCII フローチャートを作成します。手順は上から下に並べ、番号を付け、それぞれの次の行にインデントした ↳ を置いて、実際に処理を行う関数とファイルを記載します。右側は空け、左端の矢印とインデントだけを使います。これにより、全角文字で配置が崩れるのを防ぎます。成功経路だけを図示し、図の下に要件が示すすべての失敗を「手順 N が失敗 → その場合の処理」の形式で列挙します。それ自体が独立したフローである手順には、専用の図を作成し、「→ フロー N」として参照します。
  • 状態が変化するエンティティごとに、Mermaid の stateDiagram-v2 を記載します。
  • 図で表せない変更（マイグレーション、設定、インターフェースの形状）は、短いリストにまとめます。
• この作業で従うべき規約を、根拠となるパスとともに1行ずつ記載します。
• それ以外は何も記載しません。却下した方向性も、その理由も記載しないでください。 後続の実装エージェントはこのファイルを指示書として読みます。採用しないアプローチを書くと、そのアプローチが実行されるおそれがあります。

design.md がすでに存在する場合：まず内容を読み、そのうえで更新し、引き続き有効な内容は引き継ぎます。内容を確認せずに上書きしてはいけません。

6. 引き継いで終了する

次の内容を報告します。

• 選択した方向性の簡潔な要約。
• design.md のパス。

その後、終了します。実装方法と実装手段を決めるのはユーザーです。実装を始めたり、次に実行するコマンドを提示したりしてはいけません。