AI時代のLiterate Programming再解釈

Transcript

1. AI時代の Literate Programming再解釈 Embedded Documentationのススメ 古庄 和也 2025/12/3 PoliPoliエンジニアLT
2. ドキュメント管理の永遠の課題 2 コードとドキュメントの乖離 実装が進むにつれて、設計書が陳腐化する（嘘をつくドキュメント） メンテナンスコストの増⼤ 機能修正のたびに、コードとドキュメントの両⽅を修正する⼿間 情報の不整合による技術的負債 「ドキュメントが信⽤できないなら、コードを読むしかない」という現実
3. アプローチ - WhyとHowの分離 4 Why & What (PRD) なぜ作るのか / 背景 解決すべき課題、ビジネス的な価値、⽬的 ビジネスルール 仕様の詳細要件、制約事項、合意事項 合意形成のツール ステークホルダーとの共通認識を作る 管理場所：Notion / Confluence How (Code / Embedded) 具体的な処理フロー 実際の動作ロジック、アルゴリズム、条件分 岐 クラス構造 / アーキテクチャ コンポーネント間の関係性、データ構造 唯⼀の真実（SSoT） コードこそが最新で正確な情報源 管理場所：Source Code 内に集約
4. HowをMermaidで記載する 5 構造と基本フロー クラス構造Class Diagram コンポーネント間の関係性と依存関係 データフローFlowchart データの流れと処理の分岐条件 状態遷移State Diagram 複雑なステータス管理と遷移条件 動的振る舞いとデータ API呼び出しシーケンスSequence 時系列でのシステム間連携とメッセージ エラーハンドリングFlowchart 異常系の検知‧回復‧通知フロー ER図ER Diagram データベースのテーブル定義とリレーション
5. Embedded Documentationの実践 6 ⽂芸的プログラミング（Literate Programming）の再解釈 1984ドナルド‧クヌースが提唱。「プログラムは⼈間が読むための⽂学である」 重要参考⽂献 Original Paper: "Literate Programming" (The Computer Journal, 1984) Book: "Literate Programming" (CSLI Publications, 1992) 当時の課題: WEBシステム（TeX + Pascal）の複雑なツールチェーンが普及の壁に AI時代における新たな意義 AIがコードとドキュメントの接着剤となり、同期コストを劇的に低減 現代版の実践アプローチ: Embedded Documentation 複雑なツールチェーン不要。コード内に標準的なコメントとして記述するだけ
6. 実践例: Python docstringへの埋め込み 7
7. 課題 - "隣"でもまだ遠い 6 READMEやMarkdownによるColocationの限界 別タブでファイルを開く⼿間が発⽣ プレビュー操作によるコンテキストスイッチ（思考の中断） 実装変更時に、別ファイルの更新が漏れやすい 解決策: ファイルすら分けず実装ファイルに集約 コードと同じファイル内であれば、物理的な距離はゼロ 修正時に必ず⽬に⼊るため、更新漏れを防げる
8. mermaid-comment-viewer 9 ⾃作のVS Code拡張機能。コードを読みながら、コンテキストスイッチ なしで全体像を把握するために開発。 Marketplace 分離されたWebview Panel エディタ領域を汚さず、サイドパネルとして独⽴して表⽰。onDidChangeTextDocumentイベントを監視し、 カーソル位置に基づいて該当するMermaidブロックをリアルタイム抽出。 実装の⼯夫: アクティブなエディタのコンテキストを維持したまま、WebView側へメッセージパッシングを⾏う設計 完全オフライン対応 CDNに依存せず、mermaid.min.jsを拡張機能内にバンドル。WebviewのlocalResourceRoots設定を通じてロー カルリソースとして読み込み。 メリット: ⾶⾏機や新幹線など、インターネット接続が不安定な環境でも開発を継続可能 柔軟なパースロジック TypeScriptやPythonなど、⾔語ごとのコメント構⽂の違いを吸収し、正規表現Mermaidブロックを特定
9. 実際の使⽤例とインストール⽅法 10 インストールと使い⽅ 1 VS Code Marketplaceからインストール 「mermaid-comment-viewer」で検索 2 コメント内にMermaidを記述 対応⾔語のコ メントブロック内に記載 3 カーソルを合わせる ⾃動的にサイドパネルに 図がプレビューされる VS Code Marketplace で⾒る 対応⾔語と特徴 多⾔語対応: Python, TypeScript, Rust, Go, Java 等 リアルタイム: 編集内容が即座に反映 オフライン: 完全ローカルで動作（CDN不使 ⽤） /** * 決済処理フロー * Mermaid: * graph TD; Start-->Validate; */ functionprocessPayment() { ... }
10. 未来 - AIとMCPによる⾃律的メンテナンス 8 01 02 03 Howの可視化作業はAIに委譲し、⼈間は設計の正当性を検証する Context AI AIがMCP経由でConfluence のPRDを読み込み、改修の 背景（Why）を理解する Generate AI 背景を踏まえてAIがコード を修正し、同時に Docstring内のMermaid図 （How）も更新する Review Human ⼈間は、AIが⽣成したコー ドと図を⾒て、整合性を検 証することに集中する
11. まとめ - 3つのキーポイント 9 Why はコラボレーションツールへ Notion / Confluence チーム全員の「共通⾔語」として、合意形成の場にする How はコード内へ Embedded AIによる⾃律的なメンテナンスで、常に最新の設計図を保つ Visualization は快適に Tooling mermaid-comment-viewer 等のツールで、閲覧体験を向上させる AI時代こそ、「コードこそが動く設計書」を真に実現できる