Big feature without endless rework: Spec driven development with AI, UML, C4 and OpenAPI / Habr

Let's take a web system for booking shared equipment. An employee selects a projector and a time, confirms the booking, and cancels it if necessary. It sounds like a few forms and CRUD operations. The illusion of simplicity disappears when two people book the same projector at the same time, the temporary reservation gets stuck forever, and the canceled request continues to occupy time in the calendar.

Let's examine how to go from such an idea to implementation through LLM: first, make the rules visible, then agree on the model and contracts, and then pass small tasks to the agent.

Between endless meetings and premature code

The first way to deal with uncertainty is to talk more. In a meeting, everything seems clear: "we reserve for some time," "we prevent double booking," "after cancellation, we free up." But in the next discussion, it turns out that one participant understood "reservation" as ten minutes, another as the entire selected interval, and the third thought that availability is checked only at confirmation.

The team gathers again, clarifies the terms, and reaches an agreement. This can take hours and days: conversations create the feeling of progress. The problem arises when the result doesn't become a description that can be checked entirely.

Another extreme is to write code faster so that there's something to discuss. There's also clear logic here: a working screen is more specific than a conversation. However, assumptions are already becoming tables, processors, client models, and tests. When it turns out that the temporary reservation must block the equipment immediately, several related parts need to be changed. The more implementations are built on an incorrect assumption, the more expensive the correction and the broader the area of possible errors.

*Figure 1. The accuracy of the description increases along with the effort required to prepare and change it.*

Code most precisely defines executable instructions. But it's possible to implement incorrect behavior.

Between conversation and implementation there's a convenient area: data models, behavior diagrams, and interface contracts. They already force you to answer uncomfortable questions, but changing state transitions or entity relationships is usually easier than redoing the functionality they affect. In this article, we will refer to such an approach as Spec driven development: implementation relies on a coordinated description of the solution.

Route from idea to implementation

Figure 2. The main project attention falls in the middle of the route. LLM helps at all stages; the person checks the meaning and makes decisions.

For example, let's agree that the reservation lasts ten minutes, after which it cannot be confirmed. A confirmed reservation and an active reservation occupy the selected interval. Cancellation frees it. Payment, issuance, and return of equipment are outside the scope of the feature.

The diagram defines the order of clarification, not a prohibition to go back. A conflict found in the Sequence may require changing the requirement. Then we update the related artifacts to the implementation of the dependent step. Also, there is no need to describe the entire future product: first, we go through the route for one completed scenario.

1. Meetings and discussions: figuring out what we are building

We start with the people who need the feature. What problem is currently occurring? Who books the equipment? What should the user get after confirmation? What situations are considered unacceptable? Specific user stories are helpful: "two employees came for one projector," "a person opened a form and left, the equipment remained reserved."

In our example, we need to figure out the lock time, reservation period, meaning of cancellation, and behavior during competitive requests. We separately clarify boundaries: we book a specific projector with an inventory number, not an arbitrary unit from a category.

LLM can pre-form questions, group conflicting wishes, and suggest boundary situations. However, the answer "the user probably expects ten minutes" remains a model's assumption. The choice of duration belongs to the people responsible for the process.

A useful result of the meeting is agreed solutions and a short list of questions with responsible parties. If a question affects data or the public interface, it needs to be resolved before designing the corresponding part. Other, independent parts of work can continue.

2. Notes and summaries: keeping the agreed decision

After the meeting, a compact summary is needed. Full disclosure preserves the conversation, but forces the next reader to re-extract decisions from it. The note should show the chosen option, its reason, and the remaining uncertainty.

For example:

Decision: reserve blocks equipment for ten minutes from the moment of creation. Reason: the user must have time to check the parameters before confirming. The expiration is determined by the server. Question: can the reserve be extended? Decision for the first version: extension is not supported.

Such text already distinguishes an agreed-upon time from a randomly mentioned idea.

It is convenient to assign LLM to draft the outline and a list of contradictions between meetings. Participants check that the model did not turn a question into a decision and did not lose an exception. At this stage, it is especially easy to get a neat, persuasive text that falsely attributes a non-existent agreement to the team.

3. Formal requirements: replace "clear" with verifiable rules

Now we formulate the rules so that two executors get the same result. Instead of "we do not allow double booking," we write what requests occupy the resource and what to consider as an intersection.

| Rule | Consistent Behavior | | — | — | | BR-01 | An interval has the form [startsAt, endsAt): start is inclusive, end is exclusive; start is earlier than end. | | BR-02 | When created, HELD is set, and the reservation duration is ten minutes according to server time. | | BR-03 | Equipment is blocked by CONFIRMED and HELD where now < holdExpiresAt. | | BR-04 | Checking for intersection and creating a reservation constitute a single atomic operation. | | BR-05 | When now >= holdExpiresAt, the reservation has expired; it cannot be confirmed. | | BR-06 | Confirmation and cancellation are only available to the booking owner. |

Identifiers help link solutions to diagrams and scenarios. An agent can be tasked with finding a rule without an example or an ambiguous word. The final meaning is affirmed by the person. Detailed transitions and handling of repeated actions will be fixed later when we consider the booking lifecycle.

A good requirement withstands the question "How will we know it's been completed?"." The requirement "The system correctly handles simultaneous requests" does not provide such an answer. "Exactly one of two overlapping requests for free equipment is successfully created" already defines an observable check.

4. Data model and ERD: determining what exists in the system

The model contains only three entities: user, equipment unit, and reservation. Each reservation belongs to one user and relates to one unit. A user and equipment can have multiple reservations.

Figure 3. startsAt and endsAt describe equipment usage, holdExpiresAt — the time when the user makes a decision.

ERD shows the structure and cardinality of relationships. The rule prohibiting intersections needs to be written nearby: a regular foreign key is insufficient for it.

LLM can prepare a textual schema and verify field names against requirements.

It's useful to immediately separate stored data from the public response. The server needs the record owner, but there's no need to return the user's external identity to the client for confirming their reservation. On the contrary, the interface needs to know the reservation duration to explain the remaining time. Such analysis prevents the common practice of copying the entire table in the API and helps formulate a future response schema without being tied to a specific ORM.

5. Use Case: Describing the user's goals

Use Case helps verify that the project addresses the user's task. For an employee, we identify four goals: check availability, create a temporary reservation, confirm, and cancel the booking.

Figure 4. Lines connect the participant to the goals; they do not define the sequence of HTTP calls.

It's not advisable to turn this diagram into a list of all service methods. Saving the record in the database is an implementation action, while the employee needs the result of the booking. Authentication is considered a precondition for the considered actions.

LLM easily builds such a schema from the list of goals. The benefit of the review lies in checking the boundaries: ensuring the user hasn't gained the ability to confirm others' requests, cancellation hasn't disappeared, and no additional equipment management has been added, which isn't part of the current task. The general notation of these and subsequent behavioral diagrams is defined by UML.

6. C4 Context: Defining the system's boundaries

The next question is where our responsibility ends. On the Context diagram, there are an employee, a booking system, and an external identity provider. We use existing accounts, and the reservation rules belong to the system being created.

Figure 5. System context: user, target system, and external dependency.

Context is useful to discuss with people who don't need server code details. They may notice the missing external dependency or incorrectly defined responsibility. For example, if the equipment is actually provided by a separate service, its involvement becomes a new requirement.

7. C4 Container: distribute responsibility

We will break down the system into three parts: web interface, reservation API, and relational database. The interface displays data and sends commands. The API checks the user and the rules. The database stores the state and participates in ensuring atomicity.

Figure 6. C4 Container — application or data store.

On the diagram, we indicate the protocols and save the names for the future Sequence. LLM helps to assemble and draw the architecture. For the selected behavior, here it is sufficient to have one server application. The purpose of this level is more detailed in the C4 Container documentation.

8. State Machine: understanding the lifecycle

The reservation has four states: temporary reservation HELD, confirmed reservation CONFIRMED, cancellation CANCELLED, and expiration EXPIRED. From the temporary reservation, you can transition to any of the three other states. A confirmed reservation can be canceled. Cancellation and expiration complete the life cycle within our example.

Figure 7. Transition conditions are more important than the list of statuses itself. Exactly on the deadline boundary, confirmation is no longer permissible.

To prepare the diagram, a short task is sufficient:

The textual diagram can be easily edited via LLM and stored alongside the documents. Syntax and rendering are automated; checking the meaning remains the task of the review. PlantUML State Diagram description.

9. Sequence: check the interaction of participants

Now let's track the creation of a reservation: the web interface sends parameters, the API checks them, accesses the database, creates a record, and returns the result. Participant names are taken from Container, fields from ERD, and conditions from requirements.

Figure 8. The check and recording are protected by a single transaction and serialization of equipment operations.

LLM is useful to ask to find messages without a handler, transaction breaks and alternative branches. On review, we also check the moment of response: 201 is sent after successful transaction completion.

10. Activity: we reveal the algorithm and branches

Sequence answers the question "who interacts with whom", Activity — "what decisions are made". In the algorithm of creating a reservation, we check the input data, then in the protected operation, we determine blocking reservations and search for overlaps.

Figure 9. The expired HELD is excluded from blocking reservations until the overlap check is performed.

Conditions are conveniently written without being tied to a programming language:

LLM can expand the rules in Activity and offer examples for each branch. When reviewing, it is important to verify the sequence of actions with Sequence. Beautiful pictures describing different algorithms can only increase ambiguity. The same atomic area should be preserved in both representations.

11. OpenAPI: we solidify the external interface

When the behavior is clarified, we fix the HTTP contract. The tutorial document includes creating a reservation, confirmation, and cancellation. Equipment inspection and the entire process of entering it are not included. We are using OpenAPI 3.0.3, as in the original presentation; this is a choice of example format, not a recommendation to consider it the latest version.

To create a reservation, you need equipmentId, startsAt, and endsAt. The owner and reservation period are assigned by the server. Neither userId nor the desired client status is transmitted. A short fragment of the operation looks like this:

This is a fragment; schema definitions and other responses can be found in the full OpenAPI tutorial. Successful confirmation and cancellation return 200. Incorrect parameters — 400, absence of valid authentication — 401. For unknown or foreign reservations, 404 is used; conflict of time or status — 409 with a distinguishable reason code.

The contract allows for independent discussion of frontend, backend, and tests. LLM can prepare client types and handlers, verify examples against schemas. However, the description of Bearer does not implement token verification, and a correct JSON does not prove the absence of double booking. These responsibilities remain in the rules and implementation. The assignment and structure of HTTP contracts are defined by the OpenAPI specification.

12. Markdown specification: collecting a consistent project

By this point, several related representations have appeared. Now we compile a document through which a developer or agent can navigate from the goal to a specific solution: boundaries, terms, rules, model, diagrams, contract, accepted constraints, and version.

Initial requirements explained what we wanted. The final Markdown specification records the consistent structure of the selected scenario. There is no need to manually rewrite the entire OpenAPI into it: references and explanations of decisions that cannot be inferred from the request structure are sufficient.

In the applications, there is a specification for the example version equipment-reservation-v1. This is a designation of the edition of the training material, not a reference to an existing Git tag. For example, it clearly separates the stored status and the actual expiration based on server time.

LLM helps check consistency: are all states present in the model, does the response match the algorithm branch, is there a rule without a scenario?

13. BDD Scenarios: Agreeing on the Observable Result

Before writing code, we define specific initial data, action, and expected result. For example, in Gherkin terms:

Also needed are successful creation, intersection, adjacent intervals, cancellation, repeated commands, and access to another's reservation. For competition, we fix the result: from two simultaneous overlapping requests to free equipment, one gets 201, the other — 409; the blocking record remains one. The winner is not predetermined.

Scenarios are stored in a separate file. Until they have step definitions and an application, they are agreed-upon examples, not executed automated tests. Their automation is assigned to LLM when implementing the corresponding step.

14. Code and tests: one task, one review, next step

Now, the implementation can be passed to the agent. A large feature is broken down so that the result of each task can be checked separately: model and transitions; atomic reservation; confirmation and cancellation; HTTP API; web interface; final check of user scenarios. Tests are added at each step, not deferred until the last moment.

Figure 10. A human checks the result of the current step before moving to the next. Changes in business rules are returned for project agreement.

For example, a task for the reservation stage:

This is a task for a future project: the attached package does not include the service implementation. In a real repository, technology, check teams, and the latest revision of the materials are added to it.

It remains for a person to check the rule compliance and the engineering solution's reasonableness. Fast tests with controlled time are useful for domain logic. Concurrency and locks are checked on the selected database: an imitation storage cannot confirm its transactional guarantees. Then the HTTP contract and user path are checked.

If the code is wrong, we fix the code. If a project gap is found, we first agree on the change of schemas, rules, and scenarios. A small-step review helps localize the problem before the next part of the feature grows over it.

The main effort is in the middle of the process

In large development, it is useful to focus as much as possible where the solution is already sufficiently precise and changing it is still relatively simple: on data models, UML diagrams, C4 boundaries, and contracts. Conversations provide the material for these decisions. Code embodies them. Markdown connects them, and scenarios make expectations testable.

LLM lowers the threshold for schema preparation: describe the rule in plain language, get the diagram text, review the result, and make corrections. Time is primarily spent on meaning—what transition is allowed, who is responsible for the operation, what is considered a conflict. Exactly these decisions are especially costly to recover from already written code.

When the schema, data, and contract are aligned, the agent has fewer reasons to guess behavior. Implementation can be handed out sequentially as small tasks, leaving decision-making and review to the person. This does not automatically make errors negligible, but it allows for earlier detection of discrepancies and limits the scope of rework.

Educational applications

To work with the example, save the application content into files with the specified names in the assets/ directory. Text sources of diagrams are included in the specification application.