16 README 評估標準

這份文件是用來評估 repo README 的，不是拿來替 README 補內容。

repo 裡的實作、指令、資料流仍以 repo README 和程式碼為準；這裡只定義一份可接手的 README 應該回答哪些問題，以及覆蓋程度要怎麼分級。

用途

handoff 只記錄 README 覆蓋程度與缺口。真正的技術內容要回 repo 補，避免 handoff 和 repo 內容分岔。

Handoff 使用方式

• handoff 內其他文件只記：
  • Repo README
  • README Coverage
  • README Gaps
• 若某 repo README 未覆蓋必要項目：
  • handoff 只記缺口與風險
  • 不在 handoff 內代寫完整專案技術內容

README Coverage Level

必要能力與判定標準

1. Project Summary

README 至少能讓接手者回答：

• 這是什麼專案
• 目前是否仍在維護
• 正式站 / staging / CMS 入口在哪

判定原則：

• 有章節但只有專案名稱，不算覆蓋
• 待確認 可以接受，但必須明確寫出缺什麼

2. Tech Stack

README 至少能讓接手者回答：

• 主要 framework / runtime 是什麼
• package manager 是什麼
• 是否依賴 CMS / backend / 第三方服務

判定原則：

• 只列出框架名稱但看不出運行方式，算部分覆蓋

3. Local Setup

README 至少能讓接手者回答：

• 如何安裝
• 如何啟動
• 需要哪些本機前置條件
• 啟動失敗時先看哪裡

判定原則：

• 只有 npm install / yarn dev 不算完整
• 至少要有必要 env 或外部依賴提醒

4. Environment Variables

README 至少能讓接手者回答：

• 用到哪些變數名稱
• 每個變數用來做什麼
• 哪些是 public，哪些不該放 secret

判定原則：

• README 不必寫 secret 值
• secret 存放、重發與權限應導回 handoff

5. Build / Test / Quality

README 至少能讓接手者回答：

• 如何 build
• 如何做最低限度驗收
• 有沒有 test / lint / typecheck

判定原則：

• 沒有自動化測試可接受
• 但要明確寫出 smoke test 或目前缺口

6. Deployment / Rollback

README 至少能讓接手者回答：

• 目前大致怎麼部署
• 部署後怎麼驗證
• 發生問題怎麼回滾或至少去哪裡查

判定原則：

• 沒有完整平台細節可接受
• 但至少要指出部署類型、驗證方式與缺口

7. Project Structure

README 至少能讓接手者回答：

• 哪些模組或資料夾最重要
• 專案內主要責任邊界在哪

判定原則：

• 不要求逐檔說明
• 但至少要讓新接手者知道從哪裡讀起

8. Core Flows

README 至少能讓接手者回答：

• 主要資料流怎麼走
• 哪些地方最容易改壞

判定原則：

• 這一節缺失時，接手風險會明顯升高

9. Integrations

README 至少能讓接手者回答：

• 哪些第三方服務是核心依賴
• 失效時會怎樣
• 程式內大概從哪裡進入

判定原則：

• 權限與憑證細節不必放 README
• 但失效表徵與用途應能看懂

10. Troubleshooting

README 至少能讓接手者回答：

• 常見問題是什麼
• 發生時第一步先看哪裡

判定原則：

• 不需要完整 runbook
• 但至少要有第一線排查入口

11. Ownership / Maintenance

README 至少能讓接手者回答：

• 最後驗證日期
• 已知缺口
• 待補資訊

判定原則：

• 沒有維護者姓名可接受
• 但至少要有狀態與缺口

評估輸出格式

handoff 內各專案建議統一使用：

• README Coverage: A / B / C / D
• README Gaps: ...
• Next Action: ...

快速判定規則

• 若可支援接手者完成本機啟動、理解主要資料流、知道部署/回滾缺口、知道出事先看哪裡：至少 B
• 若可支援接手者獨立維運且只剩少量待確認：A
• 若大量核心資訊仍缺：C
• 若幾乎只是一段簡介：D