/codebase-audit

name: codebase-audit
description: "全面代码库审计 — 自适应并行深度分析（前后端契约、数据完整性、异常处理/安全、架构/技术债、配置/缓存），结构化 findings + 对抗验证 + 基线对比，输出按严重程度排序的统一报告和修复路线图。支持 quick 快速体检模式。Use when user asks to audit, analyze, or review an entire codebase for design issues, find hidden bugs, check architecture health, or asks '全面审查', '代码库审计', '分析设计问题', 'audit codebase', 'health check', '有哪些问题', '快速体检'. Also trigger when user asks to find silent degradation, data flow breakpoints, type mismatches between frontend and backend, or wants to understand technical debt across a project."

Codebase Audit — Adaptive Deep Analysis

Comprehensive codebase audit that adapts its agent configuration to the project's tech stack, forces structured findings, adversarially verifies Critical/High findings before they enter the report, diffs against the previous audit's ledger (resolved / still-open / new), and outputs a severity-sorted report plus a phased repair roadmap.

Core Principles

1. **READ-ONLY** — Audit agents must never create, modify, or delete files in the target. Every agent prompt starts with the read-only preamble in `references/agent-prompts.md`. 2. **Inherit the session model** — Omit the `model` param on all agents so they inherit the session model (usually the strongest available). Only override *upward* if the session model is clearly weak for cross-file reasoning. Never hardcode a specific model name in this skill. 3. **Depth over breadth** — Fewer agents with broader merged scopes beat many shallow agents. Each agent traces issues across file boundaries. 4. **Adaptive** — Agent count and dimensions vary by stack and mode. 5. **Verified findings** — Critical/High findings must survive an adversarial verify pass. Medium findings pass through but are labeled `unverified` in the report.

Operating Contract

• Direct actions: read-only inspection, local dependency audits, report writing under the target, and ledger updates under `<target>/.audit/` after the user invokes this skill.
• Escalate before: editing audited project source files, dependency manifests, `.gitignore`, CI config, remote issues, PR state, or anything outside the requested audit/report scope.
• Evidence-backed pushback: challenge "all clear" or "resolved" only with file evidence, dependency-audit output, verifier results, or ledger spot-checks.
• Feedback loop: promote repeated misses into prompt updates, ledger matching rules, or fixture eval cases rather than leaving them as session-only notes.

Gotchas

• Dependency-audit commands must run from `{TARGET_DIR}`, not the assistant's incidental cwd.
• Finder agents must not read `evals/expected-findings.json` or eval README files when auditing the planted-bug fixture.
• A previous ledger miss is not proof that a finding was resolved; spot-check the file before marking an old finding `resolved`.

Modes

| Mode | Trigger | Agents | Verify pass | Ledger | |------|---------|--------|-------------|--------| | **full** (default) | plain invocation, "全面审查" | 3–5 by stack (+ optional dims) | yes | yes | | **quick** | "quick" in args, "快速体检" | 2 (Silent Degradation & Security; Data Integrity & Registry) | no — all findings labeled `unverified` | yes |

**Optional dimensions** (full mode only, enable when user asks or the repo obviously needs them):

• `tests` — test quality: assertion strength, skip markers, coverage of critical paths (Agent 6)
• `concurrency` — races, blocking calls in async, leaked tasks/goroutines (Agent 7)

Workflow

Phase 0: Detect & Prepare

1. **Stack detection**: `package.json`/`tsconfig.json` → TS/JS; `pyproject.toml`/`requirements.txt` → Python; `Cargo.toml` → Rust; `go.mod` → Go; multiple → full-stack. 2. **Size estimate**: `tokei <target>` (fallback: `find <target> -name '*.<ext>' | xargs wc -l`), excluding vendored/generated code. If effective size ≥ 400K LOC, split each agent's scope by top-level directory and note the split in the report. 3. **Exclusions** (always, in every agent prompt): `node_modules/`, `vendor/`, `target/`, `dist/`, `build/`, `.git/`, lockfiles, generated code. 4. **Ledger**: read `<target>/.audit/findings.json` if it exists — this is the previous audit baseline (format: `references/ledger-format.md`). 5. **Deterministic dependency audit**: from `{TARGET_DIR}` (never the assistant's incidental cwd), run each matching tool and feed raw output to the Error Handling & Security prompt:

• Rust: `cargo audit`
• Node: `npm audit`
• Python metadata (`pyproject.toml` / `setup.py`): `pip-audit .`
• Python requirements (`requirements.txt`): `pip-audit -r requirements.txt`
• Python fallback with no project files: `pip-audit .`
• Go: `govulncheck ./...`

If a required tool is unavailable, the report must state `依赖审计降级跳过: <tool>`; never omit the degradation silently.

Phase 1: Assemble Dimensions

Pick the configuration by detected stack. Full prompt templates in `references/agent-prompts.md`; prepend the read-only preamble and inject `{TARGET_DIR}` / `{STACK_INFO}` into each.

**Full-Stack (5 agents)** — frontend + backend both present:

| # | Dimension | Scope (merged) | |---|-----------|----------------| | 1 | Frontend-Backend Contract | Type consistency + rendering pipeline + serialization boundaries. Reads BOTH sides. | | 2 | Data Integrity & Flow | End-to-end pipeline tracing, field dropping, declaration-execution gaps, registry coverage alignment. | | 3 | Error Handling & Security | Silent degradation, exception patterns, secrets, injection, unsafe deserialization. | | 4 | Architecture & Code Quality | Layer violations, god objects, duplication/drift, extension cost, registry cross-reference. | | 5 | Config & Persistence | Config completeness, cache key/integrity, DB schema, temp files, state persistence. |

**Backend-Only (4 agents)**: replace #1 with "API Contract & Data Integrity" (which absorbs #2's data-flow/registry scope — do NOT also dispatch #2); keep #3–#5. **Frontend-Only (3 agents)**: Component Architecture