70 lines
2.1 KiB
Markdown
70 lines
2.1 KiB
Markdown
# Domain Docs
|
|
|
|
Aleksandr-test uses a single-context documentation layout.
|
|
|
|
It is an independent test project for learning Wayfinder and AI-agent
|
|
workflows. Do not import the Amazon domain context or decisions from
|
|
Andrey's project or any other project.
|
|
|
|
## Before exploring, read these
|
|
|
|
- GLOSSARY.md at the repository root, if it exists.
|
|
- ADRs in docs/adr/ that concern the area being explored.
|
|
|
|
If these files do not exist, proceed silently. Do not flag their absence
|
|
or propose creating empty files upfront.
|
|
|
|
The domain-modeling skill creates documents lazily when terms or
|
|
decisions are actually resolved.
|
|
|
|
## File structure
|
|
|
|
```text
|
|
/
|
|
├── GLOSSARY.md
|
|
├── docs/
|
|
│ └── adr/
|
|
│ ├── 0001-slug.md
|
|
│ └── 0002-slug.md
|
|
└── ...
|
|
```
|
|
|
|
Create GLOSSARY.md only when the first project-specific term is resolved.
|
|
Create docs/adr/ only when the first qualifying ADR is needed.
|
|
|
|
Do not create GLOSSARY-MAP.md or per-context documentation as part of
|
|
this single-context setup.
|
|
|
|
## Use the glossary's vocabulary
|
|
|
|
When output names a domain concept in an issue, proposal, hypothesis,
|
|
or test, use the term defined in GLOSSARY.md.
|
|
|
|
Avoid synonyms that the glossary explicitly rejects.
|
|
|
|
If a needed concept is missing, reconsider whether it belongs to this
|
|
project or is a real gap to resolve with domain-modeling.
|
|
|
|
Keep the glossary limited to project-specific terms. It is not a spec,
|
|
an implementation guide, or a scratch pad.
|
|
|
|
Use the installed domain-modeling/GLOSSARY-FORMAT.md when writing entries.
|
|
|
|
## Architectural decisions
|
|
|
|
Read relevant ADRs before proposing changes.
|
|
|
|
If a proposal contradicts an existing ADR, surface the conflict
|
|
explicitly and explain why reopening the decision may be appropriate.
|
|
|
|
Offer an ADR only when all three conditions hold:
|
|
|
|
1. The decision is meaningfully costly to reverse.
|
|
2. A future reader would find it surprising without context.
|
|
3. It results from a real trade-off between alternatives.
|
|
|
|
Use the installed domain-modeling/ADR-FORMAT.md.
|
|
|
|
Number ADR files sequentially, starting at 0001 and incrementing the
|
|
highest existing number.
|