/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は今やソースコードであり、ドキュメントではないということです。

これは新しい、あるいは特に賢いアイデアではありません、もちろん。

Markdown is the new source codeで、Hartley Brodyは次のように書いています。

ソフトウェアのアプリケーションロジックがマークダウンとして定義・編集され、エージェントによって生成される実際のコードは、低レベルの実装詳細のようになっているように感じ始めている。

さて、上記の記事が示すように、私はAI生成コードに対して賛否両論ありますが、私のコンサルティングの仕事は、組織がこの方向に向かっていることを示しており、しばしば驚異的なスピードで進んでいます。

このエッセイの残りの部分で、Markdownがますますソフトウェアシステムにおける真実の源泉になっていくことの影響について考えていきたいと思います。

失われたソースコード

上記の引用に捉えられている考え方の一つに、LLMはコンパイラに似ており、高レベルの仕様を受け取って低レベルの実装に変換するというものがあります。この見方では、コンパイラが生成するマシンコードを見る必要がないのと同様に、LLMが生成するコードを見る必要はありません。

Code is Cheap(er)で言及したように、私はこのアナロジーに完全に同意するわけではありませんが、このエッセイに関連する理由は次のとおりです。コンパイラワークフローは元のソースコードを保持しますが、LLMワークフローは通常そうではありません。

今日、LLM生成コードは、開発者が機能を構築する際にエージェントにフィードされる一連のプロンプトを通じて作成されることがよくあります。実際には、これは生成されたコードが、その機能の「グラウンドトゥルース」に最も近いものであることを意味します。機能に関するドキュメントが他の場所に保存されている可能性はありますが（例: Linear, Slackスレッド, Wikiなど）、コードベースに関しては、生成されたコードが真実の源泉です。

私の意見では、プロフェッショナルなエージェント型コーディング環境では、一時的なプロンプトセッションから生じるLLM生成コードは理想的ではないことを受け入れ、生成されたコードと共にソースディレクトリにMarkdownをキャプチャしてチェックインする方向へ移行を開始する必要があるということです。

ソースとしてのMarkdown

Markdownには、従来のソースコードに似た多くの良い特性があります。

• プレーンテキストであるため、diff可能、grep可能、プルリクエストでレビュー可能
• LLMはネイティブに読み書きできる
• 人間はツールなしで読み書きできる

そして実際、AGENTS.md、仕様、計画、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でキャプチャし、それを生成するコードと共に/srcにチェックインすることを検討すべきだと思います。そこでは、人間とエージェントの両方がそれを見つけることができます。

/src/mdのようなものの正しい構造が何であるかは、まだ正確にはわかりません。私（や他の人）がそれに関する経験を積むにつれて、私の考えは変わるだろうと予想しています。

しかし、Markdownはソースコードになりつつあり、私たちはそれをソースコードとしてますます扱うべきであると、かなり確信しています。

（LLMはコンパイラではない、ということを念頭に置きつつ :)

</>