Markdown in /src – 將 Markdown 視為原始碼

TL;DR

• Markdown 正從文件轉向原始碼。
• 將 Markdown 與程式碼一同儲存在 /src/md 資料夾中。
• 從該 Markdown 產生程式碼與測試，而非依賴暫時性的提示會話。

為何 Markdown 應被視為原始碼

Markdown 滿足傳統原始碼檔案的核心特性：純文字、可比對差異、可搜尋，且在合併請求中容易審查。大型語言模型（LLMs）可原生讀取與撰寫 Markdown，人類也能在不需特殊工具的情況下編輯。因此，Markdown 可作為驅動程式碼產生的 意圖 層，如同編譯器的高階規格驅動機器碼。

暫時提示的問題

目前的代理工作流程經常透過一系列臨時提示產生程式碼。產生的程式碼成為事實上的唯一真實，而提示本身則散落在 Slack、Linear 或私人筆記中。這種「提示腐化」導致：

• 未來開發者與代理失去上下文。
• 無法對原始規格進行版本控制。
• 代理必須重建遺失的意圖時，增加 token 使用量。

/src/md 資料夾的優勢

意圖的就近性

將 Markdown 放在所描述程式碼的附近，可消除「規格遠端」的問題。開發者無需離開原始碼樹即可檢視模組的設計理由，代理也能在不額外查詢的情況下取得相同上下文。

人與代理的對稱性

人類與 LLM 均可消費相同的 Markdown 檔案，確保意圖、架構決策與資料模型的單一真實來源。

版本控制與審查

Markdown 檔案參與與程式碼相同的 Git 工作流程：可比對差異、進行 linting，並在合併請求的評論中討論。這使得意圖變更可追蹤且可審查。

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 警告，儲存過時的提示可能使程式碼庫混亂並增加 token 使用量。共識是保持 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 中的 Markdown 檔案，描述新功能、資料模型或 API。
2. 執行 LLM，以 Markdown 為提示產生或更新程式碼。
3. 自動從相同 Markdown 產生測試（例如使用自訂產生器或 mdtest 之類的工具）。
4. 在單一合併請求中審查 Markdown 與產生的程式碼。
5. 將任何手動編輯同步回 Markdown，以確保意圖與實作一致。

可能的陷阱與對策

• 過時的 Markdown – 建立 linting 步驟，標記未被近期提交引用的 Markdown 檔案。
• ** token 成本** – 保持 Markdown 簡潔；將其視為高階規格，而非每次提示的逐字記錄。
• 非決定性產生 – 接受 LLM 輸出可能變動；依賴測試來捕捉回歸，而非精確的產生程式碼。

結論

隨著 AI 使程式碼產生變得便宜，最有價值的資產變成了程式碼背後的 意圖。將此意圖以 Markdown 儲存在 /src/md 資料夾中，可提供就近性、版本控制，以及人類與代理共享的媒介。儘管具體結構會演進，但核心理念——將 Markdown 視為原始碼而非附屬文件——為代理式開發工作流程提供了一條務實的前進道路。