Markdownはもはやソースコードであり、/srcに置くべきだ

Markdown in /src

▲ 75perrygeo36 HNでの議論

LLMによるコーディングが普及する中、htmx作者のCarson GrossはMarkdownをドキュメントではなくソースコードとして扱うべきだと主張する。一時的なプロンプトから生成されたコードは真実の源になりがちだが、意図や設計判断は失われてしまう。彼はMarkdownを/src/mdにコードと並べてチェックインし、そこからコードとテストを導出する規約を提案。人間とエージェントの双方が参照できる局所性の高い開発手法を模索している。

Markdownは今やソースコードであり、ドキュメントではない。
原文を読む →HNでの議論RSS

HNでの議論

36
  1. aDyslecticCrow

    テストロット、仕様ロット、ドキュメントロットは見たことがあるだろう。今度はプロンプトロットを紹介しよう！

    時代遅れで、非常に冗長で、すぐに古くなるプロンプトでリポジトリを散らかすと、将来リポジトリを見るエージェントは混乱するだけだ。コンテキストウィンドウを小さく保つことは、良いLLM出力のための実際の制約であり、このワークフローはそれに完全に逆行するかもしれない。

    - プロジェクト、主要な抽象化のアイデア、エンドカスタマーなどを記述したplan.mdは素晴らしい。しかし、それは最小限に保ち、リポジトリと同期して最新にしておくべきだ。

    - ソースファイルや関数の先頭にあるブロックコメントは素晴らしく、コーディングエージェントにとってすでに非常に有用だ。すでに典型的なベストプラクティス以上のものに価値があるとは思わない。

  2. divbzero

    提案された/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 # モジュールが使用するインフラストラクチャの説明

    各サブディレクトリでコードと並んでREADME.mdを標準化するのはどうだろう？

    src/

    README.md # 人間とエージェントのエントリポイント

    TODO.md # このモジュールに対してオープンな一般的TODOのリスト

    INFRA.md # モジュールが使用するインフラストラクチャの説明

    api/

    README.md # モジュールが提供するAPIの説明

    models/

    README.md # このモジュールのデータモデルの説明

    各サブディレクトリのREADME.mdは、OPの目的「Markdownは生成するコードの隣、/srcにチェックインされるべき」によりよく合致するように思える。また、多くのコードリポジトリですでに使用されている規約でもある。

  3. fifferfaffer

    私のお気に入りのプロジェクトは通常、コメントにドキュメントがある。

    一例はSpiderMonkeyで、何をだけでなく、なぜその設計選択がなされたのかを説明する、美しく長い解説コメントを使用している。https://searchfox.org/firefox-main/source/js/public/RootingA...

    目標が「局所性」なら、コメント以上に近いものは得られない。

    エージェント的パラダイムの下でMarkdownが「エージェントのためのソースコード」になるという話なら、少なくとも視覚的にはディレクトリごとの`AGENTS.md`の方が一貫しているように思える。エージェント管理のMarkdownが頻繁に変更されるなら、単一ファイルに限定してほしい。制約は、特にエージェントにとっては良いものだ。

  4. ktpsns

    私は通常、Markdownを/docsに置く。ファイル名を大文字にはしない。代わりにドキュメントジェネレータにファイルを消費させて、HTML/PDFビルドでまともなナビゲーションが得られるようにしている。

    私たちは非常に長い間、非コードを/srcに置いていた。それはヒアドキュメントや複数行ドキュメントなどだった。実際、私の好みはテキストをコードの近くに置き、概念レベルでのみ/docs/something.mdにフォールバックすることだ。これはおそらく著者が提案していることでもある。彼はMarkdownをコードへの主要なインターフェースと見ているからだ。

  5. sroerick

    個人的には、仕様を扱うために緩くコンパイル／リントされるDSLを構築している。

    それはSEXP言語だが、Markdownでも同じように簡単にできるだろう。むしろその方が良いかもしれない。括弧のマッチングにトークンを浪費しているからだ。

    Markdownと比べると、人間の可読性はいくらか失うが、ワークフローでは多くを得る。

    私にとっては、いわゆる「自由形式のジャズコードの旅」を構造のあるものに変えてくれる。それは問いを「仕様は私のアイデアと一致しているか？そしてコードは仕様と一致しているか？」に変える。

    時々、「コード占星術リセット」を行い、物事を機能させ続けるために使っているトリックをすべて一掃しようとする。仕様言語がないと効率が落ちるのを絶対に感じる。新しいモデルでも、これを軌道に乗せ続けるために不可欠だと感じる。

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

    ここではLiterate Programmingが良いインスピレーションだと思う。また、YeggeのbeadsとGastownはこの点で本当に賢いことを言っていると思う。彼は私の好みには少しトークンマキシーだが。

この日のほかの記事

2026-09-22