cruldra/organizing-by-usage

按使用关系组织代码

核心洞察：文件应该和它的使用方聚在一起。

两层决策原则，都是同一个洞察的体现：

1. 顶层：按业务子系统组织 —— 本质是"同一业务流用的代码放在一起"。
2. 子系统内部：按使用关系聚合 —— 只被一处用的文件合进使用方，不按"名字看起来像"堆文件。

第二层比第一层更容易出错，也更需要判断工具。本 skill 的大部分篇幅是第二层。

---

第一层：顶层按业务子系统

默认结构

src/
├── core/                 # 跨子系统共享内核（配置、DB、日志、鉴权、事件总线）
├── customers/            # 客户子系统
│   ├── models.py
│   ├── schemas.py
│   ├── repositories.py
│   ├── services.py
│   ├── routes.py
│   └── tasks.py
├── courses/              # 课程子系统
└── allocation/           # 分配引擎子系统

不要把 models/、services/、repositories/、routes/、tasks/ 这类目录铺在项目根下。它的后果：一个功能散在 5-7 个目录里、修改一个需求要跨层跳、新成员看不到业务边界。

子系统划分信号

只有同时满足以下几条才构成独立子系统：

• 有明确、可用业务语言描述的职责
• 有相对稳定的领域语言（术语）
• 规则集合独立演进，不会被其他子系统随意改写
• 数据边界清晰（主要表 / 集合都属于自己）
• 对外只需暴露少量接口即可与其他子系统协作

不是子系统划分依据：

• 数据表很多 → 可能只是一个子系统的内部复杂度
• 前端开了几个新接口 → 接口是路由，不是域
• 组件看起来很大 → 子系统内部拆子目录即可

---

第二层：子系统内部按"使用关系"聚合

症状：子系统内部出现"孤儿辅助文件"

子系统内部文件越加越多，开始出现这种文件：

• xxx_middleware.py、xxx_factory.py、xxx_manager.py、xxx_translator.py
• utils.py、helpers.py、common.py

如果这些文件实际上只被一个文件 import，它们是"孤儿辅助文件"，是组织方式失败的信号。

合并/拆分三问法

遇到一个"可疑文件" A，决定它该独立存在还是合进别处：

Q1. A 在生产代码里有几个运行时使用者？

• 1 个 → 合进那个使用者
• 2+ 个 → 看 Q2

Q2. 合进去会造成循环依赖吗？

• 不会 → 按 Q1 的结论合并
• 会 → 把 A 合到更基础、被依赖的那一方，而不是"消费"它的那一方

Q3. 合并后的新文件能用一句话说清职责吗？

• 能 → 合并成立
• 不能 → 说明职责不匹配，保留 A 独立，或重新找别处合

三问法实战示例

| 原状 | Q1 使用者 | Q2 循环 | 决策 | |------|----------|--------|------| | exec_ssc_tool_factory.py（构造 exec_ssc 工具） | 1 个：agent.py | — | 合进 agent.py | | sse_translator.py（LangGraph 事件 → SSE 翻译） | 1 个：services.py | — | 合进 services.py | | token_manager.py（JWT 管理） | 2 个：agent.py（SessionExpired）+ services.py（实例化） | 合进 services.py 会循环（services 已依赖 agent） | 合进更基础的 agent.py | | tools/exec_ssc.py + tools/ui_events.py + tools/__init__.py | 都只被 agent.py 用 | — | 拍平为单文件 tools.py |

ORM-less 场景：models.py 的正确用法

原则：models.py 只存真正的数据库表定义（SQLAlchemy / Django ORM）。Pydantic BaseModel 无论它是：

• API 请求/响应 schema
• MongoDB 文档模型
• Elasticsearch 文档模型
• 配置对象

都应该放 schemas.py，而不是 models.py。

判断：这个类会不会被 Alembic / Django migration 用来生成 DDL？

• 会 → models.py
• 不会 → schemas.py

目录 vs 单文件

子系统内部，优先用单文件，只在真的装不下时才拆目录。

拆目录的触发条件：

• 单文件 > 500 行且内部有清晰的多个功能簇
• 需要多人并行开发不同部分
• 内部有需要独立发布/导入的子组件

如果你只是因为"文件看起来有点长"就拆 tools/、utils/、helpers/，大概率是在制造前面说的"孤儿辅助文件"。

---

命名：反映实际角色，不反映设计意图

反模式

类名借用了框架/模式术语，但代码里实际没遵循那个范式：

| 反模式 | 说明 | |--------|------| | XxxMiddleware 但没继承任何 Middleware 基类，也没实现中间件钩子 | 只是借了"中间层"的语义 | | XxxFactory 但只有一个 make_xxx() 方法，还常驻一堆状态 | 其实是普通对象 | | XxxService 但全是静态方法 | 应该是模块级函数 | | XxxManager 但只有 get/set 两个方法 | 应该是简单封装或直接用原始类型 |

判定问题

• 新读者看到名字能准确预测这个类做什么吗？
• 名字里的术语（Factory / Middleware / Handler / Service）在代码里真的对应到一个基类或范式吗？

示例

• ExecSscMiddleware（没继承 AgentMiddleware）→ ExecSscToolFactory（它确实在构造工具）
• UserService（全是静态方法）→ user_repository 或直接用模块级函数

---

抽象是否过度？YAGNI 自检

当你犹豫"是否要加一层抽象"时，问三个问题：

1. 这个抽象提供的钩子 / 方法，在当前代码里实际用上了几个？

   • 用了 0 个 → 不需要抽象
   • 只用 1 个 → 考虑改成函数或简单对象
   • 用了多个 → 抽象成立

2. 这个类存在的唯一原因是"测试方便"吗？

   • 是 → 考虑更轻的方案：模块级函数 + 参数注入 / ContextVar + 闭包

3. 这个基类是为"未来可能扩展"准备的吗？

   • 是 → 删掉，未来真的要扩展时再加

典型误用

| 场景 | 不该用 | 应该用 | |------|--------|--------| | 请求级数据注入到单例工具 | AgentMiddleware（只为了一个工具） | ContextVar + 闭包 | | 应用启动时装配一次 | Factory 类 | 直接 inline 到启动代码 | | 同样的逻辑两个入口（生产 + 测试） | 继承 + 多层抽象 | 一个类暴露两个方法 |

---

测试文件组织

• 测试按"被测的语义单元"组织，不必和生产文件 1:1
• 生产代码合并后，测试是否跟着合并？判断标准是语义焦点：
  • 语义相同（例如都在测"agent 装配过程"）→ 可合
  • 语义不同（例如"SSE 翻译" vs "服务编排"）→ 保留独立

---

Red Flags —— 触发组织方式重新审视

出现下列任一症状时，先停下手，怀疑组织方式有问题：

• [ ] 一个需求的改动要跨 5+ 个目录
• [ ] 子系统内部出现多个只被 1 处 import 的文件（*_manager.py / *_factory.py / *_translator.py 这类）
• [ ] 根目录下同时有 models/、services/、routes/ 等技术类型目录
• [ ] 子系统里出现和顶层同名的子目录（如 customers/services/ 下又有 services.py）
• [ ] 类名借用了框架术语但代码里没对应的基类或范式
• [ ] 引入了一个抽象，但它提供的钩子 / 扩展点一个都没用上
• [ ] Pydantic BaseModel 放在了 models.py（除非它同时是 SQLAlchemy 模型）

---

质量检查清单

做完结构设计或重构后，自检：

顶层

• [ ] 目录名体现业务能力，不是文件类型
• [ ] 新成员看目录能说出系统有哪些业务模块
• [ ] 一个业务功能的改动集中在一个子系统里

子系统内部

• [ ] 每个文件都能用一句话说清它"是什么"
• [ ] 没有只被一个文件 import 的辅助文件
• [ ] models.py 里只有真正的 ORM 表定义
• [ ] 命名能让新读者准确预测做什么
• [ ] 没有"用不上的抽象层"

命名

• [ ] 类名里的模式术语（Factory / Middleware / Service）都对应到实际的范式
• [ ] 如果去掉某个类名里的后缀，剩下的部分还能准确描述它 → 可能后缀是多余的

---

AI 助手执行守则

当用户让你组织代码或重构时，按此优先级动作：

1. 先问自己"这是第一层还是第二层问题"

   • 创建新项目 / 调整顶层目录 → 第一层：按业务子系统
   • 改子系统内部文件布局 / 判断某文件该不该合 → 第二层：按使用关系

2. 用三问法判断合并/拆分，不要凭"名字看起来像不像"

3. 命名反映实际角色。如果名字借用了基类术语但代码里没继承 / 没实现那个范式，主动建议改名

4. 默认选轻量方案。抽象不够用时再升级，不要先上重抽象

5. 怀疑"孤儿辅助文件"。只被一处用的文件，合进使用方

6. Pydantic BaseModel 默认进 schemas.py，除非它是 SQLAlchemy 模型

7. 不要默认生成 models/ services/ routes/ 这类根级目录，除非用户明确要求保留旧结构