Back to Details

review-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Skill: Review Architecture

Skill：架构评审

Purpose

目的

Review code for architecture concerns only. Do not define scope (diff vs codebase) or perform language/framework/security analysis; those are separate atomic skills. Emit a findings list in the standard format for aggregation. Focus on module and layer boundaries, dependency direction, single responsibility, cyclic dependencies, interface stability, and coupling and extension points.
仅针对架构相关问题评审代码。不要定义评审范围（差异对比 vs 整个代码库），也不要进行语言/框架/安全分析；这些属于独立的原子技能。以标准格式输出问题发现列表，用于汇总。重点关注模块与分层边界、依赖方向、单一职责、循环依赖、接口稳定性、耦合性以及扩展点。

Use Cases

使用场景

  • Orchestrated review: Used as a cognitive step when review-code runs scope → language → framework → library → cognitive.
  • Architecture-focused review: When the user wants only boundaries, dependencies, and structure checked.
  • Refactor or onboarding: Understand and critique current structure for planning or documentation.
When to use: When the task includes architecture or design review. Scope and code scope are determined by the caller or user.
  • 协同评审：作为review-code执行流程（范围→语言→框架→库→认知）中的认知步骤使用。
  • 聚焦架构的评审：当用户仅希望检查边界、依赖关系和结构时使用。
  • 重构或新人入职：为规划或文档编写，理解并评估当前代码结构。
适用时机：当任务包含架构或设计评审时。评审范围和代码范围由调用方或用户确定。

Behavior

行为规范

Scope of this skill

本技能的范围

  • Analyze: Architecture dimensions in the given code scope (files or diff provided by the caller). Do not decide scope; accept the code range as input. For large scope, consider layers or modules and summarize.
  • Do not: Perform scope selection, language/framework conventions, or security review. Focus only on architecture and structure.
  • 分析：在给定的代码范围（调用方提供的文件或差异）内的架构维度。不要自行决定范围；接受传入的代码范围作为输入。对于大范围，可按分层或模块进行总结。
  • 禁止操作：不要选择评审范围，不要进行语言/框架规范检查或安全评审。仅专注于架构和结构。

Review checklist (architecture dimension only)

评审检查清单（仅架构维度）

  1. Module and layer boundaries: Are module/service boundaries clear? Are layers (e.g. API, domain, data) respected? Do high-level modules avoid depending on low-level details?
  2. Dependency direction: Do dependencies point in the intended direction (e.g. inward toward domain, or toward stable abstractions)? No reverse or circular dependency direction at module level.
  3. Single responsibility: Does each module/class have one clear responsibility? Are boundaries cohesive?
  4. Cyclic dependencies: Are there cycles between modules, packages, or components? Suggest break points (e.g. extract interface, move shared code).
  5. Interface stability: Are public APIs and interfaces stable and minimal? Are implementation details leaking across boundaries?
  6. Coupling and extension points: Is coupling to concrete types or frameworks minimized where extension is expected? Are extension points (e.g. plugins, strategies) clear?
  1. 模块与分层边界：模块/服务边界是否清晰？分层（如API、domain、data）是否被遵守？高层模块是否避免依赖底层细节？
  2. 依赖方向：依赖是否符合预期方向（如向内指向domain，或指向稳定的抽象）？模块层面是否存在反向或循环依赖？
  3. 单一职责：每个模块/类是否有明确的单一职责？边界是否内聚？
  4. 循环依赖：模块、包或组件之间是否存在循环依赖？建议拆分点（如提取接口、迁移共享代码）。
  5. 接口稳定性：公共API和接口是否稳定且精简？实现细节是否跨边界泄露？
  6. 耦合性与扩展点：在预期需要扩展的场景中，是否最小化了对具体类型或框架的耦合？扩展点（如插件、策略）是否清晰？

Tone and references

语气与参考

  • Professional and technical: Reference specific locations (file, module, or package). Emit findings with Location, Category, Severity, Title, Description, Suggestion.
  • 专业且技术化：引用具体位置（文件、模块或包）。输出的问题发现需包含位置、类别、严重程度、标题、描述、建议。

Input & Output

输入与输出

Input

输入

  • Code scope: Files or directories (or diff) already selected by the user or scope skill. This skill does not decide scope; it reviews the provided code for architecture only.
  • 代码范围：用户或范围技能已选定的文件、目录（或差异）。本技能不决定范围；仅针对提供的代码进行架构评审。

Output

输出

  • Emit zero or more findings in the format defined in Appendix: Output contract.
  • Category for this skill is cognitive-architecture.
  • 按照附录：输出约定中定义的格式，输出零个或多个问题发现。
  • 本技能的类别为cognitive-architecture。

Restrictions

限制条件

  • Do not perform scope selection, language, framework, or security review. Stay within architecture dimensions.
  • Do not give conclusions without specific locations or actionable suggestions.
  • Do not assume a specific architecture style (e.g. clean/hexagonal) unless the project states it; evaluate against general boundaries and dependency principles.
  • 请勿自行选择范围，也不要进行语言、框架或安全评审。仅专注于架构维度。
  • 请勿在没有具体位置或可操作建议的情况下给出结论。
  • 请勿假设特定的架构风格（如整洁架构/六边形架构），除非项目明确说明；需基于通用的边界和依赖原则进行评估。

Self-Check

自我检查

  • Was only the architecture dimension reviewed (no scope/language/security)?
  • Are boundaries, dependency direction, responsibility, cycles, interfaces, and coupling covered where relevant?
  • Is each finding emitted with Location, Category=cognitive-architecture, Severity, Title, Description, and optional Suggestion?
  • Are module/package/file references precise enough to act on?
  • 是否仅评审了架构维度（未涉及范围/语言/安全）？
  • 是否覆盖了相关的边界、依赖方向、职责、循环依赖、接口及耦合性问题？
  • 每个问题发现是否包含位置、类别=cognitive-architecture、严重程度、标题、描述及可选的建议？
  • 模块/包/文件的引用是否足够精确，便于执行后续操作？

Examples

示例

Example 1: Reverse dependency

示例1：反向依赖

  • Input: Domain layer imports from infrastructure (e.g. DB driver) directly.
  • Expected: Emit a finding for dependency direction; suggest interface in domain and implementation in infrastructure. Category = cognitive-architecture.
  • 输入：Domain层直接导入基础设施层（如数据库驱动）。
  • 预期输出：输出一个关于依赖方向的问题发现；建议在domain层定义接口，在基础设施层实现。类别 = cognitive-architecture。

Example 2: Cycle between packages

示例2：包之间的循环依赖

  • Input: Package A imports B, B imports C, C imports A.
  • Expected: Emit finding(s) identifying the cycle and suggest break point (e.g. extract shared interface or type to a neutral package). Category = cognitive-architecture.
  • 输入：包A导入B，B导入C，C导入A。
  • 预期输出：输出问题发现，识别循环依赖并建议拆分点（如将共享接口或类型提取到中立包中）。类别 = cognitive-architecture。

Edge case: Small or single-file scope

边缘案例：小范围或单文件

  • Input: Single file or very small module.
  • Expected: Review internal structure (responsibility, coupling to external types); if scope is too small for module-level concerns, state that and emit only findings that apply (e.g. single responsibility, interface clarity).
  • 输入：单个文件或非常小的模块。
  • 预期输出：评审内部结构（职责、与外部类型的耦合性）；如果范围过小，无法进行模块级别的检查，则说明情况，仅输出适用的问题发现（如单一职责、接口清晰度）。

Appendix: Output contract

附录：输出约定

Each finding MUST follow the standard findings format:
ElementRequirement
Location
path/to/file.ext
or module/package name (optional line or range).
Category
cognitive-architecture
.
Severity
critical
| 
major
| 
minor
| 
suggestion
.
TitleShort one-line summary.
Description1–3 sentences.
SuggestionConcrete fix or improvement (optional).
Example:
markdown
- **Location**: `pkg/domain/order.go`
- **Category**: cognitive-architecture
- **Severity**: major
- **Title**: Domain imports infrastructure directly
- **Description**: Order service imports DB driver; domain should not depend on infrastructure.
- **Suggestion**: Define repository interface in domain; implement in infrastructure and inject.
每个问题发现必须遵循标准格式：
元素要求
位置
path/to/file.ext
或模块/包名称（可选行号或范围）。
类别
cognitive-architecture
。
严重程度
critical
| 
major
| 
minor
| 
suggestion
。
标题简短的单行摘要。
描述1–3句话。
建议具体的修复或改进方案（可选）。
示例：
markdown
- **Location**: `pkg/domain/order.go`
- **Category**: cognitive-architecture
- **Severity**: major
- **Title**: Domain imports infrastructure directly
- **Description**: Order service imports DB driver; domain should not depend on infrastructure.
- **Suggestion**: Define repository interface in domain; implement in infrastructure and inject.