codeprobe-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Standalone Mode

独立模式

If invoked directly (not via the orchestrator), you must first:

Read
```
../codeprobe/shared-preamble.md
```
for the output contract, execution modes, and constraints.
Load applicable reference files from
```
../codeprobe/references/
```
based on the project's tech stack.
Default to
```
full
```
mode unless the user specifies otherwise.

如果直接调用（不通过编排器），您必须先执行以下步骤：

阅读
```
../codeprobe/shared-preamble.md
```
以了解输出约定、执行模式和约束条件。
根据项目技术栈加载
```
../codeprobe/references/
```
中的适用参考文件。
除非用户另行指定，否则默认使用
```
full
```
模式。

Architecture & Structure Analyzer

架构与结构分析器

Domain Scope

适用范围

This sub-skill detects architectural and structural issues across these categories:

Layer Violations — Business logic in controllers, presentation logic in models, database access in views
Circular Dependencies — Direct or transitive circular imports between modules
God Objects — Oversized files and classes that do too much
Anemic Domain Model — Entity classes with no behavior, all logic in service classes
Missing Boundaries — No clear module/domain separation, cross-feature coupling
Directory Structure — Framework convention violations, flat directory anti-patterns
Config/Environment — Hardcoded environment values, missing config abstraction

此子技能检测以下类别的架构和结构问题：

层违规——控制器中包含业务逻辑、模型中包含表示逻辑、视图中包含数据库访问
循环依赖——模块之间存在直接或间接的循环导入
上帝对象（God Objects）——过大的文件和类，承担过多职责
贫血领域模型——实体类无行为，所有逻辑都在服务类中
边界缺失——模块/领域分离不清晰，跨功能耦合
目录结构——违反框架约定，扁平化目录反模式
配置/环境——硬编码环境值，缺少配置抽象

What It Does NOT Flag

不标记的情况

Small projects/scripts with fewer than 5 files — flat structure is appropriate for small codebases and adding layers would be over-engineering.
Microservices that intentionally have thin layers — a microservice with a single controller, single service, and single repository is fine by design.
Framework-standard monolith patterns that are idiomatic — e.g., Laravel's default structure for small-to-medium apps, Rails convention-over-configuration patterns, Next.js app directory conventions.
Prototypes and proof-of-concept code clearly marked as such.
Generated code directories (e.g.,
```
dist/
```
,
```
build/
```
,
```
.next/
```
,
```
__pycache__/
```
).

小型项目/脚本（文件数量少于5个）——扁平化结构适用于小型代码库，添加分层属于过度设计。
微服务（有意采用精简分层）——设计上仅包含单个控制器、单个服务和单个仓库的微服务是合理的。
符合框架标准的单体模式——例如Laravel针对中小型应用的默认结构、Rails的约定优于配置模式、Next.js应用目录约定。
明确标记为原型或概念验证的代码。
生成的代码目录（如
```
dist/
```
、
```
build/
```
、
```
.next/
```
、
```
__pycache__/
```
）。

Detection Instructions

检测说明

Layer Violations

层违规

ID Prefix	What to Detect	How to Detect	Severity
`ARCH`	Controllers containing business logic	Scan files in controller directories ( `controllers/` , `Controllers/` , `routes/` , `api/` ). Flag controllers that contain: database queries (SQL, ORM query builders beyond simple `find()` / `findById()` ), complex conditionals with business rules (3+ branches), calculations, data transformations, or validation logic beyond simple field presence checks. Controllers should delegate to services/actions.	Major
`ARCH`	Models/entities containing presentation logic	Scan model/entity files. Flag models that contain: HTML generation, string formatting for display (e.g., `toHtml()` , `formatForDisplay()` ), view-specific transformations, CSS class computation, or response formatting. Models should contain domain logic, not presentation.	Major
`ARCH`	Views/components calling database directly	Scan view files ( `.blade.php` , `.vue` , `.jsx` / `.tsx` components, `.ejs` , `.pug` , Jinja templates). Flag views that contain: direct database queries, ORM calls, raw SQL, or repository method calls. Views should receive data from controllers/props, never fetch it themselves.	Critical

ID前缀	检测内容	检测方式	严重程度
`ARCH`	控制器包含业务逻辑	扫描控制器目录（ `controllers/` 、 `Controllers/` 、 `routes/` 、 `api/` ）下的文件。标记包含以下内容的控制器：数据库查询（SQL、ORM查询构建器，简单 `find()` / `findById()` 除外）、包含业务规则的复杂条件判断（3个以上分支）、计算、数据转换或超出简单字段存在性检查的验证逻辑。控制器应将职责委托给服务/动作类。	主要
`ARCH`	模型/实体包含表示逻辑	扫描模型/实体文件。标记包含以下内容的模型：HTML生成、用于展示的字符串格式化（如 `toHtml()` 、 `formatForDisplay()` ）、视图特定转换、CSS类计算或响应格式化。模型应包含领域逻辑，而非表示逻辑。	主要
`ARCH`	视图/组件直接调用数据库	扫描视图文件（ `.blade.php` 、 `.vue` 、 `.jsx` / `.tsx` 组件、 `.ejs` 、 `.pug` 、Jinja模板）。标记包含以下内容的视图：直接数据库查询、ORM调用、原生SQL或仓库方法调用。视图应从控制器/属性接收数据，切勿自行获取数据。	严重

Circular Dependencies

循环依赖

ID Prefix	What to Detect	How to Detect	Severity
`ARCH`	Module A imports B, B imports A (direct or transitive)	Trace import/require/use statements across files. Build a dependency graph for modules/directories. Look for: (1) direct cycles — file A imports file B, file B imports file A, (2) transitive cycles — A imports B, B imports C, C imports A. Focus on module-level (directory-level) cycles which are more architecturally significant than file-level cycles within the same module. Report the specific import chain.	Major

ID前缀	检测内容	检测方式	严重程度
`ARCH`	模块A导入B，B导入A（直接或间接）	追踪文件间的import/require/use语句。构建模块/目录的依赖关系图。查找：(1) 直接循环——文件A导入文件B，文件B导入文件A；(2) 间接循环——A导入B，B导入C，C导入A。重点关注模块级（目录级）循环，这比同一模块内的文件级循环更具架构层面的重要性。报告具体的导入链。	主要

God Objects

上帝对象

ID Prefix	What to Detect	How to Detect	Severity
`ARCH`	File exceeds 500 LOC	Count total lines in each source file (excluding blank lines and comments). Flag files exceeding 500 LOC. For files exceeding 1000 LOC, escalate to critical.	Major
`ARCH`	Class with 20+ methods	Count public, protected, and private methods in each class. Flag classes with 20+ methods. List the method groups to suggest how the class could be split.	Major
`ARCH`	Single file handling request-to-response lifecycle	Look for files that handle the full request lifecycle: receiving/parsing the request, validating input, executing business logic, performing persistence, formatting the response, and logging — all in one file or class. Flag when 4+ of these concerns are in a single file.	Major

ID前缀	检测内容	检测方式	严重程度
`ARCH`	文件超过500 LOC	统计每个源文件的总行数（排除空行和注释）。标记超过500 LOC的文件。对于超过1000 LOC的文件，升级为严重级别。	主要
`ARCH`	类包含20个以上方法	统计每个类的公共、受保护和私有方法数量。标记包含20个以上方法的类。列出方法组以建议如何拆分该类。	主要
`ARCH`	单个文件处理请求到响应的完整生命周期	查找处理完整请求生命周期的文件：接收/解析请求、验证输入、执行业务逻辑、执行持久化、格式化响应和日志记录——所有操作都在单个文件或类中完成。当单个文件包含4个以上此类关注点时进行标记。	主要

Anemic Domain Model

贫血领域模型

ID Prefix	What to Detect	How to Detect	Severity
`ARCH`	Entity/model classes with only getters/setters, zero behavior	Scan model/entity classes. If a class has only property declarations, getters, setters, and constructor assignment — with no business logic methods (no validation, no calculations, no state transitions, no domain rules) — it is an anemic entity.	Minor
`ARCH`	All logic in "Service" classes operating on dumb data bags	Check if the codebase has a pattern where entity classes are pure data containers and all behavior (validation, calculation, state transitions) lives in separate `*Service` classes that manipulate the entity externally. Flag when this pattern is pervasive (3+ services operating on the same entity).	Minor

ID前缀	检测内容	检测方式	严重程度
`ARCH`	实体/模型类仅包含getter/setter，无任何行为	扫描模型/实体类。如果类仅包含属性声明、getter、setter和构造函数赋值——无业务逻辑方法（无验证、无计算、无状态转换、无领域规则）——则属于贫血实体。	次要
`ARCH`	所有逻辑都在操作哑数据容器的"Service"类中	检查代码库是否存在以下模式：实体类是纯数据容器，所有行为（验证、计算、状态转换）都在单独的 `*Service` 类中，通过外部操作实体。当此模式普遍存在（3个以上服务操作同一实体）时进行标记。	次要

Missing Boundaries

边界缺失

ID Prefix	What to Detect	How to Detect	Severity
`ARCH`	No clear module/domain separation in medium+ projects	For projects with 20+ source files, check whether the code is organized into modules, domains, or bounded contexts. If all source files live in a single flat directory or are only separated by technical layer (controllers/, models/, services/) with no domain grouping, flag it.	Major
`ARCH`	Shared database tables accessed directly across unrelated features	Search for the same database table name, model, or entity being imported/queried from multiple unrelated modules or feature directories. If `users` table is accessed from `billing/` , `notifications/` , `reports/` , and `admin/` without going through a shared `user` module, flag it.	Major
`ARCH`	Cross-feature direct imports instead of events/interfaces	Check whether feature modules import directly from other feature modules' internal files. For example, `billing/InvoiceService` importing `shipping/ShippingCalculator` directly instead of through an interface or event system. Flag tight inter-feature coupling.	Minor

ID前缀	检测内容	检测方式	严重程度
`ARCH`	中型及以上项目无清晰的模块/领域分离	对于包含20个以上源文件的项目，检查代码是否按模块、领域或限界上下文组织。如果所有源文件都位于单个扁平化目录中，或仅按技术层（controllers/、models/、services/）分离而无领域分组，则进行标记。	主要
`ARCH`	共享数据库表被跨无关功能直接访问	搜索同一数据库表名、模型或实体被多个无关模块或功能目录导入/查询的情况。例如 `users` 表被 `billing/` 、 `notifications/` 、 `reports/` 和 `admin/` 直接访问，而未通过共享的 `user` 模块，则进行标记。	主要
`ARCH`	跨功能直接导入，未使用事件/接口	检查功能模块是否直接导入其他功能模块的内部文件。例如 `billing/InvoiceService` 直接导入 `shipping/ShippingCalculator` ，而非通过接口或事件系统。标记这种紧密的跨功能耦合。	次要

Directory Structure

目录结构

ID Prefix	What to Detect	How to Detect	Severity
`ARCH`	Framework conventions violated	Check whether the project follows its framework's expected directory structure. Examples: business logic classes in a `Controllers/` directory, SQL queries in view templates, route definitions scattered across non-route files, test files mixed with source files without naming convention.	Minor
`ARCH`	No separation between layers for 20+ files	For projects with 20+ source files, check whether there is any directory-based separation between layers (controllers, services, models, views) or domains. If everything lives in one flat directory, flag it.	Major

ID前缀	检测内容	检测方式	严重程度
`ARCH`	违反框架约定	检查项目是否遵循其框架的预期目录结构。示例：业务逻辑类位于 `Controllers/` 目录中、SQL查询位于视图模板中、路由定义分散在非路由文件中、测试文件与源文件混合且无命名约定。	次要
`ARCH`	20个以上文件无分层分离	对于包含20个以上源文件的项目，检查是否存在基于目录的分层分离（控制器、服务、模型、视图）或领域分离。如果所有文件都位于一个扁平化目录中，则进行标记。	主要

Config/Environment

配置/环境

ID Prefix	What to Detect	How to Detect	Severity
`ARCH`	Hardcoded environment-specific values in source code	Search for hardcoded URLs ( `http://localhost` , `https://api.example.com` ), port numbers ( `:3000` , `:8080` , `:5432` ), hostnames, IP addresses, and file system paths in source code files (not config files). These should come from environment variables or config.	Major
`ARCH`	Missing environment abstraction	Check whether the project has an environment abstraction layer ( `.env` file + config loader, environment variables, config service). If source files read `process.env.X` or `os.environ['X']` directly in 5+ places without a centralized config module, or if there is no `.env` /config layer at all, flag it.	Minor

ID前缀	检测内容	检测方式	严重程度
`ARCH`	源代码中硬编码特定环境的值	在源文件（非配置文件）中搜索硬编码的URL（ `http://localhost` 、 `https://api.example.com` ）、端口号（ `:3000` 、 `:8080` 、 `:5432` ）、主机名、IP地址和文件系统路径。这些值应来自环境变量或配置。	主要
`ARCH`	缺少环境抽象	检查项目是否有环境抽象层（ `.env` 文件+配置加载器、环境变量、配置服务）。如果源文件在5个以上位置直接读取 `process.env.X` 或 `os.environ['X']` ，而无集中式配置模块，或者根本没有 `.env` /配置层，则进行标记。	次要

Using

file_stats.py

使用

file_stats.py

When available, run the file_stats.py script via Bash to get LOC, class count, and method count per file. The script is located in the

review

skill's

scripts/

directory (resolve relative to the skill installation, not the user's project):

bash

python3 scripts/file_stats.py <target_path>

Note: The orchestrator typically runs this script and passes results. If invoked standalone, locate the script in the sibling

codeprobe/scripts/

directory.

Use this data to:

Identify god objects (files > 500 LOC, classes with 20+ methods)
Find the largest files in the project
Get accurate LOC counts for the summary

If Python 3 or the

file_stats.py

script is unavailable, estimate from reading files directly using Read. Do not fail the analysis — proceed with manual counting.

当可用时，通过Bash运行

file_stats.py

脚本以获取每个文件的LOC、类数量和方法数量。该脚本位于

review

技能的

scripts/

目录中（相对于技能安装路径解析，而非用户项目路径）：

bash

python3 scripts/file_stats.py <target_path>

注意：编排器通常会运行此脚本并传递结果。如果是独立调用，请在同级的

codeprobe/scripts/

目录中查找该脚本。

使用此数据来：

识别上帝对象（文件超过500 LOC，类包含20个以上方法）
查找项目中最大的文件
为摘要获取准确的LOC统计

如果Python 3或

file_stats.py

脚本不可用，请通过直接读取文件进行估算。请勿终止分析——继续手动计数。

ID Prefix & Fix Prompt Examples

ID前缀及修复提示示例

All findings use the

ARCH-

prefix, numbered sequentially:

ARCH-001

ARCH-002

, etc.

所有检测结果使用

ARCH-

前缀，并按顺序编号：

ARCH-001

、

ARCH-002

等。

Fix Prompt Examples

修复提示示例

"Move the pricing calculation logic from
```
OrderController@store
```
(lines 40-75) into a new
```
PricingService
```
class under
```
app/Services/
```
. The controller should inject
```
PricingService
```
and call
```
$this->pricingService->calculate($order)
```
. The controller should only handle request parsing, service delegation, and response formatting."
"Break
```
UserManager
```
(850 LOC) into focused services: extract authentication methods (lines 50-200) into
```
UserAuthService
```
, profile management (lines 201-450) into
```
UserProfileService
```
, and notification methods (lines 451-700) into
```
UserNotificationService
```
.
```
UserManager
```
becomes a thin facade that delegates to these three services."
"Resolve the circular dependency between
```
billing/InvoiceService
```
and
```
shipping/ShippingCalculator
```
: extract the shared interface
```
ShippingCostProvider
```
into a
```
shared/contracts/
```
directory. Have
```
ShippingCalculator
```
implement
```
ShippingCostProvider
```
, and have
```
InvoiceService
```
depend on the interface instead of the concrete class."

"Replace the hardcoded URL

http://localhost:3000/api

at line 23 of

src/services/ApiClient.ts

with an environment variable: use

process.env.API_BASE_URL

loaded through the config module. Add

API_BASE_URL=http://localhost:3000/api

.env.example

"Create a domain-based directory structure: move
```
UserController
```
,
```
UserService
```
,
```
UserRepository
```
, and
```
UserPolicy
```
into a
```
app/Domains/User/
```
directory. Repeat for
```
Order
```
,
```
Payment
```
, and
```
Notification
```
domains. Each domain directory should contain its own controllers, services, models, and policies."

"将
```
OrderController@store
```
（第40-75行）中的定价计算逻辑移至
```
app/Services/
```
下的新
```
PricingService
```
类中。控制器应注入
```
PricingService
```
并调用
```
$this->pricingService->calculate($order)
```
。控制器应仅处理请求解析、服务委托和响应格式化。"
"将
```
UserManager
```
（850 LOC）拆分为专注的服务：将认证方法（第50-200行）提取到
```
UserAuthService
```
，将资料管理方法（第201-450行）提取到
```
UserProfileService
```
，将通知方法（第451-700行）提取到
```
UserNotificationService
```
。
```
UserManager
```
变为一个精简的外观类，委托给这三个服务。"

"解决

billing/InvoiceService

与

shipping/ShippingCalculator

之间的循环依赖：将共享接口

ShippingCostProvider

提取到

shared/contracts/

目录中。让

ShippingCalculator

实现

ShippingCostProvider

，并让

InvoiceService

依赖于该接口而非具体类。"

"将

src/services/ApiClient.ts

第23行的硬编码URL

http://localhost:3000/api

替换为环境变量：使用通过配置模块加载的

process.env.API_BASE_URL

。将

API_BASE_URL=http://localhost:3000/api

添加到

.env.example

中。"

"创建基于领域的目录结构：将
```
UserController
```
、
```
UserService
```
、
```
UserRepository
```
和
```
UserPolicy
```
移至
```
app/Domains/User/
```
目录中。对
```
Order
```
、
```
Payment
```
和
```
Notification
```
领域重复此操作。每个领域目录应包含自己的控制器、服务、模型和策略。"

codeprobe-architecture

Original

Translation

Standalone Mode

独立模式

Architecture & Structure Analyzer

架构与结构分析器

Domain Scope

适用范围

What It Does NOT Flag

不标记的情况

Detection Instructions

检测说明

Layer Violations

层违规

Circular Dependencies

循环依赖

God Objects

上帝对象

Anemic Domain Model

贫血领域模型

Missing Boundaries

边界缺失

Directory Structure

目录结构

Config/Environment

配置/环境

Using
`file_stats.py`

使用
`file_stats.py`

ID Prefix & Fix Prompt Examples

ID前缀及修复提示示例

Fix Prompt Examples

修复提示示例

codeprobe-architecture

Original

Translation

Standalone Mode

独立模式

Architecture & Structure Analyzer

架构与结构分析器

Domain Scope

适用范围

What It Does NOT Flag

不标记的情况

Detection Instructions

检测说明

Layer Violations

层违规

Circular Dependencies

循环依赖

God Objects

上帝对象

Anemic Domain Model

贫血领域模型

Missing Boundaries

边界缺失

Directory Structure

目录结构

Config/Environment

配置/环境

Using file_stats.py

使用file_stats.py

ID Prefix & Fix Prompt Examples

ID前缀及修复提示示例

Fix Prompt Examples

修复提示示例

Using
`file_stats.py`

使用
`file_stats.py`