YouBothAgent▾
You — Business rules and flows you own. Read these yourself.
Both — Know the idea; your agent follows the details.
Agent — Conventions and references your agent follows. Look up as needed.
Workspace▾
App & Library▾
Domain▾
Scalar▾
model.abstract.md
Every database module keeps one
lib/<model>/<model>.abstract.md: a few lines of markdown stating the rules the module obeys but its code cannot say. Read it before changing the module, and update it when one of those rules changes.What The Code Cannot Say
Take the
user module in libs/shared. Its constant file and its abstract say different things about the same two fields.What The Constant File Shows
accountId and phone are secret, optional strings.accountId: field.secret(String).optional()What Only The Abstract Says
Neither may repeat across active, dormant and restricted accounts, but both may repeat once an account has left.
- Nothing else states it. No field or type says it, and
user.document.tsrepeats the check in several methods without ever naming it as a rule. - Missing it breaks sign-up. A uniqueness index added without knowing the rule stops everyone who ever deleted an account from signing up again.
- That is the abstract's job. It holds the invariants the module obeys but cannot state (rules that must always hold), and nothing the constant file already says.
The Four Parts
Every abstract has four parts, and only the last is optional:
apps/koyo/lib/ticket/ticket.abstract.md
PartDescription
# <model> Abstract
One title line with the module name spelled as in its file name.
One sentence
What the module owns, stated as fact, right under the title with no heading.
## Rules
Two to five bullets, each an invariant a reader could not derive from the code.
## Workflow
Optional: a list under this heading, or one arrow chain with no heading at all.
In the Akan.js repository, 31 of the 33 abstracts are written with these parts, and six carry a
## Workflow list. The other two belong to the app root services _akan and _minimal, which still hold the generated scaffold unedited.A Real Example
The whole of
libs/shared/lib/user/user.abstract.md is sixteen lines, for a module with constant, document, service, signal and store files and five components:libs/shared/lib/user/user.abstract.md
Read it next to the code and notice what is and is not there:
- No types. Not one bullet names a field type, a class or a method signature.
- Only constraints and couplings. Each rule is a constraint the database cannot express on its own, or a coupling between this module and another.
- The last rule is one you would otherwise learn by breaking it. Restriction, dormancy, leaving and activation all move together with the
summaryaggregate. - One language per file. Korean is common in this repository and English is just as normal, but a language switch inside one file is not.
Replace The Scaffold
akan create-module writes the first abstract for you, called the scaffold. It already has the house shape: a title, one sentence and a ## Rules list with two starting rules. The first real edit rewrites those lines to say what this module owns.What
akan create-module project writes in an app that mounts libs/shared:apps/koyo/lib/project/project.abstract.md
- Without
libs/shared, the first rule is closed. It reads that nobody creates, updates or removes a project until the slice names a guard, matching the scaffoldedNoneguards.
Where each line goes:
| Scaffold | Becomes |
|---|---|
| # project Abstract | Written for you, spelled as in the file name. Keep it. |
| Project represents … | Rewritten as what the module owns, stated as fact. |
| ## Rules | Stays, and grows to the module's real invariants, two to five in all. |
| - Anyone may read a project; … | Mirrors the scaffolded slice guards; rewrite it whenever you change them. |
| - Removal is soft: … | Stays: removal of a model is always soft. |
| ## Workflow | Not written by the scaffold; add it, or one arrow chain, once the module has a flow. |
Keeping It Current
Read it before changing the constant, document, service, signal, store or any component of the same module. Update it only when what the module means changes:
Change
Update
Leave
When the module's meaning changes
A business invariant
✓
A rule that must always hold, such as the uniqueness rule above.
A workflow or state transition
✓
How a record moves, such as from
prepare to active.A permission
✓
Who may do what, such as an admin adjusting a restriction.
Public behavior
✓
What callers of the module can observe.
When only how the code looks changes
Formatting
✓
Whitespace and line breaks the formatter decides.
Imports
✓
Adding, removing or reordering imports.
Style
✓
A code style change that alters no behavior.
✓Do thisNot this