Communitygithub.com

项目基线检查器

用于 Claude Code 的 /baseline 技能——一个零依赖的项目就绪性检查器(69 条规则)。安装到 ~/.claude/skills/baseline。

项目基线检查器 是什么?

baseline-skill 是为 AI 编码代理(如 Claude Code)设计的一个技能,可对代码仓库进行结构化和自动化的就绪性检查。其核心是一个零依赖的 Node.js 检查器(check.mjs),执行 69 条规则的规则集(rules.json)。该技能通过生成阻塞器(exit 1,中断 CI)、警告和需要人工判断的签名项来评估仓库,而不仅仅是依赖文档中的承诺。规则按类别组织(安全、构建、配置等),并支持层级配置文件:核心配置始终运行,服务配置自动运行,高级配置(SBOM、变异测试)可选。关键功能包括:完整解释每项检查卡的“explain”模式、通过迁移模板应用最佳实践的“fix”模式,以及完整的“init”模式用于为新仓库搭建基线。该技能需要在 Node ≥18 和 git 环境下运行,并强调绝对路径解析($SKILL_DIR)以确保正确执行,避免将字面量字符串传递给 shell。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

项目基线检查器 是做什么的?

一个可测试的就绪性标准:69 条规则,每条规则都对应一个零依赖的 Node 运行器在仓库静态时执行的检查。阻塞器会导致 CI 失败(exit 1);无法用脚本判断的事项通过带日期的签名台账来解决。核心思想:不要相信书面承诺——让 check 来验证。

工具包位于此文件同目录下: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"、"检查此仓库"

  1. 选择目标仓库:请求中明确给出的路径,否则为当前工作目录。确认它看起来像个仓库(有清单文件或 .git)。
  2. 运行运行器(人类可读):
    node "$SKILL_DIR/check.mjs" --repo <target>
    
    • 如果绝对不要执行仓库的引导/测试命令(BUILD-05),则添加 --no-exec——例如在不可信的仓库、没有时间运行测试、或命令未配置的情况下。在安全时优先执行,因为 BUILD-05 是最重要的检查。
    • 如果用户想要专家级规则(SBOM、代码扫描、变异测试、符号完整性、依赖漏洞扫描、覆盖率下限),则添加 --profile advanced。当 project_type=service 时,service 配置会自动启用。
    • 添加 --json 以便以编程方式解析结果,而不是显示评分卡。
  3. 向用户展示结果,首先展示阻塞器(这些会导致 CI 失败),然后是需要修复的警告。按类别分组。不要倾倒全部 69 行——总结:就绪百分比、阻塞器数量、以及具体的 FAIL/值得注意的 WARN 及其一行说明。提供修复或搭建的选项。

模式:init——"在此处设置基线"、"采用此标准"、"搭建基线"

  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——"修复基线失败项"、"让它全绿"

  1. 先评分。对于用户希望解决的每个阻塞器/警告,应用规则自身的 fix 字段(从 rules.json 中读取)作为具体编辑操作——添加缺失的 LICENSE、将 action 固定到 SHA、将 .env 添加到 .gitignore 并轮换密钥、添加负面测试等。
  2. 对于 manual(签名)规则,不要伪造检查——帮助用户完成判断(影响范围、已有方案检查、wedge/moat),并在 .project-baseline/signoff.json 中记录带日期的条目。
  3. 重新评分以确认。

模式:explain——"SEC-03 检查什么"、"为什么 CTX-05 失败"

从 rules.json 中读取规则(每条规则包含 title、rationale、fix、source 和 check)并通俗地解释,同时说明运行器实际检查了什么。对于不熟悉的术语(SBOM、SLSA、来源证明、签名台账等),此目录中的 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 中——如果用户想要深入了解,请读取该文件。

相关技能