ソースディレクトリでMarkdownを扱うためのベストプラクティス

srcディレクトリ以下にMarkdownファイルを配置する際の構成や管理方法について、皆さんの運用ノウハウを教えてください。

基本的にはMarkdownは /docs に置く派かな。ファイル名を大文字にしたりはしない。その代わり、ドキュメント生成ツールにファイルを読み込ませて、HTMLやPDFビルドでまともなナビゲーションができるようにしてるよ。

ずっとコード以外のファイルを /src に置いてた時期もあったよ。ヒアドキュメントや複数行のドキュメントとかね。実際、個人的にはドキュメントはコードの近くにあるべきだと思うし、概念レベルで /docs/something.md に逃げるのは最終手段というスタンス。Markdownをコードの主要なインターフェースと見なす投稿者の考えは、おそらくこれに近いんじゃないかな。

自分のお気に入りのプロジェクトは、たいていドキュメントがコード内のコメントに書かれていることが多い。

一例がSpiderMonkeyで、ここは本当に素晴らしくて長い解説コメントがあるんだ。単に「何をするか」だけでなく、「なぜその設計にしたのか」という理由まで説明されている。https://searchfox.org/firefox-main/source/js/public/RootingAPI.h#33

もし目的が「局所性（locality）」なら、コメント以上に近い場所なんてないよね。

エージェント主導のパラダイムにおいてMarkdownを「エージェント用のソースコード」と捉えるなら、ディレクトリごとに AGENTS.md を置く方が、少なくとも視覚的には一貫性がある気がする。もしエージェントが管理するMarkdownが頻繁に入れ替わるなら、一つのファイルに閉じ込めておいた方がいい。制約は、特にエージェントにとっては良いものだから。

数ヶ月前に似たようなことを書いたんだ [1]。まあ、自分自身のアドバイスをあまりうまく守れていないんだけどね。

どんなプログラムソースであれ、最も興味深い部分は「そのプログラムを作るために何が必要だったか」という点にある。自分はAIが生成したコードを、バイナリと同じようなカテゴリで見ているよ。

[1] https://blog.tombert.com/Posts/Technical/2026/04-April/Stop-Pushing-AI-Generated-Code-to-Git

もしその路線で行くなら、Markdownドキュメントに対してもリッチな構文ハイライト、「定義へジャンプ」「参照箇所の表示」、デバッガなんかを使えるようにしてくれないかな？ :)

でも「LLMをコンパイラとして扱う」というメタファーはあまり好きじゃないな。その論理を突き詰めると、仕様が変わるたびにプロジェクト全体をゼロから「再ビルド」しなきゃいけなくなる。トークンコストが凄まじいだけじゃなく、実装するたびに異なる実装、あるいは仕様で曖昧だった部分のUIや設計判断が毎回変わる結果になるかもしれない。

代替案として、コード を真実のソースとして捉え、LLMは（極めて高度な）編集やリファクタリングツールとして使うのがいいと思う。それならプロンプトをコミットするのも大賛成だけど、それは「真実のソース」ではなく、「機能がどう実装されたか」を記録するドキュメントとして扱うべきだよ。

テストの劣化、仕様の劣化、ドキュメントの劣化は見てきたけど、今度は「プロンプトの劣化」か！

時代遅れで冗長なプロンプトでリポジトリを散らかすと、将来そのリポジトリを見なきゃいけないエージェントを混乱させるだけだよ。コンテキストウィンドウの制限はLLMの出力にとって現実的な壁だし、このワークフローは完全に逆効果になりかねない。

・プロジェクトの概要、主要な抽象化のアイデア、最終的な顧客などを記述する plan.md は素晴らしい。でも、それは最小限に留めてリポジトリに合わせて更新し続けるべき。

・ソースファイルや関数の冒頭にあるブロックコメントはすごくいいし、コーディングエージェントにとってもすでに有用だよ。それ以外の、今のベストプラクティス以上のものは価値があるとは思えないな。

個人的には、仕様を扱うために軽くコンパイル/リンタを通せるDSLを構築してるよ。

SEXP言語だけど、Markdownでも同じようにできるはず。カッコを合わせるのにトークンを使いすぎるから、Markdownの方がいいかもしれないね。

Markdownと比較すると、人間が読むための可読性は少し落ちるけど、ワークフローの面ではかなりの恩恵がある。

自分にとっては、これが「フリーフォームなジャズのようなコードの旅」を構造化されたものに変えてくれる。「仕様は自分のアイデアと合っているか？そしてコードは仕様と合っているか？」という問いに変換してくれるんだ。

たまに「コード占星術リセット」と称して、物事を動かすために使った小細工をすべて一掃することにしてる。仕様言語がないと効率が落ちるのを痛感するね。新しいモデルを使っても、物事を軌道に乗せ続けるには不可欠だと思う。

大規模プロジェクトに関わるほとんどの人は、Markdownの仕様書でスケーリングの限界にぶつかるんだ。すぐに巨大化して矛盾だらけになるからね。src/md フォルダを作るのはいい戦略だと思う。「1モジュール1仕様書」ルールで整理するようにしてるけど、いつもそうなるわけじゃない。でも、そうするのが役に立つと感じているよ。

Literate Programming（文芸的プログラミング）はこの点で良いインスピレーションになると思う。YeggeのBeadsやGastownも、個人的には少しトークンを消費しすぎな感じはするけど、この点に関してはすごく賢いことを言ってるよ。

人間が理解することを期待するものは、しっかり管理しておかないとね。自分は依然としてコードがその役割を担うべきだと思っているし、それでも今のところ職を失わず、利益の出るコードベースを管理できている。ソフトウェア業界は広大で多様だからね。

この手の主張をするエッセイには、一般的に「もしあなたが私と全く同じ方法で働いているなら…」という前置きをつけるべきだと思うよ。

これはVararの哲学と100%一致してるね。（https://varar.dev ）

エージェントの刹那的なセッションや仕様書、計画、設計ファイルの合間を縫って、何かしらが「生き残る」。それが src/*.md ファイルだ。

Vararを使えば、Markdownファイルの小さなパーツ（セル）をコードにリンクできるから、同期を保てるんだ。だから、（あなた自身やエージェントが）3億行のコードを全部読まなくてもシステムが何をしているか理解できる。

念のため言っておくと、私はCucumberを書いた本人だよ。みんなに嫌われているやつね。結局自分でもそのツールの愛着を失ってしまったけれど、ドキュメントとコードの同期を保つ能力は必要だと感じていた。だからこそVararを作ったんだ。エージェント時代に向けた、欠点（あるいは別の形の欠点？）の少ないツールとしてね。

提案されている /src/md という慣習の代わりにさ、各サブディレクトリにコードと並べて README.md を置くのを標準化したらどうかな？

例えば：
src/
README.md # 人間とエージェント用のエントリーポイント
TODO.md # モジュールのTODOリスト
INFRA.md # モジュールが使うインフラの説明
api/
README.md # APIの説明
models/
README.md # データモデルの説明

各ディレクトリに README.md を置く方式の方が、「Markdownはコードを生成する近くの /src にコミットすべき」という投稿者の目的に合っている気がするんだよね。それに、すでに多くのコードリポジトリで使われている慣習だし。

MarkdownをLLMに流し込む場合、出力は非決定的なんだよね。プロンプトの意図は同じでも、必ずしも同じ出力になるとは限らない。

自分としては、高レベルなMarkdownファイルを一つ置くより、コード内のインラインコメントをもっと詳細に書いて意図を説明してほしい。すでにPDR（Pull Request Description）はあるわけだし、Markdownはその延長線上に過ぎない気がする。