Gabriel Brown
89761a7da3
Agent instructions, skills, SSH host aliases and expansion triggers are worth having identical on every machine one person owns, and belong in none of the shared configuration. They live in user/ now, with a manifest saying where each piece goes and a link-user stage that puts it there. That stage does nothing unless the machine said yes. Somebody who clones Panama to try the desktop keeps their own ~/.claude/CLAUDE.md exactly where it was; the question names the destinations and defaults to no. Anything displaced goes to config/old rather than being deleted. ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md were byte-identical copies of one file, which is the drift this exists to prevent. Also adds the vitals toggles for the battery and Claude usage readouts, which had preferences and no way to reach them.
107 lines
3.9 KiB
Markdown
107 lines
3.9 KiB
Markdown
---
|
|
name: domain-modeling
|
|
description: Use when a term is fuzzy, overloaded, or contradicts how the code behaves; when writing or editing a CONTEXT.md glossary; or when a hard-to-reverse decision needs recording as an ADR.
|
|
---
|
|
|
|
# Domain Modeling
|
|
|
|
Actively build and sharpen a project's domain model as you design: challenge terms, stress-test them
|
|
with scenarios, and write the glossary and the decisions down the moment they crystallise.
|
|
|
|
This is the *active* discipline. Merely **reading** `CONTEXT.md` for vocabulary is a one-line habit
|
|
any skill can do and is not this skill. Reach for this one when you are **changing** the model, not
|
|
consuming it.
|
|
|
|
## File structure
|
|
|
|
Most repos have a single context:
|
|
|
|
```
|
|
/
|
|
├── CONTEXT.md
|
|
├── docs/
|
|
│ └── adr/
|
|
│ ├── 0001-event-sourced-orders.md
|
|
│ └── 0002-postgres-for-write-model.md
|
|
└── src/
|
|
```
|
|
|
|
A `CONTEXT-MAP.md` at the root means the repo has several contexts, and the map points to where each
|
|
one lives:
|
|
|
|
```
|
|
/
|
|
├── CONTEXT-MAP.md
|
|
├── docs/adr/ ← system-wide decisions
|
|
└── src/
|
|
├── ordering/
|
|
│ ├── CONTEXT.md
|
|
│ └── docs/adr/ ← context-specific decisions
|
|
└── billing/
|
|
├── CONTEXT.md
|
|
└── docs/adr/
|
|
```
|
|
|
|
Create files lazily, only once there is something to write. No `CONTEXT.md` yet? Create it when the
|
|
first term is resolved. No `docs/adr/`? Create it when the first ADR is needed.
|
|
|
|
## During the session
|
|
|
|
### Challenge against the glossary
|
|
|
|
When a term conflicts with the language already in `CONTEXT.md`, call it out immediately.
|
|
|
|
> "Your glossary defines *cancellation* as X, but you seem to mean Y here. Which is it?"
|
|
|
|
### Sharpen fuzzy language
|
|
|
|
When a term is vague or overloaded, propose a precise canonical one.
|
|
|
|
> "You're saying *account*: do you mean the Customer or the User? Those are different things."
|
|
|
|
### Discuss concrete scenarios
|
|
|
|
When domain relationships are on the table, stress-test them with specific scenarios. Invent the
|
|
edge cases that force the boundaries between concepts to become precise.
|
|
|
|
### Cross-reference with the code
|
|
|
|
When a claim is made about how something works, check whether the code agrees, and surface any
|
|
contradiction.
|
|
|
|
> "The code cancels whole Orders, but you just said partial cancellation is possible. Which is right?"
|
|
|
|
The schema is the highest-signal place to check, because it is where the domain nouns are declared
|
|
rather than merely used. In a Convex project that is `convex/schema.ts`; elsewhere it is whatever
|
|
file defines the tables or types. A term that appears in conversation but nowhere in the schema is
|
|
either missing from the model or is not really a domain term.
|
|
|
|
### Update CONTEXT.md inline
|
|
|
|
When a term resolves, write it to `CONTEXT.md` right then. Do not batch them: capture each as it
|
|
happens, because the precision is what fades between now and the end of the session. Use the format
|
|
in [CONTEXT-FORMAT.md](CONTEXT-FORMAT.md).
|
|
|
|
`CONTEXT.md` is a glossary and nothing else. Keep implementation details, specs, and scratch notes
|
|
out of it.
|
|
|
|
### Offer ADRs sparingly
|
|
|
|
Offer an ADR only when all three are true:
|
|
|
|
1. **Hard to reverse**: the cost of changing your mind later is meaningful.
|
|
2. **Surprising without context**: a future reader will wonder "why on earth did they do it this
|
|
way?"
|
|
3. **The result of a real trade-off**: genuine alternatives existed and one was picked for specific
|
|
reasons.
|
|
|
|
Missing any one of the three, skip it. Use the format in [ADR-FORMAT.md](ADR-FORMAT.md).
|
|
|
|
## Done when
|
|
|
|
- Every term resolved this session is in `CONTEXT.md`, in the house format, with its rejected
|
|
synonyms under `_Avoid_`.
|
|
- No implementation detail has leaked into `CONTEXT.md`.
|
|
- Every contradiction found between a stated claim and the code was surfaced, not silently resolved.
|
|
- An ADR exists for each decision meeting all three tests, and for none that miss one.
|