agentleFS
Sign inStart free
imMamdouhaboammarimMamdouhaboammar/matts-skills-into-chatgpt/skills/codebase-design/SKILL.md

codebase-design

Skill8 starsChanged 2 months agoMITView on GitHub

Shared vocabulary and patterns for designing deep modules with narrow interfaces and clean seams. Use when designing module interfaces, finding deepening opportunities, deciding where seams go, or making code more testable and AI-navigable — even if the user says \"improve this module\". Do NOT use for whole-codebase architectural surveys.

We split this skill into the rules it gives an agent

3 rules. 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 181 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    The Deletion Test: If deleting a module causes complexity to vanish, it was an unnecessary pass-through.

    line 16
  2. Distinctive:

    Key Point: Check the ratio of interface cognitive overhead to internal capabilities.

    line 46
  3. Distinctive:

    Action: When designing complex or foundational modules, draft 2–3 radically different interface designs before coding.

    line 63

“Common” is measured: kept by at least 6 in 10 of the 181 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Codebase Design

Design deep, high-leverage modules that encapsulate complex domain behavior behind minimal interfaces placed at clear architectural seams.

Core Invariants

  1. Depth Over Surface Area: Maximize internal implementation leverage while minimizing interface surface area (few methods, simple primitive parameters).
  2. Interface as Test Surface: External callers and unit tests cross the exact same seam; never pierce the interface to test internal private plumbing.
  3. The Deletion Test: If deleting a module causes complexity to vanish, it was an unnecessary pass-through; if complexity scatters across $N$ callers, it was earning its keep.
  4. Real vs. Hypothetical Seams: One adapter indicates a hypothetical seam; introduce an interface seam only when at least two concrete adapters vary across it.
  5. Exact Design Vocabulary: Strictly use canonical terminology (module, interface, depth, seam, adapter, leverage, locality); avoid vague synonyms (service, component, boundary).

Architecture & Map of Content (MOC)

┌───────────────────────────────────────┐
│       Narrow Public Interface         │  ◄── Small surface (few methods, simple inputs)
├───────────────────────────────────────┤
│                                       │
│          Deep Implementation          │  ◄── High leverage, hidden state, rich logic
│                                       │
└───────────────────────────────────────┘
ComponentResponsibilityReference
Module DeepeningRefactor shallow pass-throughs into deep modulesskills/codebase-design/DEEPENING.md
Design It TwiceExplore multi-model interface variationsskills/codebase-design/DESIGN-IT-TWICE.md
Testability RulesAccept dependencies, return pure valuesPublic seam tests

Step-by-Step Procedure (TWI)

Step 1: Evaluate Current Interface Depth & Seams

  • Action: Inspect the module's public methods, parameter signatures, and call sites.
  • Key Point: Check the ratio of interface cognitive overhead to internal capabilities.
  • Why: Shallow modules force callers to understand internal mechanics, destroying locality.

Step 2: Apply the Deletion Test & Simplify Signatures

  • Action: Consolidate fine-grained procedural methods into unified, intent-revealing operations.
  • Key Point: Hide internal state transformations and dependency instantiations behind the seam.
  • Inline Checklist:
    • Methods reduced to minimal essential operations
    • Dependencies passed in rather than created internally
    • Functions return values rather than mutating global side effects

Step 3: Align Seam with Unit Test Harness

  • Action: Structure test suites to exercise the module strictly through its public interface.
  • Key Point: Eliminate internal mocking and testing of private helper functions.
  • Why: Testing through the interface ensures tests survive internal refactors without breakage.

Step 4: Explore Alternatives (Design It Twice)

  • Action: When designing complex or foundational modules, draft 2–3 radically different interface designs before coding.
  • Key Point: Compare candidates on depth, locality, and caller ergonomics.
  • Why: The first interface that comes to mind is rarely the deepest or most maintainable.

Anti-Rationalization Guardrails

Tempting RationalizationBinding RuleEngineering Rationale
"Expose private helper functions so we can write unit tests for them."Forbidden. Test exclusively through the public interface.Testing private helpers couples tests to implementation details and prevents refactoring.
"Create an interface and adapter for a single implementation."Wait for 2 adapters before extracting a generic seam.Speculative generalization creates shallow, unnecessary abstraction layers.
"Break this 100-line cohesive function into 5 single-use files."Maintain locality inside deep modules.Excessive fragmentation increases cognitive load and scatters related logic.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free