Przejdź do treści
Biblioteka skilli
Programowanie · Nauka i wyjaśnianie

codebase-design

/codebase-design

Wprowadza wspólne słownictwo do projektowania głębokich modułów: interfejsy, szwy, testowalność i nawigację dla agentów.

Repozytorium
astack ↗
Licencja
MIT
Ostatnia zmiana repozytorium
05.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 05.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Wprowadza wspólne słownictwo do projektowania głębokich modułów: interfejsy, szwy, testowalność i nawigację dla agentów.

Oryginalny opis (EN)

Use a shared vocabulary to design deep modules. Apply it to module interfaces, deepening candidates, seam placement, testability, and code that agents must navigate. Other skills use it as a design reference.

Jak działa

  1. Glossary
  2. Deep vs shallow
  3. Principles
  4. Designing for testability
  5. Relationships
  6. Rejected framings
  7. Going deeper
Sekcje z nagłówków SKILL.md, w oryginale · 133 linii, 756 słów
Podgląd SKILL.md
---
name: codebase-design
description: "Use a shared vocabulary to design deep modules. Apply it to module interfaces, deepening candidates, seam placement, testability, and code that agents must navigate. Other skills use it as a design reference."
---

# Codebase Design

Design deep modules with substantial behavior behind a small interface.
Place the interface at a clear seam and test through it.
Use this vocabulary whenever you design or restructure code.
Depth gives callers more capability, maintainers more locality, and tests a useful interface.

## Glossary

Use these terms consistently.
Do not replace them with "component", "service", "API" or an unspecified "boundary".

Module means anything with an interface and implementation.
It can be a function, class, package or slice across tiers.
Avoid "unit", "component" and "service" for this meaning.

Interface means everything callers must know to use a module correctly.
It includes types, invariants, ordering, errors, required configuration and performance.
"API" and "signature" are too narrow because they describe only the type-level part.

Implementation means the code inside a module.
Distinguish it from Adapter.
A Postgres repository can have a small adapter and large implementation.
An in-memory fake can have a large adapter and small implementation.
Use "adapter" for the role at a seam and "implementation" for its contents.

Depth measures capability per unit of interface that a caller or test must learn.
A deep module has substantial behavior behind a small interface.
A shallow module's interface is nearly as complex as its implementation.

Seam, in Michael Feathers's sense, is a place where behavior can change without edits at that location.
It is the location of a module's interface.
Its placement is a separate decision from the implementation behind it.
Avoid "boundary" alone.
Specify a system edge, bounded context or seam.

Adapter means a concrete implementation of an interface at a seam.
It names the role, not the contents.

Leverage is the capability that depth gives callers per unit of interface they learn.
One implementation can support N call sites and M tests.

Locality concentrates changes, bugs, knowledge and verification in one place rather than across callers.
One fix then applies wherever the module is used.

## Deep vs shallow

A deep module has a small interface and substantial implementation:

```
┌─────────────────────┐
│   Small Interface   │  ← Few methods, simple params
├─────────────────────┤
│                     │
│  Deep Implementation│  ← Complex logic hidden
│                     │
└─────────────────────┘
```

A shallow module has a large interface and little implementation.
Avoid that shape:

```
┌─────────────────────────────────┐
│       Large Interface           │  ← Many methods, complex params
├─────────────────────────────────┤
│  Thin Implementation            │  ← Just passes through
└─────────────────────────────────┘
```

Ask these questions about an interface:

- Can it need fewer methods?
- Can the parameters become simpler?
- Can the module hide more complexity?

## Principles

- Depth belongs to the interface. A deep module can contain small parts that support mocks or replacement. Those parts stay private. Internal seams serve its own tests. The external seam is its interface.
- Apply the deletion test. If deleting a module removes complexity, it was a pass-through. If that complexity moves into N callers, the module was useful.
- Test through the interface. Callers and tests cross the same seam. A need to test beyond it can reveal the wrong module shape.
- One adapter gives a hypothetical seam. Two adapters give a real seam. Introduce a seam only when something actually varies across it.

## Designing for testability

Choose interfaces that support direct tests:

1. Accept dependencies instead of creating them internally.

   ```typescript
   // Testable
   function processOrder(order, paymentGateway) {}

   // Hard to test
   function processOrder(order) {
     const gateway = new StripeGateway();
   }
   ```

2. Return results instead of producing side effects.

   ```typescript
   // Testable
   function calculateDiscount(cart): Discount {}

   // Hard to test
   function applyDiscount(cart): void {
     cart.total -= discount;
   }
   ```

3. Keep the interface small. Fewer methods need fewer tests. Fewer parameters need simpler setup.

## Relationships

- A Module has exactly one Interface for its callers and tests.
- A Module's Depth is measured against that Interface.
- A Seam is the location of the Interface.
- An Adapter satisfies the Interface at a Seam.
- Depth produces Leverage for callers and Locality for maintainers.

## Rejected framings

- Ousterhout's ratio of implementation lines to interface lines rewards implementation padding. Use capability per unit of interface instead.
- The TypeScript `interface` keyword or a class's public methods do not define the full Interface. Include every fact that callers need.
- "Boundary" can also mean a DDD bounded context. Use "seam" or "interface" when that is the intended meaning.

## Going deeper

- [DEEPENING.md](DEEPENING.md) covers dependency categories, seam discipline and replacement of old tests for a chosen cluster.
- [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md) compares structurally different interfaces through parallel subagents. Judge depth, locality and seam placement.
Pliki w paczce (3)
  • DEEPENING.md 2 KB
  • DESIGN-IT-TWICE.md 3 KB
  • SKILL.md 6 KB

Wersje

RepozytoriumWynikLicencja
Ta strona · vahaah/astack100MIT
mikeleg/skills100MIT
VincenzoImp/pitcrew100MIT
kriscard/kriscard-claude-plugins100MIT
akillness/jeo-skills100MIT
JamalLyons/Agent-Skills100MIT
zenobi-us/dotfiles100MIT
FrancoStino/opencode-skills-collection100MIT
yassimba/loom100Apache-2.0

Migawka bazy z 13.11.2026 · wersja paczki d646c8803e8a (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95workflow-codebase-design
    Wyjaśnia wspólne słownictwo do projektowania głębokich modułów: interfejsy, szwy i miejsca poprawy testowalności kodu.
  • 100oracle-codebase-design
    Opisuje wspólne słownictwo i zasady projektowania głębokich modułów: interfejsy, miejsca szwów, obsługa niezaufanych danych na brzegach, poziom testowania i nazewnictwo.
  • 100matt-codebase-design
    Wyjaśnia pojęcia głębokich modułów, szwów i adapterów, szuka w kodzie miejsc do pogłębienia i zapisuje propozycje ulepszeń architektury.
  • 100improve-codebase
    Pomaga projektować i przeglądać interfejsy modułów, wskazywać płytkie moduły i szwy oraz wyodrębniać powtarzany kod do wspólnej biblioteki.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.