Back to Details

blindspot

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Blindspot

代码盲点审查

You are performing a structured critique of code, architecture, or systems. Your job is to find what the author can't see — the gaps that familiarity hides, the risks that daily use normalizes, the debt that accumulates silently.
This is not a linter. Linters catch syntax and style. You catch design decisions that will hurt later — the unwrap() that will panic in production, the O(n²) that's fine with 10 items but fatal with 10,000, the API that can't evolve without breaking clients.
你正在对代码、架构或系统进行结构化审查。你的任务是发现作者看不到的问题——因熟悉而被掩盖的漏洞、日常使用中被习以为常的风险、悄然累积的技术债务。
这不是代码检查工具（linter）。Linter捕捉语法和风格问题，而你要捕捉那些会在后续造成危害的设计决策——比如在生产环境中会触发panic的unwrap()、处理10条数据没问题但处理10000条时会崩溃的O(n²)算法、不破坏客户端就无法演进的API。

When to use

使用场景

  • During evolution self-assessment (proactive self-critique)
  • On-demand via 
    /skill run blindspot
    with a target
  • When reviewing unfamiliar code before modifying it
  • After a feature is "done" — the last-mile audit
  • When a community issue reports a class of problem (search for siblings)
  • 演进式自我评估期间（主动自我审查）
  • 通过
    /skill run blindspot
    命令按需针对目标执行
  • 修改不熟悉的代码前进行审查时
  • 功能“完成”后——最后阶段的审计
  • 社区反馈某类问题时（排查同类问题）

When NOT to use

不适用场景

  • For style/formatting issues (use clippy/rustfmt)
  • When you need to understand code before critiquing it (use 
    explore-codebase
    first)
  • For single-line fixes you can see directly (just fix them)
  • 处理风格/格式问题（使用clippy/rustfmt）
  • 需要先理解代码再进行审查时（先使用
    explore-codebase
    ）
  • 直接可见的单行代码修复（直接修改即可）

Parameters

参数

Target

目标

What to analyze. One of:
  • A file path: 
    src/tools.rs
  • A directory: 
    src/format/
  • A module or concept: "error handling in the REPL"
  • self
    — yoyo's own codebase (defaults to 
    src/
    )
要分析的对象，可选以下之一：
  • 文件路径：
    src/tools.rs
  • 目录：
    src/format/
  • 模块或概念："REPL中的错误处理"
  • self
    —— yoyo自身的代码库（默认指向
    src/
    ）

Roast level

审查强度

Controls the threshold for reporting:
  • gentle — Critical and Warning only. For when you want actionable items without noise.
  • standard (default) — Critical + Warning + Smell. The balanced default.
  • brutal — Everything, including nitpicks. For when you want the full picture.
控制问题报告的阈值：
  • gentle（温和）——仅报告严重和警告级问题。适用于需要可执行项且无冗余信息的场景。
  • standard（标准，默认）——报告严重+警告+代码异味问题。平衡型默认选项。
  • brutal（严苛）——报告所有问题，包括细枝末节的挑剔。适用于需要全面了解情况的场景。

Analysis Dimensions

分析维度

Examine the target through these lenses:
从以下视角审查目标：

1. Error handling gaps

1. 错误处理漏洞

  • unwrap()
    / 
    expect()
    on fallible operations in non-test code
  • Functions that return 
    Ok(())
    but swallow errors silently
  • Missing error context (bare 
    ?
    without 
    .context()
    or 
    .map_err()
    )
  • Panic paths reachable from user input
  • Error types that lose information (stringly-typed errors)
  • 非测试代码中对可能失败的操作使用
    unwrap()
    / 
    expect()
  • 返回
    Ok(())
    但静默吞掉错误的函数
  • 缺少错误上下文的情况（仅使用
    ?
    而未搭配
    .context()
    或
    .map_err()
    ）
  • 可通过用户输入触发的panic路径
  • 丢失信息的错误类型（基于字符串的错误）

2. Security blind spots

2. 安全盲点

  • Hardcoded secrets, tokens, or credentials
  • User input passed to shell commands without sanitization
  • Path traversal vulnerabilities (unchecked 
    ../
    )
  • Unsafe blocks without safety comments
  • Dependencies with known vulnerabilities
  • 硬编码的密钥、令牌或凭证
  • 用户输入未经过滤就传递给shell命令
  • 路径遍历漏洞（未检查
    ../
    ）
  • 无安全注释的Unsafe代码块
  • 存在已知漏洞的依赖项

3. Architecture debt

3. 架构债务

  • God objects (structs/modules doing too many things)
  • Circular dependencies between modules
  • Leaky abstractions (implementation details in public interfaces)
  • Dead code that's maintained but never called
  • Tight coupling that prevents independent testing
  • 上帝对象（承担过多职责的结构体/模块）
  • 模块间的循环依赖
  • 泄漏的抽象（公共接口暴露实现细节）
  • 被维护但从未被调用的死代码
  • 阻碍独立测试的紧耦合

4. Scalability risks

4. 可扩展性风险

  • O(n²) or worse in paths that handle user data
  • Unbounded collections (Vec/HashMap that grow without limit)
  • Missing pagination on queries or listings
  • Blocking operations in async contexts
  • Single-threaded bottlenecks in concurrent code
  • 处理用户数据的路径中存在O(n²)或更差的算法
  • 无界集合（无限增长的Vec/HashMap）
  • 查询或列表缺少分页机制
  • 异步上下文里的阻塞操作
  • 并发代码中的单线程瓶颈

5. Testing gaps

5. 测试漏洞

  • Public functions without any test coverage
  • Tests that only check the happy path
  • Tests that mirror implementation rather than behavior
  • Missing edge cases: empty input, Unicode, very large input, concurrent access
  • Brittle tests that break on unrelated changes
  • 无任何测试覆盖的公共函数
  • 仅检查正常路径的测试
  • 镜像实现而非验证行为的测试
  • 缺失的边缘用例：空输入、Unicode、超大输入、并发访问
  • 因无关变更而失效的脆弱测试

6. API design issues

6. API设计问题

  • Inconsistent naming conventions within the same module
  • Functions that accept 
    String
    when 
    &str
    would suffice
  • Missing input validation at API boundaries
  • Breaking change risks (public types that can't evolve)
  • Boolean parameters that should be enums
  • 同一模块内命名约定不一致
  • 本可使用
    &str
    却接受
    String
    的函数
  • API边界处缺少输入验证
  • 存在破坏性变更风险的公共类型（无法演进）
  • 应使用枚举却使用布尔参数的情况

7. Dependency risks

7. 依赖风险

  • Outdated dependencies with available updates
  • Heavy dependencies used for trivial functionality
  • Dependencies with single maintainers or low activity
  • Vendored or forked code that's drifted from upstream
  • Missing 
    Cargo.lock
    entries or version pinning
  • 有可用更新的过时依赖项
  • 仅用于 trivial 功能的重型依赖
  • 维护者单一或活跃度低的依赖项
  • 与上游版本偏离的 vendored 或分叉代码
  • 缺失
    Cargo.lock
    条目或版本固定

Procedure

流程

1. Scope the target

1. 确定分析范围

Determine what you're analyzing and how large it is.
bash
undefined
明确要分析的对象及其规模。
bash
undefined

For a file

针对单个文件

wc -l <target_file>
wc -l <target_file>

For a directory

针对目录

find <target_dir> -name '*.rs' | xargs wc -l | sort -rn | head -20
find <target_dir> -name '*.rs' | xargs wc -l | sort -rn | head -20

For "self"

针对"self"

find src/ -name '*.rs' | xargs wc -l | sort -rn | head -20
undefined
find src/ -name '*.rs' | xargs wc -l | sort -rn | head -20
undefined

2. Decide: direct analysis or sub-agent dispatch?

2. 决策：直接分析还是分派子Agent？

  • ≤5KB total (roughly ≤150 lines): Read directly, analyze in main context.
  • >5KB but ≤30KB: Read key files directly, focus analysis on highest-risk areas.
  • >30KB: Use sub_agent dispatch. Give each sub-agent one analysis dimension and a subset of files. Synthesize their reports.
For sub-agent dispatch, store the file contents in SharedState and dispatch focused questions:
  • "Analyze error handling patterns in these files. Find unwrap() calls, swallowed errors, and missing error context."
  • "Find scalability risks: O(n²) algorithms, unbounded collections, missing pagination."
  • 总大小≤5KB（约≤150行）：直接读取，在主上下文中分析。
  • >5KB但≤30KB：直接读取关键文件，聚焦分析最高风险区域。
  • >30KB：使用子Agent分派。为每个子Agent分配一个分析维度和部分文件，综合它们的报告。
分派子Agent时，将文件内容存储在SharedState中并发送聚焦式问题：
  • "分析这些文件中的错误处理模式，查找unwrap()调用、被吞掉的错误和缺失的错误上下文。"
  • "查找可扩展性风险：O(n²)算法、无界集合、缺失的分页机制。"

3. Analyze each dimension

3. 逐个维度分析

For each of the 7 dimensions, scan the target with appropriate tools:
bash
undefined
针对7个维度中的每个，使用合适的工具扫描目标：
bash
undefined

Error handling: find unwrap/expect in non-test code

错误处理：查找非测试代码中的unwrap/expect

grep -rn '.unwrap()' <target> | grep -v '#[cfg(test)]' | grep -v 'tests/' grep -rn '.expect(' <target> | grep -v '#[cfg(test)]' | grep -v 'tests/'
grep -rn '.unwrap()' <target> | grep -v '#[cfg(test)]' | grep -v 'tests/' grep -rn '.expect(' <target> | grep -v '#[cfg(test)]' | grep -v 'tests/'

Security: find potential secrets

安全：查找潜在密钥

grep -rn 'password|secret|token|api_key' <target> --include='*.rs'
grep -rn 'password|secret|token|api_key' <target> --include='*.rs'

Architecture: find large files (potential god objects)

架构：查找大文件（潜在上帝对象）

find <target> -name '*.rs' -exec wc -l {} ; | sort -rn | head -10
find <target> -name '*.rs' -exec wc -l {} ; | sort -rn | head -10

Scalability: find nested loops

可扩展性：查找嵌套循环

grep -rn 'for.{' <target> --include='.rs' -A 5 | grep -B 1 'for.*{'
grep -rn 'for.{' <target> --include='.rs' -A 5 | grep -B 1 'for.*{'

Testing: find public functions and check for corresponding tests

测试：查找公共函数并检查对应的测试

grep -rn '^pub fn' <target> --include='*.rs'

These are starting points. Use judgment — not every grep hit is a real finding. Read context around hits before reporting.
grep -rn '^pub fn' <target> --include='*.rs'

这些只是起点。请运用判断——并非每个grep结果都是真实问题。报告前请查看结果周围的上下文。

4. Classify findings

4. 分类发现的问题

Assign each finding a severity:
  • Critical — Will cause failures in production, security vulnerability, or data loss risk. Fix now.
  • Warning — Will cause problems under specific conditions (scale, edge cases, maintenance). Fix soon.
  • Smell — Not broken, but makes the code harder to understand, maintain, or extend. Consider fixing.
  • Acknowledged — A known trade-off that the codebase documents or explicitly accepts. Note but don't nag.
为每个发现的问题分配严重程度：
  • Critical（严重）——会导致生产环境故障、安全漏洞或数据丢失风险。立即修复。
  • Warning（警告）——在特定条件下（规模、边缘用例、维护）会引发问题。尽快修复。
  • Smell（代码异味）——当前无故障，但会降低代码的可读性、可维护性或可扩展性。考虑修复。
  • Acknowledged（已确认）——代码库中已文档化或明确接受的已知权衡。仅做记录，无需反复提醒。

5. Produce the report

5. 生成报告

Format output as:
🔍 BLINDSPOT REPORT — [target]
   Roast level: [gentle|standard|brutal]
   Analyzed: [N files, M lines]
输出格式如下：
🔍 盲点审查报告 — [目标]
   审查强度：[gentle|standard|brutal]
   分析规模：[N个文件，M行代码]

Critical (fix now)

严重问题（立即修复）

  • [category] 
    file:line
    — [description of the issue and why it matters]
  • [类别] 
    文件:行号
    — [问题描述及影响]

Warning (fix soon)

警告问题（尽快修复）

  • [category] 
    file:line
    — [description]
  • [类别] 
    文件:行号
    — [描述]

Smell (consider)

代码异味（考虑修复）

  • [category] 
    file:line
    — [description]
  • [类别] 
    文件:行号
    — [描述]

Acknowledged (known, accepted)

已确认问题（已知且接受）

  • [items explicitly documented as accepted trade-offs in the codebase]
Summary: N critical, M warnings, K smells
undefined
  • [代码库中明确记录为可接受权衡的项]
摘要：N个严重问题，M个警告问题，K个代码异味
undefined

6. Distinguish real findings from noise

6. 区分真实问题与冗余信息

Before including a finding, ask:
  • Is this actually reachable? (Dead code unwrap() isn't critical)
  • Is there context I'm missing? (A comment explaining why)
  • Does the codebase explicitly accept this trade-off? (Move to Acknowledged)
  • Would fixing this actually improve the code? (If not, skip it)
The goal is signal, not volume. Ten precise findings beat fifty grep hits.
在纳入问题前，请确认：
  • 该问题是否实际可达？（死代码中的unwrap()不构成严重问题）
  • 是否存在我未了解的上下文？（有注释解释原因）
  • 代码库是否明确接受此权衡？（移至已确认类别）
  • 修复此问题是否真的能改善代码？（若不能则忽略）
目标是传递有效信号，而非追求数量。10个精准的发现胜过50个grep结果。

RLM dispatch pattern (for large targets)

大规模目标的RLM分派模式

When the target exceeds 30KB:
  1. Partition — split files into groups by module or concern
  2. Store — 
    shared_state.set("blindspot.group-1", <file contents>)
  3. Dispatch — one sub-agent per analysis dimension per file group: 
    "You are analyzing [files] for [dimension]. Report findings as JSON:
{findings: [{file, line, severity, category, description}]}"
  4. Synthesize — collect sub-agent results, deduplicate, rank by severity
  5. Report — format the final structured report
Hard depth cap: 3. If you're already at depth 2, do direct analysis instead of dispatching further.
当目标大小超过30KB时：
  1. 拆分——按模块或关注点将文件分组
  2. 存储——
    shared_state.set("blindspot.group-1", <文件内容>)
  3. 分派——为每个文件组的每个分析维度分配一个子Agent： 
    "你正在分析[文件]的[维度]。请以JSON格式报告发现：
{findings: [{file, line, severity, category, description}]}"
  4. 综合——收集子Agent的结果，去重并按严重程度排序
  5. 报告——格式化最终的结构化报告
深度上限：3。若当前已处于深度2，则直接分析而非继续分派。

Principles

原则

  • Familiarity is the enemy. The code's author has read it a hundred times. You're the fresh eyes.
  • Severity over volume. One critical finding is worth more than twenty smells.
  • Specificity is respect. "Error handling could be improved" is useless. "
    src/tools.rs:247
    — unwrap() on user-supplied path will panic on non-UTF8 filenames" is actionable.
  • Acknowledge good decisions. If you find something the codebase handles well despite complexity, note it. Context for what's working helps prioritize what isn't.
  • Don't nag about accepted trade-offs. If there's a comment saying "// SAFETY: this is fine because X", move it to Acknowledged unless the safety argument is actually wrong.
  • 熟悉是敌人。代码的作者已经读过它上百次，你是全新的视角。
  • 严重程度优先于数量。一个严重问题胜过二十个代码异味。
  • 具体性是尊重。“错误处理可以改进”毫无用处。“
    src/tools.rs:247
    ——对用户提供的路径使用unwrap()会在非UTF8文件名时触发panic”才是可执行的。
  • 认可良好决策。若发现代码库在复杂情况下仍处理得当，请记录下来。了解哪些部分运行良好有助于优先处理问题。
  • 不要对已接受的权衡反复提醒。若有注释说明“// SAFETY: this is fine because X”，除非安全论证实际错误，否则移至已确认类别。