AI編集者開発のリアル(7)　コードから連載企画を作る：プロジェクトスキャナーの仕組み

こんにちは、パレイド思想部です。

前回は連載企画をまとめた YAML から、複数の記事 MD を自動生成するフローを紹介しました。

今回はさらにその上流——連載 YAML そのものをどう作るかの話です。

「何を書くか」を決めるのが一番大変
7ステップのスキャンパイプライン
大プロジェクトの特定テーマに焦点を絞る
依存関係の自動探索
前回の連載 YAML 生成との接続
まとめ

「何を書くか」を決めるのが一番大変

ブログを継続していると、ツールも記事も増えていきます。自分のプロジェクトなのに「どのファイルが何をしているか」を正確に把握しきれなくなる。ましてや「この機能をどう連載記事に落とし込むか」を毎回ゼロから考えるのは、記事を書くこと以上に消耗します。

ai-editor のプロジェクトスキャナーは、プロジェクトフォルダのソースコードやドキュメントを LLM に読ませて、連載企画の YAML を自動生成するツールです。

7ステップのスキャンパイプライン

Step 1: ファイル走査・個別要約
         ↓
Step 2: 階層的統合要約（プロジェクト全体像）
         ↓
Step 3: 連載 YAML 自動生成（3パターン）
         ↓
Step 4: 設計意図推定
         ↓
Step 5: ユーザー価値推定
         ↓
Step 6: 記事別 refs ファイル生成
         ↓
Step 7: パターン別ドラフト Markdown 生成

Step 1〜2 が「プロジェクトを理解する」フェーズ、Step 3〜7 が「連載を企画する」フェーズです。

Step 1：ファイルを読んで個別に要約する

プロジェクトフォルダを再帰的に走査し、コードファイル（.py, .ts, .js 等）とドキュメント（.md, .yaml 等）を収集します。

各ファイルを LLM に渡して、以下の情報を抽出します。

そのファイルが何をしているか（1〜2文の要約）
主要な関数/クラスの一覧
依存関係（import しているモジュール）

大きなファイルはチャンクに分割して処理します。1ファイルの最大読み込みは12,000文字、チャンクサイズは6,000文字です。

python -m publish scan --project-dir /path/to/project --output-dir /path/to/output --step 1

Step 1 の出力はチェックポイントとして JSON に保存されるため、途中で止まっても再開できます（--resume）。ファイル数が多いプロジェクトでは数十分かかることもあるため、この中断耐性は重要です。

Step 2：プロジェクト全体像の統合要約

Step 1 の個別要約をディレクトリ階層に沿って統合し、プロジェクト全体の要約を生成します。

ディレクトリごとの要約
  ↓  LLM で階層的に統合
プロジェクト全体の概要（Markdown）

出力は {project_name}_project_summary.md として保存されます。このファイルが Step 3 以降の入力になります。

Step 3：連載 YAML の自動生成

ここが核心です。プロジェクト要約を LLM に渡し、3つの異なる構成パターンで連載企画を提案させます。

パターン	並べ方	特徴
A：技術層順	基盤 → コアロジック → UI → 運用	アーキテクチャを体系的に理解できる
B：ユーザー課題順	課題の共感 → 解決 → 最適化 → 発展	読者が追体験しやすい
C：開発時系列順	プロトタイプ → 改善 → 機能追加	開発のリアルな物語になる

当サイトの連載ではパターン B（ユーザー課題順）を基本としています。「記事を書くのが大変」→「AI に下書きを任せる」→「サムネイルも自動化」→「Analytics で改善」という流れは、読者が自分の課題に重ねて読み進められるからです。

生成される YAML はこのような形式です。

name: "AI駆動ブログ運営ツール「ai-editor」開発記"
category: "AIツール開発"
description: "ブログ運営の全工程をAIで自動化するツール群の開発記録"
audience: "ブログ運営者・AIツール開発に興味のあるエンジニア"
tone: "技術的に正確・実践的"
patterns:
  B_user_journey:
    label: "ユーザー課題順"
    articles:
      - title: "全体像を描く：なぜ「AI編集者」を作ろうと思ったのか"
        theme: "ブログ運営の課題と ai-editor の設計思想"
      - title: "WordPress を Markdown で管理する"
        theme: "ローカルと WordPress の双方向同期"
      # ...

Step 4〜5：設計意図とユーザー価値の推定

連載企画の質を上げるため、LLM にプロジェクトの設計意図とユーザー価値を分析させます。

設計意図（Step 4）：なぜこの構造にしたのか、どんな判断があったのか
ユーザー価値（Step 5）：このツールが使う人にどんなメリットをもたらすのか

これらは連載のトーンや各回の切り口を決めるときの参考情報として、YAML と一緒に出力されます。

Step 6〜7：記事別の参照ファイルとドラフト

Step 6 では、各回の記事に関連するソースファイルのリスト（refs）を生成します。「第3回のテーマに関係するのはこのファイルたち」という対応表です。記事を書くときに、参照すべきコードが一目でわかります。

Step 7 では、refs を元に各回のドラフト Markdown を生成します。これは前回紹介した LLM 記事生成パイプラインの入力として使えます。

大プロジェクトの特定テーマに焦点を絞る

大きなプロジェクトではファイル数が膨大になり、連載企画が散漫になりがちです。--focus オプションで一言加えると、連載企画の焦点を絞れます。

python -m publish scan \
  --project-dir /path/to/project \
  --output-dir /path/to/output \
  --focus "シミュレーション機能に注目して"

LLM への指示に焦点テーマが注入され、関連するファイルやモジュールに重点を置いた連載企画が生成されます。

依存関係の自動探索

スキャン対象が大きすぎる場合、起点ファイルを指定して関連ファイルだけを探索する「フォーカススキャン」も用意しています。

python -m publish scan \
  --project-dir /path/to/project \
  --output-dir /path/to/output \
  --seed src/main.py src/core/engine.py \
  --max-depth 3

--seed で指定したファイルから import 関係を辿り、最大3ホップまでの依存ファイルだけをスキャン対象にします。Python, JavaScript/TypeScript, Bash, HTML/CSS のインポート解析に対応しています。

前回の連載 YAML 生成との接続

前回は「YAML から記事 MD を生成する」フローを紹介しました。今回のスキャナーはその上流にあたります。

プロジェクトフォルダ
  ↓  project_scanner（Step 1〜7）
連載 YAML
  ↓  generate --series（前回紹介）
記事 MD ファイル
  ↓  LLM パイプライン（第3回紹介）
本文生成 → レビュー → WordPress 同期

つまり、コードを書いたら、そこから連載企画が生まれ、記事が生成され、WordPress に公開される——この一気通貫のパイプラインが ai-editor の全体像です。

Step	処理内容	入力	出力
1	ファイル個別要約	ソースコード	JSON (ファイル別要約)
2	プロジェクト統合要約	Step 1 の JSON	Markdown (全体像)
3	連載 YAML 生成	Step 2 の要約	YAML (3パターン)
4	設計意図推定	Step 2 の要約	Markdown
5	ユーザー価値推定	Step 2 の要約	Markdown
6	記事別 refs	Step 3 の YAML + Step 1	Markdown (refs)
7	ドラフト MD 生成	Step 6 の refs	Markdown (下書き)