/src における Markdown — Markdown をソースコードとして扱う

TL;DR

• Markdown はドキュメントからソースコードへと移行しつつある。
• Markdown をコードと一緒に /src/md フォルダに格納する。
• 一時的なプロンプトセッションに頼るのではなく、その Markdown からコードとテストを生成する。

Markdown をソースコードとして扱うべき理由

Markdown は従来のソースファイルの核心的な特性を満たしている：プレーンテキストであり、差分比較可能で、検索可能、プルリクエストで簡単にレビューできる。大規模言語モデル（LLMs）は Markdown をネイティブに読み書きでき、人間も特別なツールなしで編集できる。その結果、Markdown はコンパイラの高レベルな仕様がマシンコードを駆動するように、コード生成を駆動する 意図 のレイヤーとして機能できる。

一時的なプロンプトの問題点

現在のエージェントワークフローでは、コードが一連の臨時のプロンプトによって生成されることが多い。その結果、生成されたコードが事実上の真実となる一方、プロンプト自体は Slack や Linear、またはプライベートノートに散在したままになる。この「プロンプト腐敗（prompt rot）」は以下の問題を引き起こす：

• 将来の開発者やエージェントにとってのコンテキスト喪失。
• 元の仕様をバージョン管理できない。
• エージェントが欠落した意図を再構成する必要があるため、トークン使用量の増加。

/src/md ディレクトリの利点

意図の局所性

コードを記述する Markdown をそのコードに近い場所に配置することで、「仕様の遠隔化」問題を解消する。開発者はソースツリーを離れることなくモジュールの理由を確認でき、エージェントも追加の検索なしに同じコンテキストを取得できる。

ヒューマン・エージェントの対称性

人間と LLM の両方が同じ Markdown ファイルを消費できるため、意図、アーキテクチャの決定、データモデルに関する単一の真実源が保証される。

バージョン管理とレビュー

Markdown ファイルはコードと同じ Git ワークフローに参加できる：差分比較、Lint、プルリクエストコメントでの議論が可能。これにより、意図の変更が監査可能かつレビュー可能になる。

Markdown がテストを補完する方法

テストは自動的な正しさの検証に不可欠だが、低レベルであり、機能が存在する 理由 をしばしば曖昧にする。/src/md に意図を格納し、その意図からテストを生成することで、明確な労働分担が実現される：

• Markdown – 挙動、アーキテクチャ、データに関する仕様的な記述。
• テスト – 生成されたコードが仕様と一致していることを具体的に検証する。

提案される /src/md レイアウト

具体的なフォルダ構造は、Markdown を整理し、検索可能にするのに役立つ：

src/
  md/
    README.md          # エージェントと人間のエントリポイント
    TODO.md            # モジュールの未完了タスク
    OVERVIEW.md        # モジュールの技術的概要
    features/
      FEATURE_1.md     # 機能固有の記述
    data/
      DATAMODEL_1.md   # データモデルの定義
    api/
      API_1.md         # API コントラクトと使用法
    infrastructure/
      INFRA_1.md       # インフラストラクチャの依存関係

サブフォルダはオプション。チームが機能、データ、API、インフラストラクチャといった論理的な軸に沿って関心を分離できる。

コミュニティのフィードバックの要約

• プロンプト腐敗の懸念 – @aDyslecticCrow は、古くなったプロンプトを保存するとリポジトリがごちゃごちゃになり、トークン使用量が増えると警告した。合意された見解は、Markdown を最小限に抑え、最新の状態に保ち、すべてのプロンプトの完全なトランスクリプトではなく 意図 として扱うべきだということである。
• ごちゃごちゃ vs. 価値 – @benrutter は、過剰な Markdown がリポジトリを肥大化させ、保守が難しくなると主張した。彼は、Markdown を主にレビュー時やレグレッション分析時に使うべきであり、すべてのプロンプトを恒久的なダンプとして保存すべきではないと提案した。
• ツールサポート – @xg15 は、Markdown に対する構文強調やナビゲーションについて尋ねた。既存の IDE 拡張機能はすでに豊富な Markdown サポートを提供しており、Varar や Cucumber 風の Linter などのツールで一貫性を強制できる。
• 代替的な配置 – @ktpsns と @maxk42 は、ドキュメントを /docs または別々の README ファイルに置くことを好む。重要な違いは 局所性 であり、意図をコードに近い場所（/src/md に）配置することで、実装と理由の間の心理的距離を短くできる。
• リテラートプログラミングのインスピレーション – @sroerick はこのアプローチを、緩やかにコンパイルされた DSL やリテラートプログラミングにたとえた。そして、「仕様がコードと一致する」ワークフローの必要性を強調した。
• 標準化の提案 – @divbzero は、中央のインデックスではなく、各サブディレクトリに README.md を使うことを提案した。これは一般的なリポジトリの慣習に沿っている。

実践的なワークフロー

1. 作成または更新：/src/md に新しい機能、データモデル、API を記述する Markdown ファイルを作成または更新する。
2. LLM の実行：Markdown をプロンプトとして LLM を実行し、コードを生成または更新する。
3. テストの自動生成：同じ Markdown からテストを自動生成する（例：カスタムジェネレータや mdtest などのツールを使用）。
4. レビュー：Markdown と生成されたコードを1つのプルリクエストでレビューする。
5. 同期：手動での編集を Markdown に反映して、意図と実装を一致させる。

潜在的な落とし穴と対策

• 古くなった Markdown – 最近のコミットで参照されていない Markdown ファイルを警告するLintステップを設ける。
• トークンコスト – Markdown を簡潔に保つ。すべてのプロンプトの逐語的トランスクリプトではなく、高レベルな仕様として扱う。
• 非決定的生成 – LLM の出力が変動することを受容する。正確な生成コードではなく、テストによってレグレッションを検出する。

結論

AI がコード生成を安価にする中で、最も価値あるアーティファクトはそのコードの背後にある 意図 となる。その意図を /src/md ディレクトリに Markdown として格納することで、局所性、バージョン管理、そして人間とエージェントの間の共有メディアが実現される。正確なレイアウトは進化するだろうが、核心的なアイデア——Markdown を周辺的なドキュメントではなく、ソースコードとして扱う——は、エージェント開発ワークフローの実用的な前進を示している。