為 AI Agent 時代優化文件

傳統的技術文件標準一直以來都是基於人類的直覺：如果開發者最終能夠搞清楚，那麼文件就被認為是「好」的。然而，隨著 AI 編碼代理（coding agents）成為與軟體互動的主要介面，這個標準已不再足夠。人類可以憑直覺彌補的模糊性，對代理而言卻是失敗點。

dari-docs 是一款 CLI 工具，旨在將文件品質從主觀感受轉變為可衡量的指標。透過使用成群的模擬開發者代理來嘗試僅使用提供的文件來執行真實任務，它為建立「代理可讀」的文件建立了一個可重複的回饋迴圈。

向代理可讀文件轉型

當讀者是 AI agent 時，模糊性的成本會增加。術語不一致、隱藏的假設以及缺失的設定步驟，不僅僅是小小的困擾；它們是會導致代理任務失敗或浪費上下文窗口（context windows）來嘗試推論缺失資訊的阻礙因素。

dari-docs 透過將文件視為需要測試的程式碼來解決此問題。它允許開發者定義一個具體的任務——例如「安裝 SDK 並進行第一次 API 呼叫」——然後觀察模擬代理是否能僅使用提供的文件成功完成該任務。

核心功能與工作流程

該工具透過一個主要的技術回饋迴圈運作：測試、檢查與優化。

1. 使用模擬開發者進行測試

使用 dari-docs check 指令，使用者可以將工具指向本地目錄或公開 URL。CLI 會打包文件並提交給測試代理。這些代理會嘗試執行指定的任務，並精確地報告他們在哪裡卡住，藉以識別缺失的上下文或不明確的設定指令。

2. 識別阻礙因素

dari-docs 並非進行通用的審查，而是針對阻礙任務的模糊性提供具體回饋。這包括：

• 缺失的上下文： 被假設但未明確說明的步驟。
• 不一致的術語： 同一概念使用不同的名稱，這會干擾代理的推理能力。
• 不明確的設定： 未明確定義的前置條件。

3. 自動化優化

除了僅僅識別問題之外，該工具還提供了一個 optimize 指令。這會觸發一個編輯代理，根據測試代理遇到的失敗案例來建議特定的文件修改建議。這些建議的修改會被下載到 .dari-docs/updated/ 資料夾中供人類審查，確保使用者對最終內容保有控制權。

部署模式：託管式 vs. 自管式

為了因應不同需求，dari-docs 提供兩種執行路徑：

Mode	Use Case	Requirements
Managed	最快的設定與託管執行。	dari-docs auth login
Self-managed	在您自己的 dari.dev 組織內執行，以獲得更多控制權。	dari.dev API key 與已部署的代理

社群觀點與考量

雖然「代理測試文件」的方法因使除錯變得更具實用性而受到讚揚，但社群針對其在真實工作流程中的實作提出了幾個關鍵點：

"I think one feature that would make dari-docs significantly more practical for real-world pipelines is a robust, built-in bidirectional converter between Markdown and HTML"

此外，一些使用者對將文件上傳到託管服務的敏感性表示擔憂，這一點突顯了對於具有嚴格數據隱私要求的企業而言，自管模式的重要性。

結論

隨著我們邁向一個 AI agent 比人類更有可能閱讀您文件的世界，目標是讓文件「好到連最笨的代理都能交付」。透過將文件視為可測試的資產，dari-docs 提供了一個框架，將模糊性轉變為可衡量的失敗，讓開發者能夠構建真正能被 AI 驅動的開發生命週期所存取的軟體。