architect

アーキテクト

太字またはバッククォートで示されたスキル名、あるいは /<name> として実行するスキルは、このスキルのディレクトリと同じ場所にある ../<name>/SKILL.md ファイルです。接頭辞なしで示された原則名は、../principle-<name>/SKILL.md です。そのファイルを読み、従ってください。pstack のスキルの多くはユーザー専用のため、スキルツールでは読み込めません。

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

開始

着手する前に、各フェーズにつき 1 項目を含むタスクリストを作成します（利用環境のタスクツールを使うか、タスクリストがない場合は ~/.local/state/pstack/checklists/<repo>-<branch>.md にチェックリストファイルを作成します）。

1. 把握
2. スケッチ
3. 合意
4. 実装
5. 破棄

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

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

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

フェーズ B：スケッチ

フェーズ A で作成した把握資料と設計スケッチのタスクを使って、arena スキルを実行します。各ランナーへの指示書に references/runner-prompt.md を貼り付けます。

~/.config/pstack/pstack-models.md の architect runners 行からランナーを選び、arena runners 行の代わりに使います。ファイルまたは該当行がない場合は、arena スキルのフェーズ A にあるデフォルトの席を使います。エイリアスと却下された項目には、arena スキルのフェーズ A にあるランナーのルールを適用します。

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

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

実行可能な候補をインターフェースの深さで比較します。より多くの複雑さを、より小さく単純なパブリックインターフェースの背後に隠せる設計を優先します。豊富なインターフェースは、機能を分散させず集中させることで、呼び出しチェーンを短く保てます。

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

フェーズ C：合意（任意）

デフォルトでは、統合済みの設計を使ってそのまま実装に進みます。人間による確認は行いません。

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

どちらの場合も、統合結果は foundational-thinking 原則のスキルにおける「scaffold first」モードとして、独立したコミットにできます。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 に沿ってまとめ、使い方のスケッチと統合に関する判断を含めて、成果物と一緒に提供します。