analyze-new-repo

新しいリポジトリの分析

証拠が乏しいところで確信があるふりをせず、信頼できるリポジトリ分析を生成します。

目標は、軽量な要約を生成することではありません。目標は、読者が以下を理解できるよう支援する、コンパクトで証拠に裏付けられた分析を生成することです：

• このプロジェクトが本当にやろうとしていること
• どのように構成され、どのように実行されるか
• どの設計判断がリポジトリを特徴づけているか
• どの制約、リスク、盲点が最も重要か
• アーキテクチャ上の重心が実際にどこにあるか

使用するとき

このスキルは、ユーザーが以下の場合に使用します：

• 新しいリポジトリを持ち込み、全体像をつかみたい
• プロジェクトが何をするのか、どのように構成されているのかを尋ねる
• 慣れていないコードベースのビルド、実行、テストコマンドを知りたい
• リポジトリのウォークスルーやオンボーディングの要約を求める
• 変更を加える前に、信頼性の高い初回のアーキテクチャ分析を求めている

このスキルは、単一ファイルに関する狭い質問や、すでに理解しているコードベースにおける既知のバグには使用しないでください。

作業スタイル

表面的な証拠から、影響度の高い内部へと進みます。

• 実装ファイルを読む前に、リポジトリの指示とトップレベルのドキュメントから始めます。
• 推測よりも具体的な証拠を優先します。
• 推論は推論であると明示します。
• 重要でない詳細は圧縮します。
• 何が存在するかだけでなく、なぜそれが重要かを説明します。
• シニアエンジニアやコードアナリストのように書きます：技術的に主張があり、冷静で、正確に。
• オンボーディングのチェックリストや一般的なリポジトリ要約のように聞こえるのは避けます。

調査ワークフロー

1. リポジトリのコンテキストを確立する

まず最も価値の高い方向性を示す情報源を読みます：

1. AGENTS.md
2. README*
3. docs/、CONTRIBUTING*、ARCHITECTURE*、CHANGELOG* などのトップレベルのドキュメント
4. 存在する場合は最近の git 履歴

以下を記録します：

• 表明された目的
• ランタイムとプラットフォームの前提
• 文書化されたビルド、実行、テストコマンド
• 将来の変更に影響するローカルルール
• このリポジトリの種類：アプリケーション、ライブラリ、内部ツール、テンプレート、スキルパック、研究リポジトリ、インフラリポジトリなど

2. リポジトリの慣習とワークフローのシグナルを調べる

プロジェクトがどのように維持されているかを明らかにする、コントリビューションとワークフローの成果物を探します：

• .github/ISSUE_TEMPLATE/
• .github/PULL_REQUEST_TEMPLATE*
• CONTRIBUTING*
• CODEOWNERS
• CODE_OF_CONDUCT*

リポジトリの読み方に影響するものだけを記録します：

• issue と PR の期待事項
• テストやリリースの期待事項
• 所有権の手がかり
• 変更に必要なスクリーンショット、移行メモ、評価の証拠

これらのファイルが存在しない場合は、簡潔にその旨を述べて次に進みます。

3. 表面をマッピングする

ソースに踏み込む前に、トップレベルの構造を調べます。

以下を特定します：

• 主要なアプリケーションディレクトリ
• テスト、スクリプト、ドキュメント、アセット、設定、CI フォルダ
• 依存関係マニフェスト
• 想定されるエントリポイント
• 中心的に見えるディレクトリと周辺的なディレクトリ

リポジトリが大きい場合は、代表的なディレクトリをサンプリングし、サンプリングしていることを明示します。

4. 実行フローを特定する

まずドキュメントを使用し、次に設定ファイルと照合して検証します。

以下を見つけます：

• プロジェクトがどのように起動するか
• どのようにビルドされるか
• どのようにテストされるか
• デプロイやリリースの手がかり
• 環境の前提と外部サービス

ファイル間でコマンドが一致しない場合は、それを明示的に指摘します。

5. クリティカルパスを読む

中心的なエントリポイントと、実行パス上の主要なモジュールを開きます。

重要な各モジュールについて、以下を要約します：

• 役割
• 主要な入力と出力
• 主な連携先
• アーキテクチャ上なぜ重要か

広く浅く網羅するよりも、少数の価値の高いモジュールを優先します。

6. 品質のシグナルを評価する

以下を探します：

• テストの構成と明らかなカバレッジの形
• CI や自動化
• リリースフロー
• 依存関係の健全性
• ドキュメントの完全性
• メンテナンスのホットスポットや密結合

実際に見ることができるものだけを報告します。

7. リスクと不明点を指摘する

以下について明確にします：

• 不足しているドキュメント
• 不明確なランタイムの前提
• 脆弱なセットアップ手順
• テストの盲点
• 意外な依存関係
• 変更前に深い検証が必要な部分

スケール戦略

すべてのリポジトリが同じ扱いに値すると装うのではなく、リポジトリのサイズに応じて深さを調整します。

• 小規模リポジトリ: 主要なファイルを直接読み、真の制御経路をより深く掘り下げます。
• 中規模リポジトリ: 表面全体を調査したうえで、実行とアーキテクチャを定義する 3〜5 個のモジュールを選びます。
• 大規模リポジトリまたはモノレポ: サンプリングしていることを明示的に述べます。内部に踏み込む前に、マニフェスト、ワークスペース設定、ルートのドキュメント、CI、トップレベルのアプリ/パッケージディレクトリから始めます。
• リポジトリが大きすぎて全体を網羅できない場合は、幅優先の全体把握と、代表的な 1〜2 件の深掘りを優先します。

モノレポ戦略

リポジトリがモノレポである場合、単一のアプリケーションであるかのように記述しないでください。

まずリポジトリの形を特定します。

• デプロイ可能なアプリケーション
• 共有パッケージまたはライブラリ
• インフラストラクチャまたは devops ディレクトリ
• ドキュメント、サンプル、または補助的なツール

次に、以下のルールに従います。

• ルートレベルのマニフェスト、ワークスペース設定、ルートの README/ドキュメント、CI ワークフローから始めます。
• ワークスペースのマニフェストと CI を使用して、実際に何がビルド、テスト、デプロイされているかを突き合わせて確認します。
• 動作を要約する前に、リポジトリを境界ごとに分割します。
• どのサブプロジェクトが主要で、どれが補助的かを特定します。
• 全体の形をマッピングした後、ユーザーが網羅的な対象を明示的に求めない限り、最も重要な 1〜2 個のサブプロジェクトのみを詳細分析の対象として選びます。
• デプロイ可能なアプリ、共有パッケージ、インフラストラクチャを、フラットなリストの同列のものとしてではなく、異なるアーキテクチャ上の役割として扱います。
• テスト、CI、またはデプロイが、メインのアプリケーションコードとは異なるレイヤーで動作している場合は、そのことを明示します。

判断に迷う場合は、次のようなレポート構成を優先します。

• Repository Thesis
• Repository Shape
• Execution Model
• Architectural Center of Gravity
• Quality Signals and Risks

リポジトリに複数のパッケージ、アプリ、または所有権の境界が明確にある場合は、references/monorepo-checklist.md を使用します。

スタックを考慮したヒント

依存関係のマニフェストを、最初にどこを見るかに影響させます。

• package.json、ワークスペースファイル、turbo.json、pnpm-workspace.yaml: スクリプト、ワークスペース、アプリ/パッケージの分割、および想定されるフロントエンド/バックエンドのエントリーポイントを確認します。
• pyproject.toml、requirements*.txt、uv.lock: CLI のエントリーポイント、パッケージメタデータ、ツール設定、および Python ランタイムの前提を確認します。
• Cargo.toml: バイナリとライブラリの区別、ワークスペースメンバー、およびフィーチャーフラグを特定します。
• go.mod: モジュールの境界、cmd/ ディレクトリ、および内部パッケージのレイアウトを確認します。
• docker-compose*、Dockerfile*、Terraform、Helm、またはデプロイ設定: これらは単なるパッケージングではなく、運用上の形の証拠として使用します。

スタックが上記でカバーされていない場合は、マニフェストのファイル名、ワークスペース設定、ソースレイアウト、および CI ワークフローを使用して、同じ事柄 (エントリーポイント、パッケージの境界、ビルドパス、デプロイの形) を推測します。

これらはヒントであり、言語固有の厳格なプレイブックではありません。読み取り順序とエントリーポイントの検出を改善するために使用してください。

出力形式

構造の指針として references/report-template.md のレポートテンプレートを使用してください。執筆前にコンパクトな実行チェックリストが必要な場合は references/checklist.md を使用してください。リポジトリが明確なモノレポである場合は references/monorepo-checklist.md を使用してください。

出力は次の条件を満たす必要があります。

• Repository Thesis という短いセクションで始める
• リポジトリに適合するよう選んだ、合計 4〜6 個のセクションを含める
• リポジトリがそれを必要とする場合は、固定の万能なセクション名ではなく具体的な見出しを使用する
• 常にカバーする: 目的、実行パス、主要なアーキテクチャ、リスクまたは品質シグナル
• フラットな箇条書きを優先するが、セクションでより強力な統合が必要な場合は短い段落を使用する
• 各箇条書きに少なくとも 2 つの役割を持たせる: 事実を述べ、その含意を説明する

良いセクション名の例:

• Repository Thesis
• Repository Shape
• Execution Model
• Architectural Center of Gravity
• Project Conventions
• Quality Signals and Risks
• Distinctive Design Decisions
• Unknowns Worth Verifying

すべてのリポジトリで同じセクションタイトルを機械的に再利用し、結果が汎用的に感じられる場合は避けてください。

エビデンスのルール

• 重要な主張には具体的なファイルパスを引用してください。
• 確認済みの事実、根拠のある推論、不明点を明確に区別してください。
• 裏付けのない要約よりも、特定のファイルに結びついた記述を優先してください。
• 検証していないアーキテクチャの詳細をでっち上げないでください。
• 何かを検証できない場合は、その旨を直接述べてください。
• エビデンスをアーキテクチャ上または保守上の結果に結びつける観察を優先してください。

執筆の品質基準

結果は、軽い入門的な紹介文ではなく、短いアナリストレポートのように読めるべきです。

具体的には:

• README の文章をただ言い換えるだけにしないでください。
• すべてのリポジトリを同じ要約の形に平坦化しないでください。
• このリポジトリを際立たせている設計上の決定を浮き彫りにしてください。
• 技術的に優れた読者がコードを変更する前に実際に知る必要があることを強調してください。
• 読みやすさは保ちつつも、簡潔さを追求しすぎて分析の重みが失われないようにしてください。
• 事実 + 解釈 + 含意を組み合わせた箇条書きを優先してください。
• 文はコンパクトに保ちつつも、リポジトリがそれを要する場合は少し密度を許容してください。
• リポジトリに支配的なアイデアが 1 つある場合は、機械的に左右対称なレポートを避けてください。