Code Tree

---
name: code-tree
description: 树形代码组织 skill。规则:写码前先规划树形结构(主干/侧枝/叶子);叶子 ≤ 300 行,超载升级为侧枝并新配主干,沿真实结构切分、禁止机械拆;反模式是藤/碎片/超载;AI 主动规划结构,回复开头先给结构规划。Use when writing or refactoring code, creating or restructuring modules, splitting or merging files, reviewing code structure, when a file grows past ~300 lines, when call chains are hard to follow, or when the user mentions 代码结构 / 重构 / 拆分文件 / 模块划分 / 主干 / 树形组织 / 设计模式 / 解耦 / 文件命名 / 重命名 / code structure / file organization / module boundaries / naming / rename — even if they don't say "tree".
---

# Code Tree:组织必须是树

本 skill 在生成与重构代码时,主动以树的形式规划结构——让人类既能看到枝干,也能看到所有叶面。理论来龙去脉见 [references/blog.md](references/blog.md)。

## 核心原则:先规划树,再写代码

**没有以树的形式规划的代码,必然按最短路径生长为图的形状**——函数交叉调用、数据交叉引用,能跑但没人能读懂。树(目录结构、模块边界)就是压住这种生长的骨架;"解耦"的本质是把图约束在树内,图跨越所有枝干就是坏代码。

设计模式救不了:给图状代码加抽象、包间接只是打补丁,结构没被规划过,补丁只会更难读。出路只有一个——动手之前,先把树规划出来。

## 树的三个角色:主干、侧枝、叶子

关键认知:**三者不是三种东西,是同一件事在三个尺度上的表现。**

| 角色 | 定义 | 判别标准 |
|---|---|---|
| 主干 | 起引导作用的主体 | 大、明显、能一口气读完 |
| 侧枝 | **缩小的主干**,不是细节倾倒场 | 与主干同构:大、明显、起引导作用 |
| 叶子 | 平铺的总览单元 | ≤ 300 行,不再引导,一眼总览 |

递归规则:**每个非叶子节点,都是它范围内的主干。** 这条规则在每个目录层级适用——目录树的第一层如此,第五层也如此。

特别警惕对侧枝的误解:侧枝不是"可以乱一点的地方"。脱离主干视角后,侧枝自己仍然要大、明显、起引导作用。把细节倾倒进侧枝,长出来的是藤。

## 300 行规则:触发信号,不是切割指令

一片叶子不应超过 300 行(一屏约 50~80 行,300 行约 4~6 屏,是"一眼总览"的认知边界)。

叶子超过 300 行,说明它内部已经长出了结构,只是被压平了。正确的动作:

**不是拆函数,而是升级为侧枝 + 新配一个主干。**

```text
之前(超载的叶子):
    parent/
    └── billing.rs         ← 800 行,发票/支付/退款全塞在一起

之后(升级为侧枝):
    parent/
    └── billing/
        ├── mod.rs         ← 新长出来的主干:组合 + 引导
        ├── invoice.rs     ← 叶子:发票主体
        ├── payment.rs     ← 叶子:支付主体
        └── refund.rs      ← 叶子:退款主体
```

新叶子的名字来自它内部真实长出的主体——命名规则详见下节。

两条铁律:

1. **必须同时长出一个主干。** 只拆叶子、不立主干,就是把树拆成了藤——这是 AI 最常犯的错。
2. **切分线落在真实结构上,不做机械拆分。** 按主体、职责划分,让每一片新叶子都是完整、自洽的主体;不按行数均分,不按函数数量凑,不为了拆而拆。找不到自然的切分线,说明结构其实还没长好(或命名没理清):先厘清职责(必要时询问用户),再动手。机械拆出来的"叶子"互相纠缠、各自残缺,本质仍是碎片。

## 命名:路径也要引导

主干的引导作用,一半由路径承担:读者不打开文件,先读路径定位主体。名字有歧义,结构再对,树也在误导。

**同一棵树内,同一个词不得在不同层次指不同主体。** 各层用自己所处的视角命名:名字回答"从我这一层看,它是什么",不照搬这个词在别层的含义。同一个词跨层指着不同主体,路径就从路标变成误导。

名字必须来自文件内部真实长出的主体。part_a / part_b 这类按切割顺序起的名字,是机械拆分的铁证。

检验方法:**只读路径、不看内容,能说出这个模块是什么、属于哪一层吗?** 名字经不起这个检验,无论内容多干净,树都是误导的。

## 文件内:第一屏也要引导

主干的引导作用,落在读者的每一处"第一眼":路径的第一眼是名字,打开文件的第一眼是开头。

从主干跳进一个侧枝,读者期待立刻看见这个侧枝的主干。若开头站着的是边边角角的函数——错误分支、工具方法、兼容处理——主流程被压在下面,这个侧枝就丢掉了引导作用:读者在文件内部又开始考古。

排序与树同构:**引导在前,细节在后。** 文件开头放主流程与"下一步去哪";边角函数沉到文件尾部,或移进它们本该所在的叶子。

检验方法:**只看第一屏,能说出这个文件的主流程吗?**

## 入口:接缝也要引导

读者顺着主干阅读,踩着入口语句跳进侧枝——一行调用、一次注册、一个引用。入口语句是主干与侧枝之间的接缝。

**接缝上必须认得出从属:这一行在为哪个主干做事、进入的是谁的领地。** 认不出,就是主干撕裂——树在结构上完整,在接缝上断裂。

AI 写下入口时,从属在模块内部不言自明,名字于是只说发生了什么、不说是谁的;读者站在入口,只能打开侧枝求证。检验因此必须站在使用一侧——生产一侧看不见撕裂。

从属由什么承担——名字、路径、参数、接收者,或入口所处的明确语境——形式随意,但必须在接缝上读得出来。

撕裂常常是切分线的症状:入口怎么写都说不清从属,多半是侧枝内部混了两个主体,该按主体重新切分——与"找不到自然的切分线"是同一种病:结构还没长好。

检验方法:**站在主干一侧,只读入口这一行与紧邻上下文,不打开侧枝实现,能说出它在为谁做事吗?**

## 改名:词汇也要迁移

改名不是定义侧的一次编辑,是一次词汇迁移。类型改了名,编译器逼着所有标注处跟着改;旧词的局部变量却零压力存活,继续误导。定义侧受压、使用侧无压,注意力的不对称,就是改名半途而废的机制。

**改名止步于定义侧,迁移就没有完成。** 改名那一刻起,代码、测试、文档里旧词的每一处出现,对着新词汇表重过从属检验。审计下探到接缝的两副面孔:**主干一侧,持有并调用它的局部变量;侧枝一侧,接收它的参数名**——它们站在接缝上,不是可以不审计的"文件内容"。

检验方法:**grep 旧词。每一处残留,都答得出为什么保留吗?** 答得出的(从属在语境中明确)可以留;答不出的,是没走完的迁移。

## 三个反模式

| 反模式 | 形态 | 病根 |
|---|---|---|
| 藤 | 每个函数 10~20 行、只被调用一次,函数名比函数体还长,读代码像走迷宫 | 主干消失 |
| 碎片 | 本该平铺的叶子被切成转发函数,只增加跳转、不隐藏复杂度 | 叶子被打碎 |
| 超载 | 单文件数百行,内部已有结构却拒绝长出主干 | 叶子该升级没升级 |

三者的病根是同一个:**没有在每个尺度上维护"主干要引导、叶子要平铺"这条递归规则。**

## 实操规则

### 生成代码时

1. **先定树,再写代码。** 动手前明确:这个变更落在树的哪个位置?主干是什么?叶子是什么?
2. **主干先行。** 模块入口文件起引导作用,能一口气读完,只放"下一步去哪"的引导,不放实现细节;文件内部同样主干先行——开头是主流程,边角函数沉底。
3. **叶子平铺。** 一个文件一个主体,目标 ≤ 300 行,提供总览。
4. **文件超过 300 行时**,按"300 行规则"升级为侧枝,不要继续往里加函数。
5. **不要发明只调用一次的转发函数**;不为拆而拆。
6. 跨模块调用必须走显式接口,不碰对方内部实现。
7. 命名经得起只读路径的检验:名字来自真实主体;同一棵树内,同一个词不在不同层次指不同主体;侧枝入口在接缝上读得出从属。

### 审查代码时

逐项检查:

- 主干是否清晰可见、能一口气读完?
- 每个非叶子节点是否像主干一样起引导作用?
- 只读路径、不看内容,能说出每个模块是什么、属于哪一层吗?同一个词有没有在不同层次指不同主体?
- 打开主干文件,第一屏是主流程吗?还是边角函数占了开头?
- 入口语句只看那一行与紧邻上下文,认得出它在为谁做事吗?认不出,就是主干撕裂。
- 改名之后 grep 旧词:主干中的变量、侧枝中的参数,每一处残留都答得出为什么保留吗?
- 有没有只调用一次、没有引导作用的转发函数?(碎片)
- 有没有文件超过 300 行却未升级为侧枝?(超载)
- 升级时是否新配了主干、沿真实主体边界切分?(藤 / 机械拆分)
- 执行图(调用链)是否被约束在树内?有没有跨越多个枝干的调用?

### 重构时

- 超载叶子 → 升级为侧枝,配新主干;沿真实主体边界切分。
- 同名异义 → 按所处层次的视角重命名,让路径重新引导。
- 改名视为词汇迁移:沿使用侧传播,主干中的变量、侧枝中的参数逐处重过从属检验,代码、测试、文档一处不漏,不止步于定义侧。
- 开头被边角占据 → 主流程提到文件顶部,边角沉底或移进所属叶子。
- 主干撕裂 → 从属补进接缝;说不清从属,则侧枝混了主体,按主体重新切分。
- 碎片 → 合并回叶子,恢复平铺总览。
- 藤 → 提炼主干:把主流程显式地写在一个能一口气读完的地方。

## 角色分工:AI 规划结构,人类快速 review

**结构规划是 AI 在处理过程中的职责,不是等人下达的输入。** 生成或重构代码时,主动按本理论规划树形结构,而不是放任结构随意生长。

**人类负责 review 与裁决。** AI 的输出是"统计上最常见的写法",不是"结构上最好",所以 review 不可省略;但树已由 AI 搭好,review 只是核对一棵树,不是逐文件考古。

规划如何呈现(先说明再动手、边做边说明、还是完成后说明)由各 AI 按自身习惯自由发挥,不做硬性规定;唯一的要求是让人类能轻松看清树的形状。涉及业务边界的重大分歧点,向用户确认后再继续。

## 框架切片视角

框架提供的"切片"是天然的主干/叶子单位,优先使用它们:

- **有切片供给**(树自然形成):React 组件、Express / Koa / Fastify / Axum / Gin 的 handler。一个文件一个组件、一个 handler 一条完整处理链。
- **无切片供给**(默认长成图):裸 tokio 后台任务、裸 http、裸 goroutine。此时必须手动搭树:显式建模块目录和主干文件,把执行图关进树里。

## 深入阅读

理论的来龙去脉——这段人机对话的完整故事(AI 视角)——见 [references/blog.md](references/blog.md)《代码是树,不是藤》。