evanflow-improve-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

EvanFlow: Improve Architecture

EvanFlow：优化架构

Vocabulary

术语参考

See

evanflow

meta-skill. Key terms: module, interface, depth, seam, adapter, deletion test.

查看

evanflow

元技能。核心术语：module、interface、depth、seam、adapter、deletion test。

When to Use

使用场景

"This file is too big" / "this is hard to follow"
A feature plan reveals friction the existing structure can't accommodate cleanly
Periodic architectural review (Phase D of EvanFlow rollout)
After tests reveal a module has the wrong shape

SKIP when: the user is doing a small, well-scoped change. Don't try to refactor adjacent code.

"这个文件太大了" / "这段代码难以理解"
功能开发计划暴露出现有架构无法顺畅适配的摩擦
定期架构评审（EvanFlow落地的D阶段）
测试显示某个module的设计形态不合理时

跳过场景：用户正在进行范围明确的小型改动。请勿尝试重构关联代码。

The Flow

流程步骤

1. Read Context First

1. 先读取上下文

```
CONTEXT.md
```
(if it exists) — for canonical domain language
```
docs/adr/
```
— for prior architectural decisions you must respect
The target file(s) and their direct callers

```
CONTEXT.md
```
（如果存在）——获取标准领域术语
```
docs/adr/
```
——了解必须遵循的过往架构决策
目标文件及其直接调用方

2. Identify Candidates

2. 识别候选重构点

Walk the codebase noting friction:

A concept that bounces across many modules to be understood
An interface that rivals its implementation in complexity
Files that have grown unwieldy (>400 lines is a smell, >800 is a klaxon)
Conditional logic that branches by concept (suggests two adapters in a missing seam)

遍历代码库，标记以下摩擦点：

一个概念需要跨多个module才能理解
某个interface的复杂度与其实现相当
文件变得臃肿（超过400行是预警信号，超过800行则需紧急处理）
按概念分支的条件逻辑（暗示缺失的seam中需要两个adapter）

3. Apply the Deletion Test

3. 执行删除测试

For each candidate module: "If I deleted this, where would the complexity go?"

Vanishes → the module is bloat; delete it
Concentrates across N callers → the module earns its existence; preserve and possibly deepen it
Moves to one place → the module is a thin pass-through; consider folding it

针对每个候选module思考："如果删除这个module，复杂度会转移到哪里？"

完全消失 → 该module属于冗余代码；直接删除
分散到N个调用方 → 该module有存在价值；保留并可考虑增强其深度
转移到单一位置 → 该module只是简单的中转层；考虑将其合并到目标位置

4. Embedded Grill — Candidate Selection

4. 候选点筛选评估

Before proposing changes, stress-test:

"Which candidate has the highest leverage (improves most caller code)?"
"Which candidate is safest to change (smallest blast radius)?"
"Are there ADRs that constrain the design we're considering?"
"Does the proposed deepening match domain language in
```
CONTEXT.md
```
, or are we inventing new terms?"
"If we change this seam, will it require touching tests that currently bypass the interface? (If yes, the test design is also wrong.)"

在提出改动方案前，先进行压力测试：

"哪个候选点的杠杆效应最高（能最大程度优化调用方代码）？"
"哪个候选点改动风险最低（影响范围最小）？"
是否存在ADR限制了我们正在考虑的设计方案？
"我们提出的深度优化是否符合
```
CONTEXT.md
```
中的领域术语，还是在创造新术语？"
"如果我们修改这个seam，是否需要调整当前绕过该interface的测试？（如果是，说明测试设计也存在问题。）"

5. Present Opportunities

5. 呈现重构机会

For each, name:

File(s) affected
Current shape (what's wrong)
Proposed shape (small interface, complex internals)
Benefits (in domain language from
```
CONTEXT.md
```
)
Cost (estimated PRs, blast radius)

Prioritize. Recommend ONE to tackle next.

针对每个候选点，说明：

受影响文件
当前问题（现有形态的缺陷）
提议形态（简洁的interface，复杂的内部实现）
收益（使用
```
CONTEXT.md
```
中的领域术语描述）
成本（预估PR数量、影响范围）

进行优先级排序。推荐优先处理其中一个。

6. Hand Off Per Opportunity

6. 每个机会独立推进

Each opportunity becomes its own
evanflow-writing-plans
cycle. Do not bundle multiple refactors into one plan — that's a horizontal-slice failure.

If the opportunity changes a public interface, route through

evanflow-design-interface

first.

每个重构机会都将启动独立的
evanflow-writing-plans
循环。请勿将多个重构合并到一个计划中——这属于横向切片错误。

如果重构机会涉及修改公共interface，需先通过

evanflow-design-interface

流程。

Hard Rules

硬性规则

Read
CONTEXT.md
and
docs/adr/
before proposing changes. Domain language and prior decisions must inform the design.
Deletion test first. Don't add abstractions just because they feel cleaner.
One refactor per plan. Bundling refactors hides their individual value and inflates risk.
Two adapters before a seam. Don't introduce variation points hypothetically — wait until two real implementations exist.
Never auto-commit. Refactor PRs are easy to slip past review when batched; keep them small and explicit.

提出改动前必须阅读
CONTEXT.md
和
docs/adr/
。领域术语和过往决策必须作为设计的依据。
先执行删除测试。 不要仅仅因为感觉更简洁就添加抽象层。
一个计划对应一个重构。 合并重构会掩盖各自的价值并增加风险。
有两个adapter后再添加seam。 不要假设性地引入可变点——等有两个实际实现后再添加。
切勿自动提交。 批量处理的重构PR容易在评审中被忽略；保持PR小而明确。

Hand-offs

流程衔接

Opportunity selected →
```
evanflow-design-interface
```
(if interface changes) or
```
evanflow-writing-plans
```
(otherwise)
New domain term emerged during discussion →
```
evanflow-glossary
```
to update
```
CONTEXT.md
```
Decision behind the design merits an ADR → write under
```
docs/adr/
```

选定重构机会 → 若涉及interface修改，进入
```
evanflow-design-interface
```
流程；否则进入
```
evanflow-writing-plans
```
流程
讨论中出现新领域术语 → 进入
```
evanflow-glossary
```
流程更新
```
CONTEXT.md
```
设计背后的决策值得记录为ADR → 在
```
docs/adr/
```
下撰写文档