文檔管理器 是做什麼的？
專案活知識，供人類與 AI 代理共享。程式碼是關於 如何 以及某項宣稱是否為真的唯一真實來源。
AGENTS.md + docs/ 記錄 什麼、為什麼、決策與計劃——但 當它們與程式碼衝突時，絕不能覆蓋程式碼。
核心規則
- 優先使用
AGENTS.md作為中樞。如果agents.md已存在，則使用它。如果只有CLAUDE.md存在，可以擴充它加入文檔索引，或者新增AGENTS.md並交叉連結——不要建立三個互相競爭的中樞。 - 每個產生/更新的文檔都使用相對的 Markdown 連結回到中樞及相關文檔。
- 非必要請勿刪除持久知識；建議在 ADR 上標註 已取代者 註記。
- 不要自動提交或推送。將 Git 操作留給使用者。
- 產生內容使用使用者語言（或儲存庫的主要語言）。此技能本體為英文，以利生態系相容。
- 準確性與實用性優先於篇幅。核心集合優先；選擇性文檔按需產生。
- 先意圖（專案層級）。 分類意圖：
integrate|audit|from-zero（可選混合）。請參閱第 0 步。單純功能/計劃/同步不需要意圖。 - 衝突時以程式碼為準。 無法通過結構驗證的文檔宣稱將標記為矛盾/缺失——不要為了符合文檔而發明程式碼；應修正或標記文檔。
- 先採納後整合（當意圖=integrate）。 成熟文檔 → 索引 + 缺口 + 標準連結；不要平行重寫產品願景/需求/ADR。請參閱 adopt-integrate。
- 每個主題只有一個權威。 每個主題只有一份標準文檔；其他全部連結至此。
- 採納/從零專案的涵蓋率矩陣。 產品表面（導航、ModuleId、套件）需顯示為已文檔化 / 已連結 / 缺口。
- 功能原子性。 一個 slug 大約等於一個 ModuleId 或有邊界的情境。叢集 = 索引 + 子項目。
- 狀態分類法。 references/status-taxonomy.md。
- 沙箱選擇加入 / 從零專案的一級支援。 當使用者要求時，輸出「Out: sandbox:path」（例如
test/等）。沙箱中樞需標記非 SSOT + 推廣計劃。 - 功能自動駕駛（v1.5 / v2）。 普通的「新功能 X」/「文檔化 X」→ 技能會選擇計劃或功能包，套用預設的不寫入，設定種類（新功能 | 尖峰 | 史詩 | 重新設計）。只有在選擇加入（「實現」、 「存根」、 「骨架」）時才進行實作橋接（放置/存根）——預設僅為文檔 + 一行提示。請參閱 modes.md §3 和 implementation-bridge.md。
- 計劃模式（v1.3+）。 新功能想法應放在
docs/plans/<slug>/，而不是假的實作包或完整的專案啟動。當程式碼真正存在時（不只有存根），再升級至docs/features/<slug>/。 - ArkGate 橋接（v1.4）。 如果偵測到 ArkGate（
ark.config.json、ark-check、.ark/、ark skills）或使用者剛完成一個關卡，則執行橋接子流程：從合約豐富庫存；關卡通過後 → 限定的同步 / 審計；殘餘違規 → 標記宣稱為矛盾/部分——絕不重寫文檔來為已破壞的架構開脫。無 Ark → 無操作。Implementation bridge 中的放置提示在偵測到 Ark 時會重用其層級。請參閱 arkgate-bridge.md 和 modes.md §9。 - 知識儀表板（v1.6）。 可選的靜態 HTML 視圖，顯示計劃/功能/宣稱（
scripts/generate-docs-dashboard.sh→docs/audit/generated/dashboard.html）。Markdown 是 SSOT；HTML 是 gitignored 的唯讀視圖。在審計後提供一次，或在使用者要求「儀表板」時提供。請參閱 knowledge-dashboard.md 和 modes.md §10。 - 技能強化（v1.7）。 維護者：發布前執行
validate-skill.sh+test-skill-hardening.sh。代理：透過 skill-discovery.md 偵測安裝/版本；當版本過時時建議重新安裝（不進行靜默自動修補）。 - v2.0 套件。 完成 10 倍提升：能力 1.4–1.7 加上 docs/adoption-matrix.md 追蹤。基礎安裝最低版本仍為 2.0.0；多語言 2.1.0；單體庫 2.2.0；團隊 2.3.0；橋接完成 2.4.0；當前發展線為 2.5.0+（知識作業系統朝向 100 倍的第一個增量——活主張 + CI 審計；不是第二個 10 倍）。
- 多語言技術棧偵測（v2.1 Slice A / skill 2.1.0）。 在專案探索（整合 / 審計 / 從零 / 採納）時，從檔案系統（
package.json、pyproject.toml、go.mod、…）透過 skill-discovery.md 多語言技術棧偵測（或scripts/detect-stack.sh）偵測技術棧。使用依技術棧的庫存和依技術棧的文檔佈局指引——不要假設是 Node/TS。絕不為沒有程式碼證據的框架發明 ModuleIds/端點。請參閱 modes.md §0.3。 - 單體庫中樞（v2.2 Slice B）。 偵測多套件樹（
pnpm-workspace.yaml、package.jsonworkspaces、go.work、多套件目錄）透過 skill-discovery.md 單體庫中樞（或scripts/detect-packages.sh）。根中樞是一個地圖 + 套件索引，而不是傾印；多套件涵蓋率標記缺口套件；當僅索引根目錄時，預設為套件不寫入。請參閱 modes.md §0.4。 - 團隊治理（v2.3 Slice C）。 可選的
docs/team/，包含所有者 + 批准紀錄（上次批准樣式）。請參閱 team-governance.md 以決定建立或連結；中樞連結至團隊但不變成人力資源維基；採納優先——加入團隊不得重寫產品願景 / 需求 / ADRs。沒有 CODEOWNERS 引擎或 BPM。請參閱 modes.md §11。 - 模板遙測（v2.4 Slice D）。 選擇加入的本地分類帳，僅用於模板/技能 UX 缺口（template-telemetry.md；
scripts/template-telemetry.sh）。預設關閉；絕不傳送來源/機密/儲存庫 URL；絕不聯網；選擇加入關閉時，在無網路環境中無操作。請參閱 modes.md §12。 - 活主張 + CI 結構審計（v2.5 / 知識作業系統第一個增量）。 審計矩陣使用活主張 v0：
anchor.path/ 可選anchor.symbol/ 可選anchor.hash、severity（critical|normal），判決不變。矩陣優先（audit-template.md）；程序 living-claims.md；線路 ADR-0001。真實性分數保持建議性質（儀表板啟發式）；本地無網路scripts/audit-claims.sh/ 範例docs-auditCI 是關卡（critical Contradicted 時失敗）。無 SaaS。請參閱 modes.md §6 / §13。
第 0 步——偵測範圍、模式與意圖
範圍（必要）：
| 範圍 | 時機 | 輸出重點 |
|---|---|---|
| project | 整個產品 /「專案文檔」 | 中樞 + 專案文檔（依意圖） |
| feature | 已命名的功能/模組包含程式碼（或刷新套件） | docs/features/<slug>/ + 中樞連結 |
| plan | 已命名的功能/史詩在或沒有實質程式碼之前 | docs/plans/<slug>/ + 中樞連結 |
| hybrid | 功能/計劃但還沒有中樞 | 包或計劃 + 最小中樞 |
模式（必要）：
| 模式 | 訊號 |
|---|---|
| bootstrap | 首次建立，沒有中樞/文檔，或from-zero 意圖在空白/薄弱專案上 |
| adopt | 程式碼存在；文檔薄弱/缺失或integrate 意圖 |
| audit | 「審計文檔」、「文檔 vs 程式碼」、偏移、驗證宣稱 |
| plan | 「新功能」、「計劃」、「史詩」、 「vamos a construir X」但無程式碼 |
| feature | 文檔化一個已有 (或將有) 程式碼的功能/模組 |
| sync | 差異 / PR / 為變更更新文檔；關卡後當 Ark 剛通過時 |
| roadmap | 計劃發布 / 史詩列表重新整理 |
意圖（僅在 project-level 工作時必要）：
| 意圖 | 使用者訊號（範例） | 行為 |
|---|---|---|
| integrate | 「改善文檔」、「整理」、「同步中樞」、成熟的改進 | adopt-integrate（若薄則完整）；若懷疑偏移則可選預先審計 |
| audit | 「審計」、「文檔在說謊嗎？」、「文檔 vs 程式碼」、「驗證路徑」 | 僅程式碼庫存 + 宣稱矩陣（或之後交接） |
| from-zero | 「全新的」、「從零開始」、「在 test/ 中生成文檔」、「在 X 資料夾中完整知識庫」 | 完整知識庫；若提供路徑則偏好沙箱；程式碼推斷；舊文檔僅為假設 |
推斷（不要過度追問）：
- 「nueva feature X」/「new feature X」/「quiero agregar X」→ 功能自動駕駛（無程式碼則計劃，有程式碼則功能；從措辭判斷種類）。意圖 = n/a
- 「implementá X」/「generá stubs」/「scaffold X」→ 如有需要執行 autopilot Stage A + Implementation bridge 選擇加入（僅在要求存根時才產生程式碼）
- 「generá toda la documentación en
test/」→ 意圖：from-zero | Out: sandbox:test/ - 成熟儲存庫 +「mejorá / integrá / indexá」→ 意圖：integrate
- 「auditar docs」/「código vs docs」→ 意圖：audit
- 現有
docs/的模糊project 工作 → 問一次：integrate | audit | from-zero - 已命名的單一表面 → 永遠不要要求使用者列出不寫入的項目或選擇資料夾
- 「after ark-check」/「post-gate docs」/ 關卡剛執行 + docs 意圖 → sync 或 audit 搭配 ArkGate bridge
- 「dashboard」/「docs HTML」/「knowledge report」→ 生成知識儀表板 (knowledge-dashboard.md)
- 「owners」/「quién es dueño」/「team docs」/「approval notes」/「docs/team」→ 團隊治理 (team-governance.md; modes §11)
- 「template telemetry」/「opt-in telemetry」/「record template gap」→ 模板遙測僅在使用者選擇加入時 (template-telemetry.md; modes §12); 預設關閉
- 「living claims」/「truth score」/「docs CI」/「fail on Contradicted」→ 活主張 + 本地 CI 關卡 (living-claims.md; modes §13)
成熟度（相關時）：thin | mixed | mature — 請參閱 modes.md。
如果推斷後範圍/模式仍然模糊，問一次。從 references/modes.md 載入程序。
在寫入前宣布：
Scope: <x> | Mode: <y> | Intent: <integrate|audit|from-zero|n/a> | Variant: <full|integrate|arkgate-bridge|n/a> | Maturity: <…|n/a> | Out: <root|sandbox:path> | Stack: <node-ts|python|go|mixed|unknown|n/a> | Monorepo: <yes|no|n/a> | ArkGate: <none|detected> | Slug: <slug|n/a>
當 integrate 時，列出不寫入項目（單體庫僅根索引時包含套件不寫入）。當 audit 時，列出矩陣路徑和主要矛盾。當 from-zero + 沙箱時，包含推廣計劃。當 plan 或 feature 時，列出路徑 + 預設不寫入。當 ArkGate bridge 時，列出訊號和關卡後同步 vs 審計豐富。當專案級別時，從發現結果包含技術棧和單體庫。
建議的佈局
project-root/
├── AGENTS.md
└── docs/
├── product-vision.md # bootstrap / from-zero / adopt-full
├── requirements.md
├── architecture.md
├── roadmap.md
├── team/ # v2.3 團隊治理（可選）
│ ├── OWNERS.md
│ └── approval-notes.md
├── audit/ # 意圖 audit（可選）
│ └── claims-matrix.md # 活主張 v0 列
├── adr/ # 套件 / 專案 ADR（可選）
├── plans/<slug>/ # v1.3 計劃模式（程式碼前 / 史詩）
│ └── README.md
├── decisions/
└── features/<slug>/ # 以程式碼為後盾的功能包
僅在合理時使用支援性文檔（除了 from-zero，它可能建立一個完整的最小核心集合）。
產出矩陣（摘要）
| 產出 | from-zero / bootstrap | integrate (mature) | audit | plan | feature | sync |
|---|---|---|---|---|---|---|
| 中樞 | 建立 | 擴充 / 索引 | 選擇性更新狀態 | 連結計劃 | 連結 | 如需 |
| 核心敘事文檔 | 是 | 不重寫 | 不（唯讀） | 不 | 不 | 如有影響 |
| 涵蓋率矩陣 | 是 | 必要 | 庫存的一部分 | 選擇性列 | 列 | 更新 |
| 宣稱矩陣 | 選擇性預先 | 建議若有偏移 | 必要 | n/a | 如審計則限範圍 | 如有偏移 |
計劃 docs/plans/ | n/a | n/a | n/a | 必要 | 若存在則連結 | 如有影響 |
| 功能包 | 關鍵領域 | 缺口 / 條目 | 不（除非被問） | 不（直到升級） | 必要 | 如有影響 |
團隊 docs/team/ | 若所有者已知 | 要求時建立/連結 | 不 | n/a | n/a | 如有影響 |
| 平行完整樹 | 沙箱可行 | 禁止在根目錄 | n/a | n/a | n/a | n/a |
工作流程（所有模式）
- 第 0 步 — 範圍、模式、意圖（如果是專案）、成熟度/變體、輸出、slug；在相關時偵測 ArkGate 訊號；為專案工作偵測技術棧和單體庫（skill-discovery.md Polyglot + Monorepo hubs）。
- 先發現程式碼 — 感知技術棧的庫存；如果是單體庫，則套件索引 + 每個套件的庫存；樹、清單檔案、進入點、範例測試。然後文檔（如果有）。對於已命名的功能，先搜尋該表面。如果偵測到 Ark，依照 arkgate-bridge.md 豐富庫存。
- 如果進行審計或文檔存在且意圖為 integrate/from-zero 並懷疑有偏移：執行協調（modes.md § Audit，audit-template.md）。關卡後 → 橋接交接（modes.md §9）。
- 計劃檔案 — 建立/更新以及不寫入（功能/計劃的預設值）。
- **
…
[因翻譯而截斷]