codebase-audit

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

/codebase-audit

/codebase-audit

Run a multi-dimension static audit of the current working directory.
/codebase-audit            # show the dimension menu
/codebase-audit --all      # run all applicable dimensions, no menu
/codebase-audit --ci       # non-interactive: all applicable dims, gate + exit code
/codebase-audit --config PATH
对当前工作目录执行多维静态审计。
/codebase-audit            # show the dimension menu
/codebase-audit --all      # run all applicable dimensions, no menu
/codebase-audit --ci       # non-interactive: all applicable dims, gate + exit code
/codebase-audit --config PATH

Paths

路径

  • SKILL_DIR
    = the absolute path of the directory containing this SKILL.md. Every
    references/...
    and
    scripts/...
    path below is relative to
    SKILL_DIR
    . Resolve it once and use absolute paths when handing files to subagents.
  • AUDIT_CWD
    = the repository being audited (the current working directory). All detection commands run here, and all outputs are written here.
  • Working files go in
    AUDIT_CWD/.codebase-audit/
    (add it to
    .gitignore
    ).
  • SKILL_DIR
    = 包含此
    SKILL.md
    的目录的绝对路径。下文所有
    references/...
    和
    scripts/...
    路径均相对于
    SKILL_DIR
    。只需解析一次,并在将文件交给 subagents 时使用绝对路径。
  • AUDIT_CWD
    = 要审计的仓库(当前工作目录)。所有检测命令都在此处运行,所有输出也都写入此处。
  • 工作文件存放在
    AUDIT_CWD/.codebase-audit/
    (将其添加到
    .gitignore
    )。

Dimensions

审计维度

#audit keydetection spec (relative to
SKILL_DIR
)
1performance
references/detection/01-performance.md
2security
references/detection/02-security.md
3enterprise
references/detection/03-enterprise.md
4issues
references/detection/04-issues.md
5architecture
references/detection/05-architecture.md
6dependencies
references/detection/06-dependencies.md
7i18n
references/detection/07-i18n.md
8api
references/detection/08-api.md
9resilience
references/detection/09-resilience.md
10container_iac
references/detection/10-container-iac.md
11observability
references/detection/11-observability.md
Each spec has on-demand examples at
references/detection/examples/<same file name>
.
#审计键检测规范(相对于
SKILL_DIR
)
1performance
references/detection/01-performance.md
2security
references/detection/02-security.md
3enterprise
references/detection/03-enterprise.md
4issues
references/detection/04-issues.md
5architecture
references/detection/05-architecture.md
6dependencies
references/detection/06-dependencies.md
7i18n
references/detection/07-i18n.md
8api
references/detection/08-api.md
9resilience
references/detection/09-resilience.md
10container_iac
references/detection/10-container-iac.md
11observability
references/detection/11-observability.md
每个规范在
references/detection/examples/<same file name>
中提供可按需查阅的示例。

Steps

步骤

  1. Config: if
    --config
    is given or
    .codebase-audit.yml
    exists in
    AUDIT_CWD
    , load it (format:
    references/config-schema.md
    ). Read
    dimensions
    ,
    context.maturity
    ,
    ignore
    ,
    gate
    ,
    suppress
    .
  2. Prepare:
    rm -rf .codebase-audit/results && mkdir -p .codebase-audit/results
    (in
    AUDIT_CWD
    ). Stale result files must never leak into a new run.
  3. Discovery: follow
    references/discovery.md
    ONCE, in
    AUDIT_CWD
    . Build
    discovery_context
    (including
    archetypes
    ,
    has_iac
    ,
    total_lines
    ) and write it to
    .codebase-audit/discovery.json
    . Print:
    Discovered: [languages] | archetypes: [...] | files: [n] | IaC: [yes/no]
    .
  4. Select dimensions:
    • If config
      dimensions
      is set → use it.
    • Else if
      --all
      /
      --ci
      → all 11.
    • Else → present the menu (numbers 1–11 from the table) and read the user's choice (comma-separated numbers or
      all
      ).
    • Always drop dimension 10 (container_iac) when
      discovery_context.has_iac == false
      , and note:
      Dimension 10 (Container & IaC) skipped — no Dockerfile/Terraform/K8s found
      . Print:
      Running: [selected audit keys]
      . Remember this list as
      EXPECTED
      .
  5. Run each selected dimension with this task (fill in the placeholders):
    Audit the repository at
    AUDIT_CWD
    for the
    <audit key>
    dimension. discovery_context:
    <JSON>
    . Maturity:
    <maturity>
    . Ignore paths:
    <globs>
    . Read the detection spec
    <SKILL_DIR>/references/detection/<NN-name>.md
    and follow its "How to use this spec" section: skip non-applicable items as
    skipped
    , run each item's
    signals
    to locate candidates, read only candidate snippets, apply
    confirm
    , assign severity. Consult
    <SKILL_DIR>/references/detection/examples/<NN-name>.md
    only for ambiguous candidates. Do not read the whole repository. Write exactly one AuditResult JSON object conforming to
    <SKILL_DIR>/references/schema.json
    (audit =
    <audit key>
    , score = 0) to
    AUDIT_CWD/.codebase-audit/results/<audit key>.json
    . Reply with one line:
    <audit key>: <n> findings
    .
    • If your environment can run subagents (e.g. Claude Code's Agent/Task tool, Codex subagents, Cursor or GitHub Copilot custom agents/subagents), dispatch one subagent per dimension in parallel — do not wait for one before starting the next.
    • Otherwise run them one at a time in this session. Finish and write each result file before starting the next dimension, and do not carry one dimension's snippets into the next — the result file is the only state that matters.
    • Print
      ✓ <audit key>: <n> findings
      as each completes. If a dimension fails, do NOT write a placeholder: the engine records any missing or invalid result itself.
  6. Engine (deterministic — never compute scores or the gate yourself). Run in
    AUDIT_CWD
    . Use
    python3
    , or
    python
    where
    python3
    does not exist.
    bash
    # Runtime deps (jsonschema + PyYAML). In interactive mode ask the user before installing.
    python3 -c "import jsonschema, yaml" 2>/dev/null || \
      python3 -m pip install -q -r "<SKILL_DIR>/scripts/requirements.txt"
    
    # Local (default): HTML dashboard + markdown
    python3 "<SKILL_DIR>/scripts/run_engine.py" \
      --results-dir .codebase-audit/results --expect <EXPECTED, comma-separated> \
      --discovery .codebase-audit/discovery.json \
      --out audit-report.md --formats html,md --html-out audit-report.html \
      --total-lines <total_lines> [--config .codebase-audit.yml]
    
    # CI (--ci): SARIF + markdown + gate exit code
    python3 "<SKILL_DIR>/scripts/run_engine.py" \
      --results-dir .codebase-audit/results --expect <EXPECTED, comma-separated> \
      --out audit-report.md --formats sarif,md --sarif-out audit-report.sarif \
      --total-lines <total_lines> [--config .codebase-audit.yml] --ci
    --expect
    makes the run fail-closed: a selected dimension with no valid result file is reported as ERROR (never as a clean 10/10) and, by default, fails the CI gate (
    gate.fail_on_error
    , see
    references/config-schema.md
    ). Always pass
    --total-lines
    .
  7. Report: print the engine's stdout/stderr and the report paths. In
    --ci
    mode, propagate the engine's exit code (0 = pass, 1 = gate breach, 2 = invalid input).
Scoring and gate rules:
references/scoring.md
. Compliance mapping:
references/compliance-map.md
.
  1. 配置:如果提供了
    --config
    ,或
    AUDIT_CWD
    中存在
    .codebase-audit.yml
    ,则加载它(格式:
    references/config-schema.md
    )。读取
    dimensions
    、
    context.maturity
    、
    ignore
    、
    gate
    、
    suppress
    。
  2. 准备:在
    AUDIT_CWD
    中执行
    rm -rf .codebase-audit/results && mkdir -p .codebase-audit/results
    。陈旧的结果文件绝不能混入新运行。
  3. 发现:在
    AUDIT_CWD
    中仅按照
    references/discovery.md
    执行一次。构建
    discovery_context
    (包括
    archetypes
    、
    has_iac
    、
    total_lines
    ),并将其写入
    .codebase-audit/discovery.json
    。打印:
    Discovered: [languages] | archetypes: [...] | files: [n] | IaC: [yes/no]
    。
  4. 选择维度:
    • 如果配置中的
      dimensions
      已设置 → 使用它。
    • 否则,如果使用
      --all
      /
      --ci
      → 使用全部 11 个维度。
    • 否则 → 显示菜单(表中编号 1–11),并读取用户选择(以逗号分隔的编号或
      all
      )。
    • 当
      discovery_context.has_iac == false
      时,始终移除维度 10(
      container_iac
      )
      ,并注明:
      Dimension 10 (Container & IaC) skipped — no Dockerfile/Terraform/K8s found
      。 打印:
      Running: [selected audit keys]
      。将此列表记为
      EXPECTED
      。
  5. 运行每个选定的维度,使用以下任务(填写占位符):
    在
    AUDIT_CWD
    对
    <audit key>
    维度审计该仓库。
    discovery_context
    :
    <JSON>
    。成熟度:
    <maturity>
    。忽略路径:
    <globs>
    。 读取检测规范
    <SKILL_DIR>/references/detection/<NN-name>.md
    ,并遵循其 "How to use this spec" 部分:将不适用的项目标记为
    skipped
    ,运行每个项目的
    signals
    定位候选项,仅读取候选项代码片段,应用
    confirm
    并分配 严重性。仅在候选项含义不明确时查阅
    <SKILL_DIR>/references/detection/examples/<NN-name>.md
    。不要读取整个仓库。 向
    AUDIT_CWD/.codebase-audit/results/<audit key>.json
    写入恰好一个符合
    <SKILL_DIR>/references/schema.json
    的 AuditResult JSON 对象 (audit =
    <audit key>
    ,score = 0)。回复一行:
    <audit key>: <n> findings
    。
    • 如果你的环境可以运行 subagents(例如 Claude Code 的 Agent/Task 工具、Codex subagents、Cursor 或 GitHub Copilot custom agents/subagents),则每个维度并行 分派一个 subagent——不要等待一个完成后再启动下一个。
    • 否则,在当前 session 中逐个运行。在开始下一个维度之前,完成当前维度并写入结果文件, 且不要将一个维度的代码片段带入下一个维度——结果文件是唯一有效的状态。
    • 每完成一个维度,打印
      ✓ <audit key>: <n> findings
      。如果某个维度失败,不要写入占位结果:引擎会自行记录任何缺失或无效的结果。
  6. 引擎(确定性——绝不要自行计算分数或 gate)。在
    AUDIT_CWD
    中运行。 使用
    python3
    ;如果不存在
    python3
    ,则使用
    python
    。
    bash
    undefined
—

Runtime deps (jsonschema + PyYAML). In interactive mode ask the user before installing.

—
python3 -c "import jsonschema, yaml" 2>/dev/null ||
python3 -m pip install -q -r "<SKILL_DIR>/scripts/requirements.txt"
—

Local (default): HTML dashboard + markdown

—
python3 "<SKILL_DIR>/scripts/run_engine.py"
--results-dir .codebase-audit/results --expect <EXPECTED, comma-separated>
--discovery .codebase-audit/discovery.json
--out audit-report.md --formats html,md --html-out audit-report.html
--total-lines <total_lines> [--config .codebase-audit.yml]
—

CI (--ci): SARIF + markdown + gate exit code

—
python3 "<SKILL_DIR>/scripts/run_engine.py"
--results-dir .codebase-audit/results --expect <EXPECTED, comma-separated>
--out audit-report.md --formats sarif,md --sarif-out audit-report.sarif
--total-lines <total_lines> [--config .codebase-audit.yml] --ci
   `--expect` 会使运行采用 fail-closed 策略:某个选定维度没有有效的结果文件时,
   会被报告为 ERROR(绝不会被视为干净的 10/10),并且默认情况下会导致 CI gate
   未通过(`gate.fail_on_error`,参见 `references/config-schema.md`)。始终传入 `--total-lines`。
7. **报告**:打印引擎的 stdout/stderr 和报告路径。在 `--ci` 模式下,
   传递引擎的退出码(0 = 通过,1 = gate 未通过,2 = 输入无效)。

评分和 gate 规则:`references/scoring.md`。合规映射:
`references/compliance-map.md`。