Domain Model And ADRs: Agent Skill (SKILL.md) for Claude Code, Codex and Cursor

Builds a glossary of the domain's terms from code and conversation, picks one canonical name for each concept, stress-tests the model against edge cases, writes architecture decision records (ADRs) for non-obvious choices, and flags code names that disagree.

Prompt

Installs to .agents/skills/domain-model-and-adrs-agent-skill-skill-md-for-claude-code-codex/

mkdir -p .agents/skills/domain-model-and-adrs-agent-skill-skill-md-for-claude-code-codex && curl -sL "https://prompts-gpt.com/prompts/domain-model-and-adrs-agent-skill-skill-md-for-claude-code-codex-and-cursor/raw" -o .agents/skills/domain-model-and-adrs-agent-skill-skill-md-for-claude-code-codex/SKILL.md
SKILL.md
Preview
---
name: domain-model-and-adrs-agent-skill-skill-md-for-claude-code-codex
description: "Builds a glossary of the domain's terms from code and conversation, picks one canonical name for each concept, stress-tests the model against edge cases, writes architecture decision records (ADRs) for non-obvious choices, and flags code names that disagree."
---

# Domain Model And ADRs: Agent Skill (SKILL.md) for Claude Code, Codex and Cursor

Builds a glossary of the domain's terms from code and conversation, picks one canonical name for each concept, stress-tests the model against edge cases, writes architecture decision records (ADRs) for non-obvious choices, and flags code names that disagree.

## Prompt

```
---
name: domain-model-and-adr
description: Builds a glossary of the domain's terms from code and conversation, picks one canonical name for each concept, stress-tests the model against edge cases, writes architecture decision records (ADRs) for non-obvious choices, and flags code names that disagree. Use when starting a new feature, when terminology is confusing or inconsistent, or when asked for a domain model, glossary, ubiquitous language, ADR or decision record.
---

# Domain model and ADRs

## Steps

1. Collect terms. Read the relevant code (types, tables, routes, function names) and the conversation. List every noun (Order, Cart, Workspace) and verb (checkout, archive, invite).
2. Write a glossary: one term per line, a one-sentence definition, and where it lives in the code.
3. Find conflicts: synonyms for the same thing (Account vs Workspace vs Team), one word used for two things, terms the user says that the code doesn't. For each, pick a canonical term, give the reason, and list the aliases to retire. If the choice is a judgement call, recommend one and ask the user.
4. Note relationships and rules: cardinality (a Workspace has many Projects), lifecycle states and allowed transitions, invariants (an Order total is never negative).
5. Stress-test the model with edge cases: deletion and archiving, ownership transfer, duplicates, concurrent edits, time zones, money and rounding, a user in two workspaces, partial failure. For each, say what the model says happens. If it can't answer, that's an open question or a decision to make.
6. Write an ADR for each non-obvious choice, using the layout in the example. If the repo already has ADRs (look for docs/adr/ or docs/decisions/), follow their numbering and format; otherwise use `docs/adr/0001-short-title.md`.
7. Save the glossary next to them (an existing glossary file, or `docs/glossary.md`).
8. Flag code that disagrees with the glossary: file, current name, canonical name. Propose renames; don't make them unless asked.

## Rules

- One definition per term. If you need two, it's two terms.
- Definitions use plain words and only glossary terms that are defined too.
- An ADR records a decision that was made. If it's still open, list it as a question, not an ADR.
- Keep each ADR under a page, and record the options you rejected and why.
- Don't change code or schema as part of this skill.

## Example output

```
Glossary
- Workspace: the billing and permission boundary; owns Projects. (src/db/workspace.ts)
- Member: a User's role inside one Workspace. Alias to retire: "Seat".

ADR 0003: Soft-delete Projects
Status: accepted
Context: users restore deleted projects within days; hard delete loses history.
Options: hard delete; soft delete with deleted_at; archive table.
Decision: soft delete with deleted_at, purge after 30 days.
Consequences: every Project query filters on deleted_at; a nightly purge job is needed.
```
```

## Usage Notes

Save as .claude/skills/domain-model-and-adr/SKILL.md in one project (or ~/.claude/skills/domain-model-and-adr/ for all of them); Codex reads .agents/skills/domain-model-and-adr/SKILL.md. Then ask for the job in plain words and the agent loads it. Or install with: npx skills add prompts-gpt/skills --skill domain-model-and-adr.

Example output

At a glanceDomain model output for a clinic booking appGlossary, naming conflicts, ADRs and proposed renames
Glossary terms defined
7 terms
Clinic, Practitioner, Slot, Appointment and more
Edge cases stress-tested
5 cases
2 left as open questions
ADRs written
2 ADRs
Clinic-local time; DB double-booking constraint
Code renames proposed
4 renames
e.g. Booking to Appointment, not applied

Example for: a clinic appointment-booking app (TypeScript/Postgres) where the code says "Booking," "Slot," and "Visit" interchangeably; no existing ADRs.

Glossary (docs/glossary.md)

  • Clinic: the organisation that owns Practitioners, Rooms and billing settings. (src/db/clinic.ts)
  • Practitioner: a person who delivers Appointments at one or more Clinics. Alias to retire: "Provider".
  • Availability Window: a recurring block of time when a Practitioner can be booked. (src/scheduling/availability.ts) Alias to retire: "Schedule".
  • Slot: a single bookable interval derived from an Availability Window; never stored. (src/scheduling/slots.ts)
  • Appointment: a Patient's reservation of a Slot with a Practitioner. Aliases to retire: "Booking", "Visit".
  • Patient: a person who holds Appointments; may belong to several Clinics. (src/db/patient.ts)
  • Cancellation: the transition of an Appointment to cancelled, with a reason and actor.

Conflicts resolved

ConceptCanonicalRetireReason
Reserved timeAppointmentBooking, VisitStaff and patients say "appointment"; "Visit" also means the clinical encounter record
Bookable personPractitionerProvider"Provider" collides with OAuth providers in src/auth/

Ask the user: should the clinical encounter be a separate term (Encounter)? I recommend yes.

Relationships and rules

  • A Clinic has many Practitioners; a Practitioner works at many Clinics.
  • An Appointment belongs to exactly one Patient, one Practitioner and one Clinic.
  • Lifecycle: requested → confirmed → completed; requested|confirmed → cancelled; confirmed → no_show. There are no transitions out of completed.
  • Invariant: two non-cancelled Appointments for one Practitioner never overlap.

Edge cases

  • Practitioner deleted with future Appointments: this is undefined in the current code. Open question.
  • Concurrent booking of one Slot: an exclusion constraint rejects the second booking. See ADR 0002.
  • DST change during a recurring Availability Window: times are stored in Clinic local time and expanded per date. See ADR 0001.
  • Patient at two Clinics: there is one Patient record, and Clinic-scoped notes are kept separately.
  • Payment fails after confirm: the Appointment stays confirmed and is flagged unpaid. Open question.

ADRs

ADR 0001: Store availability in clinic-local time
Status: accepted
Context: weekly windows must stay "9:00" across DST shifts.
Options: UTC instants; local time + clinic tz; per-practitioner tz.
Decision: local wall-clock time plus Clinic IANA time zone; expand to UTC when generating Slots.
Consequences: slot generation needs tz library; practitioners travelling between clinics in different zones are not supported.
Rejected: UTC drifts an hour twice a year; per-practitioner tz conflicts with room bookings.
ADR 0002: Prevent double-booking with a database constraint
Status: accepted
Context: two receptionists booked the same slot in testing.
Options: app-level check; row lock; Postgres EXCLUDE constraint on tstzrange.
Decision: EXCLUDE USING gist (practitioner_id WITH =, period WITH &&) WHERE status <> 'cancelled'.
Consequences: requires btree_gist extension; API maps constraint error to 409.
Rejected: app-level check races; locks add latency and deadlock risk.

Code that disagrees (proposed renames, not applied)

FileCurrentCanonical
src/db/booking.tsBookingAppointment
src/api/routes/visits.ts/visits/appointments
src/scheduling/schedule.tsScheduleAvailabilityWindow
src/db/provider.tsproviderIdpractitionerId
Written by AI from this prompt. Your results will vary.

Save as .claude/skills/domain-model-and-adr/SKILL.md in one project (or ~/.claude/skills/domain-model-and-adr/ for all of them); Codex reads .agents/skills/domain-model-and-adr/SKILL.md. Then ask for the job in plain words and the agent loads it. Or install with: npx skills add prompts-gpt/skills --skill domain-model-and-adr.

Make it repeatable

Keep using this prompt without pasting it in every time.

Prompt details

By
Prompts-GPT editors
Published
How prompts are written and checked

Did this prompt work?

Keep exploring

More in AI Coding Agents