file-organization

文件组织

当核心问题是**“此代码库应采用什么结构边界，以及如何在避免重组陷入混乱的前提下逐步实现？”**时，请使用此技能。

这项工作的目标不是罗列一棵庞大的目录树，并假装它适用于所有仓库。 目标是：

1. 找出真正的组织单元，
2. 区分功能、共享、框架和软件包边界，
3. 明确命名和导入规则，防止结构偏离，
4. 安全地规划迁移，
5. 返回一份结构说明，让其他工程师或 Agent 能立即据此执行。

在建议结构之前，请阅读 references/boundary-decision-matrix.md。 在移动文件或重命名目录之前，请阅读 references/migration-checklist.md。 如果问题涉及 barrel 文件、别名路径或团队约定，请阅读 references/naming-and-import-rules.md。

何时使用此技能

• 为新仓库或应用选择易于维护的文件夹策略
• 重构 components/、hooks/、utils/ 和 store/ 文件夹已无法反映业务边界的仓库
• 判断代码应放在功能模块、共享层、路由段还是工作区软件包中
• 在大型重组或迁移前审查结构偏离
• 在不断壮大的团队中统一命名、导入路径和所有权规则
• 判断拆分单体仓库/工作区是否合理，还是为时过早
• 制定迁移计划，尽量减少导入失效、文件重复和迁移未完成的情况

何时不使用此技能

• 主要任务是设计可复用的组件 API、变体或插槽/原语组合方式 → 使用 design-system 或 design-system
• 主要任务是规划框架状态的归属、缓存/存储边界，或 URL/表单/服务端状态的放置位置 → 使用 state-management
• 主要任务是让仓库能在不同机器、服务、工具链或容器上运行 → 使用 system-environment-setup
• 主要任务是任务运行器、引导脚本、钩子或本地 CI 命令设计 → 使用 deployment-automation
• 主要任务是部署拓扑或托管 CI/CD 发布 → 使用 deployment-automation 或 vercel-deploy
• 仓库只需进行简单的机械式文件移动，不涉及架构决策；这种情况下，直接执行移动即可，无需重新讨论结构设计

说明

第 1 步：先判断结构压力，再绘制文件夹结构

先按以下格式整理需求：

structure_intake:
  repo_shape: single-app | app-plus-api | monorepo | library-cli | content-site | unknown
  current_pattern: type-based | feature-based | route-colocated | package-workspace | mixed | unknown
  main_pressure:
    - scattered-feature-code
    - unclear-shared-boundaries
    - framework-routing-collision
    - premature-monorepo-split
    - monorepo-needed-now
    - naming-drift
    - import-chaos
    - migration-risk
    - onboarding-confusion
    - unknown
  change_scope: greenfield | incremental-refactor | major-reorg | audit-only
  primary_boundary_unit: feature | shared-layer | route-segment | package | unknown
  confidence: high | medium | low

如果用户的描述含糊不清，优先采用最简单明确的理解，并说明这一假设。

第 2 步：选择一种主要组织模式

本次运行中只能选择一种主要模式：

1. starter cleanup（初始结构清理）
   • 当基于类型的初始目录树仍足够小、可以在固化之前修正时使用。
2. feature modularization（功能模块化）
   • 当业务领域分散在技术目录中，需要明确功能归属时使用。
3. framework colocation（框架就近组织）
   • 当 Next.js / 类似路由器的约定应指导路由段的文件放置时使用。
4. shared layer governance（共享层治理）
   • 当仓库已有功能模块，但共享代码不断渗入各处时使用。
5. workspace split（工作区拆分）
   • 当多个可运行的应用/服务/软件包足以支持划分 apps/ 和 packages/ 边界时使用。
6. migration audit（迁移审查）
   • 当仓库更需要安全的迁移计划，而不是全新的结构方案时使用。

第 3 步：选择能够解决问题的最小边界单元

使用以下规则：

• 如果同一业务领域同时涉及组件、钩子、数据访问、测试和状态管理，优先采用功能文件夹。
• 只有当多个功能复用代码且归属明确时，才优先采用共享层。
• 如果路由／布局／文件约定语义属于架构的一部分，而不仅仅是文件存储方式，优先采用框架就近组织。
• 只有在存在多个可部署的应用／服务、可复用库或独立的依赖／运行时需求时，才优先采用工作区包。
• 不要仅仅因为代码库显得杂乱就拆分包；许多代码库需要的是更好的功能／共享规则，而不是单体仓库。
• 明确放置生成产物、文档、脚本和测试，不要把它们塞进含义模糊的工具文件夹。

第 4 步：按决策顺序选择

在以下情况下使用功能模块化

• 理解一项面向用户的功能，目前需要打开分散在许多技术文件夹中的文件
• 一个领域的变更反复涉及 components/、hooks/、utils/、api/ 和 store/
• 团队需要为每项功能或业务领域明确归属

在以下情况下使用框架就近组织

• 路由段、加载器、布局、服务端／客户端边界或文件约定决定了代码必须放在哪里
• 框架文档已定义特殊文件或保留路径
• 真正的目标是围绕路由／功能组织代码，同时避免与框架约定冲突

在以下情况下使用共享层治理

• 代码库已经有功能模块，但共享文件夹已沦为杂物堆
• 团队总在争论某项代码是否真正共享，还是仅被复用了两次
• 导入路径和聚合导出文件让边界难以辨认

在以下情况下使用工作区拆分

• 代码库包含依赖或运行时目标各不相同的多个应用／服务／包
• 共享库需要带版本号或明确的包边界
• 各个包在构建／测试／部署方面确实存在显著差异

在以下情况下进行迁移审查

• 结构方案大致已定，但如果随意迁移，就会破坏导入、文档、测试或归属
• 团队需要分阶段迁移、别名、代码转换工具或兼容性垫片

第 5 步：确保结构边界名副其实

好的结构建议也会说明它不负责什么。

示例：

• 如果真正的痛点是可复用组件基元和 API 形态，则交由 design-system 处理
• 如果真正的痛点是设计令牌／全库 UI 治理，则交由 design-system 处理
• 如果真正的痛点是运行时／服务／工具链配置，则交由 system-environment-setup 处理
• 如果真正的痛点是反复使用的脚本和任务入口，则交由 deployment-automation 处理
• 如果真正的痛点是状态／缓存归属，则交由 state-management 处理

混合需求很常见。应明确拆分，而不是强迫一种文件夹策略解决所有问题。

第 6 步：制定可复用的命名和导入规范

任何结构建议都应明确列出以下规则：

• 目录用途 — 哪些内容应放在这里，哪些不应放在这里
• 命名风格 — 文件夹和文件的大小写约定
• 共享与功能规则 — 代码在何种情况下应归入共享文件夹／包
• 公共 API 规则 — 功能／包是否通过单一边界文件导出
• 导入规则 — 是否禁止跨同级功能进行深层导入
• 测试／文档／故事文件放置规则 — 与功能就近放置，或按规则集中管理

不良迹象：

• utils/ 或 shared/ 变成杂物抽屉
• 功能代码分散在五个顶层技术文件夹中
• 聚合导出文件模糊了归属，并助长隐式深度耦合
• 没有真正的包／运行时边界，却迁移到 apps/ + packages/
• 框架特殊文件与无关的领域逻辑混杂，且没有就近组织规则

第 7 步：在更改文件前制定迁移计划

移动任何内容之前，请先制定一份变更计划，涵盖：

1. 当前的热点区域，以及它们为何造成困扰
2. 目标边界模型
3. 分阶段的移动顺序
4. 别名、导入或 barrel 文件的兼容策略
5. 测试、构建和文档的验证步骤
6. 回滚或部分采用的安全措施

如果仓库仍在活跃开发，优先选择渐进式重构，而不是一次性大规模重命名。

第 8 步：生成文件组织简报

返回一份可供他人立即执行的简洁文档。

首选格式：

# File Organization Brief

## Mode
- Primary mode:
- Why this mode fits:

## Boundary choice
- Primary organizing unit:
- What belongs in feature/shared/route/package boundaries:
- What stays out of scope:

## Recommended structure
- Top-level folders/packages:
- One example feature/package layout:
- Naming/import rules:

## Migration plan
1. First step
2. Second step
3. Verification step

## Handoffs
- Adjacent skills:
- Risks / follow-up work:

第 9 步：清晰优先，不要盲从模板

在改造现有结构时：

• 让建议与仓库当前面临的压力相符，而不是追逐流行模板
• 在框架约定有帮助时采用它们，但不要把框架文件与整个架构混为一谈
• 让代码归入最精简且持久的边界模型
• 将命名和导入规则视为架构的一部分，而不是无关紧要的清理工作
• 保留适用于前端、后端和全栈仓库的通用原则

输出格式

始终返回一份文件组织简报、仓库结构建议或迁移审计。

必备要求：

• 先对结构问题分类，再提出建议的结构
• 选择一种主要组织模式
• 明确指出边界单元
• 指明可转向的相邻技能
• 提供命名和导入规范
• 如果仓库已经存在，则提供迁移计划

示例

示例 1：基于类型的起始目录结构正在失去作用

输入

我们有 components、hooks、utils 和 store，但每次更改结账功能都要改动这四个目录。该如何重组这个 React 应用？

合适的输出方向

• 模式：feature modularization
• 建议为结账、身份验证和商品目录设置功能目录，并保留一个精简的共享层
• 规定代码在什么情况下才能移入共享层
• 将状态所有权的具体问题转交给 state-management

示例 2：Next.js 路由目录变得杂乱

输入

我们的 Next.js App Router 仓库在 app/ 中到处混放路由文件、数据辅助函数和业务逻辑。我们需要清晰的结构，同时遵循框架约定。

合适的输出方向

• 模式：framework colocation
• 将 Next.js 要求的特殊路由文件保留在指定位置
• 将路由专用代码与路由段放在一起，把可复用的领域逻辑移到路由文件之外的功能层或共享层
• 如果路由组或私有目录有助于组织代码且不会改变 URL，则可以提及

示例 3：团队希望拆分为多个包

输入

这个仓库是否应该拆分为 apps/ 和 packages/？我们现在有一个 Web 应用、一个 worker 和一个共享 UI 库。

合适的输出方向

• 模式：workspace split
• 根据可运行目标和共享库说明包边界的合理性
• 建议将 apps/ 用于可部署项目，将 packages/ 用于可复用库和工具
• 加入迁移与验证步骤，而不只是画出最终目录树

最佳实践

1. 从仓库面临的压力出发，而不是从偏爱的架构潮流出发。
2. 优先采用能减少变更扩散的最精简边界模型。
3. 将共享代码视为需要治理的例外，而不是默认归宿。
4. 让框架约定为结构提供参考，但不要让它们沦为意外的杂物间。
5. 只有在依赖、运行时或可部署项目确实需要时，才拆分为多个包。
6. 尽早明确导入和公共 API 规则；它们是组织体系的一部分。
7. 对于正在使用的仓库，采用分阶段迁移并设置验证步骤。

参考资料

• Feature-Sliced Design 文件夹结构文章
• Bulletproof React README
• Bulletproof React 项目结构
• Next.js 项目结构文档
• Turborepo 仓库结构文档
• MIT Comm Lab 文件结构指南