devcxl 设置 TS 深度模块
让此仓库中的每个 package 都成为一个深度模块：小接口背后隐藏大量行为。一个 package 的公开表面是其入口点：package 根目录下的文件：而其子文件夹中的所有内容都是隐藏的。本技能安装 dependency-cruiser 与让入口点成为唯一通路的规则，然后验证规则确实起作用。
关于相关词汇（深度模块、接口、接缝、depth），请调用 Skill 工具并传入 "codebase-design"：在后续内容中使用它的术语。
它强制形成的结构
src/packages/
<name>/
index.ts ← 一个入口点（公开）。外部从这里导入。
client.ts ← 另一个入口点。Package 可以暴露多个。
lib/ ← 实现：对外部隐藏，内部可以自由相互导入。
tests/ ← 与实现并列的测试与 fixtures（一个子文件夹，所以是私有的）。
公开表面是 package 的根文件，而不是某个指定的 index.ts。按惯例实现放在 lib/，测试放在 tests/，让每个 package 都拥有相同的"两个子文件夹"结构。不过规则本身是普适的：任何子文件夹里的任何文件都是私有的，所以你永远不需要为了新增文件夹而扩展配置。
四条规则，全部为 error：
- 入口点边界：package 外部的代码（应用代码或其他 package）只能导入该 package 的入口点（即其根文件），绝不能导入其子文件夹中的任何内容。
- 包内自由：package 自己的文件可以自由地相互导入。
- 测试通过入口点：
<pkg>/tests/下的文件可以导入任何 package 的入口点以及它自己的tests/fixtures，但不能导入任何 package 的子文件夹内部内容（包括它自己的）。跨 package 的集成测试可以，但深路径导入不行。 - 无循环依赖：不允许存在依赖循环。
入口点，而非桶文件（barrel）。 由于公开表面是每个根文件，所以一个 package 可以暴露多个小型入口点（index.ts、client.ts、server.ts），而不是把一切都集中塞进一个巨大的 index.ts。不要用桶文件来再导出整棵子树；保持入口点小而精，把实现藏在子文件夹里。
分层（哪些 package 可以依赖哪些 package）是另一回事，本仓库把它以注释桩（commented stub）的形式留在配置里供填充。
流程
1. 探测环境
- 包管理器：
pnpm-lock.yaml→ pnpm；yarn.lock→ yarn；bun.lockb→ bun；否则 npm。后续所有命令都使用该包管理器（pnpm/yarn/npm run/bunx）。 - packages 根目录：如果存在
src/则使用src/packages，否则使用packages。如果仓库已经有明显不同的约定，请与用户确认。 - 已有配置：检查是否存在
.dependency-cruiser.*文件。若已有，不要覆盖：把四条规则与 options 合并进去，并告知用户你新增了什么。
**完成条件：**包管理器、packages 根目录、是否有已有配置：这三项都已确认。
2. 安装 dependency-cruiser
使用上面探测到的包管理器，把 dependency-cruiser 安装为 devDependency。
完成条件：dependency-cruiser 已出现在 devDependencies 中。
3. 写入配置
将 dependency-cruiser.config.cjs 复制到仓库根目录，命名为 .dependency-cruiser.cjs。把 PACKAGES_ROOT 设置为步骤 1 探测到的根目录。规则是基于路径深度且与扩展名无关的，所以不需要做其他适配。
完成条件：.dependency-cruiser.cjs 存在，PACKAGES_ROOT 正确，且四条禁用规则都已写入。
4. 接入检查流程
- 新增
lint:boundaries脚本：depcruise <packages-root>（或depcruise src）。 - 将其并入仓库的"总检查"命令：那个已经运行 typecheck 的命令（例如
check/ci/validate脚本）。不要改动tsconfig，也不要新增路径别名。 - 如果没有总检查脚本，就新增
lint:boundaries并告诉用户在 CI 中加入它。
完成条件：lint:boundaries 已存在，并作为与 typecheck 同一条命令的一部分运行。
5. 搭建示例 package
创建一个会被提交的 <packages-root>/example/，作为"复制即用"的模板：
index.ts是一个入口点。导出一个委托给内部文件的函数（这样 package 看起来就是深的，而不是一个简单的透传）。lib/impl.ts：一个位于子文件夹中的内部文件，被index.ts导入，从外部无法触达。tests/example.test.ts只导入../index（一个入口点），并针对公开函数进行断言。
告诉用户这是一个可以复制或删除的起始模板。
**完成条件：**示例 package 已存在，通过根入口点暴露行为，并把 impl 隐藏在子文件夹中。
6. 验证规则确实起作用
这是整项技能的完成判定标准：一个在违反时不会失败的配置毫无价值。
- 运行
lint:boundaries。在干净的示例上必须通过。 - 临时向
tests/example.test.ts中添加一个深路径导入（例如import { thing } from "../lib/impl"）。再次运行lint:boundaries；它必须以tests-through-entrypoints报错失败。 - 撤销那个深路径导入。再运行一次，必须通过。
**完成条件：**你已经观察到了"通过 → 在深路径导入时失败 → 再撤销后又通过"这一完整流程。如果步骤 2 没有失败，说明规则没有正确接入，请修复后再结束。
7. 把约定写下来
在 packages 文件夹中写一份 README.md（即 <packages-root>/README.md，放在它所管辖的 packages 旁边），内容覆盖：src/packages/<name>/ 的目录结构（根目录的入口点、lib/ 放实现、tests/ 放测试）、"只能通过 package 的入口点（即根文件）导入"以及如何运行 lint:boundaries。显式劝阻桶文件：暴露多个小型入口点，而不是通过一个 index 再导出一整棵子树。控制在"复制即用片段 + 四条规则各一段"的范围。
然后在仓库的 agent-instructions 文件（优先 CLAUDE.md，否则 AGENTS.md，若两者都不存在则新建 AGENTS.md）中添加一个上下文指针指向它。一行就够，例如 Packages are deep modules: see [src/packages/README.md](./src/packages/README.md) before adding or importing one. 这正是让 agent 在踩到边界规则之前先发现它的关键。
完成条件：<packages-root>/README.md 存在且劝阻桶文件，且仓库的 CLAUDE.md/AGENTS.md 中有指向它的链接。
备注
- 配置中的
$1反向引用（dependency-cruiser 的 group matching）正是让一个 package 可以触达自己的内部、而外部却不能触达的关键。不要把它们拆成多个独立的 per-package 规则。 - 公开 vs 私有由深度决定：package 的根文件是入口点；任何子文件夹里的内容都是私有的。约定俗成的子文件夹是
lib/（实现）和tests/，但规则并未硬编码它们：任何子文件夹都是私有的，所以新增文件夹永远不需要改配置。新增入口点只是新增一个根文件（不需要桶文件）。 - Package 是扁平的：根目录下只有一层直接的子目录。Package 的内部可以嵌套任意深度；但 package 内不能再放另一个 package。
- 使用
.cjs（而不是.js），这样即使在"type": "module"的仓库里，配置中的module.exports也能正常工作。