跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

code-cleanup-audit

Audit a repository for architectural decay, AI-generated code smells, stale compatibility paths, dead abstractions, boundary violations, and cleanup candidates without modifying files. Use when the user asks to review code quality, find bad code, inspect AI-generated code, identify refactoring or cleanup opportunities, detect legacy leftovers, or produce a cleanup backlog that requires human confirmation before implementation.

pqpo · 已有静态检查记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add pqpo/pragma --skill code-cleanup-audit

技能说明


name: code-cleanup-audit description: Audit a repository for architectural decay, AI-generated code smells, stale compatibility paths, dead abstractions, boundary violations, and cleanup candidates without modifying files. Use when the user asks to review code quality, find bad code, inspect AI-generated code, identify refactoring or cleanup opportunities, detect legacy leftovers, or produce a cleanup backlog that requires human confirmation before implementation.

Code Cleanup Audit

Overview

Use this skill to produce an evidence-backed cleanup audit only. The output is a backlog of suspected or confirmed problems for human review, not an implementation plan that silently edits code.

Non-Negotiable Guardrails

  • Do not modify files.
  • Do not call apply_patch, formatters with write mode, generators, codemods, install commands, migration commands, or any command whose purpose is to change the workspace.
  • Do not create branches, commits, pull requests, or issue tickets unless the user explicitly asks after reviewing the audit.
  • If the user asks for fixes before seeing the audit, first produce findings and ask which items to implement.
  • If a command unexpectedly changes files, stop, report the changed paths, and ask how to proceed.
  • Preserve unrelated dirty worktree changes; treat them as user-owned.

Audit Workflow

  1. Establish repository context:

    • Read AGENTS.md first.
    • Read architecture and convention docs that directly govern the touched codebase, especially dependency boundaries, ADRs, and package conventions.
    • Run git status --short and note existing dirty files.
    • Inventory apps/packages with read-only commands such as find, rg --files, pnpm -r list --depth -1, and package manifest reads.
  2. Build a map before judging:

    • Identify package boundaries, public exports, app entry points, runtime adapters, shared schemas, tests, and docs.
    • Trace imports through package names, not only filenames.
    • Compare implementation structure against documented allowed dependencies.
    • Prefer rg over slower search tools.
  3. Inspect for cleanup categories:

    • Architecture violations: forbidden imports, cross-package relative imports, app-layer logic in shared packages, runtime-specific code in core/shared, browser-unsafe code in web/client/shared.
    • Stale compatibility: deprecated fields, fallback branches, migration shims, legacy aliases, duplicate old/new APIs, TODOs that preserve obsolete behavior, no-op adapters, unused feature flags.
    • AI-generated code smells: over-broad abstractions, fake extensibility, duplicated helpers, inconsistent naming, hand-rolled utilities where a project utility exists, speculative layers, uncalled code, verbose comments explaining obvious code, guessed data shapes.
    • Type and schema weakness: any, unsafe casts, unchecked unknown, interfaces where runtime validation is required, schema/type drift, missing boundary parsing.
    • Error and runtime behavior smells: swallowed errors, broad catch, impossible states represented as optional fields, missing cancellation/timeout handling, fragile env assumptions.
    • Test and validation gaps: core behavior without tests, snapshots masking behavior, tests that only assert mocks, missing negative cases for boundary rules.
    • Documentation drift: docs or AGENTS rules contradicted by code, public API exports not reflected in docs, stale startup/quality commands.
  4. Validate suspected issues:

    • Read surrounding code and tests before reporting.
    • Run read-only validation where useful: pnpm lint, pnpm typecheck, pnpm test, focused Vitest commands, pnpm build only when build behavior is relevant.
    • Use existing ESLint boundary rules as evidence when available.
    • Distinguish confirmed problems from cleanup candidates that need product or architectural judgment.
  5. Report without fixing:

    • Lead with findings ordered by severity.
    • Include file path and line or precise code location for each finding.
    • State the violated rule or smell, why it matters, evidence, confidence, and suggested cleanup direction.
    • Mark every item as one of: confirmed, likely, or needs human decision.
    • Include "Do not modify until confirmed" language when handing off.

Severity Standard

  • Critical: Can break runtime behavior, violate security/privacy boundaries, corrupt data, or cause CI/build failure.
  • High: Violates documented architecture, creates wrong package dependency direction, or preserves misleading/dead public API that future agents will copy.
  • Medium: Increases maintenance cost through duplication, stale compatibility, weak validation, or untested shared behavior.
  • Low: Local readability or consistency issue with limited blast radius.

Do not report pure preference, cosmetic style, or speculative rewrites unless tied to a concrete maintenance, correctness, boundary, or future-agent-copying risk.

Recommended Commands

Use commands like these as applicable. Keep them read-only.

git status --short
find apps packages docs -maxdepth 3 -type f | sort
rg --line-number "TODO|FIXME|deprecated|legacy|compat|shim|fallback|no-op|noop|any\\b|as unknown|as any" apps packages docs
rg --line-number "from ['\"]\\.\\./\\.\\./|from ['\"]\\.\\./\\.\\./\\.\\./|@pragma/(client|server|core|runtime)" apps packages
pnpm -r list --depth -1
pnpm lint
pnpm typecheck
pnpm test

Before running expensive repository-wide commands, prefer focused reads and explain why the command is useful.

Output Format

Return:

  1. Findings

    • Severity
    • Status: confirmed, likely, or needs human decision
    • Location
    • Problem
    • Evidence
    • Cleanup direction, without editing code
  2. Cleanup backlog

    • Group related findings into reviewable batches.
    • Call out which batches are safe mechanical cleanup versus architecture decisions.
  3. Non-findings and constraints

    • Mention important suspected issues that
阅读完整来源 ↗