project-baseline
一個可測試的就緒度標準:69 條規則,每條規則皆由一個零依賴的 Node 執行器對倉庫靜態進行檢查。阻塞性問題會導致 CI 失敗(退出碼 1);腳本無法做出的判斷則透過一個帶日期戳的簽核帳本(sign-off ledger)來解決。核心精神:不要相信書面承諾——用某種檢查來驗證它。
工具包位於此檔案旁:check.mjs(執行器)、rules.json(69 條規則)、config.example.json、templates/、README.md(快速入門指南)、REFERENCE.md(完整參考:規則表、分類、架構圖、CI 整合)、以及 GLOSSARY.md(對 DevOps/供應鏈術語的平實解釋)。
請先解析技能目錄。 下方的 $SKILL_DIR 意指包含此 SKILL.md 檔案目錄的絕對路徑——請將其解析為一個具體的路徑再執行任何命令(不要將字串 $SKILL_DIR 直接傳遞給 shell)。它通常位於 ~/.claude/skills/baseline。check.mjs 會從其自身所在目錄載入 rules.json,因此兩者必須保持在同一位置;請始終透過絕對路徑(node "<abs>/check.mjs" …)來呼叫執行器,而不要將它複製到其他地方。執行器僅需 Node ≥ 18 與 git;如果找不到 node,請告知使用者,而不是自行猜測。
當被呼叫時
根據使用者的話語判斷意圖,並選擇一種模式。如果未指定,預設使用 score 模式。
模式:score(預設)—— "執行 baseline"、"/baseline"、"檢查此倉庫"
- 選定目標倉庫:請求中的明確路徑,否則使用當前工作目錄。確認它看起來像一個倉庫(有 manifest 或
.git)。 - 執行執行器(人類可讀):
node "$SKILL_DIR/check.mjs" --repo <目標>- 如果不得執行倉庫的引導/測試命令(BUILD-05),則加上
--no-exec——例如,不信任的倉庫、沒有時間運行測試、或命令未設定。在安全的情況下,建議執行它,因為 BUILD-05 是最重要的檢查。 - 如果使用者想要專家級規則(SBOM、程式碼掃描、突變測試、符號完整性、依賴性漏洞掃描、覆蓋率底線),則加上
--profile advanced。當project_type=service時,service設定檔會自動啟用。 - 如果你希望以程式化方式解析結果而非顯示計分卡,則加上
--json。
- 如果不得執行倉庫的引導/測試命令(BUILD-05),則加上
- 向使用者呈現結果,首先列出阻塞性問題(這些會導致 CI 失敗),然後是需要修復的警告。依分類分組。不要列出全部 69 行——總結:就緒度百分比、阻塞性問題數量,以及具體的 FAIL/值得注意的 WARN 項目及其一行說明。主動提供修復或初始化的選項。
模式:init —— "在此設定 baseline"、"採用此標準"、"初始化 baseline"
- 將工具包複製到倉庫中(建議放入
tools/baseline/),或就地引用它。 - 初始化成品,僅在缺少時才進行(未經詢問絕不覆寫):
cp "$SKILL_DIR/config.example.json" <repo>/baseline.config.json cp "$SKILL_DIR/templates/CLAIMS.json" <repo>/docs/CLAIMS.json # 僅當倉庫對外提出宣稱時 cp "$SKILL_DIR/templates/start-here.md" <repo>/docs/start-here.md # 如果不存在狀態文件 mkdir -p <repo>/.project-baseline && cp "$SKILL_DIR/templates/signoff.json" <repo>/.project-baseline/signoff.json - 編輯
baseline.config.json以符合倉庫實際情況:設定project_type、bootstrap_command(用於 BUILD-05 的乾淨簽出安裝+測試命令)、以及makes_external_claims(設為 false 可跳過 CLAIM-* 規則)。選擇性啟用的*_globs鍵(freshness/generated/grounding)在倉庫採用那些慣例前應保持空白。 - 向他們展示
README.md中的 CI 整合方式,並將baseline作業設為必檢檢查(即規則 BUILD-06)。 - 執行首次評分。
模式:fix —— "修復 baseline 失敗"、"讓它全部變綠"
- 先執行評分。對於使用者希望處理的每個阻塞性問題/警告,套用規則自身的
fix欄位(從rules.json讀取)來對倉庫進行具體修改——新增遺漏的 LICENSE、將 action 固定到 SHA、將.env加入.gitignore並輪換機密、新增負向測試等。 - 對於
manual(簽核)規則,不要偽造檢查——幫助使用者進行判斷(影響範圍、先前藝術審查、安全壁壘/護城河),並在.project-baseline/signoff.json中記錄一條帶日期戳的條目。 - 重新評分以確認。
模式:explain —— "SEC-03 檢查什麼"、"為什麼 CTX-05 失敗"
從 rules.json 中讀取規則(每條規則都有 title、rationale、fix、source 以及 check)並平實地解釋它,同時說明執行器實際檢查了什麼。對於不熟悉的術語(SBOM、SLSA、provenance、簽核帳本……),此目錄中的 GLOSSARY.md 有其平實的解釋。
執行器如何判定(以便你解讀詳細行)
- 每條規則的結果為 PASS / FAIL / WARN / SIGN-OFF / SKIP。只有
blocker的 FAIL 才會設定退出碼為 1。 - SKIP 表示規則不適用:錯誤的
project_type(n/a for <type>)、未開啟的設定檔(profile 'advanced' off)、未採用的選擇性功能、或沒有可檢查的對象。跳過從不計入就緒度。 - 設定檔:
core始終執行;service在project_type=service時自動執行;advanced僅在指定--profile advanced或設定檔中設有profiles:["advanced"]時執行。 - 宣稱是選擇性的: CLAIM-* 僅在存在宣稱註冊表或明確設定
makes_external_claims:true時運行。沒有宣稱註冊表的倉庫不會受到懲罰。 - 設定會合理地自動偵測;倉庫根目錄下的
baseline.config.json會覆蓋設定。按鍵說明見config.example.json。 - 執行器是零依賴(Node ≥ 18 + git)且崩潰恢復力強的:一條檢查無法評估的規則會降級為 SKIP,絕不導致整個運行失敗。
備註
- 切勿將警告呈現為阻塞性問題,反之亦然——嚴重等級在
rules.json和執行器的輸出中。 - 在倉庫可信且已設定引導命令時,優先實際執行 BUILD-05(省略
--no-exec)——綠色的最重要檢查是最強的信號。 - 完整原理、規則表、分類描述、架構圖以及 CI 程式碼片段均在此目錄的
REFERENCE.md中——如果使用者想要深入瞭解,請閱讀該文件。