ai-codebase-deep-modules

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

AI Codebase Deep Modules

AI代码库深度模块（Deep Modules）

Turn “a web of shallow, cross-importing files” into a codebase that is easy for AI (and humans) to navigate, change, and test.

This skill is built around four ideas:

The codebase matters more than the prompt. AI struggles when feedback is slow, structure is unclear, and dependencies are tangled.
Match the filesystem to the mental model. Group code the way you think about it (features/domains/services), not as a grab-bag of utilities.
Prefer deep modules. Lots of implementation behind a small, well-designed public interface.
Treat deep modules as greyboxes. Lock behaviour with tests at the boundary; internal code becomes replaceable.

将“由浅层次、交叉导入的文件构成的网状结构”转变为一个便于AI（及人类）导航、修改和测试的代码库。

本技能围绕四大核心理念构建：

代码库比提示词更重要。当反馈速度慢、结构不清晰、依赖关系混乱时，AI会难以处理。
让文件系统匹配心智模型。按照你思考功能/领域/服务的方式组织代码，而非将其作为零散工具的集合。
优先使用深度模块（deep modules）。在小型、设计良好的公共接口背后隐藏大量实现细节。
将深度模块视为灰盒（greyboxes）。通过边界测试锁定行为；内部代码可被替换。

When to use this skill

何时使用本技能

Use this skill when the user wants any of the following:

Refactor an existing repo to be more navigable and safer for AI-assisted coding
Introduce/strengthen module boundaries, reduce coupling, or eliminate “spaghetti imports”
Restructure the repo by feature/domain (a “map you hold in your head” reflected on disk)
Define service/module interfaces, public APIs, and “only import from here” rules
Build fast feedback loops (tests, typecheck, lint) so AI can verify changes quickly
Plan a refactor with incremental steps, acceptance criteria, and tests

Do not use this skill for:

One-off debugging of an isolated error (use normal debugging / code review)
Purely stylistic refactors with no boundary or testing implications
Writing greenfield code where the user already has a clear modular architecture (unless they want a module template)

当用户有以下需求时使用本技能：

重构现有仓库，使其更易于导航且更适合AI辅助编码
引入/强化模块边界，降低耦合度，消除“面条式导入（spaghetti imports）”
按功能/领域重构仓库（将你脑海中的“地图”映射到磁盘上）
定义服务/模块接口、公共API以及“仅从此处导入”的规则
构建快速反馈循环（测试、类型检查、代码扫描），让AI可快速验证变更
规划包含增量步骤、验收标准和测试的重构方案

请勿在以下场景使用本技能：

孤立错误的一次性调试（使用常规调试/代码审查即可）
仅涉及风格调整、不影响边界或测试的重构
用户已有清晰模块化架构的全新代码编写（除非需要模块模板）

Inputs this skill expects (minimal)

本技能期望的输入（最低要求）

If available, ask for or infer:

Language/runtime (TS/JS, Python, Go, Java/Kotlin, etc.)
How to run the fastest meaningful check (unit tests, typecheck, lint, build)
The top 3–7 “chunks” of product behaviour (domains/features/services)
Any hard constraints (monorepo tooling, existing packages, deployment boundaries)

If the user hasn’t provided this, do not stall. Make best-effort guesses by inspecting:

package.json

pyproject.toml

go.mod

pom.xml

build.gradle

Makefile

justfile

```
src/
```
,
```
app/
```
,
```
packages/
```
,
```
services/
```
,
```
modules/
```
existing test folders and CI configs

若有可用信息，请求或推断以下内容：

语言/运行时（TS/JS、Python、Go、Java/Kotlin等）
如何运行最快速的有效检查（单元测试、类型检查、代码扫描、构建）
产品核心行为的前3–7个“模块”（领域/功能/服务）
任何硬性约束（单仓库工具、现有包、部署边界）

若用户未提供上述信息，请勿停滞。通过检查以下内容做出合理猜测：

package.json

pyproject.toml

go.mod

pom.xml

build.gradle

Makefile

justfile

```
src/
```
,
```
app/
```
,
```
packages/
```
,
```
services/
```
,
```
modules/
```
现有测试文件夹和CI配置

Workflow

工作流程

Step 0 — Establish the feedback loop (non-negotiable)

步骤0 — 建立反馈循环（必不可少）

Goal: ensure there is a fast “did it work?” loop before and during refactors.

Identify the quickest command that provides signal:

Typecheck:
```
tsc -p tsconfig.json
```
Unit tests:
```
npm test
```
,
```
pytest -q
```
,
```
go test ./...
```
Lint:
```
eslint .
```
,
```
ruff check
```
,
```
golangci-lint run
```

Prefer a single “verify” entrypoint:

make verify

just verify

npm run verify

./scripts/verify.sh

If tests are missing, propose the smallest viable starting point:
- Smoke tests for core flows
- Contract tests for the boundaries you’re about to introduce
If the loop is slow, propose speed-ups before large refactors:
- Run only impacted packages
- Split unit vs integration tests
- Cache dependencies in CI

Deliverable: a short “Feedback loop” section with the exact commands and expected outputs.

目标：确保在重构前和重构过程中存在快速的“是否有效？”循环。

识别能提供有效信号的最快命令：
- 类型检查：
```
tsc -p tsconfig.json
```
- 单元测试：
```
npm test
```
  ,
```
pytest -q
```
  ,
```
go test ./...
```
- 代码扫描：
```
eslint .
```
  ,
```
ruff check
```
  ,
```
golangci-lint run
```

优先使用单一“验证”入口：

make verify

just verify

npm run verify

./scripts/verify.sh

若缺少测试，提出最小可行的起始方案：
- 核心流程的冒烟测试
- 针对即将引入的边界的契约测试
若反馈循环缓慢，在大型重构前提出优化方案：
- 仅运行受影响的包
- 拆分单元测试与集成测试
- 在CI中缓存依赖

交付物：简短的“反馈循环”部分，包含确切命令和预期输出。

Step 1 — Reconstruct the mental map of the codebase

步骤1 — 重构代码库的心智模型

Goal: identify the natural groupings that already exist in the product.

List the product domains/features (aim for 3–10):
- e.g.
```
auth
```
  ,
```
billing
```
  ,
```
thumbnail-editor
```
  ,
```
video-editor
```
  ,
```
cms-forms
```
For each domain, identify:
- entrypoints (routes/controllers/handlers)
- data boundaries (models/schemas)
- external dependencies (APIs, DB, queues)
Capture the current pain:
- “Where do people get lost?”
- “What breaks when we change X?”
- “Where are imports crossing domains?”

Deliverable: a Module Map (table) with: domain, responsibilities, key files, current coupling risks.

目标：识别产品中已存在的自然分组。

列出产品的领域/功能（目标3–10个）：
- 示例：
```
auth
```
  ,
```
billing
```
  ,
```
thumbnail-editor
```
  ,
```
video-editor
```
  ,
```
cms-forms
```
针对每个领域，识别：
- 入口点（路由/控制器/处理器）
- 数据边界（模型/模式）
- 外部依赖（APIs, DB, queues）
记录当前痛点：
- “人们通常在哪些地方迷路？”
- “当我们修改X时，哪些部分会出错？”
- “哪些地方存在跨领域的导入？”

交付物：模块映射表（表格），包含：领域、职责、关键文件、当前耦合风险。

Step 2 — Design deep modules (few, chunky, stable interfaces)

步骤2 — 设计深度模块（少量、紧凑、稳定的接口）

Goal: reduce the number of things the agent must keep in working memory.

For each domain/module candidate:

Define the public interface (small surface area):
- functions/classes/commands exposed
- public types/data contracts
- error/edge-case semantics
Define what is explicitly internal:
- helper functions, adapters, DB queries, parsing, etc.
Decide the dependency direction:
- Prefer:
```
domain → shared primitives
```
- Avoid:
```
domain ↔ domain
```
  cross-imports
Keep the interface boring and predictable:
- stable names
- minimal parameters
- explicit return types / result objects

Deliverable: an Interface Spec for each deep module:

Public API (signatures)
Invariants (pre/post conditions)
Examples (happy path + one edge case)

See: references/module-templates.md

目标：减少Agent必须记住的内容数量。

针对每个候选领域/模块：

定义公共接口（小表面积）：
- 暴露的函数/类/命令
- 公共类型/数据契约
- 错误/边缘情况语义
定义明确的内部内容：
- 辅助函数、适配器、DB查询、解析逻辑等
确定依赖方向：
- 优先选择：
```
领域 → 共享原语
```
- 避免：
```
领域 ↔ 领域
```
  的交叉导入
保持接口简洁且可预测：
- 稳定的命名
- 最少的参数
- 明确的返回类型/结果对象

交付物：每个深度模块的接口规范：

公共API（签名）
不变量（前置/后置条件）
示例（正常路径 + 一个边缘情况）

See: references/module-templates.md

Step 3 — Align the filesystem to the map (progressive disclosure)

步骤3 — 使文件系统与映射对齐（渐进式披露）

Goal: make it obvious where to look.

Default rule: outside code imports only from a module’s public entrypoint.

Recommended structure (adapt per language):

```
src/<module>/
```
- ```
index.*
```
  (public exports)
- ```
types.*
```
  (public types)
- ```
internal/
```
  (implementation details; not imported from outside)
- ```
__tests__/
```
  or
```
tests/
```
  (contract tests for the public API)

If the repo uses packages, prefer

packages/<module>/

with explicit exports.

Deliverable: a “Move plan” listing:

directories to create
files to move
import paths to update
temporary compatibility shims (if needed)

目标：让代码位置一目了然。

默认规则：外部代码仅从模块的公共入口点导入。

推荐结构（根据语言调整）：

```
src/<module>/
```
- ```
index.*
```
  （公共导出）
- ```
types.*
```
  （公共类型）
- ```
internal/
```
  （实现细节；禁止外部导入）
- ```
__tests__/
```
  或
```
tests/
```
  （针对公共API的契约测试）

若仓库使用包，优先选择

packages/<module>/

并配置显式导出。

交付物：“迁移计划”列表，包含：

要创建的目录
要移动的文件
要更新的导入路径
临时兼容性垫片（若需要）

Step 4 — Make modules greyboxes with boundary tests

步骤4 — 通过边界测试将模块变为灰盒

Goal: you shouldn’t need to understand internals to trust behaviour.

Write/identify contract tests for each module’s public API:
- behavioural checks
- key error cases
- side effects (DB writes, events emitted) via fakes/spies
Keep tests close to the interface:
- treat internals as replaceable
Only add internal unit tests where:
- performance-critical logic needs tight coverage
- tricky algorithms deserve direct tests

Deliverable: test plan + initial contract test skeletons.

See: references/testing-and-feedback.md

目标：无需理解内部细节即可信任模块行为。

为每个模块的公共API编写/识别契约测试：
- 行为检查
- 关键错误场景
- 通过模拟/间谍测试副作用（DB写入、事件触发）
将测试放在靠近接口的位置：
- 将内部代码视为可替换的
仅在以下情况添加内部单元测试：
- 性能关键逻辑需要严格覆盖
- 复杂算法需要直接测试

交付物：测试计划 + 初始契约测试框架。

See: references/testing-and-feedback.md

Step 5 — Enforce boundaries (so the architecture stays true)

步骤5 — 强制实施边界（确保架构保持稳定）

Goal: prevent the codebase from drifting back into a web.

Pick the lightest viable enforcement:

Conventions + code review (baseline)
Lint rules (TS/JS:
```
no-restricted-imports
```
, ESLint boundary plugins)
Architecture tests (assert “module A cannot import module B”)
Language-level boundaries (Go
```
internal/
```
, Rust
```
pub(crate)
```
, Java modules)

Deliverable: an “Enforcement” section with the exact rules and where to configure them.

See: references/boundary-enforcement.md

目标：防止代码库重新回到网状结构。

选择最轻量的可行实施方式：

约定 + 代码审查（基线）
代码扫描规则（TS/JS：
```
no-restricted-imports
```
、ESLint边界插件）
架构测试（断言“模块A不能导入模块B”）
语言级边界（Go
```
internal/
```
、Rust
```
pub(crate)
```
、Java模块）

交付物：“实施”部分，包含确切规则和配置位置。

See: references/boundary-enforcement.md

Step 6 — Refactor incrementally (strangler pattern)

步骤6 — 增量重构（绞杀者模式）

Goal: avoid giant-bang rewrites.

Suggested sequence:

Create the new module folder and public interface (empty implementation).
Add contract tests (they will fail).
Add a thin adapter that wraps existing code (tests pass).
Move internals gradually behind the interface:
- keep exports stable
- delete old entrypoints only once usage is migrated
Repeat module-by-module.

Deliverable: a stepwise refactor plan with checkpoints and rollback options.

目标：避免大规模重写。

建议顺序：

创建新的模块文件夹和公共接口（空实现）。
添加契约测试（此时测试会失败）。
添加薄适配器包装现有代码（测试通过）。
逐步将内部逻辑迁移到接口之后：
- 保持导出稳定
- 仅在所有使用都迁移完成后删除旧入口点
逐个模块重复上述步骤。

交付物：带检查点和回滚选项的分步重构计划。

Output format (what to produce)

输出格式（需生成的内容）

When this skill is activated, produce a structured plan using this outline:

Current state summary (1–2 paragraphs)
Fast feedback loop (exact commands)
Module Map (table)
Proposed deep modules (list + responsibilities)
Interface specs (per module)
Filesystem changes (move plan)
Boundary enforcement (rules + tooling)
Testing strategy (contract tests first)
Incremental migration steps (with checkpoints)

Optional: copy the template from

assets/architecture-plan-template.md

激活本技能时，使用以下大纲生成结构化计划：

当前状态总结（1–2段）
快速反馈循环（确切命令）
模块映射表（表格）
拟议深度模块（列表 + 职责）
接口规范（每个模块）
文件系统变更（迁移计划）
边界实施（规则 + 工具）
测试策略（优先契约测试）
增量迁移步骤（带检查点）

Optional: copy the template from

assets/architecture-plan-template.md

Examples

示例

Example 1 — Broad request

示例1 — 宽泛请求

User says: “Make our TypeScript monorepo more AI-friendly. It’s hard to find things and tests are slow.”

Actions:

Identify
```
verify
```
loop (typecheck + unit tests) and how to run it per package.
Produce a module map (3–7 modules).
Propose deep modules with a clear public interface (
```
index.ts
```
,
```
types.ts
```
).
Recommend boundary enforcement via ESLint
```
no-restricted-imports
```
.
Add contract tests for each module.

Result: a concrete refactor plan and initial skeletons that can be executed incrementally.

User says: “Make our TypeScript monorepo more AI-friendly. It’s hard to find things and tests are slow.”

Actions:

Identify
```
verify
```
loop (typecheck + unit tests) and how to run it per package.
Produce a module map (3–7 modules).
Propose deep modules with a clear public interface (
```
index.ts
```
,
```
types.ts
```
).
Recommend boundary enforcement via ESLint
```
no-restricted-imports
```
.
Add contract tests for each module.

Result: a concrete refactor plan and initial skeletons that can be executed incrementally.

Example 2 — Specific boundary problem

示例2 — 特定边界问题

User says: “Auth imports billing and billing imports auth. We keep breaking things.”

Actions:

Identify dependency cycle and why it exists (shared types? shared DB code?).
Extract a deep module interface boundary:
- ```
auth
```
  exports
```
getCurrentUser()
```
  ,
```
requireAuth()
```
- ```
billing
```
  depends on those interfaces only (no deep imports)
Move shared primitives into
```
shared/
```
or
```
platform/
```
module.
Add an architecture rule to prevent the cycle returning.

Result: cycle removed, boundaries enforced, behaviour locked by tests.

User says: “Auth imports billing and billing imports auth. We keep breaking things.”

Actions:

Identify dependency cycle and why it exists (shared types? shared DB code?).
Extract a deep module interface boundary:
- ```
auth
```
  exports
```
getCurrentUser()
```
  ,
```
requireAuth()
```
- ```
billing
```
  depends on those interfaces only (no deep imports)
Move shared primitives into
```
shared/
```
or
```
platform/
```
module.
Add an architecture rule to prevent the cycle returning.

Result: cycle removed, boundaries enforced, behaviour locked by tests.

Troubleshooting

故障排除

Skill feels too “high level”

技能感觉太“高层”

Use the template and references to get concrete:

references/module-templates.md
references/prompts.md

Use the template and references to get concrete:

references/module-templates.md
references/prompts.md

Refactor is risky / unknown behaviour

重构风险高/行为未知

Prioritise greybox contract tests first:

freeze behaviour at the public interface
only then move internals

Prioritise greybox contract tests first:

freeze behaviour at the public interface
only then move internals

Boundaries are hard to enforce in TS/JS

在TS/JS中难以实施边界

Start with lint rules and path conventions; add architecture tests if needed. See: references/boundary-enforcement.md