文書を作るAIエージェントのアプリを、新旧2つのスタックを取り違えずに直す

## 最初に、コードから本当の起動コマンドと設定を探す まず、パッケージメタデータ、コンソールのエントリーポイント、設定ローダー、環境変数の処理、実行時ワークスペースを作成するコードを確認する。説明文と矛盾する場合は、これらの実行可能な要素を優先する。 - どのコマンドが主要アプリケーションを起動するか確認する。 - どのコマンドが旧サービスやMCP互換サービスを公開するか確認する。 - 各コマンドを実際のモジュールと関数までたどる。 - 設定テンプレートとワークスペースの既定動作を特定する。 - 参照されているパスが現在のチェックアウトにすべて存在することを確かめる。 古い概要は過去の経緯として扱い、現在の起動経路を示す根拠にはしない。 ## 変更を受け持つのが、今のスタックか古いスタックかを決める リポジトリには、現行の製品スタックと、特定用途のエンドポイントを今も支える旧世代のライブラリが併存することがある。編集する前に、どちらのスタックが対象を担当しているか特定する。 現行スタックが担当する可能性があるもの: - コマンドラインインターフェースと導入フロー - オーケストレーションとマルチエージェント実行 - 調査、生成、デザインを担うエージェント - 検索、振り返り、変換、タスク管理のためのMCP形式のツール - 設定、ログ、ワークスペースのユーティリティ - ブラウザを使ったHTML変換とNodeヘルパー - 統合を重視したテスト 旧スタックが、テンプレート駆動の生成、レイアウト推定、解析、評価、互換サーバーを今も担当している場合がある。一方のスタックで共通概念を変更すれば、もう一方にも反映されるとは考えない。 ## 特別扱いを減らし、短い関数でシンプルに作る 条件分岐を積み重ねるのではなく、例外的なケースを通常のケースとして扱える設計を優先する。仮想的なアーキテクチャ問題ではなく、実際にリポジトリで起きている問題を解く。 - 実際の要件を満たすなら、直接的で運用負荷の軽い解決策を選ぶ。 - 関数は短く、目的を絞り、分かりやすい名前にする。 - 不要な複雑さは欠陥として扱う。 - インデントが3階層を超えるなら、コード構造を見直す合図とする。 - 具体的な失敗条件がないまま、通常の制御フローを広範な例外処理で覆わない。 - 批判は人ではなく、コード、設計、前提に向け、技術的な内容に限る。 優れた判断は、特殊ケースの少なさ、対象範囲の小ささ、検証しやすい動作に表れる。 ## 型注釈を付け、依存関係を必要なだけに保つ 保守対象のスタック全体で、一貫した規約を適用する。 - 関数とメソッドに型注釈を付ける。 - 技術文書とコードコメントは、リポジトリで定められた言語で書く。 - 現行の依存関係管理ツール、リポジトリ検索ツール、言語機能、サポート対象のライブラリAPIを使う。 - 非推奨の形式より、現行のシリアライズ用インターフェースと検証用インターフェースを優先する。 - 依存関係とコード総量を最小限にする。 - ルートのパッケージ定義は主要製品に集中させる。 - 実際に独立しているサブプロジェクトの依存関係は、そのサブプロジェクトの依存関係ファイルに置く。 整理だけを目的に依存関係を移動しない。実行時と保守上の境界が実在する場合に限って分離する。 ## 変更をつながった部分まで追い、PythonとNodeの両側を調べる 変更対象の動作を担当する経路全体を調べる。 - コマンドラインの動作では、コマンド定義、共有コマンドヘルパー、設定読み込みをまとめて調べる。 - オーケストレーションでは、中心となるコーディネーターと対象エージェントの実装を調べる。 - MCPの動作では、現行のツールサーバーと旧互換サーバーのどちらが担当するか判断する。 - エクスポートと変換では、Python側のオーケストレーションとNode側の変換処理を両方調べる。 - 生成に関する概念が重複している場合、タスクが両方を明示的に対象としていなければ、担当するスタックだけを変更する。 変更範囲を限定する。似た名前が両方にあるという理由だけで、両方のスタックをまとめてリファクタリングしない。 ## 今ある設定の名前とワークスペースの場所を変えずに保つ 既存の設定キー、環境変数、導入時の動作、設定例、ワークスペースの場所は、ランタイム契約を形成している。タスクに移行作業が明示的に含まれていない限り、それらの名前を変えない。 ブラウザやコンテナへの依存は、任意の開発用追加要素ではなく、変換経路に必要な通常のランタイム要件である場合がある。ネイティブ変換ツール、モデル認証情報、ブラウザ自動操作、コンテナイメージによって、実行できる統合テストが決まることもある。 ランタイム経路を変更する場合: 1. すべての設定元と既定値を特定する。 2. 導入フローと設定例がそれらの値をどのように設定するかたどる。 3. Python側の呼び出し元と外部の変換ヘルパーを確認する。 4. 互換性を保つか、明示的な移行経路を用意する。 ## 古い文書をコードで確かめ、テストを必要な環境で分ける 文書の記述を信頼する前に、現在のファイルツリーと実行可能なエントリーポイントに照らして確かめる。古い文書は、なくなったファイルや廃止された起動フローを挙げていても、有用な概念を説明している場合がある。 必要なものに応じてテストを分類する。 - 独立したロジックを対象とする単体テスト - 特殊なデータ経路を対象とするパーサーテストやマーカー付きテスト - サンドボックスツール、ブラウザやPDFの変換、画像処理、外部ユーティリティを対象とする統合テスト - 認証情報やネットワークサービスを必要とするモデル利用テスト ブラウザ、コンテナイメージ、ネイティブ変換ツール、モデル認証情報の不足は検証上の制約であり、無関係なコードが壊れている根拠ではない。 ## 意味のある最小のテストを回し、回せなかった確認を報告する 焦点を絞った変更手順を使う。 1. どのスタックとエントリーポイントが対象の動作を担当するか確認する。 2. 完結する最小範囲を編集する。 3. 意味のある最小範囲のテストを実行する。 4. 直接結合しているPython、Node、ブラウザ、コンテナ、互換経路に限って範囲を広げる。 5. 検証を妨げた依存関係や環境要件を報告する。 最終差分を見直し、もう一方のスタックへの意図しない変更、設定契約の名称変更、古い文書参照、無関係なリファクタリング、未検証の言語間境界がないか確認する。 何を変更したか、どの経路を実行したか、どの確認に合格したか、どの確認を実行できなかったかを報告する。必要なランタイム依存関係が利用できなかった場合は、完全に検証できたと主張しない。