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 PATHPaths
路径
- = the absolute path of the directory containing this SKILL.md. Every
SKILL_DIRandreferences/...path below is relative toscripts/.... Resolve it once and use absolute paths when handing files to subagents.SKILL_DIR - = the repository being audited (the current working directory). All detection commands run here, and all outputs are written here.
AUDIT_CWD - Working files go in (add it to
AUDIT_CWD/.codebase-audit/)..gitignore
- = 包含此
SKILL_DIR的目录的绝对路径。下文所有SKILL.md和references/...路径均相对于scripts/...。只需解析一次,并在将文件交给 subagents 时使用绝对路径。SKILL_DIR - = 要审计的仓库(当前工作目录)。所有检测命令都在此处运行,所有输出也都写入此处。
AUDIT_CWD - 工作文件存放在 (将其添加到
AUDIT_CWD/.codebase-audit/)。.gitignore
Dimensions
审计维度
| # | audit key | detection spec (relative to |
|---|---|---|
| 1 | performance | |
| 2 | security | |
| 3 | enterprise | |
| 4 | issues | |
| 5 | architecture | |
| 6 | dependencies | |
| 7 | i18n | |
| 8 | api | |
| 9 | resilience | |
| 10 | container_iac | |
| 11 | observability | |
Each spec has on-demand examples at .
references/detection/examples/<same file name>| # | 审计键 | 检测规范(相对于 |
|---|---|---|
| 1 | performance | |
| 2 | security | |
| 3 | enterprise | |
| 4 | issues | |
| 5 | architecture | |
| 6 | dependencies | |
| 7 | i18n | |
| 8 | api | |
| 9 | resilience | |
| 10 | container_iac | |
| 11 | observability | |
每个规范在 中提供可按需查阅的示例。
references/detection/examples/<same file name>Steps
步骤
-
Config: ifis given or
--configexists in.codebase-audit.yml, load it (format:AUDIT_CWD). Readreferences/config-schema.md,dimensions,context.maturity,ignore,gate.suppress -
Prepare:(in
rm -rf .codebase-audit/results && mkdir -p .codebase-audit/results). Stale result files must never leak into a new run.AUDIT_CWD -
Discovery: followONCE, in
references/discovery.md. BuildAUDIT_CWD(includingdiscovery_context,archetypes,has_iac) and write it tototal_lines. Print:.codebase-audit/discovery.json.Discovered: [languages] | archetypes: [...] | files: [n] | IaC: [yes/no] -
Select dimensions:
- If config is set → use it.
dimensions - Else if /
--all→ all 11.--ci - 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 , and note:
discovery_context.has_iac == false. Print:Dimension 10 (Container & IaC) skipped — no Dockerfile/Terraform/K8s found. Remember this list asRunning: [selected audit keys].EXPECTED
- If config
-
Run each selected dimension with this task (fill in the placeholders):Audit the repository atfor the
AUDIT_CWDdimension. discovery_context:<audit key>. Maturity:<JSON>. Ignore paths:<maturity>. Read the detection spec<globs>and follow its "How to use this spec" section: skip non-applicable items as<SKILL_DIR>/references/detection/<NN-name>.md, run each item'sskippedto locate candidates, read only candidate snippets, applysignals, assign severity. Consultconfirmonly for ambiguous candidates. Do not read the whole repository. Write exactly one AuditResult JSON object conforming to<SKILL_DIR>/references/detection/examples/<NN-name>.md(audit =<SKILL_DIR>/references/schema.json, score = 0) to<audit key>. Reply with one line:AUDIT_CWD/.codebase-audit/results/<audit key>.json.<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 as each completes. If a dimension fails, do NOT write a placeholder: the engine records any missing or invalid result itself.
✓ <audit key>: <n> findings
-
Engine (deterministic — never compute scores or the gate yourself). Run in. Use
AUDIT_CWD, orpython3wherepythondoes not exist.python3bash# 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] --cimakes 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 (--expect, seegate.fail_on_error). Always passreferences/config-schema.md.--total-lines -
Report: print the engine's stdout/stderr and the report paths. Inmode, propagate the engine's exit code (0 = pass, 1 = gate breach, 2 = invalid input).
--ci
Scoring and gate rules: . Compliance mapping:
.
references/scoring.mdreferences/compliance-map.md-
配置:如果提供了,或
--config中存在AUDIT_CWD,则加载它(格式:.codebase-audit.yml)。读取references/config-schema.md、dimensions、context.maturity、ignore、gate。suppress -
准备:在中执行
AUDIT_CWD。陈旧的结果文件绝不能混入新运行。rm -rf .codebase-audit/results && mkdir -p .codebase-audit/results -
发现:在中仅按照
AUDIT_CWD执行一次。构建references/discovery.md(包括discovery_context、archetypes、has_iac),并将其写入total_lines。打印:.codebase-audit/discovery.json。Discovered: [languages] | archetypes: [...] | files: [n] | IaC: [yes/no] -
选择维度:
- 如果配置中的 已设置 → 使用它。
dimensions - 否则,如果使用 /
--all→ 使用全部 11 个维度。--ci - 否则 → 显示菜单(表中编号 1–11),并读取用户选择(以逗号分隔的编号或 )。
all - 当 时,始终移除维度 10(
discovery_context.has_iac == false),并注明:container_iac。 打印:Dimension 10 (Container & IaC) skipped — no Dockerfile/Terraform/K8s found。将此列表记为Running: [selected audit keys]。EXPECTED
- 如果配置中的
-
运行每个选定的维度,使用以下任务(填写占位符):在对
AUDIT_CWD维度审计该仓库。<audit key>:discovery_context。成熟度:<JSON>。忽略路径:<maturity>。 读取检测规范<globs>,并遵循其 "How to use this spec" 部分:将不适用的项目标记为<SKILL_DIR>/references/detection/<NN-name>.md,运行每个项目的skipped定位候选项,仅读取候选项代码片段,应用signals并分配 严重性。仅在候选项含义不明确时查阅confirm。不要读取整个仓库。 向<SKILL_DIR>/references/detection/examples/<NN-name>.md写入恰好一个符合AUDIT_CWD/.codebase-audit/results/<audit key>.json的 AuditResult JSON 对象 (audit =<SKILL_DIR>/references/schema.json,score = 0)。回复一行:<audit key>。<audit key>: <n> findings- 如果你的环境可以运行 subagents(例如 Claude Code 的 Agent/Task 工具、Codex subagents、Cursor 或 GitHub Copilot custom agents/subagents),则每个维度并行 分派一个 subagent——不要等待一个完成后再启动下一个。
- 否则,在当前 session 中逐个运行。在开始下一个维度之前,完成当前维度并写入结果文件, 且不要将一个维度的代码片段带入下一个维度——结果文件是唯一有效的状态。
- 每完成一个维度,打印 。如果某个维度失败,不要写入占位结果:引擎会自行记录任何缺失或无效的结果。
✓ <audit key>: <n> findings
-
引擎(确定性——绝不要自行计算分数或 gate)。在中运行。 使用
AUDIT_CWD;如果不存在python3,则使用python3。pythonbashundefined
—
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"
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]
--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
--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`。