audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Audit Skill

代码审计Skill

Purpose

目标

Perform a thorough, language-agnostic audit of a codebase or subset of files, producing a structured report with findings ranked by severity. Deliver the report as a Markdown file at the project root following the template in

references/report-template.md

对代码库或部分文件进行全面的、与语言无关的审计，生成按严重程度排序的结构化报告。按照

references/report-template.md

中的模板，将报告以Markdown文件形式交付到项目根目录。

Effort Level

工作强度要求

Read every line of in-scope code. Do not skim, sample, or rely on heuristics to skip files. Trace data flows from external inputs through processing layers to outputs and storage. Follow call chains across module boundaries to detect issues that only manifest through component interaction. When the scope is too large for a single pass, split work across parallel subagents (see Step 4 for partitioning strategy).

阅读所有范围内的代码行，不得略读、抽样或依靠启发式方法跳过文件。追踪从外部输入经过处理层到输出和存储的数据流。跨模块边界跟踪调用链，以检测仅通过组件交互才会显现的问题。当范围过大无法一次完成时，将工作分配给并行的子Agent处理（分区策略详见步骤4）。

Workflow

工作流程

Step 1 — Resolve Scope

步骤1 — 确定审计范围

Determine the audit scope from the user's prompt. The user may specify:

An entire repository or working directory.
One or more directories (e.g.,
```
src/
```
,
```
lib/api/
```
).
A list of specific files.
A functional area described in natural language (e.g., "the authentication flow").
A specific function, class, or code region within a file. In this case, restrict analysis to the specified code and its immediate dependencies — do not audit the entire file.

If the user specifies files or directories that do not exist, warn them about the missing paths and proceed with the files that do exist. If none of the specified paths exist, stop and ask for clarification.

If the prompt does not contain enough information to determine scope, ask a single clarifying question before proceeding. Do not guess at scope — an audit with unclear boundaries produces unreliable results.

If a previous audit report exists in the project and the user requests a re-audit, default to the same scope as the original audit. Offer to narrow to only files with prior findings if the user wants a faster pass, but do not narrow silently — new issues can appear in files that were previously clean. When a prior report exists, note in the new report which previous findings have been resolved and which persist, so the user gets a delta view.

Once scope is established, enumerate all files that fall within it. Exclude generated files (e.g., lock files, compiled output, vendored dependencies, minified bundles) unless the user explicitly includes them. For source-committed generated code (protobuf stubs, OpenAPI clients, ORM models), check for modification markers — if files contain hand-written additions or a "DO NOT EDIT" header has been removed, treat them as in-scope. While generated and vendored code is excluded from file-level analysis, cross-file analysis in Phase B should trace data flows into excluded code to determine whether it provides expected validation or safety guarantees. Report findings at the boundary, not within the excluded code.

State the resolved scope back to the user. If the scope is unambiguous, proceed immediately without waiting for confirmation.

根据用户的提示确定审计范围。用户可能会指定：

整个仓库或工作目录。
一个或多个目录（如
```
src/
```
、
```
lib/api/
```
）。
特定文件列表。
用自然语言描述的功能区域（如“认证流程”）。
文件内的特定函数、类或代码区域。在这种情况下，分析应限制在指定代码及其直接依赖项内，不得审计整个文件。

如果用户指定的文件或目录不存在，需告知用户缺失的路径，并继续处理存在的文件。如果指定的路径均不存在，则停止操作并请求用户澄清。

如果提示中没有足够的信息来确定范围，需先提出一个明确的问题再继续，不得猜测范围——边界不清晰的审计会产生不可靠的结果。

如果项目中存在之前的审计报告，且用户要求重新审计，则默认使用与原审计相同的范围。如果用户希望更快完成，可提供仅针对之前有问题的文件进行审计的选项，但不得擅自缩小范围——之前无问题的文件也可能出现新问题。当存在原报告时，需在新报告中注明哪些之前的问题已解决、哪些仍存在，以便用户查看差异。

确定范围后，列出所有符合范围的文件。排除生成文件（如锁文件、编译输出、第三方依赖包、压缩包），除非用户明确要求包含。对于源码提交的生成代码（protobuf桩代码、OpenAPI客户端、ORM模型），需检查修改标记——如果文件包含手写内容或“DO NOT EDIT”头已被移除，则将其纳入审计范围。虽然生成文件和第三方依赖包不纳入文件级分析，但在阶段B的跨文件分析中，需追踪数据流进入这些排除的代码，以确认其是否提供了预期的验证或安全保障。需在边界处报告问题，而非在排除的代码内部。

需向用户反馈确定后的范围。如果范围明确，可立即继续操作，无需等待确认。

Step 2 — Select and Confirm Categories

步骤2 — 选择并确认审计类别

Analyze the user's request and the codebase to select the most relevant audit categories from the full list:

Security vulnerabilities
Race conditions and concurrency
Dead code
Anti-patterns and code smells
Performance
Correctness
Error handling gaps
Test quality

Consider both what the user explicitly asked for and what the code naturally warrants. For example, if the codebase uses async patterns, include the concurrency category even if the user didn't mention it.

For broad requests ("audit this codebase"), default to all categories and proceed without asking for confirmation. Only present the selected categories and ask for confirmation when the selection is non-obvious — when the agent has chosen a subset based on code analysis, or when the user's request is ambiguous about which categories apply.

Use the checklists in

references/categories.md

as the basis for systematic analysis. Skip individual checklist items that do not apply to the languages, frameworks, or paradigms present in the codebase. If the codebase contains no test files, report a single finding noting the absence of tests rather than evaluating individual Test Quality checklist items.

分析用户的请求和代码库，从完整列表中选择最相关的审计类别：

安全漏洞
竞态条件与并发问题
死代码
反模式与代码坏味道
性能问题
正确性
错误处理缺失
测试质量

需同时考虑用户明确提出的需求和代码本身的特点。例如，如果代码库使用异步模式，即使用户未提及，也需包含并发类别。

对于宽泛的请求（如“审核此代码库”），默认选择所有类别并直接继续，无需确认。仅当选择非显而易见时——即Agent根据代码分析选择了子集，或用户的请求对适用类别不明确时——才需向用户展示所选类别并请求确认。

以

references/categories.md

中的检查清单为基础进行系统性分析。跳过不适用于代码库所用语言、框架或范式的检查项。如果代码库中没有测试文件，需报告一个单独的结果，说明缺少测试，而非评估测试质量的单个检查项。

Step 3 — Discover Intent

步骤3 — 挖掘设计意图

Scan the codebase for documented intent — design decisions, trade-offs, conventions, known limitations — before analysis begins. This reduces false positives by providing context that distinguishes deliberate choices from genuine issues.

Run three subagents in parallel:

Documentation Scanner — reads all documentation files project-wide (regardless of audit scope) and extracts stated decisions, trade-offs, constraints, and conventions.
Code Intent Scanner — searches in-scope source files for rationale comments, suppression directives, and explanatory block comments that express the "why" behind code choices.
History Scanner — extracts intent signals from git commit history for in-scope files, focusing on commits whose messages explain why a change was made.

This step always executes regardless of codebase size. For large codebases that use the partitioned strategy in Step 4, the same Intent Brief is shared with all partition subagents.

The output is a structured Intent Brief organized by theme (Architectural Decisions, Deliberate Trade-offs, Conventions & Standards, Known Limitations & Technical Debt, Suppressed Warnings & Intentional Deviations) — not by source type. Target no more than 100 entries, prioritized by relevance to the confirmed audit categories.

If intent discovery produces no entries, the Intent Brief is empty. Analysis proceeds normally without cross-referencing, and the report's "Context & Intent" section states that no documented intent signals were identified.

See

references/intent-discovery.md

for detailed subagent prompts, extraction rules, and the Intent Brief template.

在开始分析前，扫描代码库中的文档化意图——设计决策、权衡、约定、已知限制。这能通过提供区分故意选择与真正问题的上下文，减少误报。

并行运行三个子Agent：

文档扫描器 — 读取项目中所有文档文件（无论是否在审计范围内），提取明确的决策、权衡、约束和约定。
代码意图扫描器 — 在范围内的源文件中搜索原理注释、抑制指令和解释性块注释，以了解代码选择背后的“原因”。
历史扫描器 — 从范围内文件的git提交历史中提取意图信号，重点关注提交信息中解释修改原因的提交。

无论代码库大小，此步骤均需执行。对于在步骤4中使用分区策略的大型代码库，所有分区子Agent将共享同一个意图简报。

输出结果为按主题（架构决策、故意权衡、约定与标准、已知限制与技术债务、抑制警告与故意偏离）组织的结构化意图简报，而非按来源类型组织。目标条目不超过100条，按与已确认审计类别的相关性排序。

如果挖掘意图未产生任何条目，则意图简报为空。分析将正常进行，无需交叉引用，且报告的“上下文与意图”部分需说明未识别到任何文档化意图信号。

有关子Agent提示、提取规则和意图简报模板的详细信息，请参阅

references/intent-discovery.md

。

Step 4 — Systematic Analysis

步骤4 — 系统性分析

Large Codebase Partitioning

大型代码库分区策略

When the scope exceeds either 50 files or 10,000 lines of code (whichever is reached first), use parallel subagents to avoid superficial analysis:

Partition the scope into logical modules or directory subtrees. Aim for partitions of roughly equal size. In monorepos with multiple independent services, partition by service first — service boundaries take precedence over layer boundaries. Within a single service, prefer boundaries that align with architectural layers (e.g., data access, business logic, API handlers) rather than arbitrary file count splits.
Assign one subagent per partition. Each subagent performs Phase A (file-level analysis) on its partition independently, following the same checklist and recording format. Provide each subagent with a brief description of the overall codebase architecture, the Intent Brief from Step 3, and the applicable checklists.
After all subagents complete, perform Phase B (cross-file analysis) on the merged set of findings, focusing on interactions between partitions. Pay special attention to trust boundaries — data flowing from one partition to another is a common source of missed validation and injection vulnerabilities.
Deduplicate findings that were independently discovered by multiple subagents operating on shared or overlapping code. Consolidate into the highest-severity version and list all affected locations.

If subagents are not available or the scope is small enough, perform all phases sequentially as a single agent. When even partitioned analysis cannot cover every line, prioritize depth on security-critical and correctness-critical paths: entry points, authentication/authorization flows, data persistence, and external API boundaries.

当范围超过50个文件或10000行代码（以先达到的为准）时，使用并行子Agent避免表面化分析：

将范围划分为逻辑模块或目录子树。尽量使每个分区的大小大致相等。对于包含多个独立服务的单体仓库，优先按服务分区——服务边界优先于层级边界。在单个服务内，优先选择与架构层级（如数据访问、业务逻辑、API处理程序）一致的边界，而非按任意文件数量拆分。
为每个分区分配一个子Agent。每个子Agent独立对其分区执行阶段A（文件级分析），遵循相同的检查清单和记录格式。需向每个子Agent提供代码库整体架构的简要说明、步骤3中的意图简报以及适用的检查清单。
所有子Agent完成后，对合并后的结果执行阶段B（跨文件分析），重点关注分区之间的交互。需特别注意信任边界——在分区之间流动的数据是遗漏验证和注入漏洞的常见来源。
对多个子Agent在共享或重叠代码中独立发现的结果进行去重。合并为最高严重程度的版本，并列出所有受影响的位置。

如果无法使用子Agent或范围足够小，则由单个Agent按顺序执行所有阶段。当即使分区分析也无法覆盖每一行代码时，优先深入分析安全关键和正确性关键路径：入口点、认证/授权流程、数据持久化和外部API边界。

Phase A — File-Level Analysis

阶段A — 文件级分析

Iterate through every in-scope file. For each file:

Read the file in full. Do not skim or sample.
Walk through each checklist item from the confirmed categories, evaluating whether the code under inspection exhibits the described issue.
Before recording a finding, cross-reference it against the Intent Brief. Skip when the brief directly and explicitly addresses the exact pattern flagged at the exact location. Downgrade (report at reduced severity with a note citing the intent source) when the brief provides general context but not per-instance acknowledgment.
Record each finding immediately with its file path, line number, category, a preliminary severity (per
```
references/severity-guide.md
```
), a description of the problem, its impact, and a concrete recommendation.
When a finding involves a data flow or call chain that exits the current file, mark it for cross-file follow-up in Phase B.

Avoid recording the same logical issue multiple times when it appears in multiple files due to shared patterns (e.g., a utility function used everywhere). Instead, record it once and note all affected locations.

遍历所有范围内的文件。对于每个文件：

完整读取文件，不得略读或抽样。
对照已确认类别的每个检查项，评估被检查代码是否存在所述问题。
在记录结果前，需与意图简报进行交叉引用。如果简报直接且明确地说明了标记位置的确切模式，则跳过该结果。如果简报提供了一般上下文但未确认具体实例，则降低严重程度（在报告中注明引用的意图来源）。
立即记录每个结果，包括文件路径、行号、类别、初步严重程度（按
```
references/severity-guide.md
```
）、问题描述、影响以及具体建议。
当结果涉及数据流或调用链超出当前文件时，需标记为阶段B中跨文件跟进的项。

当同一逻辑问题因共享模式出现在多个文件中时（如随处使用的工具函数），不得多次记录，而应记录一次并注明所有受影响的位置。

Phase B — Cross-File Analysis

阶段B — 跨文件分析

After completing the file-level pass, revisit findings marked for cross-file follow-up:

Trace data from entry points (HTTP handlers, CLI parsers, message consumers, public API surfaces) through intermediate layers to terminal operations (database writes, file I/O, external API calls, responses to users).
Evaluate whether input validation, authorization, error handling, or resource cleanup is missing at any point along the traced path, even if each individual file appears correct in isolation.
Check for architectural issues: circular dependencies between modules, inconsistent error handling strategies across layers, mixed paradigms that introduce subtle bugs, and shared mutable state accessed from multiple modules.
Cross-reference new cross-file findings against the Intent Brief using the same skip/downgrade rules as Phase A.

Record any new findings and update severity assessments for file-level findings that turn out to be more or less severe in the broader context.

完成文件级分析后，重新查看标记为跨文件跟进的结果：

追踪数据从入口点（HTTP处理程序、CLI解析器、消息消费者、公共API接口）经过中间层到终端操作（数据库写入、文件I/O、外部API调用、向用户返回响应）的流动。
评估在追踪路径的任何点是否缺少输入验证、授权、错误处理或资源清理，即使每个单独的文件看起来没有问题。
检查架构问题：模块之间的循环依赖、各层之间不一致的错误处理策略、引入细微bug的混合范式、以及从多个模块访问的共享可变状态。
使用与阶段A相同的跳过/降级规则，将新的跨文件结果与意图简报进行交叉引用。

记录任何新的结果，并更新文件级结果的严重程度评估——这些结果在更广泛的上下文中可能变得更严重或更轻微。

Deduplication

去重

Before moving to report generation, deduplicate findings:

Merge findings that describe the same root cause manifesting in multiple locations into a single finding. List all affected locations in that finding.
Remove false positives identified during cross-file analysis (e.g., input that appeared unvalidated in one file but is validated by a middleware layer discovered later).
Consolidate findings that stem from the same documented trade-off in the Intent Brief into a single finding referencing the intent entry and listing all affected locations.
Reconcile conflicting severity assessments by considering the worst realistic impact.

在生成报告前，对结果进行去重：

将描述同一根本原因但出现在多个位置的结果合并为一个，并列出所有受影响的位置。
移除跨文件分析中识别的误报（如在一个文件中看似未验证的输入，实际在中间件层已验证）。
将源于意图简报中同一文档化权衡的结果合并为一个，引用意图条目并列出所有受影响的位置。
通过考虑最现实的影响，协调冲突的严重程度评估。

Step 5 — Report Generation

步骤5 — 报告生成

Generate the final report following the structure and formatting rules defined in

references/report-template.md

. Specifically:

Set the report date to the current date.
Populate the summary table with the resolved scope, confirmed categories, and finding counts by severity.
Include a "Context & Intent" section between the Summary table and the Critical severity section. This section summarizes the Intent Brief and lists key documented decisions that influenced the audit.
Assign sequential
```
AUDIT-NNN
```
identifiers starting at
```
AUDIT-001
```
. Order findings by severity (Critical first), then by category, then by file path within the same severity and category.
Write each finding with all required fields: identifier, short title, category, location (
```
file:line
```
), severity, description, impact, and recommendation.
Save the report at the project root using the filename convention in the template (
```
AUDIT-REPORT-YYYY-MM-DD.md
```
), incrementing the suffix if a file with that name already exists.

After saving the report, state the file path and a brief summary of the results to the user.

按照

references/report-template.md

中定义的结构和格式规则生成最终报告。具体要求：

将报告日期设置为当前日期。
在摘要表中填入确定的范围、已确认的类别以及按严重程度划分的结果数量。
在摘要表和严重级别为“Critical”的部分之间添加“上下文与意图”部分。此部分总结意图简报，并列出影响审计的关键文档化决策。
从
```
AUDIT-001
```
开始分配连续的
```
AUDIT-NNN
```
标识符。结果按严重程度排序（Critical优先），然后按类别排序，同一严重程度和类别内按文件路径排序。
每个结果需包含所有必填字段：标识符、简短标题、类别、位置（
```
file:line
```
）、严重程度、问题描述、影响以及建议。
按照模板中的文件名约定（
```
AUDIT-REPORT-YYYY-MM-DD.md
```
）将报告保存到项目根目录，如果该名称的文件已存在，则递增后缀。

保存报告后，需向用户告知文件路径和结果的简要总结。