Back to Details

deep-codebase-review

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Deep Codebase Review

深度代码库评审

Perform a broad structural review rather than a narrow bug hunt. Look for the places where the codebase is starting to bend: duplicated patterns, weak boundaries, missing shared abstractions, stale plans, hidden lifecycle risks, inelegant local structure, and shortcuts that will compound later.
进行全面的结构评审，而非狭义的bug排查。寻找代码库开始出现问题的地方：重复模式、薄弱边界、缺失的共享抽象、过时的规划、隐藏的生命周期风险、不够优雅的本地结构以及后续会加剧问题的捷径。

Review Workflow

评审流程

1. Establish the intended shape first

1. 先明确预期架构

  • Read the planning docs, architecture notes, roadmap, and any repo-specific guidance before judging structure.
  • Summarize the intended system shape in a few sentences for yourself before drawing conclusions.
  • If the repo has no explicit design docs, infer the intended shape from naming, layout, and current abstractions, and state that inference clearly.
  • 在评判结构之前，先阅读规划文档、架构说明、路线图以及任何仓库特定指南。
  • 先总结出预期的系统架构（几句话即可），再得出结论。
  • 如果仓库没有明确的设计文档，从命名、布局和现有抽象推断预期架构，并清晰说明该推断。

2. Build breadth before depth

2. 先建立广度认知再深入细节

  • Scan the repository structure first with fast file and text search.
  • Read enough files to understand boundaries, ownership, critical services, async paths, configuration, and tests.
  • Prefer sampling all major layers before drilling deep into one file.
  • When the codebase has a roadmap or plan document, compare that document against the current implementation while reviewing.
  • 先通过快速文件和文本搜索扫描仓库结构。
  • 阅读足够多的文件，以理解边界、归属、核心服务、异步路径、配置和测试。
  • 优先抽样所有主要层级，再深入单个文件。
  • 当代码库有路线图或规划文档时，评审时要将该文档与当前实现进行对比。

3. Review through multiple lenses

3. 从多个视角进行评审

  • Load references/review-lenses.md and use the sections that fit the codebase.
  • Prioritize behavioral and structural risks over cosmetic cleanup.
  • Treat duplication, implicit contracts, unnecessary complexity, and misplaced concepts as first-class review concerns, not secondary polish.
  • Look for code whose local shape obscures the simple idea underneath: awkward naming, needless indirection, over- or under-abstraction, repeated ceremony, tangled conditionals, and modules that are correct but hard to read or extend.
  • Treat compatibility shims, facade layers, re-export modules, and backwards-compatible wrappers as structural costs unless they serve a concrete current need.
  • Prefer the forward-looking end-state when judging refactors; if a compatibility layer makes ownership or behavior less obvious, call that out.
  • 加载[references/review-lenses.md]并使用适合该代码库的章节。
  • 优先关注行为和结构风险，而非表面的清理工作。
  • 将重复逻辑、隐式契约、不必要的复杂性和错位概念作为首要评审关注点，而非次要的优化内容。
  • 寻找那些本地结构掩盖了底层简单逻辑的代码：命名尴尬、不必要的间接层、过度或不足抽象、重复的仪式化代码、混乱的条件判断，以及功能正确但难以阅读或扩展的模块。
  • 除非兼容性垫片、外观层、重导出模块和向后兼容包装器满足当前具体需求，否则将它们视为结构成本。
  • 判断重构时优先考虑面向未来的最终状态；如果兼容性层使归属或行为变得不明确，要指出这一点。

4. Separate findings from pressure points

4. 区分发现问题与压力点

  • Call something a finding when it has a concrete downside: bug risk, race condition, data-integrity issue, maintainability hazard, design contradiction, or likely regression path.
  • Call something a pressure point when it is not broken yet but is on track to become expensive or fragile.
  • Keep speculation clearly labeled. Do not present a stylistic preference as a defect.
  • 当某内容存在具体负面影响时，将其称为“发现问题”：bug风险、竞态条件、数据完整性问题、可维护性隐患、设计矛盾或可能的回归路径。
  • 当某内容目前尚未损坏，但正朝着昂贵或脆弱的方向发展时，将其称为“压力点”。
  • 明确标注推测内容。不要将风格偏好呈现为缺陷。

5. Require evidence

5. 要求提供证据

  • Cite exact files and lines for findings whenever possible.
  • Explain the mechanism of failure or debt accumulation, not just the surface smell.
  • If a concern depends on a runtime assumption, say so explicitly.
  • If you think reuse is missing, identify the duplicated pattern and the likely seam for extraction.
  • 尽可能为发现的问题引用确切的文件和行号。
  • 解释故障或债务累积的机制，而不仅仅是表面现象。
  • 如果某关注点依赖于运行时假设，要明确说明。
  • 如果认为存在未复用的情况，指出重复的模式以及可能的提取切入点。

6. Review the tests and plans too

6. 同时评审测试和规划

  • Check whether tests reinforce the intended architecture or quietly encode the wrong shape.
  • Check whether roadmap or design documents are stale, misleading, or still missing key work that the code now depends on.
  • Note when docs imply a cleaner or more complete state than the code actually provides.
  • 检查测试是强化了预期架构，还是悄悄固化了错误的架构。
  • 检查路线图或设计文档是否过时、具有误导性，或者仍缺少代码当前依赖的关键工作内容。
  • 记录文档暗示的状态比实际代码更整洁或更完整的情况。

Default Council Mode

默认Council Mode

Council mode with sub-agents is the default for broad codebase reviews and substantial PR or branch reviews. If sub-agents are available, use them unless the user specifically forbids sub-agents or requests an ordinary small-diff review. The user does not need to say "sub-agent", "council", "parallel", or "delegate" for this default to apply.
Load references/council-review-protocol.md before delegating. Before spawning specialists, state briefly that council mode is being used and name the reviewer roles being delegated.
In council mode, the main agent is the coordinator. Specialist outputs are evidence inputs, not report sections. Assign distinct scopes, require concrete file/line evidence, reconcile contradictions, verify important claims yourself, and then produce one consolidated review.
No silent solo fallback: if council mode would normally apply but sub-agents cannot be spawned because the environment does not expose them or blocks them, explain the blocker and ask whether to continue with a solo multi-pass review.
For a user-requested solo review, run the same role-based passes locally: correctness and lifecycle, architecture and boundaries, tests and contracts, and code aesthetics, local simplicity, and maintainability.
对于全面代码库评审和大型PR或分支评审，默认使用带sub-agents的Council mode。若有可用的sub-agents，则使用它们，除非用户明确禁止sub-agents或要求普通的小差异评审。用户无需提及“sub-agent”、“council”、“parallel”或“delegate”即可触发此默认设置。
在委托之前加载[references/council-review-protocol.md]。在生成专家评审之前，简要说明正在使用Council mode，并列出委托的评审角色。
在Council mode下，主Agent是协调者。专家的输出是证据输入，而非报告章节。分配不同的范围，要求提供具体的文件/行证据，调和矛盾，自行验证重要结论，然后生成一份整合的评审报告。
禁止静默回退到单独评审：如果通常应适用Council mode，但由于环境未暴露或阻止sub-agents而无法生成，要说明障碍，并询问是否继续进行单独的多轮评审。
对于用户要求的单独评审，本地执行相同的基于角色的评审：正确性与生命周期、架构与边界、测试与契约，以及代码美观度、本地简洁性和可维护性。

Output Standard

输出标准

Default output order:
  1. Findings, ordered by severity.
  2. Structural pressure points and likely refactors.
  3. Roadmap or design alignment notes.
  4. Open questions or residual risk.
When the user asked for a review, keep findings primary. If there are no concrete findings, say so explicitly and still report the most important pressure points and testing gaps.
For a worked report shape, read examples/review-output.md when producing a full written audit.
默认输出顺序：
  1. 发现的问题，按严重程度排序。
  2. 结构压力点和可能的重构建议。
  3. 路线图或设计一致性说明。
  4. 待解决问题或剩余风险。
当用户要求评审时，将发现的问题放在首位。如果没有具体的发现问题，要明确说明，并仍报告最重要的压力点和测试缺口。
如需参考完整的报告格式，生成书面审计报告时请阅读[examples/review-output.md]。

Practical Heuristics

实用启发法

  • Prefer a small number of high-signal findings over a long list of nits.
  • Look for repeated transactional patterns, lifecycle code, adapter glue, and state transitions that want a shared helper or contract.
  • Look for god modules early; they are easier to split before more features land.
  • Look for elegant reductions: places where a small, well-named helper, value object, table-driven shape, or clearer boundary would make the code shorter, more obvious, and less error-prone.
  • Look for domain leakage where adapter-specific or UI-specific concepts have crept into the core model.
  • Look for stale abstractions that were right one milestone ago but now force awkward workarounds.
  • Look for refactors that stopped halfway and left compatibility surfaces behind; do not treat preserving old import paths or old module shapes as inherently positive.
  • When a split introduces a thin facade solely to avoid updating call sites, treat that as a likely review concern rather than a neutral implementation detail.
  • Look for retention, cleanup, idempotency, and restart behavior in any persistent or asynchronous system.
  • Treat tests, logging, and operator visibility as part of structure, not as optional add-ons.
  • 优先选择少量高价值的发现问题，而非一长串琐碎细节。
  • 寻找重复的事务模式、生命周期代码、适配器胶水代码和状态转换，这些部分可能需要共享助手或契约。
  • 尽早寻找“上帝模块”；在添加更多功能之前拆分它们会更容易。
  • 寻找优雅的简化方式：一个小的、命名恰当的助手、值对象、表驱动结构或更清晰的边界，可以使代码更短、更直观且更不易出错。
  • 寻找领域泄漏的情况：适配器特定或UI特定的概念渗透到核心模型中。
  • 寻找过时的抽象：这些抽象在之前的里程碑中是合适的，但现在需要笨拙的变通方法。
  • 寻找中途停止的重构，留下了兼容性接口；不要将保留旧导入路径或旧模块形状视为固有优点。
  • 当拆分仅引入一个薄外观层以避免更新调用站点时，将其视为可能的评审关注点，而非中性的实现细节。
  • 在任何持久化或异步系统中，关注保留、清理、幂等性和重启行为。
  • 将测试、日志和操作员可见性视为结构的一部分，而非可选附加组件。

Follow-Through

后续跟进

  • If the user wants fixes after the review, update the relevant roadmap or planning document in the same turn when the future work changes.
  • Preserve the distinction between forward-looking planning documents and changelogs.
  • 如果用户希望在评审后进行修复，当未来工作发生变化时，同步更新相关的路线图或规划文档。
  • 保留前瞻性规划文档与变更日志之间的区别。