Tech Debt

技術債（Tech Debt）

本頁彙整已知的技術債、風險與償還策略，供維護者排序。分為「程式碼」「架構」「文件／流程」「相依性」四類。

償還原則：優先處理「會影響可重現性或正確性」的項目，其次是「拖慢新使用者採用」的項目。

項目	位置	風險	建議
硬編路徑殘留	`META_PIPE_ROOT` 已可組態，但仍需全面稽核其他腳本是否有 `/Users/htlin/meta-pipe` 假設	中：非本機環境會壞	grep 全庫 `/Users/htlin`，改用相對或環境變數
未實作的資料解析	`generate_quickstart_guide.py:40` — `# TODO: Parse actual data from files`	低：目前用佔位資料	接上真實專案資料來源
測試 fixture 與 schema 易漂移	`tests/` 中依賴檔案結構的測試	中：schema 一改就紅	抽出共用 fixture builder，schema 集中定義
Merge conflict 殘留風險	git status 顯示 `tooling/python/ai_screen.py` 曾處於 `UU`（未解衝突）狀態	高：未解衝突會導致執行錯誤	確認衝突已解、`ai_screen.py` 可正常 import 與執行

項目	說明	建議
Python / R 雙語邊界	資料在 Python（CSV/DB）與 R（分析）之間交換，schema 契約隱性	明確定義交換格式與欄位契約，加驗證層
Skill 即文件即介面的耦合	流程邏輯分散在多個 `SKILL.md`，修改需人工同步	建立 SKILL 之間的交叉引用檢查（延伸 `/module-management`）
Agent teams 仍為實驗性	平行寫入靠「目錄所有權」約定，缺乏強制隔離	用 hook 強制檔案所有權，或改 worktree 隔離
品質模式雙軌	strict/draft 分支散落在多處判斷	集中到 `project_meta.py`，避免遺漏分支

項目	說明	建議
README 缺完整使用範例	issue #6	補端到端範例 + 截圖／影片（#37）
GUI 方向分歧	PR #41 與 #8 並存	收斂為單一路線，關閉重複 PR
`[Unreleased]` 累積過多	CHANGELOG 已累積 3 個 Sprint	切版釋出，建立明確版本節點
大量 Markdown（約 41,700 行）	skills/references 內容龐大，易有陳舊段落	定期用 `vale` 或連結檢查掃描失效引用

項目	說明	建議
Claude CLI 版本綁定	`ai_screen.py` 需 CLI ≥ 2.1.100 且特定 flag	已有 `_assert_claude_cli()` 啟動檢查；持續追 CLI flag 變動
外部 API 依賴	Entrez / CrossRef / OpenAlex / Unpaywall / Scopus	已有 fallback 鏈；補上速率限制與快取以降風險
R 環境設定脆弱	`setup.sh` 曾在 macOS ARM 因 `fs` 套件需 cmake 失敗（#24，已修）	R 套件化（#18）可根本降低此類風險
uv/renv 鎖檔漂移	新增依賴若忘記 lock/snapshot 會破壞可重現性	CI 檢查 lock 一致性