Topic: Appendix B. AgentClinic Domain Map
Difficulty level: Medium
Estimated study time: 6-8 hours (theory + practice)
Prerequisites: Basic understanding of web development (HTTP, routes, requests)
Familiarity with relational databases (SQL, tables, relationships)
Understanding of the MVP (Minimum Viable Product) concept
Basic knowledge of TypeScript/JavaScript
Understanding of testing principles (checkable facts, assertions)
Learning objectives: Independently design a domain model for a learning project, defining entities, their attributes, and relationships, similar to AgentClinic
Break down the full project functionality into SDD-cycle phases, explaining the order of adding routes and justifying the priority of each phase
Formulate minimum checkable facts for each phase, creating a validation checklist that can be automated
Apply domain vocabulary consistently across all specifications, identifying and correcting terminology mismatches
Distinguish elements that belong to the learning domain from those requiring a separate specification, and justify this decision
Overview: AgentClinic is a learning satire project demonstrating the SDD cycle (Specification-Driven Development) through the example of a "clinic for software agents." The domain map describes the structure of this project: what entities exist (agents, ailments, therapies, appointments, feedback), how they relate to each other, what routes serve user scenarios, and how all functionality is distributed across development phases. The key idea — the domain intentionally remains simple but sufficiently rich to demonstrate all aspects of SDD: from the first "Hello Hono" to an admin panel with counter checks. At the same time, the project deliberately excludes complex real-world scenarios (payments, authorization, external integrations) to keep the focus on the development-through-specifications process itself.
Key concepts: Domain map: A visual and textual description of a project's subject area, including entities, their attributes, relationships, and boundaries. In AgentClinic, the domain map serves as a common language between developers, testers, and specifications. It does not dictate a specific implementation but sets the framework within which the project moves.
Entity: A key object of the subject area with clear semantics. In AgentClinic, there are five main entities: Agent (software assistant), Ailment (recurring problem of an agent), Therapy (way to help an agent), Appointment (user request), Feedback (user response). Each entity has a set of attributes and rules for use in specifications.
SDD cycle (specification-driven development): A development process in which specifications (requirements.md, plan.md, validation.md) drive implementation. Instead of building everything at once, the project evolves in phases, each starting with clear checkable facts and ending with their verification.
Checkable facts: Specific, objectively measurable statements about system behavior that can be automated. For example: "GET / returns 200" or "invalid form is rejected." Facts replace vague requirements like "the application should work fast."
Development phase: A time- and scope-limited stage delivering a specific result. In AgentClinic, there are six phases: Hello Hono → Agents and Ailments → Therapies → Appointments → Feedback → Admin Panel. Each phase adds new routes and check facts without breaking previous ones.
Minimum routes: A set of URL paths sufficient to demonstrate the domain. Not all routes are needed in the first phase — this is the principle of SDD iterativity. Routes use technical English names (/agents, /ailments), while user scenarios are described in Russian using domain vocabulary.
Domain vocabulary: An agreement on unified terminology across all specifications. Prohibits synonyms like "bot/assistant/model" for the entity "agent." Technical names (routes, tables, files) remain in English; user scenarios are in Russian with consistent terms.
Learning domain boundaries: An explicit list of what does NOT enter the project without a separate specification: real medical terminology, real personal data, payment scenarios, authorization with roles, external email sending, complex charts, integrations with real services. This constraint preserves focus on the SDD process.
Practice exercises: Name: Designing a domain model for a new project
Problem: Imagine you need to create a learning project "AgentLibrary" — a library for software agents. Define at least 4 entities, their attributes, and examples, similar to the AgentClinic entity table. Then describe what routes will be needed and how they are distributed across SDD phases.
Solution: Step 1: Define entities. For example: Book (title, author, description), Agent-Reader (name, preferred genres), Review (rating, text, date), Shelf (title, public/private). Step 2: Set attributes in a table format with examples. Step 3: Design routes: /, /books, /books/:id, /agents, /reviews, /shelves. Step 4: Break into phases: (1) Hello Hono — GET / returns 200; (2) Books — list and card; (3) Agents and Reviews — related reviews for a book; (4) Shelves — creation and collection management. Step 5: For each phase, formulate 2-3 checkable facts.
Complexity: intermediate
Name: Terminology audit in specifications
Problem: You are given three fragments from different project files of AgentClinic: (1) requirements.md: "The bot should display a list of its problems"; (2) plan.md: "Create a symptoms table to store recurring malfunctions of the assistant"; (3) validation.md: "GET /agents/:id returns a related list of ailments." Find all violations of the domain vocabulary, explain why they are problematic, and rewrite the fragments correctly.
Solution: Violations: "bot" instead of "agent", "problems" instead of "ailments", "symptoms" instead of "ailments", "assistant" instead of "agent". Problem: different terms for one entity create confusion in the team, complicate document search, lead to mismatch between code (ailments table) and specifications (symptoms). Correct version: (1) "The agent should display a list of its ailments"; (2) "Create an ailments table to store recurring ailments of the agent"; (3) unchanged — already correct.
Complexity: intermediate
Name: Domain extension: boundary analysis
Problem: The team proposes adding a clinic rating system (analogous to Google Reviews) with a paid subscription for priority appointments to AgentClinic. Using the criteria from the "What is not in the learning domain" section, analyze this proposal. Describe which components violate boundaries, and suggest an alternative that preserves educational value.
Solution: Boundary violations: paid subscription — payment scenarios (explicitly prohibited); rating system with regional aggregation — complex charts and potentially real personal data; priority appointment — implicit authorization with roles (regular vs premium user). Alternative: simple satisfaction scale (1-5 stars) in the existing "feedback" entity without user binding, without aggregation, and without payments. Add as a separate phase: "Extended Feedback" with facts "feedback contains a 1-5 rating", "average rating is visible on the /feedback page".
Complexity: advanced
Name: Database schema design
Problem: Based on the described AgentClinic entities and minimum routes, design a complete SQL schema accounting for all relationships. Explain why agent_ailments is a junction table rather than a field in agents. Describe how the schema changes if adding the requirement: "one therapy treats a specific ailment of a specific agent."
Solution: Base schema: agents(id, name, description); ailments(id, title, description); therapies(id, title, description); agent_ailments(agent_id, ailment_id) — many-to-many relationship: one agent can have multiple ailments, one ailment can be in multiple agents. A junction table is needed because an array in the agents field violates first normal form and complicates queries. appointments(id, name, message, ailment_id, created_at); feedback(id, name, message, created_at). With the new requirement, add agent_ailment_therapies(agent_ailment_id, therapy_id, effectiveness_rating), where agent_ailment_id is a composite key or separate id of the agent_ailments table. This turns the relationship into a triple: agent-ailment-therapy.
Complexity: intermediate
Name: Formulating checkable facts for the "Appointments" phase
Problem: For the "Appointments" phase in AgentClinic, formulate at least 5 checkable facts covering: successful creation, validation of required fields, handling of non-existent ailment, display of saved appointments, timestamp. Indicate which facts can be checked with unit tests and which require integration testing.
Solution: Facts: (1) POST /appointments with valid data returns 201 and redirect — integration; (2) POST /appointments without name field returns 400 with error message — unit (form validation) + integration; (3) POST /appointments with ailment_id=999 returns 400 or 404 — integration (requires database); (4) GET /appointments after successful POST contains the created appointment — integration; (5) created_at of the appointment is within the last minute of test time — integration. Unit tests are possible for (2) at the input validation level without database. Others require full stack.
Complexity: intermediate
Case studies: Name: Migrating a monolithic prototype to SDD phases in an EdTech startup
Scenario: A startup developed an educational platform prototype in 3 months "on the knee": courses, lessons, homework, chats, payments, analytics — all in one repository without tests. When hiring new developers, it turned out that no one understood which functionality worked and which was a "demo stub." Investors demanded proof of operability.
Challenge: A team of 8 people could not work in parallel due to constant code conflicts. It was impossible to show investors concrete progress: "almost everything is ready" had been said for half a year. The payment system broke chats, and analytics showed random numbers. It was necessary to move to transparent, verifiable development without rewriting everything from scratch.
Solution: The tech lead adapted the AgentClinic approach: identified domain entities (Course, Lesson, Student, Assignment, Attempt, Feedback) and fixed the domain vocabulary. Split the monolith into phases, analogous to the SDD cycle: (1) "Hello Framework" — basic response; (2) "Courses and Lessons" — content viewing; (3) "Assignments" — creation and checking; (4) "Attempts" — saving student answers; (5) "Feedback" — user response. Payments and analytics were moved to separate specifications with status "outside MVP learning domain." For each phase, wrote requirements.md, plan.md, validation.md with checkable facts.
Result: In 6 weeks, the team stabilized the platform core (phases 1-4). Investors were presented with a concrete checklist: 47 checkable facts, of which 43 passed automatically. New developers onboarded in 2 days instead of 2 weeks thanks to the domain vocabulary. The payment system was added later as a separate phase with its own specification, without breaking existing functionality. The team reduced critical bugs from 15 per week to 2.
Lessons learned: Domain map and unified vocabulary eliminate "folklore knowledge" — information that exists only in the heads of individual developers
Checkable facts transform investor conversations from "almost everything is ready" into concrete readiness metrics
Explicit domain boundary definition protects the team from premature complexity and allows focus on value
Related concepts: Domain map
SDD cycle
Checkable facts
Learning domain boundaries
Domain vocabulary
Name: Integration failure due to domain vocabulary violation in a corporate project
Scenario: A major bank developed an internal system for managing credit applications. The project was divided between three teams: frontend (mobile app), backend (API), analytics (reports). Each team worked in their own documentation without a unified domain vocabulary.
Challenge: In the mobile app, "client" meant an individual who submitted an application. In the API, "client" was an internal identifier of a legal entity partner. In analytics, "client" meant any object in the CRM. During integration, data got mixed: applications of individuals were assigned to legal entities, reports showed impossible numbers. Fixing this required 3 weeks of auditing 200+ endpoints and 15 configuration files.
Solution: After the incident, they implemented an approach analogous to the AgentClinic domain vocabulary: fixed terms with definitions in a common repository. "Applicant" — an individual who submitted a credit application. "Partner" — a legal entity with a bank contract. "Application" — a unified document in the system. Technical field names in the API were left in English (applicant, partner, application), user scenarios were translated to Russian with unified terminology. An automatic documentation linter was introduced to check vocabulary compliance.
Result: New analyst onboarding time reduced from 3 weeks to 4 days. The number of integration errors related to semantics dropped by 80%. When extending the system to mortgage applications, the term "Real Estate Object" was added without conflicts with existing entities. The project became an example for other bank departments.
Lessons learned: Domain vocabulary violation is not a "stylistic problem" but a source of costly integration bugs
Separating technical names (English, for code) and user terms (Russian, for specifications) solves the problem of multilingual teams
Automating vocabulary checking (linters, CI pipelines) is more important than manual instructions
Related concepts: Domain vocabulary
Entity
Learning domain boundaries
Study tips: Create a physical or digital "wall map": print AgentClinic entities on cards and connect with relationship lines. Visual spatial arrangement helps remember structure better than table reading
Practice "reverse translation": take technical terms from code (agent_ailments table, /appointments route) and formulate their user semantics in Russian using the domain vocabulary. This trains switching between technical and user context
For each SDD phase, independently come up with a "fact that is easy to forget." For example, for the "Appointments" phase — XSS check in the message field. Compare with those suggested in the material — this develops critical thinking about specification completeness
Use the "teaching" method: explain the AgentClinic domain map to a colleague or even an imaginary listener. The attempt to explain in simple language why agent_ailments is a junction table rather than a field quickly reveals gaps in understanding
Conduct "boundary audits" for your current projects: what functions "do not belong to the domain" without a separate specification? This exercise transfers AgentClinic concepts to real practice
Create a validation.md document template for one of the phases, using the Given-When-Then format or simply a list of facts. Try to write a test implementing one of the facts — even mentally, this strengthens the connection between specification and code
Additional resources: Original document "appendix b. agentclinic domain map": Source course material on which this guide is built
Book "Domain-Driven Design" by Eric Evans: Fundamental work on domain-driven design — domain maps, bounded contexts, ubiquitous language
Book "Implementing Domain-Driven Design" by Vaughn Vernon: Practical guide to DDD implementation with code examples and patterns
Article "Specification by Example" by Gojko Adzic: Methodology for formulating requirements through checkable examples, related to the SDD cycle
Tool "Event Storming": Group domain modeling technique through events — useful for expanding domain maps in a team
SQLite Documentation (sqlite.org/lang.html): Official SQL documentation for independent schema design, analogous to that proposed in AgentClinic
Hono Framework (hono.dev): Documentation for the lightweight web framework used in the "Hello Hono" phase — for practical route implementation
Article "The C4 Model for Software Architecture" by Simon Brown: Method for visualizing software architecture, including context and container diagrams — useful for expanding domain maps
Summary: The AgentClinic domain map is not just a humorous metaphor but a carefully designed learning tool for mastering the SDD cycle. Its key principles: satirical but semantically precise domain; five clearly defined entities with attributes and examples; iterative functionality buildup through six phases with checkable facts; unified domain vocabulary separating technical English names and user Russian terms; explicit boundaries protecting against premature complexity. By mastering this map, a developer learns to design subject areas that are sufficiently rich to demonstrate real patterns but sufficiently simple for controlled learning. The main skill — translating vague wishes ("make a clinic for agents") into concrete entities, routes, tables, and facts that can be checked automatically.