Deep Modules: A Shared Design Vocabulary for Agents

Where this fits

You're pairing with an agent to refactor a tangled service that's grown into a god-class. The agent suggests splitting it into "components" with vague boundaries, and you spend hours re-aligning its mental model. The codebase-design skill gives agents a precise, shared vocabulary for designing deep modules — lots of behavior behind a small interface, placed at clean seams. It turns fuzzy refactors into conversations about specific trade-offs, making the agent's design suggestions immediately actionable and consistent with how your team thinks about code.

Why agents benefit

• Speaks your language: Uses terms like module, interface, seam, and deepness exactly, avoiding ambiguous substitutes like "service" or "API." Your agent's suggestions become interpretable and reviewable.
• Finds deepening opportunities: The skill guides the agent to spot where a module's interface is too wide or its implementation too shallow, proposing concrete interface reductions.
• Places seams deliberately: Instead of guessing, the agent can reason about where a seam should go based on deep-module principles, yielding boundaries that survive change.
• Improves testability: Designing through the interface means tests exercise behavior, not implementation details — the agent produces code that's easier to mock and verify.
• AI-navigable code: Consistent module shapes make code predictably structured, so future agent passes find the right files faster.

Practical scenarios

Finding a seam in a monolithic service

An agent analyzes a 2,000-line order processor. Using deep-module vocabulary, it identifies the core business rules as a deep module with a narrow interface (e.g., process(order) -> Result), and proposes moving I/O outside. The agent can explain why that seam reduces caller complexity.

Making a module testable through its interface

The agent redesigns a configuration loader that currently exposes multiple internal setters. It collapses them into a single load(configSource) method, hiding parsing and validation. Tests now only need one entry point, and accidental state leakage disappears.

Adding a feature without bloating the interface

Your agent adds a caching layer to an existing repository module. Rather than adding new public methods, it wraps the existing interface with a decorator, preserving the deep-module shape. The agent uses the glossary to justify that the cache doesn't change the contract.

Add it to your agent workflow

Install the skill into your project's agent configuration:

npx skills add ConnorGriffin/skills --skill codebase-design

Then instruct your agent to apply it:

Refactor the payment processing into a deep module with a small interface. Use the codebase-design vocabulary to explain your seam choices.

The agent will load the skill's glossary and principles, and you'll see design proposals that speak in terms of deepness, interfaces, and seams instead of generic "components." For more context on this skill, see the OpenAgentSkill listing.

Compare before adopting

Before you commit, evaluate the skill against alternatives. Check its GitHub stars (currently 18) and last commit date — does the author actively maintain it? Compare with other design skills like domain-modeling (which it can pair with). Most importantly, test whether the vocabulary resonates with your team's existing conventions. If you already use terms like "module" and "interface" precisely, this will slot in cleanly; if not, it still gives you a common language.

Why it is worth tracking

Even at modest star count, this skill fills a real gap: most agent skills focus on code generation or task execution, but few give agents a principled design vocabulary. The author has documented a clear methodology and structured references (DESIGN-IT-TWICE.md). As AI agents take on more refactoring and architectural work, having a shared design language becomes critical. Revisit this skill when your agent starts suggesting interfaces or you need to make your codebase more AI-navigable. Its value grows with your team's adoption — the more you use the exact terms, the better your agent’s output will align.