review-codebase

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Skill: Review Codebase

Purpose

用途

From a senior full-stack and production code-review perspective, review the current state of a given scope (single file, directory, or whole repo): architecture, design, tech debt, patterns, and overall quality. Does not depend on git diff. Complements review-code: review-code focuses on the current change (impact, regression, compatibility, side effects); this skill focuses on the current state of the given scope.

从资深全栈及生产级代码评审的视角，评审指定范围（单个文件、目录或整个代码仓库）的当前状态：包括架构、设计、技术债务、设计模式及整体代码质量。该技能不依赖Git差异内容，可与review-code形成互补：review-code聚焦于当前代码变更（影响范围、回归风险、兼容性、副作用）；本技能则聚焦于指定范围的当前状态。

Use Cases

适用场景

New module/service: Architecture and implementation review for a given dir or file.
Legacy audit: Quality and risk review for a path or repo.
Pair / sampling: Review files or dirs specified by a colleague, without requiring a current diff.
Teaching and standards: Explain or check arbitrary code against the same review dimensions.

When to use: When the user wants to review given path(s), directory(ies), or repo, not “only the current diff.” For reviewing only local changes, use review-diff. For a full orchestrated review, use review-code.

Scope: This skill focuses on current state (architecture, design, tech debt) of the given scope and does not depend on diff. It complements

review-code

(orchestrated). skills.sh options like

code-review-excellence

are more general; this skill emphasizes boundaries, patterns, and overall quality.

新模块/服务：针对指定目录或文件的架构与实现评审。
遗留代码审计：针对指定路径或代码仓库的质量与风险评审。
结对/抽样评审：评审同事指定的文件或目录，无需依赖当前差异内容。
教学与规范落地：对照统一评审维度，讲解或检查任意代码。

何时使用：当用户希望评审指定路径/目录/代码仓库，而非“仅当前差异内容”时。若仅需评审本地变更，请使用review-diff；若需完整的编排式评审，请使用review-code。

范围说明：本技能聚焦于指定范围的当前状态（架构、设计、技术债务），不依赖差异内容，可与

review-code

（编排式评审）形成互补。skills.sh中的

code-review-excellence

等选项更通用；本技能则侧重边界、模式及整体质量。

Behavior

行为规范

Scope

评审范围

Input defines scope: Single file, directory, or “repo root” etc., as specified by the user; multiple paths allowed.
Not diff-bound: Analyze current file content in the given scope; does not require a git change set. If the user also provides a diff, it can inform context but is not the sole input.

输入定义范围：由用户指定的单个文件、目录或“代码仓库根目录”等；支持多路径。
不依赖差异内容：分析指定范围内文件的当前内容，无需Git变更集。若用户同时提供差异内容，可作为上下文参考，但不作为唯一输入。

For each file in scope (state/design-centric)

针对范围内每个文件（聚焦状态与设计）

Architecture and boundaries: Are module/service boundaries clear, responsibilities single, dependency direction sensible?
Design patterns and consistency: Are patterns used appropriately? Style and patterns consistent with the rest of the repo/module?
Tech debt and maintainability: Duplication, complexity, testability, docs and comments vs. current state.
Cross-module dependencies and coupling: Too many dependencies, cycles, stable and clear interfaces?
Security and performance (current): Input validation, sensitive data, permissions, resource use and concurrency risks in the current implementation.
Concrete suggestions: Actionable refactor or improvement (with file:line).

This skill looks at full implementation and place in the whole, not “this diff.”

架构与边界：模块/服务边界是否清晰？职责是否单一？依赖方向是否合理？
设计模式与一致性：模式使用是否恰当？风格与模式是否与代码仓库/模块的其余部分保持一致？
技术债务与可维护性：是否存在代码重复、复杂度高、可测试性差的问题？文档与注释是否与当前状态匹配？
跨模块依赖与耦合：依赖是否过多？是否存在循环依赖？接口是否稳定清晰？
当前实现的安全性与性能：输入验证、敏感数据、权限控制、资源使用及并发风险等情况。
具体改进建议：可落地的重构或改进方案（需标注文件:行号）。

本技能关注完整实现及其在整体中的定位，而非“本次差异内容”。

Tone and references

语气与引用

Professional and engineering-focused: Review as if this will run in production.
Precise: Reference specific locations (file:line).

专业且聚焦工程实践：以生产环境运行标准进行评审。
精准明确：引用具体位置（文件:行号）。

Scope and priority

范围与优先级

If the scope is large (e.g. whole repo), output by layer (module/dir) or agree with the user on a priority subset to avoid shallow, generic conclusions.

若范围较大（如整个代码仓库），按分层（模块/目录）输出结果，或与用户协商优先评审的子集，避免得出浅层、通用的结论。

Input & Output

输入与输出

Input

输入

Paths: One or more file or directory paths (relative to workspace root or user-given root).
Optional: Language/framework constraints, focus (e.g. security only, performance only).

Defaults (confirm or choose; avoid free-text):

Item	Default	When to deviate
Path(s)	Repo root	Offer: [Repo root] [Current file's directory] [List top-level dirs to pick]; user selects.
Large scope	By layer (output by module/dir)	User can choose a priority subset (e.g. pick from top-level dirs).

Confirm before running: (1) Review repo root? [default] or user selects path(s) from options. (2) If scope is large, use default "by layer" or user chooses a priority subset from offered list.

路径：一个或多个文件或目录路径（相对于工作区根目录或用户指定的根目录）。
可选内容：语言/框架约束、评审重点（如仅关注安全、仅关注性能）。

默认值（确认或选择；避免自由文本）：

项	默认值	何时调整
路径	代码仓库根目录	提供选项：[代码仓库根目录] [当前文件所在目录] [列出顶级目录供选择]；由用户选定。
大范围评审	按分层输出（按模块/目录输出）	用户可选择优先子集（例如从顶级目录中挑选）。

运行前确认：(1) 是否评审代码仓库根目录？ [默认] 或用户从选项中选择路径。(2) 若范围较大，使用默认的“按分层输出”，或用户从提供的列表中选择优先子集。

Output

输出

Per file or module: Conclusions and suggestions for the dimensions above.
Format: Headings (file or module), lists, and references (file:line) so the reader can follow the source.

按文件或模块：针对上述维度给出结论与建议。
格式：使用标题（文件或模块）、列表及引用（文件:行号），便于读者定位源码。

Restrictions

限制条件

Do not assume “review only diff” when scope is not clearly “diff”; this skill defaults to full code in the given scope.
Do not give conclusions without specific locations or actionable suggestions.
Do not use vague language (e.g. “might be wrong” without type and fix direction).

请勿在范围未明确为“差异内容”时默认“仅评审差异”；本技能默认评审指定范围内的完整代码。
请勿在未标注具体位置或给出可落地建议的情况下得出结论。
请勿使用模糊表述（如“可能存在问题”但未说明类型及修复方向）。

Self-Check

自我检查

Does the review scope match the user’s path(s)/dir(s)?
Are boundaries, patterns, tech debt, dependencies and coupling, and current security/performance covered?
Are issues referenced with file:line?
Are concrete refactor or improvement suggestions given for important issues?

评审范围是否与用户指定的路径/目录匹配？
是否覆盖了架构与边界、设计模式与一致性、技术债务与可维护性、跨模块依赖与耦合、当前实现的安全性与性能？
问题是否标注了文件:行号？
是否针对重要问题给出了具体的重构或改进建议？

Examples

示例

Example 1: Single directory

示例1：单个目录

Input: Path
```
src/auth/
```
; review all relevant code under it.
Expected: Per file, list architecture and boundaries, design patterns and consistency, tech debt and maintainability, cross-module dependencies and coupling, current security and performance; reference line numbers and give improvement suggestions; do not depend on current git change.

输入：路径
```
src/auth/
```
；评审该路径下所有相关代码。
预期输出：按文件列出架构与边界、设计模式与一致性、技术债务与可维护性、跨模块依赖与耦合、当前实现的安全性与性能的评审结论；标注行号并给出改进建议；不依赖当前Git变更内容。

Example 2: Single file

示例2：单个文件

Input: Path
```
pkg/validator/validator.go
```
.
Expected: Full review of the file: its role and boundaries, entry points and dependencies, patterns and consistency, tech debt and testability, current security and performance; reference line numbers.

输入：路径
```
pkg/validator/validator.go
```
。
预期输出：对该文件进行全面评审，包括其角色与边界、入口点与依赖、设计模式与一致性、技术债务与可测试性、当前实现的安全性与性能；标注行号。

Edge case: Whole repo

边缘场景：整个代码仓库

Input: Path is repo root or “whole project.”
Expected: Output by layer (module/dir) or give a high-level summary and risk list (architecture, dependencies, tech debt), then agree with the user on a subset for deeper review; avoid one long, shallow pass.

输入：路径为代码仓库根目录或“整个项目”。
预期输出：按分层（模块/目录）输出结果，或给出高层总结与风险列表（架构、依赖、技术债务），然后与用户协商优先评审的子集；避免进行浅层、宽泛的评审。

Appendix: Output contract

附录：输出规范

When this skill produces a review, it follows this contract so that findings can be aggregated with other atomic skills (e.g. by review-code):

Element	Requirement
Scope	User-specified path(s); full code in scope; not diff-bound.
Findings format	Each finding MUST include Location ( `path/to/file.ext` or file:line), Category ( `scope` for this skill), Severity ( `critical` \| `major` \| `minor` \| `suggestion` ), Title, Description, and optionally Suggestion.
Per file/module	Headings, lists, references (file:line).
Dimensions	Architecture and boundaries; design patterns and consistency; tech debt and maintainability; cross-module dependencies and coupling; security and performance; concrete suggestions.
Large scope	Output by layer or agree on priority subset; avoid shallow pass.

Example finding compatible with aggregation:

markdown

- **Location**: `pkg/auth/service.go:31`
- **Category**: scope
- **Severity**: major
- **Title**: Module boundary unclear; auth logic mixed with HTTP handling
- **Description**: Controller contains validation and token logic; hard to test and reuse.
- **Suggestion**: Extract auth logic into a dedicated service; keep controller thin.

当本技能生成评审结果时，需遵循以下规范，以便与其他原子技能（如review-code）的评审结果进行聚合：

元素	要求
范围	用户指定的路径；评审范围内的完整代码；不依赖差异内容。
结果格式	每个结果必须包含位置（ `path/to/file.ext` 或 file:line）、类别（本技能为 `scope` ）、严重程度（ `critical` \
按文件/模块组织	使用标题、列表、引用（file:line）。
评审维度	架构与边界；设计模式与一致性；技术债务与可维护性；跨模块依赖与耦合；安全性与性能；具体改进建议。
大范围评审	按分层输出或协商优先子集；避免浅层评审。

符合聚合要求的结果示例：

markdown

- **Location**: `pkg/auth/service.go:31`
- **Category**: scope
- **Severity**: major
- **Title**: 模块边界不清晰；认证逻辑与HTTP处理耦合
- **Description**: 控制器中包含验证与令牌逻辑，难以测试和复用。
- **Suggestion**: 将认证逻辑提取至独立服务中，保持控制器轻量化。
```",