Skip to main content
Spec-driven development balances the speed of “vibe coding” with the professional rigor required to ship high-quality, bug-free software. In short, you should be maintaining clear, concise, and thoughtful Feature Requirements Docs, and you should iterate on them as your product grows and adapts to feedback. In a world where everyone is already writing lengthy prompts, SKILL.md files, AGENTS.md and more, maintaing a structured spec requires almost zero additional effort, and acai.sh aims to make that even easier. The result is a workflow that allows you to more confidently 1-shot, re-shot, refactor and rapidy iterate without worrying about your agents losing the plot and going off the rails.

​
The Spec

In Acai.sh, every spec is a feature spec — a single feature.yaml file that defines a slice of your product. This guide doesn’t get into the details of how to write the spec itself, for that see our feature.yaml guide. Specs are most commonly colocated with your code in a features/ folder, but they don’t have to be. Your specs can live anywhere (as long as it’s a git repo).
mapperoni.com
features
map-editor
feature.yaml

​
Key Principles

Function, not form

Specs should describe what the software does for the user, and how it behaves, not how it looks.

Not a status tracker

Specs describe what your feature should do. It is not a todo list nor a notepad. To track progress and delegate work, use an acai.sh server instead.

Requirements vs constraints

A good spec focuses on the surface requirements and ignores the plumbing. Only the most important constraints are included in the spec; like authn, security or engineering must-haves.

​
Feature & Implementation Boundaries

Think of your product as a heirarchy. A product has many features, and a feature can have many parallel implementations.

​
1. Product

A Product is any software system that has many features. It can be a microservice, an API, an SDK, a robot, a data pipeline, a mobile app, or a website.

​
2. Feature

A Feature is a clearly delineated “slice” of your software that brings value to the user. Example features might be personal-access-tokens, account-settings-page, role-based-access or webhook-service. Features are strongly user-oriented. They are not tightly coupled to a single UI component or code module, and can often span multiple git repositories.

​
3. Implementation

As you create branches and forks of your code, you will end up with many implementations of the same spec. Within each implementation, you may regress on some requirements while progressing others. This is where the acai.sh toolkit is specially helpful for QA and acceptance testing. In acai.sh, a single feature can have multiple implementations. For example, a “Dev” implementation on a feature branch, and a “Production” implementation on the main branch. The system gracefully handles changes to your specs or code, even across multiple git repos. To learn more about how acai and git work together, see our GitOps Guide.

​
4. Status

As stated above, your spec is not a todo list, so status and assignments should live outside of your spec. This is where the Acai CLI & server come in. You (or your agents) can attach status updates and notes to each individual requirement in your spec. This is extremely useful for coordinating work and tracking progress. Instead of creating github issue tickets to flag bugs and assign work, you create annotations that are tied to the specific requirements you wrote in your spec. At a glance you can see: which requirements are not met? Which have not passed QA? What’s left for feature-completion?

​
Completion vs Acceptance

Just because your AI agent says they completed the work, does not mean the work is actually in compliance with your spec. By convention, acai treats “acceptance” as the final status. This means it has passed your human QA and review process, whatever that may be.