architect

アーキテクト

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

太字で示された原則は principles スキルにあります。Skill ツールで principles を一度呼び出してから、名前が挙がっている各原則のファイルを読みます。

開始

作業を始める前に、各フェーズにつき1項目ずつ含むタスクリストを作成します（利用しているハーネスのタスクツール、またはタスクツールがない場合は ~/.local/state/ox/checklists/<repo>-<branch>.md のチェックリストファイルを使用します）。

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

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

新しいコードが関わるすべてのシステムについて、実際の理解を深めます。関連するサブシステムに対して、Skill ツールで how を呼び出します。ファイル名を挙げるだけでは、前提を把握したことにはなりません。how の指示に従って、アーキテクチャの説明を作成します。設計によって所有権やレイヤー構造を再定義する場合は、既存の構造の根拠を制約として扱えるように、Skill ツールで why も呼び出します。

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

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

Skill ツールで arena を呼び出し、設計スケッチのタスクとフェーズ A で得た前提資料を渡します。各ランナーへの指示には RUNNER-PROMPT.md の内容を貼り付け、あわせてこのファイル、RATIONALE-TEMPLATE.md、およびプロンプトで名前が挙がっている principles ファイルの絶対パスを渡します。ランナーは arena の panel シートです。

設計を2回行います。最初の案で十分に見えても、統合前に、構造が異なる候補を少なくとも2つ作成します。これは 設計空間を網羅する ことを具体化するものです。1つの構造の中で部分的な修正を加えるのではなく、全体の形が異なる選択肢を検討します。

統合前に、DESIGN-RED-FLAGS.md に照らしてすべての候補を評価します。次の貢献者は、開いたファイルしか見ないエージェントであり、最も近い例をコピーして、コンパイルが通る最短の経路を選ぶと想定します。1つのファイルだけ見れば正しく見える変更が、リソース全体にとっても正しい設計を優先します。

実現可能な候補について、インターフェースの深さを比較します。より多くの複雑さを、より小さくシンプルな公開インターフェースの背後に隠せる設計を優先します。つまり、エクスポートとイベントは少なく、それぞれがより多くの役割を果たします。豊富なインターフェースは、機能をレイヤー間に分散させず集中させることで、呼び出しチェーンを短く保てます。

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

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

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

呼び出し元から「チェックポイント付きで設計して」「実装前に止めて見せて」などと明示的に求められた場合に限り、チェックポイントを設けます。その場合は、統合した設計を提示して承認を待ちます。

どちらの場合も、基盤を築く思考の「まず足場を作る」モードとして、統合内容を単独のコミットにできます。成果志向の実行に従い、実装時に計画され、範囲が定められた変更による破損は問題ありません。実装前に設計へ厳しい検討を加える場合は、統合したスケッチに対して Skill ツールで interrogate を呼び出します。

人間がチェックポイント中またはその後に設計の形へ異議を唱えた場合は、それをフェーズ A の証拠として扱います。さらにコードを書く前に、前提を再確認し、フェーズ B をもう一度実行します。

フェーズ D：スケッチに基づいて実装する

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

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

実装によって摩擦が生じ続け、スケッチでは吸収できない場合は、そのスケッチを破棄します。第一原理から再設計するおよび根本原因を修正するに従い、間違った設計に修正を継ぎ足さないでください。

判断の手がかりは、単発の事例ではなく パターン です。具体的には、次のような兆候があります。

• 無関係なコード間で、同じ形の回避策が繰り返し現れる。
• 無関係なエッジケースが複数あり、どれも特別な分岐が必要になる。
• コンパイルや型チェックを通すために、型に回避策（any、キャスト、--[[@as T]]、実際には常に設定されるオプションフィールド）が必要になる。
• スケッチでは状態を共有しないとしていたのに、「ロックが必要だ」という反射的な対応が出てくる。
• 抽象化を使うために、呼び出し側がその内部ルールを把握しなければならない。
• 実装全体で、同じ形のフェーズ D からの逸脱が 2 つ以上ある。

判断は慎重に行ってください。エッジケースがいくつかあるだけで、アーキテクチャが不適切だとは限りません。複雑さが本質的に伴う問題もあります。データの複雑さは、設計の複雑さとは異なります。

破棄する場合：

1. 構築したものよりも how を重視して、Skill ツールを呼び出します。
2. 第一原理から再設計するに従い、新しい制約を初日からの前提として設計し直します。
3. 追加する前に削るに従います。新しいスケッチは、成長する前に古いスケッチより小さくなっている必要があります。
4. フェーズ B に戻り、arena を再実行します。

成果物

まず呼び出し側の使用例を記述し、そこから型のスケッチを導きます。小規模な変更では、新しい型とシグネチャを 1 つのファイルにまとめます。大規模な変更では、モジュールマップと型定義を作成します。根拠は RATIONALE-TEMPLATE.md に沿った形式で併せて提出し、使用例のスケッチと統合判断を含めます。