不只寫給工程師看：AI-Ready 技術文件的新趨勢

隨著生成式 AI 的程式撰寫能力日益成熟，過去多由工程師負責的網路服務串接與系統整合工作，如今也逐漸可以交由 AI 協助完成。這項轉變不僅改變了軟體開發流程，也使技術文件的主要閱讀對象開始產生變化：過去以工程師為核心讀者的說明文件，未來還必須進一步考量大型語言模型的閱讀、理解與應用需求。

就舉網路地圖圖磚服務為例，過去工程師若要將底圖整合至網站或 GIS 軟體中，通常必須先閱讀技術文件，逐一確認圖磚網址格式、支援的縮放層級、座標系統、樣式檔、API 金鑰、使用限制與版權標示方式，再依照不同程式框架撰寫串接程式。如今，這些工作愈來愈常由生成式 AI 協助完成；使用者只要提出「將某個地圖服務加入網頁」或「在 QGIS 中載入向量圖磚」等需求，AI 便需要自行理解文件內容，找出正確的服務端點與參數，並產生可執行的程式碼。因此，技術文件除了要讓工程師看得懂，也必須以更清楚、完整且具結構的方式，讓大型語言模型能夠準確擷取資訊，避免自行猜測網址、遺漏必要設定，或產生不符合授權規範的程式碼。

Maptoolkit 所提供的網路地圖圖磚服務，便是一個具體案例。除了供一般使用者閱讀的 Quick Start 與技術文件外，Maptoolkit 另在網站根目錄提供一份 llms.txt，將服務端點、樣式網址、圖磚來源、支援語言、程式範例、版權標示、速率限制與使用規範等重要資訊，集中整理成大型語言模型較容易讀取的純文字格式。相較於一般網頁中分散於導覽選單、不同頁面與互動元件之間的內容，llms.txt 減少了版面與介面雜訊，也明確告訴 AI 哪些網址可以使用、哪些組合並不存在，以及產生程式碼時不可省略哪些設定。換言之，所謂「AI-ready」並不是讓網頁外觀變得不同，而是額外準備一份結構清楚、資訊集中且規則明確的機器閱讀指南，協助 AI 更準確地理解並串接服務。

說明網頁：https://docs.maptoolkit.org/quick-start

給 LLM 閱讀的文件：https://www.maptoolkit.org/llms.txt

llms.txt 不只是把 Quick Start 網頁轉成純文字，除了降低 HTML 雜訊，更將整個服務所需的關鍵資訊集中整理，不僅減少 token 使用，也可以幫助 AI 一次建立理解完整上下文。內容包括：

  1. 明確告訴 AI「這是什麼服務」
  2. 集中列出所有服務端點
  3. 把可用樣式完整列成清單
  4. 提供完整而非片段式的程式碼
  5. 將署名規則寫成可執行規範
  6. 提供移轉規則
  7. 集中放入授權、速率與隱私限制

對於使用者而言，只需要在 AI 要執行的任務之前輸入以下提示詞（prompt），就可以幫助 AI 理解任務所需的資源：

在撰寫任何程式碼之前，請先取得並完整閱讀以下網址中的原始內容：https://www.maptoolkit.org/llms.txt。請使用你所具備的任何方式來讀取，例如內建的網頁擷取或瀏覽工具；如果可以使用終端機，也可以透過 curl 或 wget 等指令取得內容。

請勿摘要該檔案、不要委託其他工具代為閱讀，也不要依賴你先前對 Maptoolkit 的既有知識；這份檔案是唯一可信的資訊來源。若無法取得該檔案，請停止操作並告知我，不要自行猜測或虛構網址、樣式名稱或 API 細節。

參考文件：