Spec-Driven Development

In Claude Code, install the Akka plugin from the AI Marketplace:

This registers the Akka marketplace, installs the Akka skill (CLI, MCP server, AI coding assistant, and project scaffolding), and activates it.

+ This configures your environment — ensuring the Akka CLI is installed, Java and Maven are available, and your Akka download token is properly configured. Once setup completes, you are ready to start building.

With direct prompting, you supply prompts to your favorite AI assistant and get generated code back. This can be useful for demonstrations and sample applications, but this level has no reliable source of truth. AI assistants are well known for producing different output for the same prompt. Attempts to move toward a reliable source of truth and decrease the random nature of the output lead to the next maturity level.

While code assistant chat logs can be saved and exported, they are unsuitable for use as a source of truth, a specification, or a document that can be committed to version control. The next evolution is typically when people create a single specification file in markdown. This file contains the entirety of an application specification, including the details on what is being built, why it is being built, and how it should be built (tech specifications).

This maturity level has a single source of truth (the spec file) which can be version controlled. More importantly, LLMs can judge how well the generated code conforms to the specification. Deviations above a certain threshold can fail builds and trigger human-in-the-loop workflows that may result in many iterations refining the specification.

Crucially, this single file specification is usually written mostly by humans. It becomes unwieldy once a specification reaches a certain level of complexity.

A single SPEC.md or specification.md file may be enough for some projects. Many sample or demonstration applications can be built properly with just a single file. However, when your needs and complexity reach a certain point, you need a formal process. This process is iterative, git-friendly, and enlists the aid of the AI assistant both in building the spec and generating the code from it. It addresses the need to build formal specifications that are consumable by both human and AI alike while reducing random and unexpected output. This process is covered in detail below.

Running akka specify init <dir> provisions a new AI-assist ready project directory. It scaffolds an empty Akka project and grabs all of the markdown templates necessary for the spec-driven process. Once you have run this command, change to the directory of your new project (if you are not already there) and launch your favorite code assistant.

One of the important files that comes with your new project is a constitution. The constitution.md file is where unbreakable rules for the entire project are defined. This file contains mandates about technology requirements, design rules, and more. Akka gives you a default constitution that contains all of the mandatory requirements for Akka applications. In addition to the Akka-specific constitution, the initialization process lets you add an additional layer of constitution. Use this to include mandates from your company, organization, team, etc. It then becomes easy to maintain your own constitution while still benefiting from Akka’s rules.

The constitution is typically defined once at the start of a project and only refined as necessary. Constitution amendments are considered one-off exceptions and not part of the core development loop.

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.

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 seamlessly deploys your service, automatically doing a rolling update of the service cluster if one is already running.