agentsclimarketplace

Codebase design

Skill neumie/almanac/skills/other/codebase-design

Personal agent toolkit — curated skills for LLM coding agents

Install
npx -y skills add neumie/almanac --skill codebase-design

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use when designing module interfaces, seams, deep modules, testability, AI-navigable architecture, or when another skill needs design vocabulary.

SKILL.md

2.9 KB, 549 tokens by cl100k_base, as published. Nobody here has run it

Codebase Design

Design deep modules: lots of behavior behind a small interface, placed at a clean seam, testable through that interface. Use this language wherever code is designed or restructured. Aim for leverage for callers, locality for maintainers, and testability for everyone.

Glossary

Use these terms exactly. Do not drift into "component", "service", "API", or "boundary" when these terms fit.

Module: anything with an interface and an implementation. Scale-free: function, class, package, or tier-spanning slice.

Interface: everything a caller must know to use a module correctly: type signature, invariants, ordering constraints, error modes, required config, and performance characteristics.

Implementation: code inside a module. Distinct from adapter: an adapter is about the role it fills at a seam.

Depth: leverage at the interface. A module is deep when lots of behavior sits behind a small interface; shallow when the interface is nearly as complex as the implementation.

Seam: place where behavior can be altered without editing in that place; the location where a module interface lives. Use "seam" instead of "boundary" unless discussing DDD bounded contexts.

Adapter: concrete thing satisfying an interface at a seam.

Leverage: what callers get from depth: more capability per interface fact they learn.

Locality: what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place.

Principles

  • Depth is a property of the interface, not the implementation. A deep module can have internal seams and internal composition; callers still see one small external interface.
  • Deletion test. Imagine deleting the module. If complexity vanishes, it was pass-through. If complexity reappears across callers, it was earning its keep.
  • The interface is the test surface. Callers and tests should cross the same seam.
  • One adapter means a hypothetical seam. Two adapters means a real seam. Do not introduce a seam unless something actually varies across it.

Designing For Testability

Good interfaces make testing natural:

  1. Accept dependencies; do not create them internally.
  2. Return results where possible; avoid hidden side effects.
  3. Keep surface area small. Fewer methods and params mean simpler callers and tests.

Going Deeper

  • For dependency categories and safe deepening, read ~/.claude/skills/almanac/codebase-design/references/deepening.md.
  • For alternative interface exploration, read ~/.claude/skills/almanac/codebase-design/references/design-it-twice.md.

Keep looking

Skills are one crate of 328,083. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.