agentleFS
Sign inStart free
theonly1metheonly1me/shadowclone/skills/design-deep-modules/SKILL.md

design-deep-modules

Skill25 starsChanged 32 days agoMITView on GitHub

Use when designing or reshaping a module, or when callers coordinate too many steps. Also use it when the user says "this is hard to test", "callers know too much", or "simplify this interface". Puts related state and decisions behind a small interface that states what the caller wants. Tests then use that interface instead of the internal steps. Not for typing values at a boundary (use `typescript-type-safety`).

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

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

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈10

    Distinctive · estimate

    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:

    Do the tests use the public interface, and replace dependencies only at outside boundaries?

    line 20
  2. Distinctive:

    Read the callers. List the state, the order of steps, and the rules that they coordinate.

    line 25
  3. Distinctive:

    Put that state and those decisions under one owner.

    line 26
  4. Distinctive:

    If the boundary is not clear, compare two placements by caller effort, error handling, and test effort.

    line 27
  5. Distinctive:

    Remove each layer that only forwards calls.

    line 29
  6. Distinctive:

    Write tests against the new interface, then remove the knowledge that callers no longer need.

    line 30
  7. Distinctive:

    Easy route: Add a helper for each of the four steps, and keep the order in each command.

    line 35
  8. Distinctive:

    Best route: Add one operation that takes the intended change and does the four steps inside.

    line 37
  9. Distinctive:

    Use an options object when callers would otherwise pass related values in a fixed order.

    line 42
  10. Distinctive:

    Do not add an abstraction without a concrete variation or isolation need.

    line 44

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “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

Design Deep Modules

Use when

Callers repeat the same sequence of calls, a layer only forwards arguments, or tests must reach through layers to see behavior. A deep module gives callers a lot of behavior through a small interface.

Gates

  1. Can each caller state its intent in one call, without knowing the internal order of steps?
  2. Does one owner hold each piece of related state and each decision about it?
  3. Does each new layer serve a real variation or isolation need, not only forwarding?
  4. Do the tests use the public interface, and replace dependencies only at outside boundaries?
  5. Are the invariants and the error behavior part of the interface contract?

Process

  1. Read the callers. List the state, the order of steps, and the rules that they coordinate.
  2. Put that state and those decisions under one owner. Name an operation for what the caller wants.
  3. If the boundary is not clear, compare two placements by caller effort, error handling, and test effort.
  4. Move the internal order of steps behind the interface.
  5. Remove each layer that only forwards calls.
  6. Write tests against the new interface, then remove the knowledge that callers no longer need.

Example

Situation: Three commands each read a config file, merge it with defaults, check a policy, and take a lock before they write. Easy route: Add a helper for each of the four steps, and keep the order in each command. Hidden cost: Each command still owns the order. A new command can skip the policy check, and each test must repeat the four steps. Best route: Add one operation that takes the intended change and does the four steps inside. The commands call that operation. Evidence: Each command became one call. A test through the new operation failed without the policy check, and the step tests in each command were no longer needed.

Guardrails

  • Use an options object when callers would otherwise pass related values in a fixed order.
  • Return the outcomes that callers need, and keep side effects inside their owner.
  • Do not add an abstraction without a concrete variation or isolation need.
  • A short interface still costs effort if callers must call it in a hidden order.

Completion

  • The new interface: its exported names and one call example.
  • The caller steps that the module now owns.
  • The test command for the new interface, with its result line.

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