turborepo-architecture

Turborepo 架构

适用于 Turborepo + Bun/pnpm 工作区的可移植 monorepo 规范。单独使用此 技能即可，无需依赖其他技能。

职责： 工作区配置、包边界、turbo 任务/缓存、根目录脚本。

不属于此技能： Turbo CLI 深入文档、远程缓存供应商配置，或应用内的功能 模块树（HTTP 路由 / Start 页面属于对应技术栈的应用架构文档）。

如果目标仓库已有 monorepo 规则文档（例如 AGENTS.md），且与此处冲突， 以仓库规则为准，除非用户要求迁移以遵循此技能。

核心技术栈默认值

部分	默认值
包管理器	Bun 工作区（如果已在使用 pnpm/npm，也可以继续使用）
布局	apps/*、packages/*
编排	Turborepo（turbo.jsonc / turbo.json）
内部包	"exports": { ".": "./src/index.ts" } — Bun 直接运行 TS
环境变量	应用拥有 .env + T3 Env src/env.ts；包使用 .make(options)
验证	完成阶段运行完整任务图；编辑过程中迭代使用 --filter

模式

1. 搭建 — 根据 checklist.md + tree.md 新建应用/包。
2. 应用 — 正确添加脚本、依赖和 turbo 配置。
3. 审查 — 对照 rules.md；提出调整建议。

核心硬性规则

1. 工作区 + 共享版本固定 — 通过 catalog（或等效方式）共享依赖；工作区依赖使用 workspace:*。
2. 由 Turbo 编排脚本 — 它不是包管理器。包脚本不得为同一任务递归调用 turbo run。
3. transit DAG — 使用不含脚本的 transit / topo 节点，并设置 dependsOn: ["^transit"]，以便 typecheck / test 并行运行，同时在依赖源代码变更时使缓存失效。
4. 持久化 / 会修改内容的任务不缓存 — dev、监听服务器、format、lint:fix、typegen → cache: false（长时间运行的进程还需设置 persistent: true）。
5. Lint/format/test/typecheck 是各工作区的脚本，由 Turbo 运行（跳过未定义相应脚本的包）。
6. 应用拥有环境变量；包的库代码不得读取 process.env — 将选项传入工厂/Layers。
7. 内部入口 = ./src/index.ts，除非该包需要发布/构建（dist/）。
8. 按包名筛选 — 使用 --filter=@org/api，不要误用文件夹路径进行筛选。
9. 在活跃的 monorepo 中优先采用干净的破坏性变更 — 在同一变更中删除垫片/双写/弃用别名；同时更新调用方。
10. 完成阶段的验证 = 完整任务图，除非用户明确推迟质量门禁。

详情：rules.md、tree.md、examples.md。

渐进式展开

需要	阅读
规范目录结构	references/tree.md
规则 + 反模式	references/rules.md
搭建 / 审查清单	references/checklist.md
良好与不良布局	references/examples.md
可选扩展	下方的 扩展

扩展

仅在存在匹配的技术栈（或用户提出要求）时加载：

条件	扩展
Bun workspaces.catalog / 命名目录	with-catalog.md
仅根目录使用 Knip	with-knip.md
各软件包使用 Oxlint + Oxfmt	with-oxlint-oxfmt.md
Vitest 脚本 + turbo 测试任务	with-vitest-workspaces.md
应用环境变量 vs 软件包 .make	with-env-packages.md
软件包中的 Effect 服务	with-effect-packages.md
可选类型生成 / OpenAPI 代码生成	with-typegen.md
嵌套的 packages/<group>/* + 第二层作用域	with-engine-nested.md
turbo prune --docker + 空 Root Directory	with-docker-deploy.md
明确列出允许 / 禁止导入的表格	with-dependency-boundaries.md
用于本地基础设施的根目录 compose 辅助工具	with-compose-local.md

边界与应用架构

此技能负责monorepo 接线和软件包边界。在应用内部，功能文件夹树（Elysia 模块、TanStack Start 路由）属于该应用的架构指南——不要在此处另行设计 HTTP/UI 布局。