Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

domain-structure

/domain-structure

Układa drzewo katalogów projektu według domen tak, by każda ścieżka czytała się jak wywołanie i każdy plik miał jeden powód do zmiany.

Repozytorium
dusk_code ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.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
1
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.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

Układa drzewo katalogów projektu według domen tak, by każda ścieżka czytała się jak wywołanie i każdy plik miał jeden powód do zmiany.

Oryginalny opis (EN)

Lay out and keep a codebase as a tree of domains where every path reads like a framework call and every file has one reason to change. Use when adding a file or module, deciding where code goes, splitting a large file, restructuring or auditing a project's layout, reviewing structure in a change, or starting a new project; any language.

Jak działa

  1. The model
  2. Adding code
  3. Worked examples
  4. Audit
  5. Restructure
  6. The map: structure.md
  7. Before finishing a change
Sekcje z nagłówków SKILL.md, w oryginale · 155 linii, 1 379 słów
Podgląd SKILL.md
---
name: domain-structure
description: "Lay out and keep a codebase as a tree of domains where every path reads like a framework call and every file has one reason to change. Use when adding a file or module, deciding where code goes, splitting a large file, restructuring or auditing a project's layout, reviewing structure in a change, or starting a new project; any language."
source: "dusk_code"
author: "Neil Ermak"
license: MIT
tags: [project, architecture]
---
# Domain structure

Keep a codebase readable from its paths alone. A newcomer opens the tree, reads the
names, and knows where a thing lives before opening a file. Follow the project's own
conventions and its structure document first; apply these rules where they are silent.

## The model

- **Package, domain, subdomain.** A package (crate, npm package, Python package) is a
  tree of domains; a domain may hold subdomains. A path is a sentence:
  `core::runtime::agent::compaction`, `billing/invoice/pdf`. Two or three levels are
  usual; a fourth needs a reason.
- **A front door per module.** Each directory has one entry file (`mod.rs`, `index.ts`,
  `__init__.py`) holding a one-paragraph doc of what the module is for, its submodules,
  and flat re-exports of what others use. Callers import from the door
  (`protocol::thread::Message`), never from the file behind it. Files behind a door are
  free to move. The door holds no implementation.
- **One reason to change per file.** A file answers to one decision. Several internal
  steps of one action (parse, validate, write for a single `save`) are one reason.
- **Domains over layers.** Group by what a thing is about (`thread`, `invoice`,
  `project`), not by what it is (`types`, `models`, `handlers`, `services`, `utils`,
  `helpers`, `common`). A grab bag is a domain nobody named yet.
- **The top level is a map.** A package root holds its domains and the few files that
  start it (`lib.rs`, `main.rs`, `index.ts`, `__main__.py`). A feature never adds a
  root file.
- **A contract package is the vocabulary.** With several programs, one package holds
  the requests, responses, events and shared data. Everyone uses its words; its domains
  mirror the core's.
- **Clients draw, the core decides.** Anything that decides, stores, checks or parses
  user intent lives in the core and reaches clients through the contract. A client
  keeps presentation: layout, themes, which panel is open. The same rule written in two
  clients is a missing core function.

## Adding code

1. Name what the code is about in one or two words. That is its domain. Find it in the
   map; search for the nearest existing code before creating anything.
2. Pick the file by asking what would make this code change. If an existing file
   changes for the same reason, add it there. If the file has another reason, do not
   widen it.
3. Second-responsibility test. Describe the file in one sentence without "and". If you
   cannot, or if two people could edit it in one week for unrelated features, it has two
   responsibilities: make it a directory with the file's name, one file per
   responsibility, and a door that keeps the old import path. Steps of one action do
   not count; a length past about 400 lines is a question, past 800 an answer.
4. New domain or extend one. Create a domain when the thing has its own nouns, its own
   state or lifecycle, and at least two files you can name today. Otherwise extend the
   closest domain. Never create a directory for one file or for a future that has not
   arrived.
5. Shared code. Something used by two domains goes to the domain that owns the concept
   and is re-exported from its door. If it is about the machine, it goes to `platform`;
   about files on disk, to the module that owns those files; about text shown to people,
   to the presentation domain. If you still want `utils`, write down what the helpers
   have in common: that word is the module's name.
6. Name the file for what it does: a noun for a thing (`invoice.rs`, `lock.rs`), a verb
   phrase for an action (`send.rs`, `run_command.rs`). Tests sit beside the code in a
   `tests` file or directory.

Names that say what a file does: `compaction.rs`, `path_completion.rs`, `rate_limit.ts`,
`atomic_write.py`, `approval.rs`. Names that do not: `utils.rs`, `helpers.ts`,
`common.py`, `misc`, `shared`, `types.ts`, `manager.rs`, `service.py`, `data.rs`,
`core2`, `new_`, `stuff`.

## Worked examples

A good tree (Rust; the same shape holds elsewhere):

```
protocol/src/          the contract: thread/ project/ config/ client/request/
core/src/
  lib.rs               doc: one line per domain
  config/  mod.rs  file/  live.rs
  project/ mod.rs  git.rs  diff.rs  files.rs
  runtime/ mod.rs  agent/  thread/  goal/
  state/   mod.rs  thread/  project/
tui/src/  gui/src/     ui/ pages/ ... presentation only
```

Splitting a file with two responsibilities, import path unchanged:

```
before  message/sources.rs       stores pasted sources AND decodes and shrinks pictures
after   message/sources/mod.rs   doc, `pub use store::ThreadSources; pub use picture::picture;`
        message/sources/store.rs
        message/sources/picture.rs
        message/sources/tests.rs
```

The same rules in three languages:

| | Rust | TypeScript | Python |
|---|---|---|---|
| Package | crate | workspace package | distribution package |
| Front door | `mod.rs` with `//!` doc and `pub use` | `index.ts` with a header comment and `export { X } from "./x"` | `__init__.py` with a docstring, imports and `__all__` |
| Hidden files | private `mod x;` | not listed in `exports`; lint against deep imports | leading underscore or absent from `__all__` |
| Caller writes | `core::project::Diff` | `import { Diff } from "@app/core/project"` | `from app.project import Diff` |
| Layer smell | `types.rs`, `util/` | `components/ hooks/ services/ types/` at the root | `models.py views.py utils.py` holding every feature |
| Domain fix | `project/diff.rs` | `project/{Diff.tsx,useDiff.ts,api.ts,index.ts}` | `project/{diff.py,api.py,__init__.py}` |

Framework-mandated folders (`app/` routes, `migrations/`) stay; put domains inside or
beside them and keep the mandated files thin.

## Audit

1. List every directory with its file count, and every source file with its line count,
   sorted by size. Read each front door and the first lines of suspicious files; read
   excerpts, not whole files.
2. Flag: root files that are features; grab-bag modules; files past about 400 lines
   with more than one reason to change (name the reasons); directories with no door doc
   or with one file; imports that reach past a door; layer-named groups; a concept
   implemented twice, above all logic copied between clients; names that do not say
   what the file does; a map document that disagrees with the tree.
3. Rank: high for a wrong domain or duplicated logic, medium for a file to split, low
   for naming and docs. Give each finding a path, the rule it breaks, and the target
   path or split. Report the 15 to 25 most valuable; do not dump every file.
4. Change nothing during an audit. Separate mechanical moves from findings that need
   behavior to move between packages; those are features, not restructures.

## Restructure

- Moves only: paths, module declarations, imports, re-exports. No behavior change, no
  type or function renames, no formatting sweep, no fixes noticed on the way; note
  those for later.
- Keep old import paths working through the door when callers are many; remove the
  alias in a later change.
- Move with the version-control move command so history follows. One commit per
  restructure that builds, passes lint and the full tests. Check the working tree first;
  never move files others are editing without agreement.
- Update the map document in the same commit. Ask before a restructure that touches
  many packages or public import paths.

## The map: `structure.md`

Keep one short document (`docs/structure.md` or the project's equivalent) with: the
rules in the project's words; for each package a tree of its directories two levels
deep with a file count; one line for each root file and each domain whose name does not
explain itself; where tests live; the known exceptions and why. No file lists, no
function names. Update it in the commit that adds, removes, renames or splits a
directory; an edit inside a file never touches it. When the map and the tree disagree,
the tree is right and the map is a bug to fix now.

## Before finishing a change

- Every new file sits in a domain; nothing new at a package root.
- Each touched file still fits one sentence without "and".
- No new `utils`, `helpers`, `common`, `types`, `misc`.
- New directories have a door with a doc paragraph and flat re-exports; no caller
  imports past a door.
- No decision, storage, check or parsing added to a client; nothing copied from another
  client.
- Shared vocabulary went into the contract package first.
- Names say what the file does; tests sit beside the code.
- The map document matches the tree.
- Build, lint and tests ran; say what was run and what was not.

Wersje

W bazie nie ma innych skilli o nazwie domain-structure.

Migawka bazy z 13.11.2026 · wersja paczki 02d05360a5b8 (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

  • 100project-structure-guide
    Prowadzi przez organizację katalogów projektu zgodnie z dobrymi praktykami danego języka: zakładanie projektów, reorganizację, dodawanie modułów, konfigurację buildu i decyzje o miejscu plików.
  • 90project-structure
    Pomaga ustalić, gdzie powinien leżeć kod, jak grupować pliki i wykrywa antywzorce w strukturze katalogów projektu.
  • 100structure-review
    Przegląda i porządkuje strukturę istniejącego kodu, zwłaszcza wygenerowanego przez AI, przed scaleniem dużej zmiany.
  • 100file-operations
    Tworzy, czyta, edytuje, wyświetla i usuwa pliki oraz bada strukturę katalogów projektu.
  • 100project-structure
    Wskazuje, gdzie w repozytorium z siedmioma serwerami leży kod i gdzie umieścić nowy plik: narzędzie, zasób, prompt, transport, moduł pomocniczy, flagę linii poleceń lub skrypt.
  • 100readme-updater
    Aktualizuje README projektu na podstawie bieżącej struktury i kodu, gdy zmienia się układ katalogów lub pliki projektu.

Uwagi i zgłoszenia

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