/srcにおけるMarkdown

Markdown in /src Carson Gross 2026年9月21日 TLDR Markdownはドキュメントではなく、ソースコードになりつつあります。 Markdownは、生成されるコードの隣の/srcにチェックインされるべきです。 コードとテストは、一時的なプロンプトから派生するのではなく、そのMarkdownから派生すべきです（少なくともプロンプトセッションは最終的に永続化されたMarkdownに変わるべきです）。 はじめに モンタナ州立大学の教授としての収入を補うために、サイドでコンサルティングを行っています。コンサルティングとコードを書くこと、システム構築を手伝うことを楽しんでいます。それ自体のためだけでなく、スキルを最新の状態に保ち、学生にソフトウェア開発の最新のアイデアについて教えることができるからです。 明らかに、過去数年間で開発において最も大きな出来事は、エージェントコーディング、つまりLLMを使用して手作業コーディングの代わりにコードを生成することです。このトピックについては、いくつかのエッセイを書いてきました。 Yes, and… Code is Cheap(er) The University In The AI Era Working With AI: A Concrete Example この記事では、エージェントコーディングを優先する企業で働く中で、私にとってますます明確になっているアイデアについて議論したいと思います。それは、Markdownがもはやドキュメントではなく、ソースコードになっているということです。 これは新しい、あるいは特に賢い考えではありません、もちろん。Hartley Brodyは、Markdown is the new source codeという記事で次のように書いています。 アプリケーションロジックがマークダウンとして定義および編集され、エージェントによって生成される実際のコードが、ある種の低レベルの実装詳細のようになっているように感じ始めています。 さて、上記の記事が示すように、私はAI生成コードについて賛否両論です。しかし、私のコンサルティングの仕事は、組織がこの方向に向かっていることを、しばしば驚異的なスピードで示しています。 この記事の残りの部分では、Markdownがますますソフトウェアシステムの真実の源になりつつあることの影響について考えていきたいと思います。 失われたソースコード 上記の引用で捉えられている考え方の一つは、LLMはコンパイラに似ており、高レベルの仕様を受け取って低レベルの実装に変換するというものです。この見方では、コンパイラが生成するマシンコードを見る必要がないのと同様に、LLMが生成するコードを見る必要はありません。 Code is Cheap(er)で言及したように、私はこのアナロジーにいくつかの理由で完全に同意するわけではありませんが、この記事に関連するのは次の点です。コンパイラワークフローは元のソースコードを保持しますが、LLMワークフローは通常そうしません。 今日、LLM生成コードは、開発者が機能を構築する際に、エージェントにフィードされる一連のプロンプトを通じて作成されることがよくあります。実際には、これは、生成されたコードがその機能の「グラウンドトゥルース」に最も近いものであることを意味します。機能に関するドキュメントが他の場所に保存されている可能性があります（例: Linear、Slackスレッド、Wikiなど）。しかし、コードベースに関しては、生成されたコードが真実の源です。 私の意見では、プロフェッショナルなエージェントコーディング環境では、一時的なプロンプトセッションから生じるLLM生成コードが理想的ではないことを受け入れ、生成されたコードと共にソースディレクトリにMarkdownをキャプチャしてチェックインする方向に向かう必要があります。 ソースとしてのMarkdown Markdownには、従来のソースコードに似た多くの優れた特性があります。 プレーンテキストであるため、diff可能、grep可能、プルリクエストでレビュー可能です。 LLMはネイティブで読み書きできます。 人間はツールなしで読み書きできます。 そして実際、AGENTS.md、specs、plans、TASK.mdなどで、ある程度、すでにソースとして機能しています。私たちはまだそのソースをキャプチャすることを標準化していません。 Markdown is the new source codeで、Brodyは作業中にMarkdownファイルを.scratch/research/や.scratch/plan/に保存していると述べています。私も同様の一時的なニーズのために/tmpディレクトリを作成するという慣例を採用しました。 私の提案は、これらのファイルの一部を、既存のソースコードと共に新しいディレクトリ、/src/mdに昇格させることです。 この提案されたディレクトリにキャプチャされたMarkdownは、従来の設計ドキュメントよりも低レベルになります。 アーキテクチャ上の決定が含まれます。 ソースレベルの決定が含まれます。 低レベルのデータ設計の決定が含まれます。 これは、プロジェクトマネージャーやデザイナーが伝統的に管理する仕様よりも、仕様に近いものです。 局所性 私は局所性のファンであり、Markdownを/srcに移動することには強力な局所性上の利点があると考えています。 コードモジュールには、コードの意図を説明するMarkdownが含まれるようになります。 Wiki/Notion/Confluence/Jiraのどこかにある「遠隔地の仕様」はありません。 /srcのMarkdownは、人間とエージェントの両方によって消費できます。 エージェントは、特定のコードベースに関するコンテキストを取得するために他の場所を探す必要がなくなります。 Linear/Wikiなどについてはどうですか？ システムの動作に関するその他の真実の源は、引き続き存在できます。これらのソースは、高レベルおよび/または「プロセス指向」のドキュメントを提供します。高レベルの設計ドキュメント、ワークフローの解決が必要な問題などです。しかし、システムのコアで現在の静的な意図された動作は、ソースディレクトリのMarkdownに直接キャプチャされることが増えるでしょう。 テストについてはどうですか？ 多くの人がオンラインで、テストが新しい仕様である（あるいは常にそうであった）と述べているのを見かけました。私はそれに真実があると思います。しかし、テストは人間/エージェントのインタラクションの良いメカニズムではありません。 それらは多くの儀式を伴い、テストしているものをしばしば曖昧にします。 それらは通常、ほとんどの人間が扱いたいと思うレベルよりも低いです。特にシステムを理解する際には。 Mermaid図のような高レベルの説明は、それらに自然に適合しません。 次の労働分担が理にかなっていると思います。 Markdownは/srcに配置され、仕様（のようなもの）となります。 テストは/test（または他の場所）に配置され、そのMarkdownに基づいて、正確さの自動確認を提供します。 繰り返しになりますが、中心的な考えは、プロンプトからコードとテストを生成するのではなく、開発者は/srcディレクトリのMarkdownで作業し、そこからコードとテストが派生するというものです。 /src/md Markdownはどのように見えるか /src/mdのMarkdownは、システムの正式な仕様と高レベルの設計ドキュメントの間に位置します。 ソースコードと同様に、このMarkdownには複雑性予算が関連付けられています。これらのドキュメントをクリーンで、適切に構成され、適切な抽象化レベルに保つためには、慎重な管理が必要です。 開発者は、Markdownと派生コードの両方とやり取りすることが期待されるため、両者を同期させること（適切な場合）は重要なスキルになります。例えば、開発者は生成されたコードに対して減算的、制約的な作業を行うことが多く、その変更はMarkdownに戻す必要があるかもしれません。 私は、エージェントを/src/mdのコンテンツの大部分を生成するために使用すべきではないと信じています。このディレクトリは主に人間が作成し、キュレーションすべきです。 提案される/src/md規約 これは必然的にこの記事の最も弱い部分です。なぜなら、これは新しいアイデアであり、私はまだそれを広範囲に使用していないからです。これは私の考えを声に出して共有し、議論を促すものです。それを踏まえて、ここに可能な/src/md標準があります。 src/ md/ README.md # すべてのmdのインデックス、エージェントのエントリポイント TODO.md # このモジュールで公開されている一般的なTODOリスト OVERVIEW.md # このモジュールの技術的な概要 features/ # オプション FEATURE_1.md # 機能固有のドキュメントセット data/ # オプション DATAMODEL_1.md # モジュール内のデータモデルの説明 api/ # オプション API_1.md # モジュールが提供するAPIの説明 infrastructure/ # オプション INFRASTRUCTURE_1.md # モジュールが使用するインフラストラクチャの説明 ここでは、features、data、api、infrastructureのディレクトリはすべてオプションです。アイデアは、モジュールの動作の堅牢な作業説明を/src/mdフォルダに直接キャプチャするために、異なる軸で分割することです。 結論 コードの生成コストが安くなるにつれて、価値が残るのはコードの背後にある意図です。つまり、コードが何をするのか、なぜそれをするのか、そして何をしてはならないのかです。 今日、その意図は、一時的なプロンプトセッションで失われたり、Wiki、チケット、Slackスレッドに散らばったりすることがよくあります。 局所性の観点から、この意図をMarkdownでキャプチャすることを検討すべきだと考えています。