principle-model-the-domain
Use when writing stateful logic, branch-heavy code, or the same shape assumption repeated across files. Capture domain rules with a state machine, typed model, or lookup table so invalid states cannot be built.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- principle-model-the-domain
- description
- Use when writing stateful logic, branch-heavy code, or the same shape assumption repeated across files. Capture domain rules with a state machine, typed model, or lookup table so invalid states cannot be built.
- disable-model-invocation
- true
03 SKILL.md 正文
Model the domain
Encode the domain as a data structure in which invalid states cannot exist and branches become unnecessary, instead of scattering its rules through conditionals. Choosing the structure at the moment you write the code costs little. Introduced afterwards, it looks like a refactor, and refactors tend to be postponed indefinitely.
When it applies
Writing stateful logic, code with heavy branching, and the same assumption about a data shape repeated across files. Apply it whenever you name the data shape for a code task.
Skip it when the current shape is clear, local, and unlikely to grow. Prefer plain code there. Be wary of an abstraction that adds indirection unless it also eliminates something: a branch, a repeated rule, a reachable invalid state, or a lifecycle hazard.
What to do
Reach for the structure that fits:
- A state machine in place of scattered booleans, phase flags, or lifecycle checks. An agent session with
is_authenticated,is_elevated, andis_lockedbooleans permits "locked and elevated". A state machine withAnonymous,Authenticated,Elevated, andLockedstates and explicit transitions does not. - A typed model in place of loose parameters or repeated assumptions about shape.
- A lookup table, map, registry, or tagged union in place of branching scattered over files. A tool registry that maps each tool name to its handler and required permission puts the authorization rule in one table a reviewer can read.
- A reducer or a command and event model in place of ad hoc mutation.
- Modules built around a single area of domain knowledge, rather than around steps in a pipeline. Execution order (load, validate, transform, save) does not define ownership.
- A small module boundary that collects repeated behavior, ownership, or invariants.
- Queues, caches, indexes, graphs, trees, or normalized collections where the access patterns call for them.
- If nothing standard fits, write down what the code must never permit and how the data is read, then find a structure that encodes exactly that.
Signs you skipped it
A new feature adds one more branch to an existing if/else chain. A second boolean has to be kept consistent with a first. Phase-named modules each repeat the same domain rule.
The failure it prevents
Rules duplicated across files that drift apart, and invalid states that are reachable because nothing prevents constructing them.
Done when
Domain rules live in one structure and invalid states cannot be constructed.
Related: principle-foundational-thinking, principle-type-system-discipline, principle-minimize-reader-load, statechart.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.