| name | vibe-risk-analyzer |
| description | Analyze project codebase health and vibe-coding risk with a 0-100 scoring system across 12 dimensions (plus a conditional AI App Surface dimension for LLM applications), centered on AI-as-maintainer concerns. Deterministic per-dimension scoring with a standing-deduction ledger that automatically re-verifies prior findings on every scan. Outputs a structured diagnostic report with scores, findings, paired Refactoring Risk + AI Extension Risk metrics (Drift Watch in the high-score regime), static dependency graph, and a ready-to-use remediation prompt (interactive or autonomous). Use this skill whenever the user asks to audit, analyze, score, or health-check their project, mentions "vibe coding risk", "code quality", "project health check", "risk analysis", "dependency graph", or wants to understand their codebase structure before refactoring — even if they don't explicitly say "vibe coding" (in any language).
|
| version | 4.1.0 |
| license | MIT |
Vibe Coding Risk Analyzer
Detect and quantify the risks accumulated from unchecked AI-assisted ("vibe") coding,
with scoring centered on AI-as-maintainer concerns rather than traditional human
code review. Produce a standardized diagnostic report with scores, findings, a
dependency graph, and a remediation plan.
Vibe-coded projects often look fine on the surface but harbor invisible structural
debt: god files that exhaust AI's context window, pattern drift that makes AI
coin-flip between three toast systems, missing type contracts that force AI to guess
call signatures, and the absence of AGENTS.md / rules / scan tests that would prevent
the next session from regressing. This skill makes that debt visible and actionable.
v4 note: See CHANGELOG.md. v4 makes scoring deterministic
(sub-item IDs + composition formula + scorecard.json), adds a standing
deduction ledger that re-verifies prior findings on every scan, declares
vendored/data-asset code via .vibe-riskrc.json, reworks Module SRP around
flow-cost (the token cost of understanding one business flow) instead of
raw file size, makes coverage refactor-neutral & critical-path-first, and adds
a conditional AI App Surface dimension for LLM applications.
Full rationale & evidence: PROPOSAL-v4.md.
When to activate
- User requests a project audit, health check, or risk analysis
- User mentions "vibe coding", "code quality", "project health check",
"risk analysis", or "dependency graph" (in any language)
- User wants to visualize dependencies or understand codebase structure
- Before a major refactor to establish a baseline
- Before handing a project over to an AI agent for autonomous maintenance
- Periodically (recommended: every 2-4 weeks on active vibe-coded projects)
Scan modes
| Mode | When to use | What runs | Time |
|---|
| Quick | Fast pulse check, CI gate | Phase 1 only (automated tools), skip Phase 2 | ~2 min |
| Full | Periodic deep audit (default) | All phases + static dependency graph | ~10 min |
Default to Full when unspecified. In Quick mode, dimensions requiring manual
sampling (Pattern drift survey, Test quality review) score "N/A" and are re-weighted
proportionally so the total stays out of 100. AI-specific dimensions (Context
Artifacts, Prohibition Density, Structural Invariants, Determinism) remain fully
scored in Quick mode since they are automation-friendly.
Scoring system (100 points, 12 dimensions + conditional Dim 13)
| # | Dimension | Weight | What it measures |
|---|
| 1 | Module Granularity & SRP (incl. Complexity) | 14 | Flow-cost（理解一条业务流需装载的 token）+ file/function size distribution; pure-data assets & delegation facades exempted |
| 2 | Pattern Consistency | 14 | Coding convention uniformity; module stacking (duplicate toast/HTTP/date libs) |
| 3 | Type Safety & Contracts | 12 | TS/JSDoc coverage on exported APIs, any usage, request/response schemas — AI's primary "memory" |
| 4 | Test Coverage & Structural Invariants | 12 | Critical-path coverage first, denominator-audited, refactor-neutral; scan-test fence density — AI's feedback loop |
| 5 | AI Context Artifacts | 10 | AGENTS.md, .cursor/rules, .claude/skills, ADRs — AI's long-term memory |
| 6 | Architecture & Structure | 8 | Directory organization, separation of concerns, layer clarity |
| 7 | Dependency Health | 7 | Circular deps, unused/vulnerable deps |
| 8 | Explicit Prohibition Density | 6 | Grep-verifiable ❌ / PR-NNN: rules per 10k LOC — AI's fence |
| 9 | Naming & Discoverability | 6 | Naming conventions, semantic clarity |
| 10 | Duplication & Dead Code | 5 | Copy-paste blocks, unused exports/files |
| 11 | Determinism & Side-Effect Hygiene | 3 | SSR/CSR divergence, non-deterministic render, import-time side effects |
| 12 | Security & Tooling Config | 3 | Hardcoded secrets, linter |
| 13 | AI App Surface（条件激活,v4 NEW） | 8 | LLM 应用专属:提示词资产管理、流式/中断卫生、成本护栏、provider 抽象、agent 协议漂移登记 |
Dim 13 仅在 Step 0 检测到 LLM 应用特征时激活（@anthropic-ai/*/openai/provider 注册表/
SSE chat 路由等）。激活时满分变为 108,总分归一化:total = round(sum / 108 × 100);
未激活时按 12 维原样计 100,非 AI 项目不受任何影响。
v4 评分确定性：每条扣分子项有唯一 ID（如 SRP-F2）,维度分按统一组合公式计算
（同一证据只计一次、分档不叠加、维度内封顶）,并产出机读 scorecard.json 工件。
不再有"拿不准就从宽"——边界情况按公式取低档并登记 disputed 待下轮复核。
See scoring-reference.md for per-dimension criteria & the
composition rules.
Risk levels
| Score | Level | Meaning |
|---|
| 0–30 | CRITICAL | Near-unmaintainable; AI cannot reliably work |
| 31–50 | HIGH | Structural refactoring urgently needed |
| 51–70 | MODERATE | Noticeable risks; needs continuous attention |
| 71–85 | LOW | Healthy; maintain current practices |
| 86–100 | EXCELLENT | Exemplary engineering practices |
Risk metrics (paired) + high-score regime
The report shows two independent risk numbers:
- Refactoring Risk (0-100) — "will a large rewrite collapse?" — driven by
size × health × test-safety × perf-debt（perf-debt 自 v4 起只计 Phase 2
确认后的信号,不计裸 grep 候选）.
- AI Extension Risk (0-100) — "will the next AI session regress?" — driven by
health × pattern-drift × prohibition-deficit × context-deficit × determinism.
v4 high-score regime：health ≥ 90 时 deficit 趋零,两个乘法公式饱和在 MINIMAL
而失去信息量。此时报告额外输出 Drift Watch 三先行指标（新增模块守卫密度 /
本轮 diff 新增代码覆盖率 / 禁令陈旧数）替代风险解读;总分 ≥ 95 视为
"AI-native 满级"——报告写"满级,剩余扣分均为台账内政策项",不写"距满分差 N 分"。
See scoring-reference.md § AI Extension Risk Calculation & § Drift Watch for formulas.
Workflow
Phase 1 ─ Automated scanning Collect raw data with tools (Steps 0–14,
│ incl. Step 0.5 .vibe-riskrc + Step 14 ledger re-verify)
Phase 2 ─ Manual analysis Human-level judgment; confirm/discard perf-debt candidates
│
Phase 3 ─ Generate report Fill the mandatory template; emit scorecard.json
│
Phase 4 ─ Persist history Append to .vibe-risk-history.json (v3 schema, with ledger)
│
Phase 5 ─ Remediation prompt P-1 re-adjudication first, then interactive/autonomous
│
Phase 6 ─ Static dependency graph SVG/PNG to .vibe-risk/ (graphviz-free fallback included)
│
Phase 7 ─ Self-evolution reflection E1–E5 checklist; remind user to file a proposal
if (and only if) this run deposited candidates
Phase 1 — Automated scanning
Run a series of automated tools to gather raw data. This is the evidence
foundation — every score in the report traces back to data collected here.
Read references/automated-scanning.md
for the complete step-by-step procedure (Steps 0–14, plus environment-pitfall
warnings: persistent shell cwd, CRLF anchors, multi-layer escaping).
Summary of steps:
| Step | What it does | Key tool |
|---|
| 0 | Detect tech stack, framework, package manager; detect LLM-app signals → activate Dim 13 | Read config files |
| 0.5 | Read .vibe-riskrc.json (vendorGlobs / dataAssetGlobs / generatedGlobs) (v4) | Read config |
| 1 | Class-aware census (source/test/data/vendored/generated) + flow-cost inputs | references/scripts/census.mjs |
| 2 | Circular dependency detection (alias-aware fallback chain) | madge → skott → import-scan |
| 3 | Unused deps & dead code (workspace-aware; skip + no-penalty if unconfigurable) | knip (JS/TS) |
| 4 | Vulnerability audit (mirror registries: explicitly hit the official one) | npm audit / pip-audit / govulncheck |
| 5 | Code duplication | jscpd |
| 6 | Test detection + coverage + denominator audit + critical path coverage | Glob + config read |
| 7 | Framework-specific scan — advisory findings feed only, never a headline score | react-doctor (React/Next.js) |
| 8 | Performance & memory debt — emits candidates (Phase 2 confirms) | Grep patterns |
| 9 | Existing Agent rules & skills inventory | Glob for .cursor/rules, .claude/skills |
| 10 | Score history | Read .vibe-risk-history.json |
| 11 | AI Context Artifact census | Glob for AGENTS.md, ADRs, docs/architecture |
| 12 | Explicit prohibition density | Grep for ❌ / PR-\d+: / "prohibited" |
| 13 | Structural invariant tests | Glob + scan for full-tree static analysis tests |
| 14 | Standing-deduction ledger re-verification (v4) | Run each entry's verify_cmd |
Each step has built-in fallbacks: if a tool fails, score manually from code
sampling and document the failure in the report. Never silently skip a dimension.
Empty-but-green tool results (e.g. madge processing 0 files under TS path
aliases) MUST be reported as vacuous, not as a pass.
Phase 2 — Manual analysis (Full mode only)
Automated tools catch surface-level issues. This phase applies engineering judgment
to assess dimensions that require understanding intent.
-
Pattern consistency sampling: Sample 5–8 files across different directories.
Look for mixed state management, data fetching, async styles, CSS approaches,
and module stacking (duplicate toast/HTTP/date libs).
-
Naming audit: Scan file names and exported symbols for consistent conventions.
-
Architecture review: Examine the top-level directory tree.
-
SRP spot check: Open the 10 largest files. Determine if each handles a single
responsibility or mixes concerns.
-
Type safety & contract check: Search for unannotated any, missing
@param/@returns on exported functions, Redux slices without @typedef,
API routes without request/response schema.
-
Test quality spot check: Sample 2–3 test files. Check for behavioral
assertions vs snapshot-only, edge case coverage, and critical path coverage
(auth / payment / data-mutation).
v4 rule — confirm-or-discard: Step 8 only produces perf-debt
candidates. In this phase, adjudicate each candidate category (sampling is
fine) into confirmed / discarded; only confirmed signals feed the
Refactoring-Risk multiplier. Report both numbers (candidates → confirmed) —
the conversion rate itself is a false-positive-rate signal.
Phase 3 — Generate report
- Read report-template.md — this is mandatory.
- Fill in every section. Never skip a section.
- Consult scoring-reference.md for per-dimension
criteria, the global composition rules, and calibration anchors
(5 anchors; Anchor E "AI-native" — ≥95 is 满级, report it as such).
- All scores must be specific integers, never ranges. Write
10/12, not 8-12/12.
- Every deduction cites its sub-item ID (e.g.
SRP-F2) in the Deductions
tables, carries a kind (policy / debt / disputed), and the full set is
emitted as .vibe-risk/scorecard.json — the machine-readable derivation of
the total. Two agents scoring the same commit MUST produce identical scorecards.
- All problems must reference concrete file paths (and line numbers when available).
- Report language follows the user's language preference.
- Compute both risk metrics (Refactoring Risk + AI Extension Risk); when
health ≥ 90 additionally compute Drift Watch per scoring-reference.
- For HIGH/EXTREME AI Extension Risk, P0 remediation MUST include:
- Create
AGENTS.md if missing
- Add first
.cursor/rules/*.mdc covering top drifting pattern
- Add first structural scan test
- Convert top 3 drifting patterns into grep-verifiable
❌ prohibitions
- For HIGH/EXTREME Refactoring Risk, add strategy recommendations per v2.
- Ledger reconciliation: the report's Section 10 shows the standing-deduction
diff (新增 / 清除(陈旧) / 维持) produced by Step 14 — never re-derive prior
deductions from prose.
Phase 4 — Persist score history
After generating the report, write/update .vibe-risk-history.json in the project
root. v4 uses schema v3 (adds the standing-deduction ledger + rubric marker):
{
"schema_version": 3,
"standing_deductions": [
{
"id": "SD-001",
"dimension": "module_srp",
"sub_item": "SRP-F3",
"points": -2,
"kind": "policy",
"reason": "vendored upstream-fork file (8.8k tokens) locks the >4000 tier",
"clearing_condition": "upstream upgrade, or the project's divergence-registry policy changes to allow splitting",
"verify_cmd": "node references/scripts/census.mjs --file <path/to/vendored-file>",
"registered": "2026-06-09",
"last_verified": "2026-06-10"
}
],
"scans": [
{
"date": "2026-04-23T12:00:00Z",
"mode": "full",
"skill_version": "4.0.0",
"rubric": "v4",
"total": 58,
"level": "MODERATE",
"total_loc": 24350,
"total_files": 187,
"project_scale": "MEDIUM",
"refactoring_risk": 53,
"refactoring_risk_level": "MODERATE",
"ai_extension_risk": 71,
"ai_extension_risk_level": "HIGH",
"drift_watch": null,
"perf_debt_confirmed": 9,
"perf_debt_candidates": 21,
"prohibition_count": 4,
"context_artifact_score": 5,
"ai_app_surface_active": false,
"scorecard": ".vibe-risk/scorecard.json",
"dimensions": {
"module_srp": 10,
"pattern_consistency": 8,
"type_safety_contracts": 6,
"test_coverage_invariants": 4,
"ai_context_artifacts": 5,
"architecture": 6,
"dependency_health": 5,
"prohibition_density": 2,
"naming": 4,
"duplication": 3,
"determinism": 2,
"security_tooling": 3,
"ai_app_surface": null
},
"top_issues": ["2x 2200-token god files", "no AGENTS.md", "0 scan tests"]
}
]
}
Ledger maintenance rules: Step 14 updates last_verified per entry; cleared
(陈旧) entries are removed from standing_deductions and logged in that scan's
top_issues/report diff — the ledger never grows stale silently. kind: policy
entries are the project's registered ceilings; kind: debt are expected to clear;
kind: disputed are borderline calls awaiting the next scan's re-read.
Backwards compatibility: v1 → migrate dimension names and bump to 2 (as in
v3.x). v2 → bump schema_version to 3, add empty standing_deductions, and
seed the ledger from the most recent entry's top_issues/scope_note
(each seeded entry gets kind: "disputed" until first verified). Old entries
keep rubric: "v3" implicitly (absent field = v3); v4-rubric scores are not
directly comparable — note the baseline reset in the report's first v4 scan.
Append each scan. Never overwrite previous entries. Recommend adding
.vibe-risk-history.json to version control for team visibility.
Phase 5 — Generate remediation prompt
Generate a ready-to-copy remediation prompt (Report Section 11).
- Read remediation-prompt.md — single source of truth
for the prompt template, behavior rules, and placeholder reference. Both
templates begin with a mandatory P-1 re-adjudication stage: before fixing
anything, every TODO inherited from a prior report/ledger is re-verified
(run its
verify_cmd or a minimal probe); stale findings are skipped and
logged — never "fix" a phantom problem.
- Choose mode (v3 new):
interactive (default for human users) — AI presents plan, waits for
confirmation at each TODO.autonomous — AI executes P0→P1→P2 sequentially with self-review gates,
without per-step confirmation. Use when the user is a cloud agent, CI, or
when explicitly requested.
- Replace all
{placeholders} with actual data from this scan.
- Output the filled prompt inside a fenced code block for one-click copy.
- The prompt language matches the user's preference.
Phase 6 — Static dependency graph
A text report tells you what is wrong. A dependency graph shows you where the
structural problems live and how they connect.
v3 change: Default output is now a static SVG/PNG saved to a
project-relative .vibe-risk/dependency-graph.svg (cross-platform: Windows,
macOS, Linux, cloud), suitable for cloud agents / CI / PR attachments. On a
cloud agent with a dedicated artifacts mount you may override to that absolute
path (e.g. /opt/cursor/artifacts/). Interactive localhost mode is still
available with --interactive.
Read references/visualization-guide.md
for setup, commands, and interpretation.
Quick start (static, default):
mkdir -p .vibe-risk
npx madge --image .vibe-risk/dependency-graph.svg --extensions js,ts,jsx,tsx src/
graphviz 缺失时（v4 内置兜底,常见于 Windows/cloud）：不要放弃静态图——用
自带脚本生成目录级聚合 SVG（实测比 150 节点的逐文件图更可读）：
node <skill>/references/scripts/graph-fallback.mjs --root src --out .vibe-risk/dependency-graph.svg
Quick start (interactive, opt-in):
npx skott --displayMode=webapp --trackThirdPartyDependencies --cwd=src
Visual patterns map to scan findings:
- God files → high fan-in + fan-out nodes
- Circular dependencies → highlighted cycles
- Dead code → orphan nodes with no incoming edges
- Architecture violations → cross-layer arrows
- Refactoring order → leaf nodes first, hub nodes last
In Full mode, always attempt to generate the static graph (non-interactive).
Offer interactive mode only when the user is local and requests it.
Phase 7 — Self-evolution reflection (v4.1)
At the end of every scan (and of any remediation driven by this skill), run the
E1–E5 checklist in SELF-EVOLUTION.md: did this run expose
a rule misfire, an uncaught tool break, a risk no dimension can hold, threshold
calibration evidence, or an improvised workaround that would be needed again?
Deposits go to the bounded candidate registry; if any exist, append the fixed-format
🧬 进化候选 reminder to the final summary and ask the user whether to file a
proposal. The skill never silently modifies itself — every change goes through
a user-approved proposal that passes CHANGE-GATE.md. Zero
deposits → zero output (don't nag).
Monorepo support
If the project root contains pnpm-workspace.yaml, lerna.json, turbo.json,
nx.json, or package.json with workspaces (or de-facto multi-package layout
like a nested app with its own lockfile):
- List all packages/apps in the workspace.
- Ask the user: scan a specific package, or scan all?
- If scanning all (v4 default semantics): score each package independently
and keep one history file + one scorecard per package (e.g.
<repo>/.vibe-risk-history.json + <repo>/<package>/.vibe-risk-history.json)
— a weighted average hides single-package regressions, so it is at most an
optional summary row. The report uses the side-by-side multi-column variant
of the template (one column per package).
- If scanning one: treat that package as the project root.
Agent Rules & Skills recommendation matrix
After scoring, cross-reference findings with the project's existing AI configuration.
| Project Signal | Missing Config | Recommend | Priority |
|---|
No AGENTS.md at all (v3) | Missing primary briefing | [DOC] AGENTS.md with dev env + conventions | MUST |
| Dim 8 (Prohibition Density) score ≤ 2 | No grep-verifiable fence | [RULE] <domain>-guardrails.mdc with PR-NNN pattern | MUST |
| Dim 4 structural invariants = 0 | No scan tests | [TEST] src/lib/__tests__/<topic>-safety.test.js | MUST |
| Pattern drift detected | No code-conventions rule | [RULE] code-conventions | MUST |
| Uses i18n | No i18n rule | [RULE] i18n-guardrails | MUST |
| React/Next.js project | No react-doctor skill | [SKILL] react-doctor | RECOMMENDED |
| No commit convention | No pr-commit skill | [SKILL] pr-commit | RECOMMENDED |
| Has tests but no sync guard | No test-guardian skill | [SKILL] test-guardian | RECOMMENDED |
| Inconsistent naming | No naming rule | [RULE] naming-conventions | RECOMMENDED |
| Blurred architecture boundaries | No architecture rule | [RULE] architecture-boundaries | MUST |
| TS strict off / any abuse | No type-safety rule | [RULE] type-safety | MUST (v3: elevated) |
| No tests at all | No test skill/rule | [SKILL] test-guardian | MUST |
| No periodic audit | Not scheduled | [SKILL] vibe-risk-analyzer | RECOMMENDED |
| LLM app, prompt changes untested (v4) | No prompt-change gate | [RULE] prompt-change-guard + `[TEST] golden/eval per prompt asset | MUST |
| LLM app, SSE/stream paths untested (v4) | No stream-error fence | [TEST] sse-error-path spec（错误帧/心跳/abort 贯通） | MUST |
| Vendored agent-CLI fork present (v4) | No divergence registry | [DOC] provider-divergence-registry（每条差异 = 双方行为对照 + 分叉理由 + 验证方式） | MUST |
Each recommendation includes: type tag, name, priority, trigger finding,
description, and a 3-5 line content skeleton so the user can create it immediately.
Recommended tools
Read references/tools-matrix.md for the full
recommended tools list organized by ecosystem (JS/TS, Python, Go).
Only recommend tools the project does NOT already have.
Rules
- Read report-template.md before generating output. The template is the contract.
- Never output a partial report. Every section must be filled.
- Scores are integers, never ranges, and must be derivable. Every deduction
cites a sub-item ID; the dimension total follows the composition formula in
scoring-reference.md;
scorecard.json is emitted alongside the report.
No "lenient" judgment calls — borderline cases take the lower tier per
formula and are registered in the ledger as kind: disputed.
- Problems cite files. Every issue references at least one file path.
- Tool failures are documented, not hidden — and vacuous passes too. If a
tool fails, state why and score manually from code sampling; if a tool ran
but processed 0 relevant files (alias-blind madge, unconfigured knip), say
"vacuous" explicitly and use the fallback chain.
- Respect project type. Adapt dimensions to the detected stack. Pure JS
projects: score contracts via JSDoc coverage instead of TS coverage. Python:
skip React-specific checks but apply Python equivalents.
ui_heavy projects
get the coverage profile in scoring-reference § Dim 4. LLM applications
activate Dim 13.
- First-party code only in thresholds.
vendorGlobs / dataAssetGlobs /
generatedGlobs from .vibe-riskrc.json are excluded from size/duplication
thresholds and reported in their own "third-party-in-tree" section. Absent
config = whole tree is first-party (backward compatible).
- Report language matches user preference.
- Always persist history using v3 schema (with standing-deduction ledger).
Migrate v1/v2 files in place on first encounter; seed the ledger from the
latest entry's prose as
disputed.
- Monorepo: ask before scanning; per-package trend lines by default.
Never silently scan only one package; never let a weighted average mask a
single-package regression.
- Always generate remediation prompt. Section 11 is mandatory in Full mode.
Both modes start with the P-1 re-adjudication stage. Default
interactive
for humans, autonomous for cloud agents.
- Always generate static dependency graph in Full mode (graphviz-free
fallback when needed). Offer interactive graph only when running locally.
- Report both risk metrics; at health ≥ 90 add Drift Watch; at total ≥ 95
report "AI-native 满级" instead of distance-to-100.
- Ledger is the memory. Standing deductions live in the ledger, are
re-verified every scan (Step 14), and cleared entries are announced — prior
findings are never trusted from prose alone.
- Self-evolution is human-gated. Run the Phase 7 reflection after every
scan/remediation; deposits only ever become changes via a user-approved
proposal. Never edit this skill's normative files during a run
(see SELF-EVOLUTION.md hard boundaries).
- Every skill modification passes the change gate. Real-value evidence,
project-agnostic normative text, anti-bloat budgets, verifiability, and the
proposal checklist in CHANGE-GATE.md — applies to all files including the
gate itself. An edit that fails any gate is not made.
Reference files
