av/facts

facts 是什麼？

av/facts 是一種工作流程與規格格式，用於將專案管理為 .facts 檔案中的原子主張清單。每行是一則簡短、結構化的陳述，描述應為真的事實，並可選擇包含shell 指令，由機器執行以驗證該主張。

核心目的是讓代理與團隊保持專案需求可讀且可驗證：撰寫粗略真相、精煉為精確規格，然後實作並驗證。可執行 facts check 查看哪些主張通過、失敗或需手動處理。

主要功能

• 原子「fact」規格格式 (.facts)：每行一則主張，以純文字字串撰寫，按領域以 Markdown 標題組織。
• 生命週期標記追蹤進度：使用 @draft、@spec 和 @implemented（或任何自訂標記）顯示每個主張在管線中的位置。
• 指令驗證：對於包含 command 的事實，facts check 執行指令，若指令退出碼為 0 即視為真。
• 自動驗證與狀態分組：facts check 檢查檔案、執行所有指令，並分組結果（例如綠色通過、紅色失敗、黃色手動）；若有任何失敗則非零退出。
• CI 友善的退出碼與篩選：以標記運算式篩選檢查（例如 --tags "mvp and not blocked"），驗證規格子集。
• 代理管理轉換與規格對應實作：代理讀取事實清單，拾取 @spec 事實、建置它們、執行 facts check，並將通過事實標記為 @implemented，規格隨之更新。

如何使用 facts

1. 安裝 CLI/代理工具（專案提供多種安裝選項，包括 Rust 二進位檔與下方所述 npx 指令）。
   • 範例：npx skills add av/facts
   • 然後請代理執行 Init facts（例如「Init facts」），偵測堆疊並建立初始 .facts 檔案。
2. 建立或編輯 .facts 檔案，使用文件化格式：
   • 以標題按領域組織（例如 # auth、# data）。
   • 每行一則主張。
   • 以生命週期階段標記標記每個事實，例如 @draft、@spec 或 @implemented。
   • 對於可驗證主張，加入在主張成立時退出 0 的 command。
3. 執行驗證：使用 facts check 檢查與驗證所有事實（或以 --tags 限制）。檢視哪些通過、失敗或需手動處理。
4. 與代理迭代：將粗略想法寫為 @draft，精煉為 @spec，讓代理實作 @spec 事實，並在通過 facts check 後標記為 @implemented。

使用情境

• 變更後專案規格驗證：維持活的檢查清單，列出必須為真的事項，編輯後執行 facts check 快速查看何者仍成立。
• 將需求轉為可執行檢查：將「必須為真」陳述（例如認證行為或資料處理規則）轉為具指令驗證的事實。
• 以事實生命週期管理進行中工作：使用 @draft → @spec → @implemented 溝通進度，確保每個主張已實作驗證或明確標記需精煉。
• 自動程式碼基底探索與分類：使用 facts-discover 技能掃描程式碼基底，按生命週期階段分類事實，包括新增遺漏真相。
• 依規格實作：使用 facts-implement 流程，代理讀取 @spec 事實、建置程式碼、以 facts check 驗證，並更新標記。

常見問題

facts 僅是文件格式，還是真的會驗證主張？ 兩者皆可：無指令的事實可由代理對程式碼基底驗證；有 command 的事實則執行指令並檢查退出碼 0。

facts check 做什麼？ 檢查檔案、執行所有提供的指令、依狀態分組結果（通過/失敗/手動），若有任何失敗則非零退出。

事實如何組織與追蹤？ 事實存於 Markdown/YAML 相容結構的 .facts 檔案中，以標題組織領域，並以標記（包括 @draft、@spec、@implemented）追蹤生命週期狀態。

能否僅檢查專案部分？ 可。facts check 支援以 --tags 及布林運算式篩選標記。

替代方案

• 測試套件 (單元/整合測試)：傳統測試可驗證行為，但 .facts 檢查清單強調人類可讀的原子主張與生命週期/狀態管線，而非僅自動通過/失敗。
• 靜態文件 + 程式碼審核：文件可記錄需求，但通常不可直接執行；facts 透過 facts check 將主張連結至驗證。
• 支援需求可追溯性的規格工具：連結需求與實作的工具可提供可追溯性，但 facts 專用逐行主張格式，具選擇性指令執行與基於標記的生命週期轉換。