エージェント時代におけるリテラテプログラミングの再考が必要です

2026年3月9日原文(silly.business)

概要

Literate programming は、コードと説明文を組み合わせて理解しやすくする手法。
実際には、コードと説明文の 二重管理 が負担となり普及が限定的。
Emacs Org Mode やJupyter Notebookが代表的な実践例。
LLM（大規模言語モデル）エージェント の登場で、この負担が大幅に軽減。
今後は、物語のように読めるコードベース実現の可能性。

リテラテプログラミングの現状と課題

Literate programming は、コードと説明文を並列に記述し、初心者でも理解できる物語的なコードベースの実現を目指す手法。
実際には、 コード本体と説明文の2つのストーリーを維持 する手間が大きく、普及が限定的。
歴史的には、 Jupyter Notebook がデータサイエンス分野で広く使われており、計算・結果・説明が同じ画面に表示される構成。
Emacs Org Mode のorg-babelパッケージは、多言語対応のリテラテプログラミングをサポートし、任意の言語を実行し結果を文書に自動挿入可能。
しかし、Orgファイルを「ソース・オブ・トゥルース」として使うと、編集ごとに「tangle（抽出）」作業が必要となり、 実運用では煩雑さが課題。

個人利用での実践例とメリット

個人設定や手順書の管理 にはリテラテプログラミングが有効で、コマンドライン作業をOrgファイル内でコマンドとして記述・実行・編集し、手順書と実行履歴を同時に作成。
手順書作成と実行が一体化 することで、追加のメモ作成が不要となる利便性。
LLMエージェント （Claude、Kimiなど）はOrg Mode構文を高精度で扱え、説明文とコードの同期やtangle処理を自動化可能。

LLMエージェントによる革新

テストや機能検証時、 エージェントにOrg形式のランブック作成を依頼 し、説明文で意図を確認、コードブロックは対話的に実行可能。
説明文とコードの同時編集や自動反映 が可能となり、二重管理の負担が消滅。
AGENTS.mdファイルで、エージェントに「Orgファイルを唯一の正とし、説明文を必ず記述し、実行前にtangleする」などの運用ルールを指示可能。
エージェントは何度でも説明文の修正・再生成に対応し、 リテラテプログラミングの最大の障壁だった追加労力を排除。
コードベースを多様な形式にエクスポートでき、 読むことが主業務となるエンジニアにも有用。

Org ModeとMarkdownの比較・今後の展望

Org Modeの Emacs依存 が普及の障壁であり、より汎用的なMarkdownへの移行も検討されるが、 Markdownにはメタデータ記述機能が不足。
Org Modeは プロパティやヘッダー引数 で、コードブロックの実行先や詳細設定など、プログラム的な制御が可能。
過去はEmacs Lispで独自機能を組み込むことで柔軟性を確保していたが、今はLLMが自動で必要なLispコードを生成可能。
「物語のように読めるコードベース」 という理想の実現に、エージェントの力で現実味が増している。
大規模コードベースでの本格運用は未経験 だが、手順書やテスト用途では高い効果を実感。

結論と今後の課題

リテラテプログラミングの普及を阻んでいた労力が、LLMエージェントにより解消。
コードと説明文の同期や抽出・実行が自動化され、 コードの可読性や品質向上にも寄与 する可能性。
今後は、 エンジニアの主な役割が「読むこと」へ移行 する中で、物語的なコードベースの重要性が増すと予測。
Org Modeの枠を超えた、より汎用的なドキュメント形式の模索と、 大規模プロジェクトでの実践検証 が今後の課題。

Hackerたちの意見

LLMは言語モデルだから、書かれた言葉の明確さに投資するのはめちゃくちゃ効果的だよね。「リテラルプログラミング」が必須かどうかは分からないけど、良い名前やドキュメンテーション、型の署名、戦略的なコメント（「なぜ」について）、良いREADME、考え抜かれた抽象化があれば、しっかりしたパターンが確立できると思う。フルで「リテラルプログラミング」をやる必要はないかも。コミュニケーションに焦点を当てるっていうのがいいかもね。ノートブックや例、スクリプトなんかがパターンを強化するのに役立つよ。結局のところ、それが大事なんだよね：人間の読者とLLMの両方が従うべきパターンを確立すること。

└

そうだね、必要なのはdocstringと戦略的コメント、そしてリテラルプログラミングの中間くらいだと思う。基本的に、コードの高レベルな構造をドキュメント化するのはすごく役立つ。ファイルレベルやサブディレクトリレベル、プロジェクトレベルでの広範なdocstringみたいな感じ。問題は、主要なアーキテクチャの概念や決定がファイルやディレクトリをまたいでいることが多いから、必ずしもそこが正しい場所じゃないってこと。それに、コードファイルに何が適切か、デザインドキュメントに何が適切か、どうやってそれらを同期させるかっていう問題もある。

└

ノートブックはリテラルプログラミングの一例だよ。

最近、いくつかのプラクティス（ちゃんとしたREADMEやアーキテクチャを書くこと、言語を正確かつ明確に使うこと、文脈を提供すること、リテラルプログラミング）が人間を助けるために作られたのに、広く採用されていない傾向に気づいたよ。理由は「手間がかかりすぎる」っていうこと。でも、LLMを助けるためにやると、急にみんなやる気になるみたい。

└

プログラミングの経験から言うと、人間は具体的な質問が出るまではドキュメントをちらっと見るだけだよね。それで、答えを探すよりも他の人に聞くことが多い。最大の問題は、人間は必要になるまでドキュメントが必要だって気づかないこと。あるプロジェクトでは、docblockスタイルのコメントをたくさん使ってたんだけど、どのファイルを開いても自然言語か注釈のどちらかに少なくとも一つのエラーがあったよ。もしLLMが実行するすべてのタスクでドキュメントを実際に使っているなら、もしくはそれなしでは十分な出力ができないなら、それが日常の仕事でドキュメントを書くための動機付けになると思う。

└

ドキュメントはコードよりも早く腐るよね。コードが動くためには正確である必要はないし、コメント（特にデザインドキュメント）を無視して、直接コードに行く方がいいことが多い。

└

何年も前に盗んだ観察を言い換えると、私たちの中の何人かは、コンピュータと話すことを学べば人間と話すことを学ぶ必要がなくなると思ってたんだ。だから、彼らは感情的な成長の最も重要な4年間をそれに費やして、卒業したらその分野で他の誰よりも遅れていることに気づいたんだ。

└

LLMが自分のインラインドキュメントを積極的に修正してくれたことがあって、すごく嬉しいサプライズだった。「コメントが古くなっていて、実際の実装を反映していないことに気づきました。修正してもいいですか？」って聞いてきたんだ。

└

もしかしたら、そういう人たちがプログラマーを管理していて、自分でコードを書いていなかったら、似たようなことをしていたかもしれないね。

└

違うのは、彼らがそのREADMEやアーキテクチャ、その他のドキュメントを書くのにLLMを使ってるってこと。努力をしてないんだよね。

テストコードと本番コードを対称的に持つのは、たくさんの利点があるよ。ダブルエントリー会計みたいなもので、コードの動作をコード自体から見ることもできるし、それが本当にやっていることを証明するコードからも見られる。テストや本番コードのどちらかを変えることでコードを変更できて、もう一方がそれに従う形になる。コードレビューも楽になるし、本番コードに混乱したらテストコードが説明を持ってることが多いから、逆も然り。必要に応じて切り替えればいいんだ。たくさんの利点があるけど、もちろん余分なコードが増えるのがデメリットかな。読みやすさの向上がそれに見合うかはあなた次第。

ここ10年くらい、ほぼ全てのコーディングでリテラルプログラミングを使ってきたよ。nbdevを作ったおかげで、ノートブックを使ってソフトウェアを書いたり、ドキュメント化したり、テストしたりできるようになった。ここ数年で、LLMをノートブックやnbdevと統合してSolveitを作ったんだけど、会社のみんながほぼ全ての仕事で使ってる（弁護士や人事もね）。リテラルプログラミングはプログラミングだけじゃなくて、もっと色々なことに役立つって分かったよ！

Hacker Newsで議論の続きを見る

ハクソク