AGENT SKILL

setup-ts-deep-modules

将 dependency-cruiser 接入 TypeScript 仓库,使每个包都成为深模块——实现隐藏在子文件夹中,只能通过入口点文件访问。用户调用。

License 许可
MIT
最近更新
2026-07-23
Stars
★ 1
Forks
0

01 前言 Front Matter

name
setup-ts-deep-modules
description
将 dependency-cruiser 接入 TypeScript 仓库,使每个包都成为深模块——实现隐藏在子文件夹中,只能通过入口点文件访问。用户调用。
disable-model-invocation
true

02 资源文件 2

03 SKILL.md 正文

设置 TS 深模块

让本仓库中的每个包都成为深模块:以小接口承载大量行为。包的公共表面是其入口点——包根目录中的文件——而子文件夹中的一切都被隐藏。本技能会安装 dependency-cruiser,配置使入口点成为唯一进入方式的规则,然后证明这些规则确实会生效。

要获取相关词汇(深模块、接口、接缝、深度),请运行 /codebase-design 技能——全程使用其中的语言。

强制采用的形态

src/packages/
  <name>/
    index.ts        ← 入口点(公开)。包外从这里导入。
    client.ts       ← 另一个入口点。包可以暴露多个入口点。
    lib/            ← 实现:对外隐藏,内部可相互导入。
    tests/          ← 同位置的测试和夹具(位于子文件夹,因此私有)。

公共表面是包的根文件——而不是某个指定的 index.ts。按照约定,实现位于 lib/ 中,测试位于 tests/ 中,使每个包都采用相同的双文件夹形态。不过规则本身是通用的:任意子文件夹中的任何内容都是私有的,因此绝不需要为了添加文件夹而扩展配置。

四条规则,严重性均为 error:

  1. 入口点边界——包外代码(应用代码或其他包)只能导入该包的入口点(根文件),绝不能导入其子文件夹中的任何内容。
  2. 包内自由——包自己的文件可以自由地相互导入。
  3. 通过入口点测试——<pkg>/tests/ 下的文件可以导入任意包的入口点和自身的 tests/ 夹具,但绝不能导入任何包的子文件夹内部内容(甚至自己的也不行)。允许跨包集成测试;不允许深层导入。
  4. 无循环——不得存在依赖循环。

使用入口点,而不是桶文件。 由于公共表面是每个根文件,因此包可以暴露若干小型入口点(index.ts、client.ts、server.ts),而不是让所有内容都通过一个庞大的 index.ts 汇聚。不鼓励使用重新导出整个子树的桶文件——入口点应保持小巧,实现则隐藏在子文件夹中。

分层(哪些包可以依赖哪些包)是另一项关注点;配置中为其保留了带注释的桩,由本仓库自行填写。

步骤

1. 检测环境

  • 包管理器——pnpm-lock.yaml → pnpm,yarn.lock → yarn,bun.lockb → bun,否则使用 npm。下方每条命令都使用该包管理器(pnpm/yarn/npm run/bunx)。
  • 包根目录——如果 src/ 存在,则使用 src/packages,否则使用 packages。如果仓库已有明显不同的约定,请向用户确认选择。
  • 现有配置——检查 .dependency-cruiser.* 文件。如果存在,不得覆盖:将四条规则和选项合并进去,并告诉用户添加了什么。

完成标准: 已知包管理器、包根目录和现有配置状态。

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)。
  • 将其纳入仓库的综合检查命令——即已经运行类型检查的命令(例如 check/ci/validate 脚本)。不得修改 tsconfig,也不得添加路径别名。
  • 如果没有综合脚本,则添加 lint:boundaries,并告诉用户将其纳入 CI。

完成标准: lint:boundaries 存在,并与类型检查作为同一命令的一部分运行。

5. 搭建示例包脚手架

创建并提交 <packages-root>/example/,作为可复制模板:

  • index.ts——入口点。导出一个委派给内部文件的函数(让包明显是深的,而不是透传层)。
  • lib/impl.ts——位于子文件夹中的内部文件,由 index.ts 导入,无法从外部访问。
  • tests/example.test.ts——仅导入 ../index(入口点),并针对公共函数进行断言。

告诉用户这是可以复制或删除的起始模板。

完成标准: 示例包存在,通过根入口点暴露其行为,并将 impl 隐藏在子文件夹中。

6. 证明规则确实生效

这是整个技能的完成标准——无法在违规时失败的配置毫无价值。

  1. 运行 lint:boundaries。它必须在干净的示例上通过。
  2. 临时向 tests/example.test.ts 添加深层导入(例如 import { thing } from "../lib/impl")。再次运行 lint:boundaries——它必须失败,并给出 tests-through-entrypoints。
  3. 撤销深层导入。再次运行——它必须通过。

完成标准: 你已观察到先通过,再因深层导入而失败,最后再次通过。如果步骤 2 没有失败,说明规则接入不正确——必须在完成前修复。

7. 记录约定

编写 README.md,并将它放在包文件夹中(<packages-root>/README.md)——紧邻它所管辖的包——涵盖:src/packages/<name>/ 布局(入口点位于根目录、lib/ 存放实现、tests/ 存放测试)、“仅通过包的入口点(根文件)导入”,以及如何运行 lint:boundaries。明确不鼓励使用桶文件——应当暴露若干小型入口点,而不是通过单个 index 重新导出整个子树。内容限制为可复制片段,并让四条规则每条各用一个段落说明。

然后从仓库的智能体指令文件添加指向它的上下文指针——如果 CLAUDE.md 存在则使用它,否则使用 AGENTS.md(如果两者都不存在,则创建 AGENTS.md)。一行即可,例如:包采用深模块设计——添加或导入包之前,请参阅 [src/packages/README.md](./src/packages/README.md)。这样智能体才能主动发现边界规则,而不是被规则绊倒。

完成标准: <packages-root>/README.md 已存在并明确不鼓励使用桶文件,而且仓库的 CLAUDE.md/AGENTS.md 已链接到该文件。

说明

  • 配置中的 $1 反向引用(dependency-cruiser 的分组匹配)使包能够访问自身内部内容,同时禁止外部访问——不要将它们展开成逐包独立规则。
  • 公共与私有由深度决定:包的根文件是入口点;子文件夹中的任何内容都是私有的。约定的子文件夹是 lib/(实现)和 tests/,但规则并未将它们硬编码——任何子文件夹都是私有的,因此新文件夹绝不需要修改配置。添加入口点只需添加根文件——无需桶文件。
  • 包是扁平的:根目录下只有一层直接子目录。包的内部结构可以任意深地嵌套;包不能包含另一个包。
  • 使用 .cjs(而不是 .js),使配置的 module.exports 即使在 "type": "module" 仓库中也能工作。

04 同仓库更多 Skills