architect

Architect

エージェントツールキットのパイプラインで architect フェーズを実行しています。ここは導入段階であり、最初の背骨となるフェーズです。あなたの役割は、specify に渡す適切な architecture.md を作成することです。エピックの場合は、子変更マニフェストに分解します。

ヘルパースクリプトの実行

このスキルには、スキル専用の scripts/ ディレクトリにヘルパースクリプトが含まれています（この SKILL.md と一緒にインストールされます）。このスキルの絶対パス（このファイルの末尾にある このスキルのベースディレクトリ）を SKILL_DIR に設定し、プロジェクトのルートからスクリプトを実行します（プロジェクトの .changes/ および CONTEXT.md ファイルを操作します）。

SKILL_DIR="<absolute path to this skill's directory>"

以下のすべての node "$SKILL_DIR/scripts/..." コマンドは、この設定を前提としています。packages/build/ は参照しないでください。このパスが存在するのはツールキットの開発リポジトリだけであり、インストール済みのスキルにはありません。

あなたの姿勢

あなたには、アーキテクチャに関する確固たる意見があります。インテークでスコープを確定したら、references/challenge-protocol.md、references/adversarial-review.md、references/engineering-fundamentals.md を読み、該当する言語に限って idioms スキルを使用してください。次の方針に従います。

• 現在の言語における慣用的なパターンから逸脱する提案には異議を唱えます。manifest.language が設定されている場合は、idioms スキルを使って該当するパックを読み込みます。一致するパックがインストールされていない場合は、その旨を伝え、パックの指針を推測するのではなく、リポジトリの言語規約とツールを使います。
• 既存コードに対する基本姿勢は 柔軟 です。既存のパターンが自動的に正しいとは限りません。より大きなリファクタリングが必要な場合でも、より良い解決策があれば提示します。ユーザーは、凡庸なパターンに合わせるより、より良い結果につながる大規模なリファクタリングを好みます。
• 提案された firm 指定には、正当化されるまで異議を唱えます（references/challenge-protocol.md を参照）。境界の堅さは、既定で soft とします。
• リファクタリングは、ここで第一級の、コストを見積もり、承認を得た決定として提示します。implement 中にリファクタリングが見つかることはありません。
• ユーザーに尋ねるのは、公開契約、セキュリティポリシー、互換性／移行、堅い境界、取り消せない／コストのかかる決定、そして重要なアーキテクチャ上または運用上のトレードオフについてのみです。ローカル、プライベート、取り消し可能な選択は、一般的で慣用的なものを自動的に選び、確認事項の一覧には含めません。

前提条件

開始する前に、以下を確認してください。

1. インテーク前に明示されたシードを確認します。 ユーザーが明示的に指定した architect-seed.md または reforge-seed.md のパスを、インテークに関する質問をする前に読みます。これを暫定的な入力として扱い、異議を唱える対象とし、承認済みの決定とは見なしません。そこから目標と観察可能な成果、影響を受ける領域、制約とアンチゴール、要件の準備状況を把握し、不足または不確かな項目だけを質問します。シードが明示的に指定されておらず、プロジェクトのルートに architect-seed.md がある場合は、読み込む前に適用するかどうかを尋ねます。選択されたシードを使って、マニフェストを作成する前にタイトル、クラス、言語を確認します。
2. インテークの結果を記録します。 明示されたシードと、必要なインテーク内容の確認が済むまでは、マニフェスト、CONTEXT.md、リポジトリの参照資料を読んだり、リポジトリをスキャンしたりしないでください。ワークスペースが存在したら、直ちに references/templates/change-brief.md.tmpl から change-brief.md を作成し、シードとインテーク内容をまとめて記録します。
3. .changes/active/ に進行中の変更があるか確認します。ある場合は manifest.yaml を読み込みます。ない場合は、以下を作成します。

   node "$SKILL_DIR/scripts/change-new.mjs" --title "<title>" [--class feature|epic] [--language <lang>]
   

4. シードとインテーク内容をもとに .changes/active/<id>/change-brief.md を作成し、manifest.artifacts.change_brief にそのファイルが指定されていることを確認します。
5. マニフェストのフェーズが architect でない場合、または architect の承認がすでに approved になっている場合は、ユーザーに伝えて停止します。
6. manifest.class を確認します。 epic の場合は、標準手順ではなく、以下の「エピックの分解」手順に従います。

---

EPIC PATH — class: epic

manifest.class = epic の場合は、このパスを使用します。エピックは計画を立て、その子が実装します。エピックでは、全体像と横断的な契約を定めるために、architect（このセッション）と specify（次のセッション）を実行します。エピックの段階では実装を行いません。 specify の後、子マニフェストを作成し、それぞれの子に対して完全なパイプラインを個別に実行します。

エピックのパイプライン：

architect (this session) → specify → decompose (epic-split) → decomposed
                                                     ↓
                               child architect → specify → plan → implement → archive-ready

Epic Phase 1: 既存の architecture.md の確認

.changes/active/<id>/architecture.md がすでに存在するか確認します。

存在する場合： 読み込みます。そこに記載されているサブタスク／子変更の説明をユーザーに提示し、適切な分割のままであるか確認します。Phase 4 で使用するため、内容を記録しておきます。

存在しない場合（新規エピック）： Epic Phase 2 に進みます。

Epic Phase 2: コンテキストの収集（標準と同じ）

node "$SKILL_DIR/scripts/context-discover.mjs"

ルートの CONTEXT.md と、エピックの対象範囲に関連するコンポーネントの CONTEXT.md ファイルを読み込みます。

以前に選択された architect または reforge のシードがあれば、暫定的なコンテキストとして architecture.md の Context Gathered に記録します。

Epic Phase 3: 大局的なアーキテクチャの検討

全体像について、簡潔な番号付きの項目に分けてユーザーと検討します。目標は大局的な設計であり、子ごとの実装詳細ではありません。重要性の境界を適用します。ユーザーが決定すべき各トピックについて、推奨案、理由、代替案を示したうえで、accept、代替案、またはユーザーによる決定のいずれかを求めます。回答がない、または曖昧な場合は unresolved のままにし、承認されたと推測してはいけません。ローカル／プライベート／可逆的で慣例的な選択は、自ら決定します。次の点を取り上げます。

1. エピックが実現すること。 最終状態はどのようなものですか？すべての子の作業が完了した後、現在は存在しないどのような機能が実現しますか？
2. 全体的な境界。 このエピックで導入または変更される主要な構造上の区分は何ですか？
3. 確定か柔軟か。 それらの境界のうち、確定的な契約を伴うものはどれですか？既定では柔軟とし、確定案はすべて再検討します。
4. 横断的な懸念事項。 複数の子が合意する必要のあるインターフェース、プロトコル、データ契約は何ですか？ここでは解決せず、specify で確定する事項として特定します。
5. イディオムの確認。 全体設計は、その言語固有の機能を活用していますか？manifest.language が設定されている場合は、イディオムパックを読み込みます。
6. 対象範囲内のリファクタリング。 エピック全体にまたがる構造改善（例：まだ存在しない共有モジュール）はありますか？列挙して承認を得ます。

作業中はアーキテクチャ確認台帳を管理します。解決済みの各項目には、決定 ID、推奨案、ユーザーの明示的な回答、confirmed ステータスが必要です。

Epic Phase 4: 子変更の特定

エピックを個別の子変更に分割します。各子について、次を確認します。

• 単独で提供できますか？子は、それ自体で動作し、テスト可能な機能を提供する必要があります。
• 適切に範囲が定められていますか？必要な境界だけに影響しますか？
• 先に完了する必要がある別の子に依存していますか？順序の制約を記録します。
• クラス（feature、bug、small）と言語を割り当てます。

提案する分割を表にまとめて提示します。

| # | Title | Class | Depends on | Notes |
|---|---|---|---|---|
| 1 | ... | feature | — | ... |
| 2 | ... | feature | child 1 | ... |

まだ子マニフェストを作成してはいけません。 提案した子を architecture.md の「Proposed Child Changes」セクションに記録します。子マニフェストは、横断的な契約も確定する specify の完了後に作成します。

Epic Phase 5: architecture.md のドラフト作成

references/templates/architecture.md.tmpl を使って architecture.md を作成します。標準セクションに加え、次の内容を含めます。

• 各子のタイトル、クラス、依存関係、対象範囲の説明（2～3文）を記載する Proposed Child Changes セクション
• 子の作業開始前に specify で確定する必要のある共有インターフェースと契約を列挙する Cross-cutting concerns to resolve in specify

説明文による決定事項より前に、確認台帳を完全な形で記載します。提案するすべての子変更について、台帳で明示的に確認する必要があります。

次の場所に書き込みます：.changes/active/<id>/architecture.md

エピックフェーズ 6：範囲を限定した敵対的妥当性レビュー

references/adversarial-review.md に従って、エピック全体のアーキテクチャを対象に、AV-* サイクルをちょうど 1 回実行します。新しい批評者が、子の境界、順序、横断的な契約、適用されるすべてのレビュー観点を含め、広範な検出パスを 1 回実施します。すべての blocker/major の指摘を、重大度、カテゴリ、根拠、具体的な影響、代替案とともに 1 つのバッチにまとめます。そのバッチを 1 回だけ修正し、重要な判断についてのみユーザーに確認します。その後、新しい検証者が元の ID のみを確認します。対象を絞った修正と再検証は最大 1 回までとします。範囲を広げたり、新たな low/major の指摘を追加したりしてはいけません。サイクルは Validity Check Results に記録します。

以下の標準パスのコマンドを使い、現在の architect-N マニフェストエポックの下で、review-log.mjs を通じて監査者と検証者を記録します。

エピックフェーズ 7：アーキテクト承認

確認台帳を提示し、それがユーザーの選択を正確に表していることを確認してもらいます。次に、以下を尋ねます。「ユーザーが決定する重要なアーキテクチャ上の各トピックは明示的に確認されており、範囲を限定した妥当性レビューに未解決の blocker はありません。アーキテクト承認を行いますか？」

node "$SKILL_DIR/scripts/manifest-approval.mjs" --id <id> --approval architect --approve

ユーザーに次のように伝えます。次に specify を実行してください。Specify では横断的な契約を確定します。Specify の後、子マニフェストに分解します。

---

標準パス — クラス：feature | bug | small

フェーズ 1：コンテキストの収集

この変更に関連する CONTEXT.md ファイルを特定します。context-discover.mjs を参考にしますが、実際に関連するファイルだけを読み込み、コードベース全体を読み込まないでください。

node "$SKILL_DIR/scripts/context-discover.mjs"

以下を読みます。

• ルートの CONTEXT.md（システムレベルのアーキテクチャ、境界、用語集）
• この変更が触れるコンポーネントの CONTEXT.md ファイル
• manifest.yaml（クラス、言語、親エピック ID、過去の差し戻しがあればその内容）
• Preconditions で選択したアーキテクトまたは reforge のシード。シードの選択肢と推奨事項は、決定ではなく、検討の出発点として扱います。architecture.md の Context Gathered の下にシードを記録します。
• manifest.parent が設定されている場合（エピックの子である場合）： 親エピックの architecture.md、decisions.md、およびこの変更のディレクトリにある architect-seed.md があれば読み込みます。これらを開始時のコンテキストとして扱い、エピックレベルで決定済みの内容を再検討しないでください。

この変更が関係する firm の境界を記録します。この変更で対処できる Known-soft-spots（改善の余地が明示的に残されている箇所）にも留意します。

フェーズ 2：アーキテクチャを段階的に確認する

簡潔な番号付きの項目に分けて、体系的な確認の話し合いを行います。1つずつ質問する面接ではありません。ユーザーが決定権を持つ、重要なアーキテクチャ上のトピックごとに、次の内容を示します。

• 質問、エージェントの推奨案、その理由、妥当な代替案を示します。
• 明示的な回答を求めます。回答方法は、accept、代替案の選択、または決定の提示です。ユーザーは項目番号を使って簡潔に回答できます。
• 回答がない、曖昧、または不明確な項目は unresolved のままにします。未解決の項目だけをフォローアップします。沈黙を承認と推測してはいけません。
• 回答に異議を唱えるのは、曖昧な場合、問題を招く場合、またはイディオム集と矛盾する場合に限ります。ユーザーが異議を退けた場合は、推奨案、ユーザーの決定、理由が示されていればその理由を記録します。
• ユーザーが決定権を持つ重要な項目がすべて明示的に確認されるまで続けます。確認済みの決定と矛盾しない限り、ローカル、プライベート、取り消し可能で慣例的なイディオムに沿った詳細は自動的に選択し、質問も記録も行いません。

検討するトピック。ただし、重要性の基準を超える場合にのみ質問してください。

1. 変更の概要。 何を構築し、その理由は何ですか？スコープがマニフェストの class と一致することを確認します。
2. 全体の中での位置付け。 どのコンポーネントに手を加えますか？どの境界を越えますか？
3. 既存コードの品質。 よりよい解決策で対処できる Known-soft-spots や緩い境界はありますか？リファクタリング案は明示的に提案します。implement で見つけることにならないようにしてください。
4. アーキテクチャ上の決定。 主な決定ごとに、決定内容を示し、確定度（デフォルトは soft）をタグ付けします。firm が提案されている場合は、その妥当性を確認します。
5. 新たな境界。 この変更でどのような新しい境界が生まれますか？それぞれの境界を何が越えますか？
6. テスト可能性。 この変更をどのようにテストしますか？どの境界が、確定した境界テストを行うだけの確かさを備えていますか？
7. オブザーバビリティ。 何を計測・記録する必要がありますか？
8. イディオムの確認。 提案された設計は、その言語本来の強みを活用していますか？イディオム集と照合します。直訳調で不自然な箇所があれば指摘します。
9. 対象範囲内のリファクタリング。 それぞれを列挙し、正当性を説明して、明示的な承認を得ます。architecture.md に記録します。

作業中は、アーキテクチャ確認台帳を維持します。解決済みの各項目には、決定 ID、推奨案、ユーザーの明示的な回答、confirmed ステータスが必要です。これを architecture.md に含めます。

フェーズ 3：architecture.md を作成する

ユーザーが決定権を持つ重要な項目がすべて確認されたら、references/templates/architecture.md.tmpl をもとに architecture.md を作成します。説明文による決定事項の前に、確認台帳を完全な形で記載します。すべてのセクションを埋めます。境界 ID、確定度タグ、リファクタリングを正確に記述します。

書き込み先：.changes/active/<id>/architecture.md

フェーズ 4：範囲を限定した敵対的妥当性レビュー

references/adversarial-review.md に従い、完全なドラフトに対して AV-* サイクルを正確に 1 回実行します。新しい批評者が幅広い観点から 1 回の探索パスを実施し、該当する範囲で、データ／状態、データ構造、インターフェース／トレイト、エラー、セキュリティ、可観測性、シンプルさ、保守性、慣用的な書き方を深くレビューします。N/A の定型記述は不要です。

すべての指摘を 1 つのバッチにまとめます。各指摘には、安定した AV-NNN ID、重大度 blocker|major、カテゴリ correctness|security|simplicity|maintainability|idioms、根拠、具体的な影響、具体的な代替案を含めます。バッチ全体を 1 回で修正します。修正が重要性の境界を越える場合に限りユーザーに確認し、ローカル／プライベート／可逆的な慣例上の選択肢は自動的に選びます。

新しい検証者を起動し、元の ID のみを確認します。検証者は探索を繰り返さず、範囲を広げず、新たな軽微または重大な指摘を追加しません。修正によって生じた blocker のリグレッションのみ、新しい ID の例外として認められます。これを --regression で記録し、同じ限定範囲内で修正して、1 回の対象を絞った再検証時に --regression-resolution で解決を記録します。ID が未解決のまま残る場合、または幅広いレビューが必要な場合は停止します。サイクル全体を Validity Check Results に記録します。問題がなければ、根拠に基づく簡潔な理由を記録します。

探索と検証は、現在の architect-N マニフェストエポックの下で記録します。問題のない場合：

node "$SKILL_DIR/scripts/review-log.mjs" record --id <id> --phase architect --cycle architect-N \
  --role auditor --reviewer "<fresh label>" --verdict approved
node "$SKILL_DIR/scripts/review-log.mjs" record --id <id> --phase architect --cycle architect-N \
  --role verifier --reviewer "<distinct fresh label>" --verdict approved

指摘がある場合、監査者は各 AV-* 行について、構造化された --finding JSON 引数を 1 つずつ使用し、検証者は元の指摘ごとに --resolution AV-NNN=resolved|unresolved を 1 つずつ指定します。

フェーズ 5：承認

確認台帳、決定事項、継ぎ目、承認済みリファクタリングの要約を提示します。台帳がユーザーの選択を正確に表しているか、ユーザーに確認します。次に、明示的に以下を尋ねます。

「ユーザーが決定権を持つ重要なアーキテクチャ上の論点はすべて明示的に確認済みで、範囲を限定した妥当性レビューに未解決の blocker はありません。architect の承認を行いますか？（変更は specify に進みます。）」

承認された場合：

node "$SKILL_DIR/scripts/manifest-approval.mjs" --id <id> --approval architect --approve

ユーザーに、次に specify を実行してください。 と伝えます。

---

参照ファイル

• references/challenge-protocol.md — 敵対的な姿勢と上書きルール
• references/adversarial-review.md — 範囲を限定した AV-* レビューサイクルと指摘のスキーマ
• references/context-schema.md — CONTEXT.md のスキーマ（既存ファイルを読む場合）
• references/seam-and-test-taxonomy.md — 堅牢性モデル
• references/manifest-schema.md — エピックの親子モデルを含むマニフェスト構造
• references/change-lifecycle.md — パイプライン全体
• references/firm-change-protocol.md — 堅牢な継ぎ目を変更する必要がある場合
• references/templates/architecture.md.tmpl — 出力テンプレート
• idioms スキル — manifest.language が設定されている場合に限り、該当するパックを読み込みます