用途
file-organization 技能用于指导应用和包中相关实现文件的组织方式，重点解决何时使用文件夹、index.ts、命名入口，以及应避免的做法（如 mega-barrels、基名冲突）。它适用于分组相关实现文件、index.ts 公共 API、导入路径和文件夹命名。
该技能不覆盖 Next.js lucide 风格包导入优化、Fastify 路由结构或 Drizzle schema 设计。
主要能力
技能基于以下假设：TypeScript ESM，导入说明符带 .js 扩展名；kebab-case 目录名；应用本地组索引使用命名再导出，包子路径在文件夹是已发布模块边界时可以使用 export *。
核心原则包括：
- 一个文件夹分组同一关注点的 2 个以上实现文件。
- 当所有导出共享同一运行时，index.ts 是该组的公共 API。
- 在文件夹内去掉文件夹名前缀（oauth-google.ts → oauth/google.ts）。
- 文件夹外导入组（.../feature/index.js）；文件夹内直接导入同级文件。
- 单文件模块保持为文件；测试与实现放在一起。
- 混合运行时 → 使用带命名入口文件的文件夹，不设统一索引。
使用方式
技能通过约束和模式来指导实践。
必须（MUST）：
- 使用 kebab-case 文件夹名。
- 在应用本地组索引中使用命名再导出（避免 export * mega-barrels）。
- 在创建文件夹前解决基名冲突（auth.ts vs auth/）。
不得（MUST NOT）：
- 添加父级 mega-barrels（lib/index.ts、components/ui/index.ts）。
- 创建 foo/foo.ts 加薄再导出索引。
- 在 Fastify 自动加载树（routes/、plugins/）中添加 index.ts。
- 在服务器和客户端模块使用不同运行时时，将它们统一在一个索引中。
应该（SHOULD）：
- 保持组索引小而内聚（一个功能域）。
- 当再导出会造成导入循环时，使用命名入口文件。
- 优先使用现有包子路径而非新的根 barrel。
交互方面：与 next-v16 互补（barrel 导入优化 ≠ 功能组索引）；与 typescript-v6 互补（ESM 路径、命名导出）；当仓库规则指定例外（catalogs mapper、Drizzle schema index）时，仓库规则覆盖此技能。
模式示例：
组索引（同一运行时）：
oauth/ shared.ts google.ts index.ts # 仅命名再导出
消费者：import { getOAuthAllowedCallbackUrls } from '../lib/oauth/index.js'
拆分运行时（无统一索引）：
logger/ server.ts client.ts
无 index.ts
消费者直接导入命名入口文件（logger/server、logger/client）。
命名入口（避免循环）：
catalogs/ index.ts # 仅字典 mapper.ts # 从 ./index.js 导入 — 不再导出
反模式：
- 单层前缀汤：难以导航；应使用文件夹。
- lib/index.ts 再导出所有内容：mega-barrel；减慢构建并模糊边界。
- auth.ts 与 auth/ 并存：模块解析陷阱。
- 统一索引包含 cookies + document：破坏服务器/客户端边界。
适用场景
适用于需要组织 TypeScript ESM 项目文件结构的场景，特别是应用和包中相关实现文件的分组、公共 API 设计、导入路径管理和文件夹命名。
限制
技能不覆盖 Next.js lucide 风格包导入优化、Fastify 路由结构或 Drizzle schema 设计。具体实现需结合项目实际情况，仓库规则可能覆盖此技能。