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)

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

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?
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.
Single responsibility: Does each module/class have one clear responsibility? Are boundaries cohesive?
Cyclic dependencies: Are there cycles between modules, packages, or components? Suggest break points (e.g. extract interface, move shared code).
Interface stability: Are public APIs and interfaces stable and minimal? Are implementation details leaking across boundaries?
Coupling and extension points: Is coupling to concrete types or frameworks minimized where extension is expected? Are extension points (e.g. plugins, strategies) clear?

模块与分层边界：模块/服务边界是否清晰？分层（如API、domain、data）是否被遵守？高层模块是否避免依赖底层细节？
依赖方向：依赖是否符合预期方向（如向内指向domain，或指向稳定的抽象）？模块层面是否存在反向或循环依赖？
单一职责：每个模块/类是否有明确的单一职责？边界是否内聚？
循环依赖：模块、包或组件之间是否存在循环依赖？建议拆分点（如提取接口、迁移共享代码）。
接口稳定性：公共API和接口是否稳定且精简？实现细节是否跨边界泄露？
耦合性与扩展点：在预期需要扩展的场景中，是否最小化了对具体类型或框架的耦合？扩展点（如插件、策略）是否清晰？

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:

Element	Requirement
Location	`path/to/file.ext` or module/package name (optional line or range).
Category	`cognitive-architecture` .
Severity	`critical` \| `major` \| `minor` \| `suggestion` .
Title	Short one-line summary.
Description	1–3 sentences.
Suggestion	Concrete 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.