soukupl Keep architecture & domain model current
Maintain a living, high-level map of the system so structure stays legible as it grows.
The artifact
./ARCHITECTURE.md (or the repo's existing equivalent — CONTEXT.md, docs/architecture.md).
Keep it high-level and durable:
- Domains / bounded contexts — the core concepts and what each owns.
- Components — services, modules, packages and their responsibilities.
- Relationships — who calls/depends on whom; data flow at a glance (a small diagram or list).
- Key decisions — link to the ADRs in
docs/adr/rather than restating them here (see theadrskill); significant choices are recorded there with date and deciders.
Use the domain-modeling skill for the thinking
For the actual modeling — naming concepts, finding boundaries, spotting a missing abstraction —
invoke the domain-modeling skill (mattpocock-skills). This skill is about persisting and
maintaining that model; domain-modeling is about deriving it. Use them together.
When to update
- A new domain concept, service, or module appears → add it and its relationships.
- A dependency or boundary changes → fix the map.
- Before large changes → read this file first to ground your mental model; after → reconcile it.
Keep it terse and true. A wrong architecture doc is worse than none — reconcile or delete stale parts.