Spec-driven development

Your project starts with a constitution, constitution.md, which holds the rules for the whole project: the default Akka requirements, plus any your organization or team adds. Define it once at the start and change it only as an exception. Use /akka:constitution to create or update it. See The constitution.

It is possible to specify an entire application by supplying a prompt to the /akka:specify agent command, but it is not recommended. If your application is simple enough that it can be specified in a single prompt or file, use a single-file spec instead — the full spec-driven process is likely overkill for your needs.

To specify a new feature, use the following syntax from inside your AI agent:

The short description of the feature is turned into a branch name like 00#-feature-short-description where the description you supply is converted to kebab case. This also becomes the name of the new git branch.

The prompt for the feature specification should exclusively define the what and why of the feature, and should not contain any technical implementation details. In the sample prompt below for a chess application core website, the prompt mentions that the app does not use federated authentication. While this seems like a how level (plan) declaration, it belongs at the higher specification level because the concept of federation is a high level specification — the prompt does not mention how federation should be coded.

This creates a new specification in the specs/001-core-users directory, in the 001-core-users branch. At this stage, resist the temptation to go and manually edit the spec. Clarification is the next step.

There is no mention in this prompt of services or UI applications or how a web application is supposed to be served. Keep your feature specifications scoped to something small enough where you have a clear idea of the acceptance criteria and the generated code can easily be reviewed by humans or AI. Opinions vary on the scope of a "feature" so this is something teams generally decide amongst themselves and often on a per-feature basis.

Clarification is a critical step in this process. Start it by using a single command with no parameters:

Your AI assistant then analyzes your constitution, your feature specification, and any conversation history you have built up and identifies gaps. It looks for places where it would have to make a decision and it does not already have enough information to make that decision. If you run /akka:clarify on the chess core users feature, you will likely be asked several questions.

Typical clarification questions include how users are uniquely identified (internal UUID or username), what happens to deleted users, and whether users can have multiple concurrent sessions from multiple devices. Achieving this level of clarity is a hallmark of spec-driven development that you rarely get with single-file specs or even less formal multi-file specifications.

Once your AI assistant can no longer detect any more necessary clarifications, it is time to define the implementation plan.

The implementation plan is your technical architecture and technical design. Here you specify the how of your application. While it is a popular notion that anyone can build a spec-driven application, this is not entirely accurate. You need to be able to decide how you want your application to be built, and you need to know how to describe that in natural language clear enough for an LLM to understand it.

If you get all the way to code generation for the feature and you did not get what you wanted, then you may need to iterate on the implementation plan. Amendments to the plan are tracked diligently along with constitution and feature updates.

It is worth remembering that, like the specify step, the input to the plan step is a prompt, not the full and final plan. Your agent produces the final plan as output.

Take a look at this sample plan prompt for the chess game sample first feature.

There is a balance between including something in your specification prompt and assuming that your AI assistant will infer other important items that need to be in the final plan. It is common to spend extra time iterating on the plan prompt to make sure that the plan output is correct. Thankfully the plan output is categorized by priority and functional requirements, making it easy to verify.

In other words: make sure you agree with the functional requirements before continuing on to the next step. If you want to add requirements to the plan, do so interactively with your agent and it will update the plan accordingly.

The next step toward a running feature is to generate a task list with /akka:tasks. This takes your clarified specification and your implementation plan and converts them into a formal set of work items. Your agent identifies which tasks should be done first and which ones can be done in parallel. If you are satisfied with the set of tasks generated, continue to the next step.

You can also provide updates to the task list here by discussing it with your agent.

It is finally time to have your assistant write the code. When you use the /akka:implement command in your chat prompt, it creates your application code. Make sure that before you run this command, you are satisfied with the level of effort or "thought" being used by your agent. The results can vary drastically between medium and high effort levels.

During this step, it is common to see the agent make mistakes, generate compilation failures, and produce test failures. This is normal and the agent should be iterating toward the right answer. Only stop the agent in the middle of this step if you see something drastically wrong or you see the agent diverging from the solution over time instead of converging.

The default Akka constitution mandates both unit and integration tests, so these should also be generated and verified during this step.

When the code is complete, you should be able to exercise any RESTful APIs or user interfaces created. Akka makes this step easier as well.

You should never have to leave your agent chat during the spec-driven SDLC. If you use the /akka:build command, you get a ton of extra bonus features beyond a simple mvn compile exec:java.

Once your service is running — either locally after /akka:build or deployed via /akka:deploy — use the /akka:inspect command to verify it against your specification. Inspect exercises your service at runtime:

This is inspection: your agent checks that the running service actually behaves the way the specification says it should. If inspect finds issues, iterate with /akka:implement and /akka:build before deploying.

If you want to deploy your service to Akka’s infrastructure through Akka Automated Operations, use the /akka:deploy command. This command prompts you for the organization and project into which you want to deploy. It then deploys your service, automatically doing a rolling update of the service cluster if one is already running. After deployment, the command verifies component health and inspects the deployed service using backoffice tools.

Two additional commands help you maintain quality as your project evolves: