Skip to content
Skills Library
Programming · Planning

software-design

/software-design

Design judgment for modules, interfaces, and where information lives. Use when designing or restructuring a module or interface, deciding where an abstraction goes, evaluating a decomposition, placing rationale in comments or scoped docs, or comparing alternative designs for a larger change.

Repository
skills ↗
Licence
MIT
Last repository change
16.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 16.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Design judgment for modules, interfaces, and where information lives. Use when designing or restructuring a module or interface, deciding where an abstraction goes, evaluating a decomposition, placing rationale in comments or scoped docs, or comparing alternative designs for a larger change.

Original author description

Design judgment for modules, interfaces, and where information lives. Use when designing or restructuring a module or interface, deciding where an abstraction goes, evaluating a decomposition, placing rationale in comments or scoped docs, or comparing alternative designs for a larger change.

How it works

  1. Deep modules
  2. Decomposition
  3. Volatility
  4. Where information lives
  5. Comments
Original SKILL.md headings · 112 lines, 904 words
SKILL.md preview
---
name: software-design
description: >-
  Design judgment for modules, interfaces, and where information lives. Use
  when designing or restructuring a module or interface, deciding where an
  abstraction goes, evaluating a decomposition, placing rationale in comments
  or scoped docs, or comparing alternative designs for a larger change.
---

# Software Design

**Reduce the amount of information a developer must know, and make the
remaining information obvious.** Software complexity is whatever makes a
system difficult to understand or modify—especially when essential information
is hidden or distant. The goal is **information locality**: the information
needed to understand and modify a part of the system is colocated and easy to
find.

Design for the reader, and the reader is a fresh session: the next engineer, a
reviewer, or an agent with no memory of this conversation. Whatever the author
knew — the request, the rejected alternatives, the failure that shaped the
fix — survives only if it lands in the repository: code, names, comments,
contracts, tests, or the nearest scoped `AGENTS.md`. Judge a design by how
much a fresh reader must gather before they can change it safely.

## Deep modules

A deep module concentrates knowledge: a good abstraction replaces a large
implementation burden with a much smaller interface burden. Callers get
leverage — one implementation pays back across every call site — and
maintainers get locality — change, bugs, and verification concentrate in one
place. When designing an interface, ask: can it have fewer methods, simpler
parameters, more hidden inside?

- **The interface is the test surface.** Callers and tests use the same
  interface. Wanting to test past the interface usually means the module is
  the wrong shape.
- **The fresh-reader test.** Can someone use the module correctly from its
  interface alone, without opening the implementation or its siblings? If
  crucial behavior is discoverable only by reading the implementation, the
  interface is incomplete; state it in the interface's comment.

## Decomposition

More files, functions, layers, or services is not more modularity. Every
split adds a place a reader must find, load, and reconnect — so split only
when the piece can be understood from its interface without loading its
neighbors. When understanding one piece routinely requires reading three
siblings, the split scattered the logic instead of hiding it; recombine or
deepen instead.

Scattering applies to knowledge too: one invariant half-stated in two
documents, a policy duplicated across layers, a rationale narrated in both a
comment and a nearby `AGENTS.md`. Keep one canonical statement at the
narrowest durable place and link to it from everywhere else — two copies
drift.

There is no useful static threshold for size — lines of code must grow with
essential behavior. A long module that reads top to bottom in one place often
beats a short one that forwards to five others. Judge by the information a
reader must hold, not by static analysis.

## Volatility

How much change is coming to a part of the system is usually written down,
not guessed. The gap between the project's declared goal state and the current
implementation, its roadmap and scope decisions, and open issues all declare
where change is planned and where it is not.
Commit history is not a signal: frequent edits can mean a bad design
forcing rework, not a volatile domain.

An awkward design in an area with no declared change ahead is tolerable
debt. The same flaw on a path the roadmap keeps touching taxes every
future change. When nothing declares an area's future, assume ordinary
volatility rather than using stability as an excuse. Spend design effort
where declared change is coming.

## Where information lives

Code states what happens; it cannot state intent, rejected alternatives,
incident history, or which behavior callers may rely on. Put each fact at the
narrowest durable place a reader will actually encounter:

- **A type, schema, constraint, or lint** for anything an agent could
  otherwise silently violate — prose is advisory; mechanisms survive
  imperfect attention.
- **The interface's comment** for the contract: what callers may depend on.
- **An adjacent comment** for local rationale a reader cannot reconstruct
  from the code.
- **The nearest scoped `AGENTS.md`** for subsystem workflow and conventions.

## Comments

**A comment carries information that cannot be expressed in code.** The test
for any comment: does it help the next reader build an adequate theory of the
program? The author is inside the box, writing to a reader who stands outside
and cannot see what the author saw.

A comment that restates *what* the code does fails the test — it adds reading
without adding information, and it goes stale when the code moves. Write what
the code cannot say:

- **On an interface, what a caller would otherwise get wrong.** Imagine a
  caller who sees only the signature. What would they assume wrongly? What
  would they have to open the implementation to learn? Say that. Use a name
  or a type first when the language allows, and comment only what is left. If
  the signature says everything, write no comment. A widely used interface
  needs its full contract. A private helper with one nearby caller usually
  needs nothing. Do not repeat what the module's comment already says.
- **In an implementation, why — and whatever is not obvious.** The reason the
  code takes this shape (efficiency, a vendor quirk, an incident), the key
  idea of a non-obvious algorithm, the invariant that must not change
  casually, and where it is verified.
- **Key ideas and conclusions, stated explicitly.** Do not leave the reader
  to deduce what the author already knows.

A comment cannot — and need not — say everything. Comments about purpose and
reasoning stay true longer than comments that name the pieces currently in
place.
Files in this package (2)
  • SKILL.md 6 KB
  • agents/openai.yaml 1 KB

Versions

RepositoryScoreLicence
This page · usetemi/skills90MIT
gustavovalverde/skills100MIT

Database snapshot: 13.11.2026 · package version 0c24f97fe20e (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90codebase-design
    Module design discipline from John Ousterhout's A Philosophy of Software Design, depth as the metric (a lot of functionality behind a simple interface), information hiding vs. leakage, the concrete red flags that mark a shallow module, and comparing at least two designs before…
  • 100software-design-philosophy
    Manage software complexity through deep modules, information hiding, and strategic programming. Use when the user mentions "module design", "API too complex", "shallow class", "complexity budget", "strategic vs tactical", "deep module", "information leakage", "pass-through…
  • 100api-and-interface-design
    Stable API and interface design patterns. Use when designing REST/GraphQL endpoints, module boundaries, type contracts between modules or frontend/backend, or changing public interfaces.
  • 100api-and-interface-design
    Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.
  • 100api-and-interface-design
    Stable API and interface design patterns. Use when designing REST/GraphQL endpoints, module boundaries, type contracts between modules or frontend/backend, or changing public interfaces.
  • 100api-and-interface-design
    Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.