architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Surface architectural friction and propose deepening opportunities: refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.

Fast by default: scope the exploration to the area the user names or the friction they describe, present the top candidates, and hold the rival-interface sub-agent fan-out until asked. Deep mode (the

deep

skill is active): whole-codebase sweep, full candidate list, sub-agent interface exploration on the picked candidate.

识别架构层面的痛点，并提出深度优化机会：将浅模块重构为深模块的方案。目标是提升可测试性与AI可导航性。

默认快速模式：将探索范围限定在用户指定的区域或描述的痛点，呈现优先级最高的候选方案，在用户要求前不启用子代理进行竞品接口探索。深度模式（激活

deep

skill）：扫描整个代码库，列出全部候选方案，并针对选中的候选方案展开子代理接口探索。

Glossary

术语表

Use these terms exactly in every suggestion. Consistent language is the point. Don't drift into "component," "service," "API," or "boundary." Full definitions in LANGUAGE.md.

Module: anything with an interface and an implementation (function, class, package, slice).
Interface: everything a caller must know to use the module: types, invariants, error modes, ordering, config. Not just the type signature.
Implementation: the code inside.
Depth: leverage at the interface, a lot of behavior behind a small interface. Deep = high leverage. Shallow = interface nearly as complex as the implementation.
Seam: where an interface lives; a place behavior can be altered without editing in place. (Use this, not "boundary.")
Adapter: a concrete thing satisfying an interface at a seam.
Leverage: what callers get from depth.
Locality: what maintainers get from depth (change, bugs, knowledge concentrated in one place).

Key principles (see LANGUAGE.md for the full list):

Deletion test: imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
The interface is the test surface.
One adapter = hypothetical seam. Two adapters = real seam.

This skill is informed by the project's domain model:

CONTEXT.md

and any

docs/adr/

. The domain language gives names to good seams; ADRs record decisions the skill should not re-litigate. See CONTEXT-FORMAT.md and ADR-FORMAT.md. When the work touches a toolchain (Python, Rust, TypeScript, Prisma), TOOLING.md carries the commands, configuration shape, and pitfalls for it.

所有建议中必须严格使用以下术语，保持语言一致性是核心要求。请勿随意使用“component”“service”“API”或“boundary”这类词汇。完整定义请参考LANGUAGE.md。

Module：任何拥有Interface和Implementation的单元（函数、类、包、代码片段）。
Interface：调用方使用该Module所需了解的全部信息：类型、不变量、错误模式、执行顺序、配置。不仅仅是类型签名。
Implementation：模块内部的代码。
Depth：接口的杠杆作用，即简洁接口背后承载大量行为。Deep表示高杠杆作用，Shallow表示接口复杂度几乎与实现复杂度相当。
Seam：Interface所在的位置；无需原地修改代码即可变更行为的节点（请使用该术语，而非“boundary”）。
Adapter：在Seam处满足Interface要求的具体实现。
Leverage：调用方从Depth中获得的收益。
Locality：维护者从Depth中获得的收益（变更、bug、知识集中在一处）。

核心原则（完整列表请参考LANGUAGE.md）：

删除测试：假设删除该模块。如果复杂度随之消失，说明它只是一个透传模块；如果复杂度分散到N个调用方中重新出现，说明它具备存在的价值。
Interface即测试面。
一个Adapter=假设性Seam；两个Adapter=真实Seam。

本skill会参考项目的领域模型：

CONTEXT.md

及所有

docs/adr/

文件。领域语言为优质Seam命名；ADR记录的决策，本skill不会重新讨论。请参考CONTEXT-FORMAT.md和ADR-FORMAT.md。当工作涉及工具链（Python、Rust、TypeScript、Prisma）时，TOOLING.md提供了对应的命令、配置格式及注意事项。

Process

流程

1. Explore

1. 探索

Read existing documentation first:

```
ARCHITECTURE.md
```
at the root: the prior map of modules, seams, and invariants. Re-derive only what changed since it was written.
```
CONTEXT.md
```
(or
```
CONTEXT-MAP.md
```
+ each
```
CONTEXT.md
```
in a multi-context repo)
Relevant ADRs in
```
docs/adr/
```
(and any context-scoped
```
docs/adr/
```
directories)

If any of these files don't exist, proceed silently. Don't flag their absence or suggest creating them upfront. Exception: when

ARCHITECTURE.md

is missing on a nontrivial codebase, offer once to seed it from this run's exploration, using ARCHITECTURE-FORMAT.md; write only what the user confirms.

Then use the Agent tool with

subagent_type=Explore

to walk the codebase. Don't follow rigid heuristics. Explore organically and note where you experience friction:

Where does understanding one concept require bouncing between many small modules?
Where are modules shallow (interface nearly as complex as the implementation)?
Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no locality)?
Where do tightly-coupled modules leak across their seams?
Which parts of the codebase are untested, or hard to test through their current interface?

Apply the deletion test to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.

首先阅读现有文档：

根目录下的
```
ARCHITECTURE.md
```
：记录了模块、Seam和不变量的历史映射。仅推导自文档编写以来发生的变更。
```
CONTEXT.md
```
（或多上下文仓库中的
```
CONTEXT-MAP.md
```
+ 每个
```
CONTEXT.md
```
）
```
docs/adr/
```
中的相关ADR（及所有上下文范围内的
```
docs/adr/
```
目录）

如果上述文件不存在，直接继续操作，无需提示缺失或建议提前创建。例外情况：如果非小型代码库缺少

ARCHITECTURE.md

，可主动提出一次，基于本次探索结果，按照ARCHITECTURE-FORMAT.md生成初始版本；仅在用户确认后编写内容。

随后使用Agent工具，设置

subagent_type=Explore

遍历代码库。无需遵循固定规则，以自然方式探索并记录遇到的痛点：

理解某个概念需要在多个小模块间反复跳转的位置？
哪些模块属于Shallow（接口复杂度几乎与实现复杂度相当）？
哪些纯函数仅为了可测试性被提取，但实际bug隐藏在调用逻辑中（缺乏Locality）？
哪些紧耦合模块的实现细节跨Seam泄露？
代码库中哪些部分未测试，或难以通过当前Interface进行测试？

对疑似浅模块应用删除测试：删除它会让复杂度集中，还是仅仅转移？如果是“集中”，则为目标信号。

2. Present candidates

2. 呈现候选方案

Present a numbered list of deepening opportunities. For each candidate:

Files: which files/modules are involved
Problem: why the current architecture is causing friction
Solution: plain English description of what would change
Benefits: explained in terms of locality and leverage, and also in how tests would improve

Use CONTEXT.md vocabulary for the domain, and LANGUAGE.md vocabulary for the architecture. If

CONTEXT.md

defines "Order," talk about "the Order intake module", not "the FooBarHandler," and not "the Order service."

ADR conflicts: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly (e.g. "contradicts ADR-0007, but worth reopening because…"). Don't list every theoretical refactor an ADR forbids.

Do NOT propose interfaces yet. Ask the user: "Which of these would you like to explore?"

以编号列表形式呈现深度优化机会。每个候选方案需包含：

文件：涉及的文件/模块
问题：当前架构引发痛点的原因
解决方案：用平实语言描述变更内容
收益：从Locality和Leverage的角度解释，同时说明测试层面的改进

使用CONTEXT.md中的领域词汇，以及LANGUAGE.md中的架构词汇。如果

CONTEXT.md

定义了“Order”，则使用“Order录入Module”，而非“FooBarHandler”或“Order service”。

ADR冲突：如果候选方案与现有ADR冲突，仅当痛点足够严重、值得重新讨论该ADR时才提出。需明确标记（例如：“与ADR-0007冲突，但值得重新讨论，原因是……”）。无需列出所有ADR禁止的理论重构方案。

请勿提前提出Interface设计。询问用户：“您希望深入探索哪一个方案？”

3. Interview loop

3. 访谈循环

Once the user picks a candidate, run the

core-interview

skill against it. The decision tree to walk: constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.

Side effects happen inline as decisions crystallize:

Naming a deepened module after a concept not in
CONTEXT.md
? Add the term to
```
CONTEXT.md
```
, same discipline as
```
/drill
```
(see CONTEXT-FORMAT.md). If it doesn't exist, create it lazily when the first term is resolved.
Sharpening a fuzzy term during the conversation? Update
```
CONTEXT.md
```
right there.
Did the settled design change the system's shape (new module, moved seam, new invariant)? Update
```
ARCHITECTURE.md
```
right there, per ARCHITECTURE-FORMAT.md.
User rejects the candidate with a load-bearing reason? Offer an ADR, framed as: "Want me to record this as an ADR so future architecture reviews don't re-suggest it?" Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing. Skip ephemeral reasons ("not worth it right now") and self-evident ones. See ADR-FORMAT.md.
Want to explore alternative interfaces for the deepened module? See INTERFACE.md.

用户选中候选方案后，针对该方案运行

core-interview

skill。遵循以下决策树：约束条件、依赖关系、深度优化后模块的形态、Seam背后的内容、保留的测试。

随着决策逐渐明确，同步执行以下操作：

为深度优化后的模块命名，而该概念未在
CONTEXT.md
中定义？将该术语添加到
```
CONTEXT.md
```
中，遵循与
```
/drill
```
相同的规范（参考CONTEXT-FORMAT.md）。如果文件不存在，在第一个术语确定时按需创建。
对话过程中模糊术语被明确？ 立即更新
```
CONTEXT.md
```
。
最终设计改变了系统形态（新增模块、移动Seam、新增不变量）？ 立即按照ARCHITECTURE-FORMAT.md更新
```
ARCHITECTURE.md
```
。
用户因关键原因拒绝候选方案？ 主动提议记录为ADR，表述为：“需要我将此记录为ADR吗？这样未来的架构评审就不会再提出相同建议了。” 仅当该原因确实能帮助后续探索者避免重复建议时才提出。忽略临时原因（如“现在不值得做”）和显而易见的原因。参考ADR-FORMAT.md。
希望探索深度优化后模块的替代Interface？ 请参考INTERFACE.md。