doc-sync

doc-sync 是一項自動化文件管理工具，旨在於 AI 輔助開發環境中強制執行上下文衛生 (context hygiene)。它維護一套雙文件標準：CLAUDE.md 用於操作導航，README.md 用於存放架構性的隱性知識。透過掃描儲存庫，它能繪製目錄結構、審核版本漂移，並將錯誤置放的架構性描述從導航文件中遷移至結構化文件中。這確保 AI 代理程式不會因過大的上下文窗口而過載，並透過自動加載索引，精準獲取執行當前任務所需的信息。

• 對 CLAUDE.md 導航層級與 README.md 的覆蓋範圍進行全儲存庫級別的審核。

• 強制區分操作指令（如指令、建構步驟）與解釋性架構知識。

• 自動化建立與同步表格索引，確保文件與子目錄能被正確索引以供 AI 發現。

• 執行內容遷移，移除 CLAUDE.md 中過多的敘述並將其移動至 README.md，以維持高效的 Token 使用率。

• 驗證索引完整性，識別缺失的文件，並校正已刪除或移動文件導致的過時索引條目。

• 支援作用域執行，允許用戶在儲存庫、特定目錄或單一檔案父目錄層級觸發文件同步。

• 專為使用 AI 代理程式進行長期程式碼庫維護與技術債管理的軟體工程師設計。

• 要求遵循 .claude 目錄中定義的文件規範。

• 非常適合用於具有複雜目錄結構、且擔心 LLM 注意力漂移風險的專案。

• 自動排除生成的檔案、供應商依賴項與 Git 內部檔案，以防止索引污染。

• 遵循嚴謹的工作流程：探索、審核、內容遷移、索引更新與最終驗證，確保文件狀態乾淨且獨立。

• 當程式碼庫遵循即時上下文 (just-in-time context) 原則時運作效果最佳，通常將操作元數據控制在 200 個 Token 內，架構文件控制在 500 個 Token 內。