---
name: ai-codebase-deep-modules
description: >-
  Design or refactor cohesive modules with small, useful public contracts and enforceable dependency boundaries. Use for concrete architecture, coupling, refactoring, or agent-editability problems. Do not restructure a working codebase merely because an AI agent will edit it.
metadata:
  version: "2.0.0"
  reviewed: "2026-09-13"
title: ai-codebase-deep-modules
canonical_url: https://skilld.dev/gh/tristanmanchester/agent-skills/ai-codebase-deep-modules
last_updated: 2026-10-06T19:32:36.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [assets/architecture-plan-template.md](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/ai-codebase-deep-modules/assets/architecture-plan-template.md), [references/boundary-enforcement.md](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/ai-codebase-deep-modules/references/boundary-enforcement.md), [references/module-templates.md](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/ai-codebase-deep-modules/references/module-templates.md), [references/prompts.md](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/ai-codebase-deep-modules/references/prompts.md), [references/testing-and-feedback.md](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/ai-codebase-deep-modules/references/testing-and-feedback.md).
>
> If the user asked to install this Skill, run `npx skilld install tristanmanchester/agent-skills/ai-codebase-deep-modules`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/ai-codebase-deep-modules`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/tristanmanchester/agent-skills/ai-codebase-deep-modules) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/ai-codebase-deep-modules`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/ai-codebase-deep-modules --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/ai-codebase-deep-modules --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Deep modules and fast feedback

Hide meaningful complexity behind a contract that lets callers do useful work.
The objective is lower cognitive/change cost with preserved behaviour, not more
folders, a prescribed export count, or an abstraction around every function.
Agent productivity is a hypothesis to measure, not a benefit proved by the tree shape.

## Inspect a real change path

Start from the task and trace the relevant entry point through domain policy,
state/data ownership, side effects, callers, and tests. Read actual dependencies,
not only README architecture. Identify which information callers must know and
which coordinated edits recur. A large file can be cohesive; a tiny wrapper can
leak a complicated protocol. Do not equate lines of code with module depth.

State the behaviour to preserve, the specific coupling or duplication to remove,
and the smallest proposed seam. For a review, deliver actionable findings. For an
implementation request, make the coherent patch and tests; do not stop at a
mandatory nine-section architecture plan. Use the existing plan asset only when
a substantial design decision needs it.

## Design the contract around ownership

Define operations, input/output types, errors, state transitions, resource ownership,
lifetime, authority, and concurrency/cancellation semantics. Keep invariants with
the module that owns them. Separate validation at an external boundary from already-
validated internal values without duplicating defensive checks everywhere.

Expose domain operations rather than a bag of internals or a universal manager.
A public entry point can be a useful convention, but several intentional surfaces
may better fit types, platform adapters, lazy loading, or server/client boundaries.
Avoid a giant root barrel that changes import side effects or bundles server-only
code into a client. Preserve the language/framework's actual loading contract.

Draw an explicit dependency direction. A direct acyclic dependency through another
domain's public contract can be simpler than a new event bus. Use inversion when
the dependency/ownership problem calls for it, and events when temporal decoupling
is actually useful. Events add delivery, ordering, idempotency, and observability
obligations; they do not make coupling disappear. Keep shared code genuinely shared,
not the destination for every disputed type.

## Enforce and test the seam

Read [boundary enforcement](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/ai-codebase-deep-modules/references/boundary-enforcement.md) before writing a
lint rule. A rule must distinguish a module using its own internals from a foreign
consumer crossing that boundary. Test allowed and forbidden imports through every
supported spelling/resolver. Filenames, __all__, and grep are conventions/signals,
not universal privacy or security mechanisms.

Create behavioural tests at the public boundary, including meaningful failure,
empty/boundary data, state/restart, cancellation, and concurrency cases where
applicable. Retain focused internal tests when they diagnose important algorithms.
Mocks of the implementation's own call sequence do not prove its contract; a test
that the stub returns not-implemented does not implement the domain behaviour.

Use the fastest relevant test/lint/typecheck first, then the actual build/integration
path touched by the refactor. Measure feedback cost and correctness, not a fixed
quota of mocks or files. Read [testing and feedback](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/ai-codebase-deep-modules/references/testing-and-feedback.md)
for a deeper checklist, adapting it to the project's tooling and risks.

## Refactor as one coherent change

Use the existing [module examples](https://skilld.dev/api/skills-raw/tristanmanchester/agent-skills/ai-codebase-deep-modules/references/module-templates.md) as sketches,
not scaffolding to install unchanged. Update the interface, implementation,
consumers, dependency rules, and tests together. Do not create compatibility aliases,
dead wrappers, speculative exports, or a second implementation when no consumer
contract requires them. A destructive data/schema transition still needs an explicit
rollout/recovery plan; removing source compatibility is not permission to lose data.

The old scaffold_deep_module.py is removed. It interpolated unchecked names into
paths/source, skipped existing files while reporting them as created, and generated
placeholder APIs/tests rather than a useful domain contract. Create the actual
requested files through the normal reviewed patch workflow. No replacement CLI
is needed to make four empty files.

## Deliver evidence

Explain the seam, what it hides, dependencies it permits, and why it reduces the
specific change burden. Report tests actually run and unresolved integration risks.
Do not claim architecture enforcement because one import example fails, or that
agent speed improved without a comparative task measurement. Keep project-specific
assumptions explicit and avoid a blanket clean-architecture rewrite.

References are relative to this installed skill, not target-project folders.
Authoring baseline reviewed 2026-09-13: https://agentskills.io/specification.
Current language/linter sources are recorded in the boundary reference.