Markdownに説明とコードを直接書けるCLIツールを自作 A developer built a CLI tool that lets you write explanations and code directly together i…
- 開発者がMarkdown内に解説文とコードを混在させて書き、そこからコードのみを抽出・実行できるCLIツールを個人開発した試みの紹介。
- LLM時代に文書とコードを一体化させる発想で、ドキュメントとソースの分離による情報の散逸を防ぐ狙いがある。
English summary
- A developer built a CLI tool that lets you write explanations and code directly together in Markdown, then extract and run the code blocks.
- The idea targets LLM-era workflows where keeping prose and source unified reduces context loss.
Zennに投稿された個人開発記事で、筆者はMarkdownファイル内に解説文とコードブロックを直接書き、そこからコード部分のみを取り出して実行できるCLIツールを作ったと報告している。LLMを用いた開発フローでは、コードと意図・背景情報を切り離さずに保持しておくことが有効だという問題意識が背景にある。
従来、ソースコードのコメントやREADMEに設計意図を記述するのが一般的だが、コメントは冗長になると嫌われ、READMEはコードと別ファイルに置かれるため同期が取りにくい。筆者の発想は逆で、Markdownを主、コードを従として扱い、ドキュメント駆動でコードを管理する。コードフェンス内のスクリプトをCLIが抽出・実行することで、説明と実装が常に同居する構造になる。
このアプローチはDonald Knuthが提唱した文芸的プログラミング(Literate Programming)の系譜に位置づけられると見られる。近年ではJupyter NotebookやQuarto、ObservableなどがMarkdown/ノートブック形式でコードと文章を混在させる仕組みを提供しており、Rustコミュニティの`rustdoc`によるドキュメントテストもコードと説明を一体管理する例として知られる。
開発者がMarkdown内に解説文とコードを混在させて書き、そこからコードのみを抽出・実行できるCLIツールを個人開発した試みの紹介。
LLMコーディングが普及する中で、AIに渡すコンテキストとしての「意図」を機械可読な形でコード近傍に置く需要は今後高まる可能性がある。今回のCLIは個人プロジェクトの域に留まるものの、ドキュメントとコードの分離問題に対する小さな実験例として参考になる。
なお、同様の実行可能Markdownツールとしては`mdx`や`runme`、`markdown-exec`なども存在し、シェルスクリプトをMarkdownから実行する用途は徐々に広がりつつある。
This Zenn post describes a personal project: a CLI tool that lets developers write explanations and source code together inside a single Markdown file, then extract and execute the code blocks from it. The author frames the idea as a response to LLM-driven development, where keeping intent and code physically close helps preserve context that would otherwise be lost across files.
Traditionally, design rationale lives either in code comments, which are often discouraged when verbose, or in README files that drift out of sync with the code they describe. The author flips that hierarchy: Markdown becomes the primary artifact, with code embedded inside fenced blocks. The CLI then parses the document, extracts the executable portions, and runs them. The result is a workflow where prose and implementation coexist by construction rather than by discipline.
This approach can be seen as a descendant of Donald Knuth's literate programming, where source code is woven into a human-readable narrative. Modern variants of the idea are widespread: Jupyter Notebooks and Quarto support mixed code and prose for data work, Observable does the same for JavaScript visualizations, and Rust's rustdoc runs doctests to keep examples synchronized with library behavior. Tools like runme, mdx, and markdown-exec have similarly been exploring executable Markdown for shell workflows and runbooks.
A developer built a CLI tool that lets you write explanations and code directly together in Markdown, then extract and run the code blocks.
The LLM angle is worth noting. As coding assistants increasingly rely on the surrounding context to produce useful suggestions, embedding intent, constraints, and rationale directly next to the code may become more valuable. A Markdown-first format could plausibly serve as a richer context source for AI tools than bare source files, though it remains to be seen whether such formats will gain broader traction beyond individual experiments.
The project itself appears to be a small, personal CLI rather than a production-grade framework, and the author does not claim otherwise. Still, it is a useful data point in an ongoing conversation about how documentation and code should be organized in an era when both humans and machines read source repositories. Readers interested in the broader space may want to compare it with existing executable-Markdown runners to understand the trade-offs around parsing rules, language support, and reproducibility.
本ページの本文・要約は AI による自動生成です。正確性は元記事 (zenn.dev) をご確認ください。
