Skip to content
SkillModel-led1,295 tokens in use

Codebase Design

Shared vocabulary for deep modules: a lot of behaviour behind a small interface, placed at a clean seam and testable through that interface.

328,754 stars on the repository MIT Licensemattpocock/skills · skills/engineering/codebase-design
claude plugin install mattpocock-skills@claude-plugins-official
View source

Install command as written in the repository's README

Skill label

measured from its files

What installing Codebase Design costs

57tokens idle
1,295tokens in use
2,451tokens, up to

Idle is what sits in context while the skill is installed. In use is its instructions, loaded when it runs. Up to adds the files its instructions link. Counts are approximate, made offline with cl100k_base.

Model dependence Model-led

Script-ledMixedModel-led

Mostly instructions, so how well it works depends on the model that follows them.

This describes the skill's structure, how much of it is scripts. It does not say how well it works.

Touches

Nothing detected: no shell, network, file writes, git or credentials in its files.

Declared tags come from the skill's frontmatter; detected ones from its scripts and code blocks. This is detected, not audited.

How it scores

Quality

How well the skill is written, counted from its own files: its frontmatter, its steps, examples, stated output and constraints, its size and whether every file it ships is one it names.How we score it →
Good
  • Frontmatter12/15
  • Structure17/25
  • Examples9/15
  • Output10/15
  • Size15/15
  • Resources10/15

Security

Starts at 100 and loses points for each thing in the skill's files that a reader should look at first.How we score it →
Excellent

No findings.

Repository health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum.How we score it →
Excellent
  • Development activity96
  • Maintenance100
  • Community56
  • Maturity32
  • Momentum40

Codebase Design gives the model a fixed glossary (module, interface, implementation, depth, seam, adapter, leverage, locality) and a set of principles for designing or restructuring code. It asks the model to use these terms exactly and to avoid component, service, API and boundary.

Two companion documents cover deepening a cluster of modules by dependency category and exploring alternative interfaces with parallel sub-agents.

What You Get

  • A glossary of eight terms, with the words to avoid for each
  • Principles including the deletion test, the interface as the test surface, and the rule that one adapter means a hypothetical seam while two mean a real one
  • DEEPENING.md, with four dependency categories (in-process, local-substitutable, remote but owned, true external) and the testing strategy for each
  • DESIGN-IT-TWICE.md, a pattern that spawns three or more sub-agents to design the interface in radically different ways and compares them on depth, locality and seam placement

Common Use Cases

  • Reshaping a cluster of shallow modules into one deep module
  • Deciding whether a port is justified at the boundary between your code and a third-party service
  • Giving a team and its agents one consistent vocabulary for design discussions

What Makes It Unique

It defines depth as leverage at the interface and sets aside the ratio of implementation lines to interface lines, because that ratio rewards padding. It gives a concrete test for whether a seam is real, and a replace-the-old-tests rule for testing a deepened module. A Rejected framings section names the alternatives it set aside.

Under The Hood

The skill is reference text with no scripts. The model reads SKILL.md when a design task matches its description, and loads DEEPENING.md or DESIGN-IT-TWICE.md when it needs them. The design-it-twice pattern starts sub-agents with fresh context windows. The skill itself runs no commands and reaches no network.

Join founders building with open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on SubstackJoin 750+ subscribers