architect

Architect

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

開始

開始前に、各フェーズを1項目ずつ含むToDoリストを作成します。

1. Ground
2. Sketch
3. Agree
4. Implement
5. Scrap

フェーズA：問題の把握

新しいコードが関わるすべてのシステムについて、実態に即したメンタルモデルを構築します。関連するサブシステムに how スキルを適用します。ファイル名を挙げるだけでは、十分な把握とは言えません。how が定めるアーキテクチャの説明を作成します。設計によって所有権やレイヤー構成を再定義する場合は、既存の構成に why スキルも適用し、その根拠を推測ではなく制約として扱えるようにします。

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

フェーズB：スケッチ

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

arena runners の行の代わりに、pstack 設定ファイルの architect runners の行からランナーを選びます（Cursor では ~/.cursor/rules/pstack-models.mdc、ほかのハーネスでは ~/.agents/pstack-models.md）。ファイルまたは該当の行がない場合は、claude-opus-5-5-xhigh と grok-4.7-xhigh-fast を使います。エイリアスと除外された項目については、arena スキルのフェーズAにあるランナーのルールに従います。

設計を2回行います。最初の案で十分に見えても、統合前に構造の異なる候補を少なくとも2つ用意します。これにより、設計空間を徹底的に探索するという原則スキルを具体化します。同じ形の中の部分的な修正ではなく、全体の形が異なる代替案を検討します。

各候補を統合する前に、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 に沿ってまとめ、使い方のスケッチと統合に関する判断を含めて、成果物と一緒に提供します。