code-analyzer

code-analyzer

用途

为用户清晰、按优先级呈现项目的健康状况：哪些地方存在问题、有哪些风险、哪些地方杂乱、缺少什么，以及可以添加什么。输出是一份结构化报告，而不是一堆猜测。每条发现都指向一个真实文件，用通俗的语言说明问题，并提出改进方向。

这是一项诊断技能，不是重构技能。审计过程中唯一允许写入的内容是报告文件本身——不要编辑代码、运行格式化工具，也不要在审计过程中提交任何内容。只有用户阅读报告并明确选择要修复的问题后，才能更改代码。

适用场景

• 用户要求审查项目、执行审计、检查代码质量，或笼统地询问“这份代码库有什么问题”
• 用户询问整个项目中的安全问题、漏洞或加固措施
• 用户询问“有什么可以改进”或“接下来应该做什么”
• 用户希望根据现有项目提出新功能构想
• 匈牙利语对应说法：“nézd át”、“auditáld”、“találj hibákat”、“javasolj fejlesztéseket”

如果用户有明确的 Bug 或功能需求（“修复这个崩溃问题”、“添加这个端点”），则不属于此技能的适用范围——直接处理即可。

前置条件

开始前，请确认基本情况：

1. 位于项目目录中

git rev-parse --show-toplevel 2>/dev/null || pwd

最好是 Git 仓库（这样可以阅读近期历史记录以了解上下文），但这不是必需的。记录项目根目录，并在报告的所有路径中以此为基准。

2. 工作树状态

git status --porcelain 2>/dev/null

存在未提交的更改不影响审计——你不会修改任何内容。只需留意用户可能正在处理中；如果发现中途修改的文件出现在审计结果中，应标明，以便用户判断问题是由其当前工作引起，还是原本就存在。

工作流

步骤 1：确定审计范围

整个项目的审计范围没有明确边界。在阅读任何代码之前，先从以下三个维度确定工作范围：

• 重点：涵盖所有维度，还是仅关注一个方面（安全 / 质量 / 性能 / 测试 / 文档 / 构想）？
• 范围：整个仓库、某个子目录，还是一组已更改的文件？对于非常大的仓库（源文件超过约 1000 个），应明确抽样——优先检查修改最多、体积最大或最核心的模块，而不是生成一份范围宽泛但浅尝辄止、遗漏实际问题的报告。
• 限制条件：有哪些内容需要跳过（生成的代码、供应商依赖、计划删除的旧模块、第三方 SDK）？

交互式使用（有人参与）：如果已传入重点参数，就按该参数执行；否则，用一条简短消息说明默认计划，然后继续，除非用户提出异议。不要把这变成冗长的访谈——用户想要的是发现的问题，而不是启动会议。

非交互式使用（没有人可供询问——在自动化、评估或流水线中运行）：采用合理的默认设置（整个仓库、所有维度、标准忽略项），并在报告的执行摘要中写明范围决策，而不是提问。绝不要停下来等待输入。

第 2 步：了解项目

在评判项目之前，先在脑中建立对它的整体认识。尽可能并行收集以下信息：

• 语言和规模：统计每种语言的文件数和大致行数。使用 git ls-files（或 find）配合 wc -l 即可。
• 包 / 构建清单文件：package.json、pyproject.toml、requirements*.txt、Cargo.toml、go.mod、pubspec.yaml、Gemfile、pom.xml、build.gradle*、composer.json 等。这些文件能告诉你项目使用的框架、运行时版本和依赖项。
• 现有工具：代码检查器、类型检查器、格式化工具、安全扫描器、测试运行器——查看配置文件（.eslintrc*、ruff.toml、tsconfig.json、pytest.ini、.golangci.yml、analysis_options.yaml 等）和 CI 工作流（.github/workflows/、.gitlab-ci.yml、Makefile）。
• 入口点和结构：main.*、index.*、顶层目录（src/、lib/、app/、cmd/）。
• 文档：README*、CONTRIBUTING*、docs/、CHANGELOG*。快速浏览即可，不必通读。
• 近期活动：运行 git log --since="3 months ago" --pretty=oneline | head -50，查看热点和开发意图。

了解已配置的工具很重要：如果项目已在 CI 中运行 ruff 和 mypy，再挑出重复的风格问题只会增加噪声。报告应优先关注现有流水线未能发现的问题。

除非用户另有要求，默认跳过以下内容：node_modules/、.git/、dist/、build/、target/、vendor/、.next/、__pycache__/、.venv/、生成的代码、锁文件。这些内容会淹没有用信息。

第 3 步：让现有工具处理繁琐工作

在自己阅读代码之前，先运行项目已配置的工具并记录输出。这更快、更可靠，也能提供大家都信任的信号。有关各技术栈的命令（JS/TS、Python、Go、Rust、Dart/Flutter、Kotlin/Gradle、Swift、C/C++ 等）、密钥扫描模式，以及值得避免的副作用命令，请参阅 references/tooling.md。

如果未安装某个工具，请在报告中注明“运行 <tool> 可以发现此处的更多问题”，然后继续（参见“关键约束——不得自动安装”）。

如果项目主要语言的标准工具均未安装或配置，那么这一缺失本身就值得在工具 / 开发体验部分报告——这意味着团队可能以为已有的正确性保障实际上并不存在。

在报告中汇总工具输出（包括数量和少数重要发现），不要把原始日志直接一股脑交给用户。

第 4 步：有针对性地阅读代码

现在进行人工 / 大模型驱动的检查。对于非平凡的代码库，按检查维度并行启动通用子 Agent——安全性、正确性、质量 / 性能——让每个 Agent 都能深入检查，不受其他方面干扰；要求它们按第 6 步规定的条目格式返回发现，并附上文件和行号引用。（Explore Agent 适合梳理代码分布位置，但它们负责定位代码而非评判代码，因此不要让它们代做审查。）对于小型代码库（几十个文件），自己集中检查会更快、更连贯。

对于以下每个维度，都要寻找具体且可定位的问题，而不是凭感觉判断。每项发现都必须指向真实位置：通常是文件（尽可能附上行号范围）；对于项目级缺失（没有 .gitignore、没有 LICENSE、没有测试目录、没有 CI 配置），填写 Where: project root（或缺失路径，例如 Where: tests/ (missing)）即可，也符合预期。规则是“不能含糊其辞”，而非“必须始终指向单独一行”。

正确性和 Bug

• 未处理的错误路径（被拒绝的 Promise、被吞掉的异常、被忽略的返回值）
• 空值 / 未定义 / 缺失的可选值处理
• 差一错误、循环边界错误、过时引用
• 竞态条件和异步顺序错误
• 死代码、不可达分支、矛盾条件
• 类型混淆（尤其是在动态语言中） 安全
• 注入：SQL、NoSQL、操作系统命令、路径遍历、模板、LDAP
• 跨站脚本（将未转义的内容输出到 HTML/DOM）
• 硬编码的机密信息、API 密钥、令牌、私钥（如果仓库足够小，可以在提交历史中一并搜索）。报告此类问题时，请遮盖密钥值——仅显示前 4 个字符和类型（例如 AKIA… AWS 访问密钥），切勿显示完整密钥。报告文件位于仓库中，可能会被提交、粘贴到问题中或分享出去；将密钥复制到报告中会扩大泄露范围。
• 弱加密：将 MD5/SHA1 用于安全场景、自定义加密、用于令牌的弱随机数
• 不安全的默认设置：过于宽松的 CORS、缺少身份验证检查、生产代码路径中存在调试路由
• 不安全的反序列化、SSRF、开放重定向
• 工具扫描阶段尚未标记的依赖项 CVE
• 记录敏感数据
• 信任边界处缺少输入验证

代码质量

• 文件过大、函数过长、嵌套过深、条件逻辑复杂
• 可抽取的重复代码（但仅限抽取能明显改善代码的情况——有时，重复代码比糟糕的抽象更简单）
• 误导性命名：变量、函数、模块的名称与其实际作用不符
• 与代码矛盾的注释
• 项目已有既定风格，但各模块之间风格不一致

架构

• 本应相互独立的层之间耦合过紧
• 模块之间存在循环依赖
• 业务逻辑混杂在 UI、路由处理程序或迁移中
• 缺少抽象或过早引入抽象

性能

• N+1 查询模式
• 热路径上的同步 I/O
• 无界循环、缺少分页
• 紧密循环中的大型内存分配、重复编译正则表达式、循环中的字符串拼接
• 查询形态暗示缺少索引（可查看架构时）

测试

• 关键路径缺少测试（身份验证、支付，以及任何与资金或数据丢失相关的功能）
• 测试没有验证有意义的内容，或断言循环论证
• 容易产生间歇性失败的模式（真实时间、真实网络、共享全局状态）
• 解析器、验证器、边界条件缺少边缘用例测试

文档与开发体验

• README 章节缺失或过时（设置、运行、测试、部署）
• 公共 API 缺少文档字符串或类型提示
• 环境变量/配置未记录
• 缺少 CHANGELOG，或发布流程不明确
• 构建缓慢、错误消息不清晰、缺少提交前钩子

功能与增强建议 这是最具推测性的维度。只有代码中存在明确依据时才建议功能——例如 TODO、只实现了一半的流程、明显的功能缺口（如“API 提供了列表/获取/创建接口，却没有删除接口”），或亟待自动化的手动工作流。请明确将这些标记为想法，而非问题。不要为了列出更多内容而凭空创造功能。

步骤 5：评分并确定优先级

为每项发现指定两个属性，方便用户筛选并决定采取哪些行动：

• 严重性：critical（数据丢失、安全漏洞、核心流程中断）、high（实际存在的 bug、常见场景下的故障、在合理条件下可被利用）、medium（正确性或质量问题，但有变通方案）、low（风格问题、轻微异味）、info（想法、观察——放入“想法”部分）
• 置信度：high（能指出确切的异常代码行并说明问题所在）、medium（这种模式很可疑，也可能确实有问题，但需要运行代码才能验证）、low（可能是有意为之——标记出来让维护者确认）

如果你发现自己写了很多 low confidence / low severity 项，请停下来。这些内容会让报告难以阅读，也会掩盖重要问题。删除所有不会改变用户本周计划的内容。

发布前先验证。 对于 critical/high 级别的问题，误报比漏掉低级问题更损害用户对你的信任。此外，你还没有亲自查看子 Agent 报告的代码，因此其中的所有问题也都要验证。请重新打开引用的文件并确认：

• 行号指向了所述问题对应的代码（子 Agent 和工具输出的行号经常会偏差几行，或引用已重构的文件）
• 问题在上下文中确实存在——输入未在上游验证，“未使用”的函数并非通过反射或路由表调用，“缺失”的测试也并非放在名称不同的目录中
• 严重性符合你实际能够描述的利用路径或故障场景

未通过这项检查的问题，请删除或降低严重性。

步骤 6：生成报告

将报告保存到项目根目录下的 CODE_AUDIT_<YYYY-MM-DD>_<HHMM>_<auditor>.md，例如 CODE_AUDIT_2026-06-29_1430_claude-opus-5-5.md，除非用户要求直接在对话中提供或另存到其他位置。时间戳记录审计运行时间，<auditor> 记录执行审计的人或模型，这样多次审计的报告就会并排保存，而不会悄悄覆盖上一份报告。使用本地时钟和审计者身份生成文件名：

date +%Y-%m-%d_%H%M        # the date + time component, e.g. 2026-06-29_1430

对于 <auditor>，如果由 Agent 运行审计，请使用模型 ID（例如 claude-opus-5-5）；如果由人工执行，请使用 git user.name（转换为小写 slug，并将空格替换为 -）。

使用用户提出请求时所用的语言撰写报告（用户用匈牙利语提出请求，就用匈牙利语撰写报告）；保留以下章节标题、ID 和类别/严重性标记，以便报告格式保持一致。严格使用以下结构——这是用户可以快速浏览的约定：

# Code audit — <project name> — <YYYY-MM-DD HH:MM>

## Executive summary
<3–6 lines: scope of audit (and any scoping defaults you chose), headline counts (critical/high/medium/low/ideas), the single biggest concern, and the single highest-leverage improvement>

## Findings

### Critical
<one entry per finding, in the format below — or "None" if nothing critical>

### High
...

### Medium
...

### Low
...

### Ideas (feature & enhancement opportunities)
...

## What was NOT analyzed
<honest list: paths skipped, tools not run, areas you only sampled>

## Suggested next steps
<3–5 bullets: which findings to act on first and why; how the user could attack the list>

问题条目格式：

#### [<id>] <short title>
- **Where**: `path/to/file.ext:LINE` (or `path/to/file.ext` if it's file-level)
- **Category**: bug | security | quality | performance | tests | docs | architecture | idea
- **Severity / Confidence**: high / high
- **What**: <one or two sentences describing the issue>
- **Why it matters**: <impact in plain terms>
- **Suggested fix**: <concrete direction; code sketch only if it really helps>

使用稳定的 ID，例如 SEC-01、BUG-01、Q-01、IDEA-01，方便用户之后引用。

文字务必简洁。用户需要对这个列表进行分类处理——每多一段文字，都会拖慢进度。

步骤 7：交接并提供后续选项

交互式使用：交付报告后，为用户提供清晰的选项。未经用户要求，不要开始修复：

Audit complete. Report at CODE_AUDIT_<YYYY-MM-DD>_<HHMM>_<auditor>.md.

Want me to:
  1. Fix specific findings — name the ids, e.g. "fix SEC-01, BUG-02, Q-03"
  2. Open GitHub issues for the high/critical items (via `gh issue create`)
  3. Drill into one finding in more depth
  4. Re-run the audit with different scope or focus

等待用户指示。如果用户选择修复，请将每项发现作为独立的小任务处理——阅读相关代码，进行最小改动，并在继续之前确认。不要将互不相关的修复打包成一个大型提交。

报告文件未被 Git 跟踪；请告知用户，让其决定是提交、移动报告，还是将 CODE_AUDIT_*.md 添加到 .gitignore——不要替用户执行这些操作。

非交互式使用：跳过选项菜单。说明报告的绝对路径，然后停止——调用方系统会读取报告并决定下一步。

输出原则

这些原则对报告质量的影响，胜过上面的任何单条规则：

• 可定位胜过巧妙。 一条带有真实文件和行号的朴素发现，胜过十条优雅却抽象的批评。
• 可信度胜过覆盖面。 一份简短、精准、值得用户信任的报告，胜过一份冗长、需要用户费力辩护的报告。
• 尊重用户已有的取舍。 如果项目明显选择了你会另作选择的约定，这不算发现——这是他们的决定。发现应指出实际代价（正确性、安全性、可维护性），而不是个人偏好。
• 区分想法与缺陷。 功能建议绝不能与 Bug 混在一起。用户需要知道哪些问题要修复，哪些建议可以考虑。
• 如实说明跳过了什么。 “未分析的内容”是一个独立章节，不是脚注——它能告诉用户还有哪些盲区。

关键限制

• 只读审计。除编写报告外，不要运行格式化工具、编辑文件、提交更改，也不要在审计过程中推送更改。
• 不要运行包安装程序、依赖更新，或任何会修改 node_modules / .venv / 锁文件的操作。如果未安装某个工具，请注明；不要擅自安装。
• 绝不要在报告或回复中完整复制任何机密值——请将其脱敏（见步骤 4 中的安全部分）。
• 每项发现都必须可定位——指出具体文件（尽可能附上行范围），或注明明确的项目级位置，例如 project root 或 tests/ (missing)。如果无法指出任何具体位置，就不要将其写入报告。
• 不要凑数。如果某个类别没有发现，请写“无”——这也是有用的信息。
• 除非能说明如何利用漏洞以及造成什么影响，否则不要声称存在漏洞。如果利用路径含糊不清，应降低严重性级别。
• 对于非常大的项目，应明确说明抽样范围。绝不要默默跳过半个代码库。
• 如果用户在报告后要求修复，请将每项发现作为一个独立的小任务处理。不要将无关更改混进同一次编辑。