simplify-layout

简化布局

让文件树名称简短且分组清晰：文件夹承载所属领域，叶子文件使用简短的动词或方面名称，相关代码放在一起。

标准结构：references/layout-model.md。

范围

1. 优先处理用户提供的路径（包、功能或子树）。
2. 若未提供路径，且 diff 呈现布局调整特征，则处理当前 Git 更改。
3. 如果边界不明确，只询问一次。

默认提出方案（只读的重命名／分组映射）。只有用户要求应用／迁移／实施时，才改写路径。

初始步骤

1. 阅读项目中的命名或布局指南（如有）（AGENTS.md、CONTRIBUTING、嵌套的所有权文档、设计系统文档）。
2. 遍历目标树；绘制简略的当前布局草图。
3. 加载布局模型：references/layout-model.md。
4. 与 1–2 个角色相似的同级文件夹比较（可选，用于了解 public/ / private/ 信任边界等本地约定）。

原则

1. 路径上下文取代文件名前缀

不要在叶子名称中重复父文件夹（或包）的名称。

避免	推荐
queries/user-profile-query.ts	queries/users/profile.ts
auth/auth-token-helper.ts	auth/token.ts
rows/events/event-row-mapper.ts	rows/events/map.ts
packages/billing 下的 billing-invoice-summary.ts	invoices/summary.ts

2. 文件夹 = 名词／领域；文件 = 方面／操作

• 领域文件夹：users/、billing/、auth/、orders/、seed/
• 叶子文件：card.ts、detail.ts、overview.ts、create.ts、sync.ts、map.ts
• 若架构类型需要，可保留稳定的角色文件夹：queries/、services/、components/、hooks/、errors/、utils/——这些名称也要简短

3. 将相关代码归到同一个父文件夹下

把会一起变更的同级文件放在同一个文件夹中。优先采用：

queries/
  users/profile.ts
  users/list.ts
  orders/detail.ts
  orders/overview.ts
  billing/invoice.ts

而不是在同一层级平铺 users-profile.ts、orders-detail.ts、billing-invoice.ts，或将相关模块散落在无关的根目录中。

4. 名称简短；仅在有歧义时写全

• 清晰时优先使用一个单词：day、stamp、lookup、list、card
• 仅在需要时使用 kebab-case 多词名称：dimension-filters.ts、currency-fraction-digits.ts
• 不要生造需要词汇表才能理解的 2–3 个字母的晦涩缩写
• 服务或包的文件夹名称可以较长（analytics-traffic-read），前提是它是公开的领域名称；其中的文件名称应简短（service.ts、errors/…）

5. 深度应服务于分组，而非形式

• 当平铺文件夹混杂多个领域，或名称开始带有前缀时，拆分文件夹
• 不要为“以后可能用到”而添加空架子文件夹
• 不要嵌套 utils/helpers/lib 层级；一个私有辅助文件夹就足够
• 尊重现有信任边界（public/ / private/ / `internal/）——缩短其中的名称，不要将这些边界扁平化

6. 每个文件只关注一个主要事项

如果文件混杂无关的导出组，或超过约 250–400 行且预计会继续增长，则拆分。拆分后的名称应体现具体方面，而不是使用 helpers / misc / shared2。

工作流

提出方案（默认）

1. 绘制当前树的简略结构。
2. 标出造成阻碍的问题：名称过长、路径段重复、领域混杂、同级文件散落、巨型文件、无用的嵌套。
3. 使用针对该架构类型（包、功能或 UI）调整后的布局模型，提出目标树——不要将数据层文件夹名称强行套用到 UI 上。
4. 列出每个重命名／移动的旧路径 → 新路径表格。
5. 指明哪些内容不得重命名（磁盘上的迁移文件、公开的 SDK 路径、持久化资源 ID、API 路由），除非用户明确要求。

应用（仅在用户要求时）

- [ ] Create/move/rename files per the map
- [ ] Update imports, package exports, and path aliases as needed
- [ ] Move colocated tests with their sources
- [ ] Update nearest ownership/layout docs if paths changed
- [ ] Delete emptied leftovers
- [ ] Run the project's targeted format/lint/typecheck/tests for touched areas

保持行为不变。除非该子树已使用 barrel 文件（index.ts / index.js），否则不要新增。不要重命名已应用的迁移文件或外部契约。

需要指出的问题

• 叶子名称重复描述父文件夹（…/events/event-*.ts）
• 所属包内的路径重复包含包名或品牌名 （packages/acme 下的 acme-*）
• 扁平目录中有许多通过前缀区分的文件（同级的 foo-bar-baz.ts）
• 相关模块分散在相距较远的文件夹中，且没有共同的父目录
• utils/、helpers/、common/、misc/ 这类杂物目录
• something.service.ts 让服务文件夹形态变得扁平（当本地服务结构如此时，优先使用 something/service.ts）
• 深层目录树中每一层的名称都很模糊

修复规则

• 优先重命名或移动，而不是改写逻辑
• 应用短名称和分组规则时，遵循本地架构惯例（功能信任分组、UI 基元）
• 保持工作区中无关的更改不受影响
• 除非用户要求实施，否则仅进行只读操作

验证

仅对已修改的文件或包使用项目现有的质量检查命令（格式化、lint、类型检查、测试）。 优先执行有针对性的检查，而不是完整代码库的检查；重命名涉及共享契约时除外。

如果架构、迁移或生成路径相关产物发生移动，请运行项目针对该范围的常规迁移或代码生成步骤。

审查输出

## Scope

[path]

## Current (abbrev)

[tree]

## Friction

1. …

## Target

[tree]

## Rename map

| Before | After |
| ------ | ----- |

## Do not rename

- …

## Apply?

Propose only / ready to apply when asked

相关技能

技能	适用场景
unsmell	命名和分组之外的可维护性问题（重复、复杂度、类型）

多 Agent 验证

当此技能在多 Agent 实施或修复工作流中运行时，每个子 Agent 仅对分配给自己的文件、包或范围运行有针对性的检查，并报告是否需要更广泛的检查。协调者负责项目的完整质量门禁流程，并将最终检查失败的问题分派给相应的子 Agent。 如果没有可用的多 Agent 框架，则在聊天中运行相同的有针对性检查。