Skip to content

Instantly share code, notes, and snippets.

@ryogrid

ryogrid/article.md

Last active December 30, 2025 22:28
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save ryogrid/709b026847b68b64b2fc36802d63262b to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save ryogrid/709b026847b68b64b2fc36802d63262b to your computer and use it in GitHub Desktop.
Download ZIP
PGの（ほぼ）全部のシンボルのドキュメントを生成してみた
Raw
article.md

どうも、ryo_grid です。

これは、PostgreSQL Advent Calender 2025 (シリーズ1) の23日分が空いていたので28日に書いた記事です。

はじめに

「PostgreSQLの内部実装を読みたいけど、100万行超のCコードはちょっと...」

そんなあなたに朗報です。 AIエージェントがPostgreSQLのソースコードを解析して生成した、関数や構造体ごとのドキュメントがあります!
というわけで、今回はそのような取り組みを行う個人プロジェクトである create_pg_super_document を紹介します。

  • create_pg_super_document
    • (もっとまともな名前をつければよかったとちょっと後悔しています^^;)

まずは、実際に生成されたドキュメントを見てみましょう。

生成されたドキュメントの例

シンボルごとのドキュメント

generated_docs/ ディレクトリには、PostgreSQLの各シンボル（関数・構造体・定数など）のドキュメントがマークダウンファイルとして格納されています。

例えば、walreceiverのエントリポイントである WalReceiverMain 関数のドキュメントだと以下のようなこんな感じ。

GitHub ActionsとGitHub PagesでWebページとしてもホスティングしてあり、それだとこちら。

なお、Webページとしてホスティングしてあるページのrootは以下です。

  • PostgreSQL 17.6 LLM Generated Symbol Documents
    • 右上の検索フォームでインクリメンタルサーチできるようにしてあるのが地味に便利だと自分では思っています
    • 18系でなしに、17.6かよ！というお声もあるかと思いますが、後述の通り生成するのに結構時間がかかるので当面は17.6のもののままだと思います...

いくつか生成に失敗して漏れているものはあるものの、ほとんどの関数や構造体のドキュメントについては生成されていると思います。 なお、contribディレクトリ配下はまだ生成できていません。

トピック別ドキュメント

シンボル単位だけでなく、特定のサブシステムについて解説するドキュメントも生成してみました。
（今後も増やしていく予定）

topic_specific_generated_docs/about_wal/ には、WAL（Write-Ahead Logging）システム全体の包括的なドキュメントが格納されています。

せっかくなので一部抜粋して、なんか映えそうな図を貼っておくと、WALのデータフローは以下のように可視化されています。

flowchart LR
    A[Transaction] --> B[XLogInsert]
    B --> C[WAL Buffer]
    C --> D[WAL Files]
    D --> E[Standby Server]
Loading

このように、個別シンボルの詳細に加え、サブシステム全体の俯瞰など詳細度・抽象度の違うドキュメントの生成についてもトライしています。

このプロジェクトの目的

PostgreSQLは巨大なコードベースから成るソフトウェアです。
内部実装を理解しようとすると、以下のような課題に直面します。

課題 従来のアプローチ
関数の役割がわからない ソースコードのコメントを読む / grep
呼び出し関係が複雑 ctagsやcscope等で追いかける
サブシステム全体の構造が見えない 公式ドキュメント + 解説サイト + 個別の解説記事や資料（スライドとか）

現在の取り組みは、AIエージェントを活用して生成したドキュメントにより、これらの労力をいくらかでも緩和することです。
特に、PG hackerの方々というより、コードベースよく分かってないけどコントリビューションしてみたい！といった方々の感じる敷居を下げることを目的としています。

仕組み

技術スタック

  • Python
  • GNU GLOBAL
    • (公式曰く）source code tagging system
  • DuckDB
    • 組み込みDB。SQLiteでないのは、内部でスレッド並列でデータ処理してくれたりするらしいので速いかなーと期待して。実際のところ比較はしていません...
  • AI Agent (Claude Code)
    • ひと月100$のプランのサブスクで使えるusageだと、シンボルのドキュメント生成はなんだかんだ一カ月くらいかかかりました
      • ノンストップで処理が行えればもっと短期間で行えたと思いますが、usageのlimitがあるので、1-2時間で一旦処理が止まって、数時間後に再開されるというような動作をしていました
    • Pythonコードとプロンプトの書き換えは必要かと思いますが、同様のことは他のAI Agent、といいますか、コーディングエージェント？でもできるはずです

シンボルごとのドキュメント生成

大まかなフローは以下のとおりです。

flowchart LR
    A[PostgreSQL<br/>ソースコード] --> B[GNU GLOBAL<br/>シンボル抽出]
    B --> C[DuckDB<br/>データ整理]
    C --> D[AI Agent<br/>ドキュメント生成]
    D --> E[Markdown<br/>ドキュメント]
Loading
  1. GNU GLOBAL でソースコードからシンボルの定義・参照関係を抽出
  2. DuckDB にシンボル情報と依存関係を格納・整理
  3. AIエージェント（Claude Code） がコンテキストを取得しながらドキュメントを生成

詳細な実行手順やテーブルスキーマについては、リポジトリのREADMEをご参照ください。

基本的には私以外でも再現可能なようにしてあるつもり・・・です。
GNU GLOBALで解析済みのシンボル間の依存関係や生成済みのシンボルドキュメントについては、データをリポジトリ内にDuckDBのdbファイルとしてぶち込んで格納してあるので、それらのデータを使って何かするということも可能です。

トピック別ドキュメントの生成方法

シンボル単位のドキュメントはclaudeコマンドをコマンドラインツールとして用いたバッチの形で生成しましたが、トピック別ドキュメントは、インタラクティブモードのClaude Codeにプロンプトを与えて、サブエージェント（Claude Codeの機能）も活用しつつ生成しました。

flowchart TB
    O[Orchestrator<br/>Claude Code Interactive]
    O --> A[Architecture<br/>Analyzer]
    O --> B[Detail<br/>Documenter]
    O --> C[Integration<br/>Optimizer]
    
    A --> D[依存関係マップ]
    B --> E[詳細ドキュメント]
    C --> F[最終成果物]
Loading

3つのサブエージェントが以下の役割を担います。

サブエージェント 役割
Architecture Analyzer エントリポイントから依存関係を探索し、構造を把握
Detail Documenter 重要シンボルの詳細ドキュメントを作成
Integration Optimizer 各ドキュメントを統合・整理して最終成果物を生成

自作のMCPサーバ経由でシンボル情報を取得しながら、段階的にドキュメントを構築させました。 詳細は 利用したプロンプト と 各サブエージェントの定義 をご参照ください。

なお、別にシンボルのドキュメントを参照させなくても同じようなドキュメントは生成できたと思いますが、私の主観的評価ではシンボルのドキュメントを参照可能としたことで、生成されるドキュメントの品質はいくらか上がったように感じています。
（コードを直で読ませると、それだけしか読んでなくて大丈夫!？という程度の量を読んだ段階で、コードは理解した！と言ってドキュメントの生成に移ってしまったりする）

あとは、トークンの消費は減っていた（る）のではないかと思います。

その他生成したもの

  • ENTRY_POINTS.md
    • PGを構成する各種プロセスのエントリポイントのドキュメントへのリンク集
  • CODE_TREE.md
    • コードツリーの構造をいくから見やすくしたもの
    • ディレクトリ内にコードの説明をするREADMEなどがある場合は、それへのリンクも抽出してある

注意

AI生成のため、残念ながら正確性は保証しません！

リポジトリのREADMEにも記載していますが、生成されたドキュメントはAIが作成したものです。
おおむねうまくいっているように見えますが、いわゆるハルシネーションが起きている箇所もあるだろうと思っています。
従って、少なくともシンボルごとのドキュメントにはソースコードへのリンクも含めてあるので、これ怪しくね・・・？という時はソースコードと併せてご参照下さい。

おわりに

PostgreSQLの内部構造に興味がある方、コントリビューションを検討している方は、ぜひ一度覗いてみてください。
きっと、コードリーディングがいくらかラクになるはずです。 では、enjoy!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment