この記事は株式会社TRAILBLAZER Advent Calendar 2025 の 8日目の記事です。

ソリューション事業部の @yosimaeta です。

新しい環境にジョインした際、最初に直面するのがドメイン知識の獲得と、既存コードベースの把握です。

現在私が向き合っているのは、多くの事業ドメイン機能を内包する 「本格的なモノレポ」 です。
所属プロジェクトでは既にドキュメントが整備されていて、ビジネス背景や大枠のアーキテクチャについては既存の資料で十分に学ぶことができます。

とはいえ、詳細な仕様や「今の挙動」、そして行間に潜む文脈を正確に把握するには、やはり コードそのもの を読み解く必要があります。

本記事では、入社直後のオンボーディング期間（約2週間）を利用して取り組んだ 「AIを活用してコードベースを構造化して理解する」 という個人的な試行錯誤についてご紹介します。

目次

「読む」のではなく「構造化する」
AIによる構造解析とドキュメント化
構築した「Knowledge Base」の実例
おわりに

1. 「読む」のではなく「構造化する」

膨大なコードを漫然と読むだけでは、記憶の定着は困難であり、システム全体の構造も見えてきません。
そこで、AI（GitHub Copilot / Gemini）を壁打ち相手に読み解いた内容を Markdownファイル に書き起こし、自分専用の「Knowledge Base」を構築することにしました。

目的の整理

最初からチーム全員のための完璧な仕様書を目指すのはハードル高いため、あくまで「自分が開発を行うための・現状を理解するためのメモ」としてスタートしました。

overview.md
- そのディレクトリ（施策）のビジネス目的と構成概要
flow.md
- 処理フロー図とデータ連携の可視化
repository-overview.md
- リポジトリ全体の依存関係や推測される設計思想

2. AIによる構造解析とドキュメント化

実際にKnowledge Baseを作成する際に行った、AIとの対話プロセスを紹介します。
最初から完璧な指示はできないので、曖昧な指示からスタートしつつ、出てきたアウトプットに対して欲しい情報を補足していきました。

Case 1: 複雑なディレクトリ構造の意図を紐解く

各ディレクトリにはアプリケーションコードとインフラ定義が同居していて、おおよそ推測はつきつつも初見では構成意図を掴むのに時間がかかります。

実際のディレクトリ構成例（一部抜粋・加工）

feature-promotion/
├── app/
│   ├── cloud_functions/
│   │   ├── trigger_event/
│   │   └── process_logic/
│   └── workflows/
│       └── main_process.yml
├── terraform/
│   ├── envs/
│   │   ├── dev/
│   │   └── prod/
│   └── modules/
│       ├── functions.tf
│       └── pubsub.tf

これをAIに分析させ、「なぜこの構成なのか」を言語化しました。

🧑‍💻 私の指示

このディレクトリ構造と主要ファイルを分析し、アーキテクチャの特徴を要約してください。特に terraform/envs と app の関係性について解説してください。

🤖 AIの分析結果 → overview.md へ

環境分離
- Terraformは envs 配下で環境（dev/stg/prod）ごとにstateを管理しており、環境間の独立性が高い

デプロイ単位
- app 配下のコードは terraform/modules を通じてデプロイされ、アプリケーションとインフラが密結合に管理されている（マイクロサービス的な独立性）

Case 2: 処理フローを可視化する

コードを追うだけでは理解しづらい「非同期連携」の流れを可視化します。

🧑‍💻 私の指示

app/workflows のYAML定義と、そこから呼ばれる cloud_functions のコードを読み込み、処理フローをMermaid記法で図解してください。

🤖 AIの出力 → flow.md へ

このように図解させることで、「Pub/SubをトリガーにWorkflowがオーケストレーションし、複数のFunctionsを制御している」という全体像が一目で理解できるようになりました。

3. 構築した「Knowledge Base」の実例

最初の2週間ほどで、リポジトリ外（ローカル環境）に以下のような構造のKnowledge Baseが出来上がってきました。
AIに複数のディレクトリや設定ファイルを横断的に読み込ませることで、単一のREADMEを読むだけでは得られない「リポジトリ全体の傾向」が見えてきました。

作成された Knowledge Base の一部

my-knowledge-base/
├── repository-overview.md       # リポジトリ全体の概観
├── repository-challenges.md     # 発見した課題一覧
├── ideal-architecture.md        # 将来的なアーキテクチャ構想
├── gcp-services-overview.md     # 利用しているGCPサービスカタログ
│
├── feature-promotion/           # 各施策ドメインごとの詳細
│   ├── flow.md                  # Mermaidによる処理フロー図
│   └── overview.md              # 概要・設計意図
├── feature-search/
│   ├── flow.md
│   └── overview.md
├── common-platform/
│   ├── flow.md
│   └── overview.md
│
└── ... (他 20+ ディレクトリ)

得られた洞察の例 (`repository-overview.md` より)

実際にAIがコードから導き出した洞察の一部です。
具体的な機能名ではなく、システム全体に通底する 設計思想 を掴むことができました。

レイヤー構造の推測
- 『データ集約層』がSingle Source of Truthとして機能し、『リアルタイム層』がイベント処理を担当、それらを『オーケストレーション層』がつなぐ構造になっている
標準化されたパターン
- 機能ディレクトリごとにインフラ構成（Terraform）が統一されているため、一つの機能を理解すれば他の機能も類推して読み解くことができる
堅牢性のための工夫
- 非同期処理における『重複実行防止』のための共通モジュールが各ワークフローで徹底して利用されており、データの整合性を重視している

「コードにはこう書いてある」という事実だけでなく、「設計者はこういう意図で組んでいる（はずだ）」という推測を含めて言語化できた点が大きな収穫でした。

既存のドキュメントとの答え合わせもしつつ、（よくある）仕様書には書いてない…という部分を補う役割でも使えそうでした。

4. おわりに

この取り組みによって、リポジトリの構造や変更時の影響範囲といった「土地勘」は、比較的早い段階で身についたと感じています。

しかし、現状の成果物はあくまで私のローカル環境に散らばる 「個人の理解を助けるためのメモ」 に過ぎません。
今後は、このKnowledge Baseをさらに発展させ、普段の業務プロセスやチームの開発フロー自体に組み込んでいきたいと考えています。

GitHub Copilot Workspace なども検討し、チーム全体で「活きたコンテキスト」として利用できる状態を目指す
新しくジョインしたメンバーが初日から開発に必要な全コンテキストと環境が即座に整う——そんな「AI前提のオンボーディング体験」を実現

これからも日々の開発を通じて試行錯誤を重ねて、プロダクトと組織への貢献に繋げていきたいと思います。

株式会社TRAILBLAZERでは、一緒に働くエンジニアを募集しています。
少しでも興味を持っていただいた方は、ぜひ採用ページをご覧ください！