Communitygithub.com

AdarGit008/baseline-skill

用於 Claude Code 的 /baseline 技能 — 一個零依賴的專案就緒度檢查工具(69 條規則)。安裝至 ~/.claude/skills/baseline。

baseline-skill 是什麼?

此技能為 Claude Code 提供了一個名為「baseline」的專案就緒度檢查功能。它包含 69 條由 Node.js 腳本(零依賴)執行的測試規則,旨在靜態分析倉庫狀態。阻塞性問題(Blocker)會導致 CI 失敗(退出碼 1),而無法自動判斷的事項則需透過帶日期戳的簽核帳本(sign-off ledger)手動記錄。整個工具包(包括 runner、規則 JSON、設定範例、範本與參考文件)應與其 SKILL.md 檔案一同存放。使用者可透過「score」(預設評分)、「init」(初始化標準)、「fix」(修復失敗)及「explain」(解釋規則)四種模式與之互動。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add AdarGit008/baseline-skill

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

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"、"檢查此倉庫"

  1. 選定目標倉庫:請求中的明確路徑,否則使用當前工作目錄。確認它看起來像一個倉庫(有 manifest 或 .git)。
  2. 執行執行器(人類可讀):
    node "$SKILL_DIR/check.mjs" --repo <目標>
    
    • 如果不得執行倉庫的引導/測試命令(BUILD-05),則加上 --no-exec——例如,不信任的倉庫、沒有時間運行測試、或命令未設定。在安全的情況下,建議執行它,因為 BUILD-05 是最重要的檢查。
    • 如果使用者想要專家級規則(SBOM、程式碼掃描、突變測試、符號完整性、依賴性漏洞掃描、覆蓋率底線),則加上 --profile advanced。當 project_type=service 時,service 設定檔會自動啟用。
    • 如果你希望以程式化方式解析結果而非顯示計分卡,則加上 --json。
  3. 向使用者呈現結果,首先列出阻塞性問題(這些會導致 CI 失敗),然後是需要修復的警告。依分類分組。不要列出全部 69 行——總結:就緒度百分比、阻塞性問題數量,以及具體的 FAIL/值得注意的 WARN 項目及其一行說明。主動提供修復或初始化的選項。

模式:init —— "在此設定 baseline"、"採用此標準"、"初始化 baseline"

  1. 將工具包複製到倉庫中(建議放入 tools/baseline/),或就地引用它。
  2. 初始化成品,僅在缺少時才進行(未經詢問絕不覆寫):
    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
    
  3. 編輯 baseline.config.json 以符合倉庫實際情況:設定 project_type、bootstrap_command(用於 BUILD-05 的乾淨簽出安裝+測試命令)、以及 makes_external_claims(設為 false 可跳過 CLAIM-* 規則)。選擇性啟用的 *_globs 鍵(freshness/generated/grounding)在倉庫採用那些慣例前應保持空白。
  4. 向他們展示 README.md 中的 CI 整合方式,並將 baseline 作業設為必檢檢查(即規則 BUILD-06)。
  5. 執行首次評分。

模式:fix —— "修復 baseline 失敗"、"讓它全部變綠"

  1. 先執行評分。對於使用者希望處理的每個阻塞性問題/警告,套用規則自身的 fix 欄位(從 rules.json 讀取)來對倉庫進行具體修改——新增遺漏的 LICENSE、將 action 固定到 SHA、將 .env 加入 .gitignore 並輪換機密、新增負向測試等。
  2. 對於 manual(簽核)規則,不要偽造檢查——幫助使用者進行判斷(影響範圍、先前藝術審查、安全壁壘/護城河),並在 .project-baseline/signoff.json 中記錄一條帶日期戳的條目。
  3. 重新評分以確認。

模式: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 中——如果使用者想要深入瞭解,請閱讀該文件。

相關技能