こんにちは。ノバセルの新開です。

この記事はノバセルテクノ場出張版2025 Advent Calendar 2025の12日目の記事です。

はじめに

私の所属するインフラ＋OP改善チームでは、負債解消や定型作業の型化を軸に、自動化を積極的に進めています。

その中で私は、開発フローを「周辺理解 → 課題発見 → 設計 → 実装」の 4 フェーズに整理して運用しています。

理解: コードリーディング & コンポーネント理解
- 現在の設計がどのデザインパターンに分類され開発者の思想が理解できる
- アーキテクチャ図を作成できる
発見: 自分の中で定めた正解の型との比較
- 技術書を読む & 時事的トレンドを追う
- 現実のコードと自分が吸収した知識体系との差分によって課題が見えてくる
設計: アーキテクチャを理解した上で最小限のコストで実現
実装

私が中でも最重要だと考えているのが "周辺理解" です。理解が浅いまま設計や実装に踏み込むと、中長期的にはかえって負債を生むことに繋がってしまうと考えています。

既存設計がどのデザインパターンに基づいているか
実装者がどんな思想でコンポーネントを組んだのか
アーキテクチャを図として再構成できるか

これらは、コードリーディングの世界でも何度も語られてきた重要テーマです。

ディープコードリーディングのすすめ｜牛尾剛では、「主要開発者が何を考えて書いたかまで読み解く」ことを重視していて、私もその姿勢を継承しています。

ただ、現実には巨大リポジトリを手作業で読むには時間が足りない。そこで「理解速度をどう最大化するか」が私の最重要テーマになりました。

知らないコードベースに挑むという、誰もが感じるコードリーディングの壁

しかし現実には、大規模リポジトリのコードリーディングは想像以上に負荷が高く辛いです。

何百ファイルもある
境界が見えにくい
設計思想が散在している
どこから読めばいいのかが分からない

巨大リポジトリは、まず「どこから読めばいいか分からない」という壁があります。フォルダ構造を眺めるだけで時間が経過し、責務ごとの境界を推定するのにさらに膨大な時間が必要となる。

AIに質問しても、粒度が変わり、回答内容が毎回異なり、抜け漏れも多い。質問の粒度や文脈の与え方によって回答が毎回ブレる。「正しい地図」を安定して得ることは意外と難しいです。

リポジトリの"構造"が分からない状態では、どんなAIを使っても迷子になります。そこで私は「最初に地図を作る」「その作業を自動化する」という方向に舵を切りました。

Claude Custom Skill で“地図を描く”という発想

チャットのような単発の対話では、AI の回答はどうしても揺らぐ。そこで私は、解析手順そのものを固定化し、毎回同じ工程でリポジトリを読めるように Claude Custom Skill を作成しました。作成したSkillはこちら

この Skill は、コードを読み"要約する"のではなく、"構造化します"。

なぜClaude Custom Skill を採用したのか

理由はいくつかありますが、特に強調したいのが「理解したつもり」の状態を脱し "安全に変更できる" 状態にまで引き上げられる設計が可能である点です。

柔軟に出力をカスタマイズすることで、単なるコード理解の支援に留まらず、影響範囲・リスク・プロジェクト固有の検証手順を明示的に整理できます。特に、変更の影響範囲が大きい領域では、コード理解と運用判断を切り離して考えることはできません。

静的なドキュメントではなく、状況に応じて判断を補助する仕組みを持つことで、レビュー漏れや認識齟齬による運用リスクを下げられると考えました。この点が、「理解したつもり」の状態から、「安全に変更できる」状態への移行を支援できると判断し、Custom Skill を採用した大きな理由となります。

Skill の内部処理：3段階パイプライン

構造抽出（Structural Extraction）
- ディレクトリ構造を走査
- ファイル種別を分類
- エントリポイントや SDK 境界を検出
レイヤリング（Layering）
- 関連するディレクトリを "層" として再構成
- 責務ごとの境界（Provider / Domain / SDK / Tests）を自動で判断
- ASCII 図として依存関係を可視化
メタ分析（Meta Analysis）
- 読むべき順序を推定
- 依存集中点（ホットスポット）を抽出
- 理解コストの高い領域をランキング化

どんな大規模リポジトリでも再現性高く同じ分析手順を踏むように設計しています。結果として、人間が 1〜2 日かけて行う“全体理解フェーズ”を数秒で代替できるようになります。

本記事では例としてterraform-provider-snowflakeのリポジトリを読み込ませてみました。

github.com

実行結果：Skill が描く"コードベースの地図"

最もインパクトがあると感じているのが、この地図（レイヤーモデル）です。

flowchart TB
    A["main.go<br/>(Entry Point)"]

    B["pkg/provider<br/>(Terraform Plugin SDK Boundary)<br/>- provider.go: リソース/データソース登録<br/>- 認証処理・設定読み込み"]

    C["pkg/resources<br/>(100+ リソース)"]
    D["pkg/datasources<br/>(55+ データソース)"]

    E["pkg/schemas<br/>SDK Object → Terraform Schema 変換<br/>(部分自動生成)"]

    F["pkg/sdk<br/>Snowflake SDK (112,000+ lines)<br/>- client.go: 70+ DDL Commands<br/>- 各オブジェクトの CRUD 操作<br/>- コード自動生成"]

    G["gosnowflake (Snowflake Driver)<br/>+ sqlx (DB操作)"]

    A --> B
    B --> C
    B --> D
    C --> E
    D --> E
    E --> F
    F --> G

＊出力されたレイヤ関係図をMermaid記法に変換しています。実際の出力はこちら

リポジトリ全体がレイヤとして再構成され、役割が明確に可視化されています。 Skill なら安定したフォーマットで即座に得られ、「まず全体像を掴む」という工程が一気に軽くなりました。

読むべき順序 Top5：理解の最短ルートが可視化される

構造が分かったら、次に欲しいのは「どの順番で読むと最短で理解できるか」になります。 Skill はレイヤー・依存方向・ファイル数をもとに、自然な読み順を生成してくれます。

優先度	ファイル / ディレクトリ	着目すべき観点	理由
1	main.go	エントリポイント、プロバイダー起動フロー	全体構造の起点
2	pkg/provider/provider.go	プロバイダー定義、設定スキーマ	全リソースの登録点
3	pkg/sdk/client.go	SDK クライアント構造	Snowflake 操作の中核
4	pkg/resources/warehouse.go	リソース実装パターン	標準 CRUD の代表例
5	pkg/sdk/warehouses.go	SDK 実装パターン	リソースと SDK の対応関係

※ この後も Resource 共通部 / Schema 生成 / Grant 系 / Datasource / Generator / Test などが続く（全15項目）

実際に生成された順位づけはこちら

この順位づけは新人オンボーディングでも利用できます。読む動線をあらかじめ決めておくと、理解スピードが劇的に向上します。

ホットスポット分析：影響範囲の大きい"危険箇所"の可視化

開発前には「変更による影響範囲の大きい箇所」も理解しておくことが重要です。

flowchart TB
    A["pkg/sdk/client.go"]

    B["pkg/sdk/common_types.go<br/>(識別子定義)"]
    C["pkg/sdk/config.go<br/>(設定)"]
    D["pkg/sdk/grants.go<br/>(権限)"]

    E["pkg/resources/common.go<br/>(DiffSuppress / Validation / Helper 関数)"]

    F["pkg/resources/warehouse.go<br/>(100+ リソース)"]
    G["pkg/resources/grant_*.go<br/>(複雑な権限)"]
    I["pkg/datasources/warehouses.go<br/>(55+ データソース)"]

    A --> B
    A --> C
    A --> D

    B --> E
    C --> E
    D --> E

    E --> F
    E --> G
    E --> I

＊抽出されたホットスポットをMermaid記法に変換しています。実際の出力はこちら

設定・接続まわり
共通インフラ層
ドメイン的に重要かつ依存集中モジュール

これらは、変更時のリスクが危険度: 高で、レビューでも注視すべき領域と分かります。改修前に"危険箇所の特定"ができているのは非常に強いと思います。

終わりに：コードリーディングは"構造化の行為"へ

私は「エンジニアの生産性は事前理解の質で決まる」と考えています。実装スピードは AI が補完する時代になりつつありますが、代わりに "理解" の重要度は以前より増していると思います。

Custom Skill を使って最初の俯瞰作業を自動化すると、コードリーディングが「読む行為」から「構造化の行為」に変わることでしょう。どれだけ大規模なリポジトリであっても、まず Skill によって安定した（読みやすい）地図を描かせてみてください。

—— 読む前に、地図を作れ。これがこの記事のメッセージです！