architect

アーキテクト

not implemented の本体や擬似コードを使って、型、関数シグネチャ、クラスの構造、モジュールの境界をスケッチします。複数のモデルの視点を統合してから、選んだスケッチに沿ってコードを埋めます。

開始

作業を始める前に、各フェーズにつき1項目ずつの作業リストを作成します。

1. 基盤を把握する
2. スケッチする
3. 合意する
4. 実装する
5. 破棄する

フェーズ A：問題の基盤を把握する

新しいコードが関わるすべてのシステムについて、実態に即した理解を築きます。関連するサブシステムで how スキルを使います。

ファイル名を挙げるだけでは基盤の把握にはなりません。how が定めるアーキテクチャの説明を作成してください。設計によって既存の所有権やレイヤー構造を再定義する場合は、既存の構造に関する根拠を制約として明確にし、推測にしないために why スキルも使います。

周辺システムとの統合が不要な、真にグリーンフィールドの作業である場合に限り、フェーズ A を省略します。

フェーズ B：スケッチする

設計スケッチのタスクとフェーズ A で得た基盤把握の成果物を使い、arena スキルを実行します。各ランナーのプロンプトとして references/runner-prompt.md を渡します。

arena runners の代わりに、architect runners ロールからランナーを選びます。デフォルトは fable、opus、sonnet です。エイリアスと却下されたエントリーには、arena スキルのフェーズ A にあるランナーのルールが適用されます。起動には pstack-harness スキルを使います。同スキルの「ロールの起動」セクションでロールを解決し、この CLI の起動呼び出しを組み立てます。

設計は2回行います。最初の案で十分に見えても、統合する前に、構造が少なくとも2つ異なる候補を出すよう求めます。これは exhaust-the-design-space 原則スキルを具体化するものです。1つの形の中で部分的に修正するのではなく、全体構造の異なる案を検討します。

すべての候補を統合前に references/design-red-flags.md に照らして審査します。次の担当者は、開いたファイルだけを見て、最も近い例をコピーし、コンパイルが通る最短の道を選ぶエージェントだと想定してください。1つのファイルからは正しく見える変更が、リポジトリ全体にとっても正しい設計を優先します。

実現可能な候補を、インターフェースの深さで比較します。より多くの複雑さを、小さくシンプルな公開インターフェースの背後に隠せる設計を優先します。機能をレイヤー間に散らさず集約することで、豊富なインターフェースは呼び出しチェーンを短くできます。

Arena は統合済みの設計パッケージを1つ返します。その統合判断によって、根拠の「統合判断」セクションを埋めます。

フェーズ C：合意する（オプトイン）

デフォルトでは、統合済みの設計に基づいてそのまま実装に進みます。人によるチェックポイントは設けません。

呼び出し元が「/architect with checkpoint」「実装前に止めて見せて」などと明示的に求めた場合は、チェックポイントを有効にします。その場合、統合済みの設計を提示し、承認を待ちます。

チェックポイントがない場合、または呼び出し元の承認後は、foundational-thinking 原則スキルの「まず足場を作る」モードに従い、統合結果を独立したコミットとして出荷できます。outcome-oriented-execution 原則スキルに従えば、実装時に計画・範囲を明確にした破壊的変更は問題ありません。実装前に設計を敵対的な観点から検証するには、統合済みのスケッチに interrogate スキルを使います。

人がチェックポイント中または事後に設計の形に異議を唱えた場合は、それをフェーズ A の証拠として扱います。コードをさらに書く前に、基盤を把握し直し、フェーズ B を再実行します。

フェーズ D：スケッチに沿って実装する

not implemented の本体をコードに置き換え、擬似コードをロジックに置き換えます。統合済みのスケッチが契約です。そこからの逸脱は、黙って吸収すべき摩擦ではなく、表面化させるべきシグナルです。スケッチで想定していなかったパラメーターが関数に必要になった場合は、スケッチが誤っていたのか、要件を見落としていたのか、実装が範囲を逸脱しているのかを確認してください。

フェーズ E：アーキテクチャが間違っているなら破棄する

実装で繰り返し生じる摩擦をスケッチで吸収できないなら、そのスケッチは破棄します。redesign-from-first-principles と fix-root-causes の原則スキルに従い、間違った設計に修正を継ぎ足さないでください。

兆候となるのは、単発の事例ではなく パターン です。次の点に注目してください。

• 無関係なコードのあちこちで、同じ形の回避策が繰り返し現れる。
• 無関係な複数のエッジケースすべてに、専用の分岐が必要になる。
• コンパイルするために、型に逃げ道（any、キャスト、実際には常に設定されているオプションフィールド）が必要になる。
• スケッチでは状態を共有していないはずなのに、「ロックが必要だ」と反射的に考える。
• 呼び出し元が抽象化の内部ルールを知らなければ使えない。
• 実装全体で、同じ形のフェーズ D からの逸脱が 2 つ以上ある。

判断は慎重に行ってください。いくつかのエッジケースだけでアーキテクチャが否定されるわけではありません。問題によっては、正当に複雑なこともあります。データの複雑さは、設計の複雑さではありません。

破棄する場合：

1. 構築したものを対象に、how スキルをもう一度使います。
2. redesign-from-first-principles に従い、新しい制約が初日から前提だったものとして再設計します。
3. subtract-before-you-add の原則スキルに従い、追加する前に削ります。新しいスケッチは、発展させる前の段階で古いものより小さくなるべきです。
4. フェーズ B に戻り、arena を再実行します。

成果物

呼び出し元の使い方を先に記述し、それを基に型のスケッチを導き出します。小規模な変更では、新しい型とシグネチャを 1 つのファイルにまとめます。大規模な変更では、モジュールマップと型定義を用意します。根拠は references/rationale-template.md に沿った形式で使用方法のスケッチと統合判断を含め、成果物とともに提出します。