modularity

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

/modularity — Modular Design Enforcement

/modularity — 模块化设计强制规范

Every design, plan, and implementation MUST produce small, focused modules where any single change touches the fewest files possible and every touched file fits comfortably in context.

Why this matters: When files are large or tightly coupled, Claude must compact context to fit them — risking loss of key details. Modular design prevents this by keeping each unit small enough to reason about completely.

When to invoke: During PLANNING (after brainstorming, before or alongside writing-plans) and during REVIEW (as part of code review criteria). This skill applies to both new code and modifications to existing code.

所有设计、规划和实现工作都必须产出小而聚焦的模块，确保任何单次变更涉及的文件数量尽可能少，且每个被修改的文件都能完整放入上下文范围内。

为什么这很重要： 当文件体积过大或耦合度太高时，Claude 必须压缩上下文才能容纳这些内容，这会导致关键信息丢失的风险。模块化设计可以避免这个问题，它能让每个单元都小到可以被完整理解。

适用场景： 规划阶段（头脑风暴后，编写计划前或编写计划的同时）和评审阶段（作为代码评审标准的一部分）。本规范同时适用于新代码开发和现有代码修改。

The Rules

规则

Rule 1: File Size Limits

规则1：文件大小限制

File type	Soft limit	Hard limit	Action at hard limit
Source code (logic)	150 lines	300 lines	MUST split before proceeding
Test files	200 lines	400 lines	MUST split into focused test suites
Config / data	100 lines	200 lines	MUST split into per-concern configs
Documentation	300 lines	500 lines	MUST split into linked pages

Soft limit: Refactor soon. Flag in code review. Hard limit: Do not proceed. Split first, then continue.

Line counts exclude blank lines and comments. If a file approaches the soft limit during implementation, split it before the next commit — not "later."

文件类型	软限制	硬限制	触发硬限制后的操作
源代码（逻辑层）	150 行	300 行	必须先拆分再继续开发
测试文件	200 行	400 行	必须拆分为聚焦的测试套件
配置/数据文件	100 行	200 行	必须按关注点拆分为独立配置
文档	300 行	500 行	必须拆分为可互相链接的页面

软限制： 尽快重构，在代码评审中标记。 硬限制： 禁止继续开发，先拆分再继续。

行数统计不包含空行和注释。如果开发过程中某个文件接近软限制，要在下次提交前拆分，不要等「以后」。

Rule 2: Single Responsibility Per File

规则2：每个文件单一职责

Every file answers ONE question:

"What does this file do?" must have a one-sentence answer.
If the answer contains "and," the file does too much — split it.
If two developers could work on different parts of the file simultaneously on unrelated tasks, it should be two files.

每个文件只解决一个问题：

「这个文件是做什么的？」这个问题必须能用一句话回答。
如果回答里包含「和/以及」，说明文件承担的职责太多，需要拆分。
如果两个开发者可以同时在同一个文件的不同部分开发互不相关的功能，那这个文件应该拆分为两个。

Rule 3: Change Locality

规则3：变更局部性

Design so that any single feature, fix, or change touches at most 3-5 files (excluding tests). If a change requires touching more than 5 source files:

STOP. The design has a coupling problem.
Identify which files are changing for the same reason — they should share an abstraction.
Identify which files are changing for different reasons — they need a cleaner interface between them.

设计时要确保任何单个功能、修复或变更最多只涉及 3-5 个文件（测试文件除外）。如果一个变更需要修改超过5个源代码文件：

立刻停止，你的设计存在耦合问题。
找出因为相同原因需要修改的文件，它们应该共享一层抽象。
找出因为不同原因需要修改的文件，它们之间需要更清晰的接口。

Rule 4: Interface-First Design

规则4：接口优先设计

Before writing any implementation:

Define the module's public interface — what it exposes to consumers.
Define its dependencies — what it imports/requires.
The interface should be understandable without reading the implementation.
Consumers should never need to know implementation details.

If you can't define the interface in <10 lines, the module is too complex — decompose further.

编写任何实现代码前：

定义模块的 公共接口（public interface） —— 即它对外暴露的内容。
定义它的 依赖（dependencies） —— 即它导入/需要的内容。
无需阅读实现代码就能理解接口的作用。
调用方永远不需要了解实现细节。

如果你不能用10行以内的代码定义接口，说明模块过于复杂，需要进一步拆分。

Rule 5: Context-Window-Aware Decomposition

规则5：结合上下文窗口考量的模块拆分

When designing a system, apply this test to every module:

"Can Claude read this file, its tests, and the files it directly depends on — all at once — without exceeding context or needing to compact?"

If no: the module is too large or has too many dependencies. Decompose until the answer is yes.

Practical guideline: Any single task (implement, fix, review) should require reading at most 5-7 files totaling under 1500 lines. Design the system to make this true.

设计系统时，对每个模块都做如下测试：

「Claude 能否同时读取这个文件、它的测试文件以及它直接依赖的所有文件，不超出上下文窗口限制，也不需要压缩内容？」

如果答案是否定的：说明模块太大或者依赖太多，继续拆分直到答案为是。

实操指南： 任何单个任务（实现、修复、评审）需要阅读的文件最多不超过5-7个，总代码行数不超过1500行。系统设计要满足这个要求。

Rule 6: Dependency Direction

规则6：依赖方向

Dependencies flow ONE direction (no circular imports).
High-level modules depend on abstractions, not low-level details.
If module A imports module B and module B imports module A, extract the shared concern into module C.

依赖只能单向流动（禁止循环导入）。
高层模块依赖抽象，而非底层细节。
如果模块A导入模块B，同时模块B导入模块A，把公共逻辑抽离到模块C中。

Rule 7: Co-location

规则7：关联文件就近放置

Files that change together live together. Organize by feature/domain, not by technical layer.

WRONG (layer-based):
  controllers/user.ts
  controllers/order.ts
  services/user.ts
  services/order.ts
  models/user.ts
  models/order.ts

RIGHT (feature-based):
  user/controller.ts
  user/service.ts
  user/model.ts
  order/controller.ts
  order/service.ts
  order/model.ts

When a change to "users" only touches files in

user/

, modularity is working.

会一起修改的文件放在一起。按功能/领域组织文件结构，而非技术层级。

WRONG (layer-based):
  controllers/user.ts
  controllers/order.ts
  services/user.ts
  services/order.ts
  models/user.ts
  models/order.ts

RIGHT (feature-based):
  user/controller.ts
  user/service.ts
  user/model.ts
  order/controller.ts
  order/service.ts
  order/model.ts

如果修改「用户」相关逻辑只需要改动

user/

目录下的文件，说明模块化设计是有效的。

Applying This Skill

本规范的应用方法

During Planning (brainstorming / writing-plans)

规划阶段（头脑风暴/编写计划）

During Implementation (executing-plans)

开发阶段（执行计划）

As you write code:

Check file size after each commit. If approaching the soft limit, split NOW.
If a function grows beyond 30 lines, extract sub-functions or a helper module.
If you're adding a new feature and touching >5 files, stop and ask: "Is there a missing abstraction?"

编写代码时：

每次提交后检查文件大小，如果接近软限制，立刻拆分。
如果某个函数超过30行，抽离子函数或者辅助模块。
如果你要开发新功能，需要修改超过5个文件，停下来问问自己：「是不是缺少了一层抽象？」

During Review (code-review / receiving-code-review)

评审阶段（代码评审/接收代码评审）

Verify these as part of every code review:

No file exceeds the hard limit
Each file's responsibility is clear and singular
Change locality: the PR touches a reasonable number of files
No circular dependencies introduced
New modules have well-defined interfaces

每次代码评审都要验证以下几点：

没有文件超出硬限制
每个文件的职责清晰且单一
变更局部性：PR涉及的文件数量合理
没有引入循环依赖
新模块有定义清晰的接口

When Modifying Existing Code

修改现有代码时

If existing code violates these rules:

You are NOT required to fix all violations in unrelated files.
You ARE required to not make violations worse.
If the file you're modifying already exceeds the hard limit, include a split as part of your change.
If your change would push a file past the soft limit, split first.

如果现有代码违反了这些规则：

你不需要修复不相关文件里的所有违规问题。
你不能让违规问题变得更严重。
如果你要修改的文件已经超出硬限制，把拆分工作纳入你的变更内容里。
如果你的变更会把某个文件推到软限制以上，先拆分再修改。

Splitting Strategies

拆分策略

When a file needs to be split, use these patterns:

By sub-feature:

auth.ts

→

auth/login.ts

auth/register.ts

auth/token.ts

By abstraction level:

api.ts

→

api/routes.ts

api/middleware.ts

api/validation.ts

By data type:

utils.ts

→

string-utils.ts

date-utils.ts

array-utils.ts

Extract shared logic: If two files share helper functions, extract to a shared module rather than duplicating.

当某个文件需要拆分时，可以使用这些模式：

按子功能拆分：

auth.ts

→

auth/login.ts

auth/register.ts

auth/token.ts

按抽象层级拆分：

api.ts

→

api/routes.ts

api/middleware.ts

api/validation.ts

按数据类型拆分：

utils.ts

→

string-utils.ts

date-utils.ts

array-utils.ts

抽离公共逻辑： 如果两个文件有相同的辅助函数，抽离到公共模块，不要重复编写。

Anti-Patterns

反模式

Pattern	Problem	Fix
"God file" — one file does everything	Impossible to change safely	Split by responsibility
"Shotgun surgery" — one change touches 10+ files	Missing abstraction	Extract shared concern
"Barrel files" re-exporting everything	Hides dependency structure	Import directly from source
Premature abstraction for one use case	Unnecessary complexity	Three similar blocks > one premature abstraction
Layer-based organization	Unrelated files change together	Reorganize by feature
"Utils" or "helpers" grab-bag	No clear responsibility	Split by domain or delete

反模式	问题	修复方案
「上帝文件（God file）」—— 单个文件承担所有职责	无法安全地做修改	按职责拆分
「霰弹式修改（Shotgun surgery）」—— 单次变更涉及10个以上的文件	缺少抽象	抽离公共关注点
「桶文件（Barrel files）」导出所有内容	隐藏依赖结构	直接从源文件导入
为单个使用场景提前做抽象	不必要的复杂度	三个相似的代码块 > 一个不成熟的抽象
按层级组织文件结构	不相关的文件会一起被修改	按功能重新组织
「Utils」或「helpers」大杂烩	没有清晰的职责	按领域拆分或者删除

Rationalization Prevention

避免合理化借口

Excuse	Reality
"It's just one more function"	That's how 800-line files happen. Split now.
"Splitting will create too many files"	Many small files > few large files. Always.
"I'll refactor later"	You won't. The soft limit exists to prevent this.
"This file is the natural home for this"	If it exceeds the limit, it's not. Find a better home.
"It's all related"	Related is not the same as same-responsibility.
"The framework forces this structure"	Most frameworks work fine with smaller modules. Check.

借口	现实
「就多加一个函数而已」	800行的大文件就是这么来的，现在就拆分。
「拆分后文件太多了」	多而小的文件永远好过少而大的文件。
「我以后再重构」	你不会的。软限制的存在就是为了避免这种情况。
「这个文件本来就该放这个逻辑」	如果它超出了大小限制，就不该放。找个更合适的位置。
「这些内容都是相关的」	相关不等于职责相同。
「框架强制要求这个结构」	绝大多数框架都支持更小的模块，核实一下。