Agent Skills: Tech Fit Analyzer

Tech Fit Analyzer

既存のコードベースに特定の技術を導入することが正当かどうかを評価し、 導入した場合に具体的に何が変わるかを明らかにする。

このスキルが存在する理由：技術の選定はレバレッジの高い意思決定であり、 良い選択は何年にもわたる生産性向上として複利的に効いてくる一方、 悪い選択は巻き戻しコストの高い技術的負債になる。 目的は、流行への追従ではなく、証拠に基づいた誠実な評価を提供すること。

ワークフロー概要

1. コンテキストの把握
→ 2. 並列調査（リポジトリ分析 + 技術リサーチ）
→ 3. 適合性の評価
→ 4. レポート生成

ステップ1：コンテキストの把握

分析に入る前に、以下の情報を確認する。

リポジトリについて（必須）：

• コードの所在（ローカルパスまたはGitHub URL）
• 主要な言語・フレームワーク
• プロジェクトの規模感（個人の小さなプロジェクト？本番稼働のモノリス？マイクロサービス？）

候補技術について（必須）：

• 検討している具体的なツール/ライブラリ/フレームワーク名
• 導入で解決したい課題（または興味を持った動機）

あると良い情報（文脈から明らかでなければ聞く）：

• チームの規模と経験レベル
• 制約事項（例：「ビルドシステムは変えられない」「Node 18必須」）
• 時間的な切迫感（じっくり検討できるのか、次のスプリントで必要か）

会話の中で大半の情報がすでに出ている場合は、そこから抽出する。 わかっていることを再度聞かない。不足分だけ質問する。

ステップ2：並列調査（サブエージェントによるオーケストレーション）

このステップでは、リポジトリ分析と候補技術のリサーチを並列に実行する。 メインスレッドのコンテキストウィンドウを圧迫・汚染しないために、 それぞれの調査はサブエージェントに委任し、要約だけをメインに返す構成にする。

並列化の設計思想

リポジトリの全ファイルを読み込んだ生データや、Webリサーチの全文をメインスレッドに 流し込むと、コンテキストが膨張して後続の分析品質が落ちる。 サブエージェントに「調査して要約を返せ」と指示することで、メインスレッドには 構造化された要約のみが届き、評価ステップに集中できる。

サブエージェント A：リポジトリ分析

以下の指示でサブエージェントを起動する：

あなたはリポジトリ分析の専門エージェントです。

対象リポジトリ: [パスまたはURL]

以下を調査し、構造化された要約を返してください：

1. プロジェクト構造（ディレクトリの全体像、主要ディレクトリの役割）
2. 技術スタック（言語バージョン、フレームワーク、主要な依存ライブラリとバージョン）
3. ビルド・ツールチェーン（バンドラー、コンパイラ、タスクランナー）
4. テスト基盤（テストフレームワーク、テストの有無と傾向）
5. CI/CDパイプライン（使用しているCIシステムと主要なジョブ）
6. コードの規模感（ファイル数、主要言語ごとの概算行数）
7. アーキテクチャパターン（MVC、レイヤード、モジュラーモノリスなど、読み取れる範囲で）

ローカルリポジトリの場合：
- まず `bash scripts/repo-snapshot.sh [パス]` を実行してスナップショットを取得
- 参考: references/stack-detection.md にconfig→スタックの対応表あり
- 主要な設定ファイルを読み、代表的なソースファイルを2-3個確認する

GitHub URLの場合：
- web_fetch でリポジトリページ、依存管理ファイル（raw URL経由）、READMEを取得
- CI設定があれば取得
- 代表的なソースファイルを1-2個取得

【重要】生データをそのまま返さないこと。上記7項目の構造に沿った要約を返す。
各項目は箇条書きで簡潔に。具体的なバージョン番号や依存名は省略せず含める。
全体で200-400行程度に収める。

サブエージェント B：候補技術のリサーチ

以下の指示でサブエージェントを起動する：

あなたは技術リサーチの専門エージェントです。

調査対象の技術: [技術名]
導入先の文脈: [言語/FW/規模の簡潔な説明 — ステップ1で把握した内容を要約して渡す]

web_search を使って以下を調査し、構造化された要約を返してください：

1. 技術の概要（何を解決するか、主な特徴、現在のバージョン、ライセンス）
2. システム要件・前提条件（対応言語バージョン、ランタイム要件など）
3. 移行ガイドの有無（特に「[現行技術]からの移行」に関する公式/コミュニティ情報）
4. 既知の問題・制約（GitHubのissue傾向、Stack Overflowでの頻出問題）
5. コミュニティの健全性（直近のリリース頻度、コントリビューター数、採用トレンド）
6. 類似技術との比較（主な代替候補とそれぞれの長所短所）
7. 実際の導入事例（ブログや事例紹介で見つかる移行体験談）

【重要】各情報源のURLと日付を明記すること。
12ヶ月以内の情報を優先する。
全体で200-400行程度の要約に収める。

オーケストレーションの手順

1. ステップ1の情報が揃い次第、サブエージェントA・Bを同時に起動する
2. 両方の完了を待つ
3. 返ってきた2つの要約をメインスレッドで統合し、ステップ3の評価に進む

エラー時の対応

• サブエージェントAが失敗した場合：メインスレッドで主要設定ファイル（package.json、go.mod等）のみ手動確認し、限定的な分析で続行。レポートに「リポジトリ分析が不完全」と明記する。
• サブエージェントBが失敗した場合：ユーザーに情報不足を伝え、既知の情報のみで評価する。レポートに「Web調査未完了：最新情報が反映されていない可能性あり」と明記する。
• 両方失敗した場合：ユーザーに状況を報告し、手動での情報提供（技術の公式ドキュメントURL、リポジトリの主要設定ファイルの内容等）を依頼する。

ステップ3：適合性の評価

ここがスキルの分析の中核。以下の5つの軸で評価する。

3-1. 技術的な互換性

具体的な接合点を確認する：

• 言語/ランタイムのバージョンは要件を満たしているか？
• 既存ライブラリとの依存関係の衝突はないか？
• 現在のビルドシステムと統合できるか、それとも新しいものが必要か？
• 現行フレームワークとの既知の非互換性はないか？
• テスト基盤はそのまま使えるか、変更が必要か？

判定：高 / 中 / 低 の互換性を、具体的な根拠とともに示す。

3-2. 移行コスト

導入にかかる工数を見積もる：

• 変更が必要なファイル/モジュールはどの程度か？
• 段階的に導入できるか（既存手法と共存可能）、それとも全面切替が必要か？
• 最小限の導入パス（MVP）は何か？（例：「まず1モジュールだけ適用」）
• 自動移行ツール（codemodなど）は存在するか？
• CI/CDパイプラインの変更は必要か？
• 所要時間の概算（時間 / 日 / 週 / 月単位）と、その前提条件

確信を持てない場合は正直に伝え、より正確な見積もりに何の情報が必要かを説明する。

3-3. 期待されるメリット

一般論ではなく、このコードベース固有のメリットを述べる：

• パフォーマンス改善 — 可能なら定量化（例：「類似プロジェクトの事例からバンドルサイズが XからYに削減」）
• 開発体験の向上 — コード量の削減、型安全性の向上、APIのシンプル化
• 保守性 — 複雑性を減らすのか、それとも場所を移すだけか？
• エコシステムの恩恵 — より良いツール群、コミュニティサポートの充実
• セキュリティ — 現行の手法にある既知の脆弱性を解消するか？

すべてのメリット主張は、リポジトリの現状の何かを具体的に参照すること。 「速くなる」は無価値。「現在のセットアップはXを使っており、既知のパフォーマンス問題Yがある。 この技術はZという仕組みでそれを解消する」が有用。

3-4. リスク・注意点

ここは網羅的に。多くの導入分析がこのパートで手を抜いて失敗する：

• 破壊的変更：既存機能の何が壊れうるか？
• 学習コスト：チームが現在使っているものとどれくらい異なるか？
• ロックイン：この決定を撤回するのはどれくらい大変か？
• メンテナンス負荷：このプロジェクトは活発にメンテされているか？放棄されたら？
• 隠れたコスト：インフラ変更が必要か？ライセンス費用は？
• エコシステムの成熟度：実戦で検証済みか、まだ尖った最先端か？

3-5. 自己批判的分析：この導入は本当に正当か？

最も重要なセクション。 技術導入には、よく知られた失敗パターンがある： チームが実際の問題を解決するためではなく、新しくて面白いから導入してしまうこと。 このセクションの役割は「悪魔の代弁者」になること。

以下の問いに誠実に答える：

• 課題の実在性：この技術が解決する問題は、このコードベースで実際に痛みになっているか？ それとも理論上の問題か？
• コスト対効果の比率：移行にかかる工数は、得られるメリットに見合うか？ 6ヶ月のプロジェクトでわずかなDX改善のために2週間の移行は割に合わない可能性がある。
• 既存スタックでの代替：現行技術の設定変更やちょっとしたリファクタリングで 同じ課題を解決できないか？
• 新規性バイアスの確認：動機は「これが今のモダンなやり方だから」であって、 「課題Xを解決するため」ではないのでは？トレンドの追従は技術的な根拠ではない。
• 機会費用：この移行に費やす時間で、チームは他に何を達成できるか？

このセクションは、導入が十分に正当化されていない場合、居心地の悪い内容になるべき。 礼儀のために結論を和らげない — ユーザーが必要としているのは誠実な分析。

ステップ4：レポート生成

構造化されたMarkdownレポートを会話内に直接出力する。以下のテンプレートを使用：

# 技術適合性分析: [技術名] → [リポジトリ名]

## サマリー

[2-3文のエグゼクティブサマリー。全体的な推奨を含む：
 推奨 / 条件付き推奨 / 現時点では非推奨]

## リポジトリのプロファイル

- **プロジェクト**: [名前/パス]
- **スタック**: [言語、フレームワーク、主要な依存]
- **規模**: [大まかなサイズ/複雑性]
- **この分析に関連する現行の課題**: [特定された場合]

## 候補技術の概要

[候補技術の簡潔な説明と、解決しようとする課題。
 バージョン、ライセンス、コミュニティの健全性指標を含む。]

## 評価

### 技術的な互換性: [高/中/低]

[接合点、衝突、要件に関する具体的な所見]

### 移行コスト: [見積もり]

[前提条件を明示した工数見積もり。最小限の導入パスを含む。]

### 期待されるメリット

[リポジトリ固有の、根拠のある具体的なメリット]

### リスク・注意点

[網羅的なリスク評価]

### この導入は正当か？

[自己批判的分析。直接的に答えるべき問い：
 「以上すべてを踏まえて、このチームは本当にこれをやるべきか、
  それとも時間のもっと良い使い道があるか？」]

## 推奨

[最終的な判断。導入を推奨する場合は具体的な次のステップ、
 推奨しない場合は代替案の提案を含む。]

レポート品質チェックリスト

レポートを提示する前に確認する：

• [ ] すべてのメリット主張がリポジトリの具体的な何かを参照している
• [ ] 移行コスト見積もりに前提条件が明示されている
• [ ] リスクセクションが少なくとも破壊的変更、学習コスト、可逆性をカバーしている
• [ ] 自己批判的分析が形式的でなく、本当に批判的である
• [ ] 推奨が具体的な行動を含んでいる（次のステップが明確）
• [ ] 汎用的な埋め草がない — すべての文がこのリポ × この技術に固有

行動指針

• バイアスの自覚：あなたはアドバイザーであり、推進者ではない。技術が合わないなら 明確にそう言う。ユーザーは煮え切らない「たぶん」より、はっきりした「いいえ」の方が助かる。
• スコープの規律：聞かれたことを分析する。React vs Vue を聞かれて、 強い理由がない限り Svelte を持ち出さない。
• 不確実性は許容する：何かを評価するのに情報が足りなければ、推測するのではなく 「Xを評価するにはYの情報が必要です」と言う。
• 抽象より具体：「パフォーマンスが向上する」は駄目。 「[根拠]に基づき、バンドルサイズが約30%削減できる可能性がある」が良い。
• ユーザーの文脈を尊重する：ソロ開発者の計算と20人チームの計算は異なる。 スタートアップのプロトタイプと規制産業のエンタープライズシステムでは制約が違う。 これを織り込む。