Best Practices: Feature Specification – Gunther Popp – AI‑Driven Development & Agentic AI

Feature specifications form the foundation of AI-Driven Development. This article explains what they should contain, how they differ from data models and implementation plans, and how to maintain them as Documentation as Code.

Introduction

Feature specifications are, of course, not an invention of AI-Driven Development. Ideally, every development process starts implementation from documented requirements. Unfortunately, that is not as self-evident in practice as it sounds. Even today, many projects struggle precisely because their requirements are unclear, incomplete, or difficult to access. Other projects dispense with separately documented requirements altogether, often arguing that they have an agile process and an issue tracker. Tickets can contain requirements, but in practice they are often not treated that way, and proper requirements documentation falls by the wayside.

Once you decide to adopt AI-Driven Development, taking shortcuts through minimally documented tickets no longer works. Together with the semantic data model, feature specifications form the foundation for communicating with agents. Without properly documented requirements, implementation plans cannot be created properly either, and the result is faulty or incomplete code. You could certainly argue that this fact alone justifies introducing an AI-Driven Development process.

What Is a Feature Specification?

A feature specification is a document that is easy for both people and agents to read. I recommend storing it as a Markdown file in a repository. In smaller projects, it lives alongside the code; in larger initiatives, a separate specification repository can be worthwhile. It describes the behavior of a coherent part of the target system: who it is for, what should happen, what must not happen, and how we know it is done.

Feature files can be created with the help of agents, but they must always be reviewed and approved by people acting as the Human-in-the-Loop (HITL). As of autumn 2026, agents cannot recognize requirements that are wrong from a domain perspective and therefore do not question them.

That does not mean I create a feature file for every small change. A simple ticket really is enough for a typo, a text change, or a minor bug fix. Some judgment is needed here. AIDD is not about establishing yet another heavyweight process; quite the opposite. Increasingly capable agents enable short cycles, bug fixes, and continuous improvements. I write a feature file when new observable behavior is added or existing behavior changes in a way that stakeholders would notice.

How It Differs from Other Documents

I distinguish between four types of documents in an AIDD process:

Feature specification (what / why). Describes the system’s behavior at the UI or API boundary. I cover the key content and a recommended structure in more detail below.
Semantic data model (what / glossary). Entities, attributes, types, relationships, enumerations, GDPR annotations, and domain rules. The SDM is the glossary on which the feature specification builds.
Architecture documentation (how / high level). Fundamental architectural decisions, layers, interfaces, integration points, and non-functional requirements. The agent uses this information to create the implementation plan, but the architecture documentation is independent of individual features.
Implementation plan (how / low level). Implementation steps, test strategy, scope, exclusions, and decisions the agent cannot make on its own. A single specification can also lead to several implementation plans, depending on its size or module boundaries.

For the survey management example I have used in several blog posts, the distinction looks like this: the feature specification says that an administrator can create a survey with a title and creator, add ordered questions of defined types, and delete a survey together with its dependent data. The semantic data model says what a Question is and which values QuestionTypeEnum defines. The architecture documentation explains the service’s basic structure, including the layers to implement. The implementation plan says that we build persistence first, then repositories, then the service layer, then the REST API, and how all of this should be covered by tests.

Content and Structure

The same point applies to the content and structure of a feature specification: there is no need to reinvent the wheel for an AIDD process. There are countless approaches, templates, and best practices for capturing and documenting requirements. From my perspective, what matters is that the result is understandable to both people and agents.

One approach I view rather negatively is documenting requirements in EARS (Easy Approach to Requirements Syntax), as promoted and implemented by Amazon Kiro. At first glance, the idea seems sensible: use a structured syntax to express requirements precisely, unambiguously, and in a testable form. The hope, at least, is that this makes it easier for agents to understand the requirements correctly. Yet although EARS was originally developed for people, I find its syntax difficult for human stakeholders to read. In many projects, these stakeholders already carry a substantial workload of domain reviews and requirements documentation. A cumbersome syntax like EARS does not make that task easier, and there is a real risk of parallel documents emerging with the same requirements in “normal” prose.

What works for me is documenting requirements in ordinary prose, using Markdown and the project’s language: German in a German team, English in an international one. I used to have the impression that models generally found English easier, so I preferred it. With the newer frontier models, I no longer find that to be the case. What matters is that all project-specific domain terms are consistent with the semantic data model, which serves as the glossary. If the SDM uses English for its entities and the features are written in German, the English entities, attributes, and other terms from the SDM are still used. I simply ignore complaints about the resulting mix of German and English; the priority is getting the right results from the AIDD process.

For the functional description of backend features, I use traditional use cases, sometimes journeys, and interface contracts. A journey might read as follows: an administrator creates a survey with a title and creator, adds three questions, retrieves the complete structure, deletes a question, and finally deletes the survey. That is enough to understand the desired functionality. Journeys also help find the right granularity for a feature. If I cannot describe a journey, for example because a feature has been confused with a single API endpoint, that may indicate that the scope is too narrow. If I struggle to describe the functionality in one coherent journey, the scope is probably still too broad. Interface contracts belong in the requirements only when they are not an outcome of the implementation. This means interfaces that the new backend service is expected to use unchanged. In my view, putting requirements for new interfaces into the specification as, for example, an OpenAPI contract is not a good idea. That is far too detailed and preempts an essential part of the design and implementation phase.

Journeys are also a good choice for UI-heavy features, describing how users interact with the interface. Personas are often used here to illustrate different user roles and their behavior. References to mockups or design documents are also common, clarifying the intended visual implementation. The photo carousel example shows a UI specification organized by areas of behavior.

A useful structure for a feature file could look like this:

Summary. A short paragraph explaining what the feature is, who it is for, and why it was created.
Goals and non-goals. Particularly important for agents. Human developers often take it for granted that the backend team builds only the API and no UI; agents do not.
Functional description. See above.
Non-functional requirements. Feature-specific non-functional requirements that go beyond the architecture documentation. Examples include permissions or accessibility requirements.
Business or UI rules. Only rules specific to the feature that are not already in the semantic data model, or a reference if they are defined there.
Error cases. Expected error cases that can be verified through the UI or API.
Acceptance criteria. The conditions for considering the entire feature done. The same principle applies as for error cases: they must be verifiable “from the outside,” through the UI or API.
References. Links to interface contracts, mockups, and so on.

Documentation as Code

Documentation as Code is an approach in which requirements and other project documents are treated like source code. They are versioned, maintained in the repository, and ideally checked automatically. Markdown files for feature specifications are a typical example. As mentioned above, I recommend that small to medium-sized projects keep them in the same repository as the source code. In this setup, I can use the bootstrap prompt or AGENTS.md file to instruct agents to keep the specification consistent with the code. Changes to the specification are then reviewed and approved as part of the PRs for code changes.

A separate specification repository may become useful in large projects with many participants, several independently developed modules, and correspondingly complex dependencies between them. If requirements are maintained in each module’s repository in that situation, inconsistencies can creep in and the overall picture can get lost, for both people and agents.

When opting for a separate specification repository, it is important that the AIDD tools support working across multiple repositories. This allows agents to update requirements in the specification repository alongside source code in the module repository, then open two PRs, for example: one for the specifications and one for the actual source code. To ensure consistency, both PRs must of course be reviewed and approved together.

Spec-Driven Development

If you have already explored requirements and AI in software development, you may have come across the term Spec-Driven Development (SDD). In my view, SDD is not particularly well defined, but it can roughly be distilled into the following principles:

Requirements are captured and documented before implementation begins.
Requirements are continuously updated during implementation.
Requirements are treated on an equal footing with source code in the project, for example by maintaining and versioning them in the version control system.

This brings us back to the ideas discussed earlier in this article. SDD also adds a tooling aspect. There are now several implementations and toolkits that support this approach. One example is Amazon Kiro, mentioned earlier in the article.

An open-source SDD implementation is also available: Spec Kit on GitHub. Version 1.0.0 was officially released in August 2026. A separate blog post will specifically cover SDD with Spec Kit.

Conclusion

“No code without a requirement” is enjoying a revival with AI-Driven Development that I very much welcome. Feature files in Markdown can be created and maintained easily with all the usual tools. Existing mechanisms for managing source code, such as version control and code reviews, can therefore be applied directly to specifications as well. Agents also help us address a perennial pain point in project work: continuously adapting and updating requirements to reflect the actual implementation.

If you have not yet ventured into AI-Driven Development, the prospect of finally having complete, up-to-date requirements documentation alone should be reason enough to take the first step into this new world of software development.