[MS] Spec-Driven Development comes to Azure Cosmos DB: The First Database Extension for GitHub Spec Kit - devamazonaws.blogspot.com
AI coding agents can write much of an application's code, but developers still need to review the decisions behind it. For a Cosmos DB application, that includes choosing partition keys, modeling access patterns, and configuring the client. Those decisions affect cost, performance, and reliability long after the code compiles.
We've written before about how Azure Cosmos DB supports agents at query time, with tools and guidance for exploring and querying data. Today we're announcing the public preview of the Azure Cosmos DB extension for GitHub Spec Kit, the first database extension in its ecosystem. It brings Cosmos DB guidance into spec-driven development, helping you and your coding agent work through application design before implementation.
What is spec-driven development?
In spec-driven development (SDD), you work through requirements, design, and tasks before implementation. The agent produces a document at each stage that you can read, correct, and approve.
GitHub Spec Kit is an open framework for this workflow, with commands for each stage:
/specify: capture what you're building and why in a specification./plan: turn the spec into an architecture and a data model. This is where database decisions get made./tasks: break the plan into ordered, verifiable units of work./implement: generate the code, task by task, against that plan.
For example, you can check whether the proposed partition key supports your busiest queries while reviewing the plan. Changing it there is usually simpler than reworking the data layer after implementation. You decide when the plan is ready, then review the code and tests the agent produces.
Spec Kit also supports extensions that add domain-specific commands and hooks to this workflow.
From general-purpose to Cosmos-aware
Spec Kit is database-agnostic. Without an extension, its database recommendations depend on the model's existing knowledge and the context you supply. The Cosmos DB extension adds guidance on partitioning, RU costs, point reads, indexing, and resilient client configuration.
It complements the Cosmos DB Agent Kit skills by making Cosmos DB guidance available through Spec Kit commands and implementation hooks.
The extension provides:
- Code-generation commands for point reads, partition-aware and parameterized queries, managed-identity authentication, resilient clients, and other Cosmos DB patterns.
- Data-modeling guidance to help you choose containers and partition keys based on how the application reads and writes data.
- An advisor before implementation. The
before_implementhook selects the relevant patterns and includes their best-practice rules directly in the implementation context. - A review after implementation. The
after_implementhook instructs the agent to check the generated code against Cosmos DB guidance, fix the issues it identifies, and check again. You should still review and test the result.
The extension works with compatible Spec Kit agents, including GitHub Copilot, Claude Code, Codex, Cursor, and Gemini CLI, and can be used alongside other extensions.
Make it your team's own, with presets
Your team may also have naming standards, preferred SDK patterns, security requirements, and review steps. Spec Kit's presets let you add these conventions to the workflow without forking the Cosmos DB extension.
See the Spec Kit preset guide for installation instructions, template customization, and managing priorities when combining presets.
With a preset you can:
- Wrap or override command templates to include your team's requirements in planning and implementation.
- Customize a shared workflow that uses the Cosmos DB extension alongside other extensions.
- Maintain your customizations separately from the extension, making it easier to adopt updates without maintaining a fork. Overrides still need review when the underlying commands change.
A platform team could publish a preset that adds approved regions and authentication requirements to the planning template, for example. Developers who install that preset would have those requirements available when they run the command.
The documents and code still need your review. A preset supplies shared instructions; it doesn't enforce compliance with your team's policies.
We measured it
We evaluated both the generated code's adherence to Cosmos DB best practices and the results of building complete applications.
Best-practice checks. We compared code generated with and without the extension's guidance across models, languages, and complexity levels. The checks covered client application-name configuration, point reads using an ID and partition key, handling a 404 as a missing item, parameterized and partition-scoped queries, ETags, transactional batches, keyless authentication, and partition-key design.
- With the guidance applied, the average pass rate improved by 0.10, or about 10 percentage points, with improvements in 19 of 24 test combinations. Results were also more consistent between runs.
- The largest gain was in setting the client application-name: +0.79 in pass rate. Tests of individual best-practice commands showed gains of +0.14 to +0.37. Models that already followed the guidance had less room to improve.
- We also tuned the advisor's command recommendations, improving precision from 0.57 to 0.68.
These tests show that supplying the guidance improved adherence to the best practices we checked. They don't establish that every command produces correct code in every application.
End-to-end application tests. When agents ran the full workflow autonomously, they often skipped the recommended Cosmos DB commands and wrote the data layer without that guidance. That finding led to the changes in v0.2.0: the advisor now includes the relevant rules directly in the implementation context, and both the advisor and review hooks are configured as non-optional. The review also instructs the agent to apply fixes and recheck the code.
The updated extension scored modestly higher on average than the previous version for both models with usable results, although the uncertainty leaves room for no improvement. It performed roughly on par with Spec Kit alone and remained below the agent working without Spec Kit in those autonomous tests. A third model produced no usable scores because of agent runtime failures. These tests did not measure the effect of human review at each stage.
The clearest measured benefit so far is improved best-practice conformance when the guidance is supplied. The application tests helped us improve how that guidance reaches the agent, but they don't yet demonstrate a broader end-to-end advantage.
See the efficacy note for the methodology, results, and limitations.
How it fits with other Cosmos DB tools
The Spec Kit extension adds application planning and implementation guidance to the existing Cosmos DB tools for coding agents:
- Tools and MCP integrations, through the Azure Cosmos DB extension for VS Code and the optional MCP mode in Azure Cosmos DB Shell, let agents explore and query data within the permissions you grant.
- Agent Kit skills provide Cosmos DB knowledge for everyday coding tasks.
- The Spec Kit extension adds Cosmos DB commands and hooks to a workflow with specifications, plans, implementation tasks, and code review.
You can use these together or choose the ones that fit your work. The extension is intended for projects where you want to document and review application design as part of the coding workflow.
Try it
The extension is in public preview and installs in one line. From a project using Spec Kit's specify CLI:
specify extension add cosmosdb --from https://github.com/AzureCosmosDB/spec-kit-cosmosdb/archive/refs/tags/v0.2.0.zip
Then work through the Spec Kit flow (/specify, /plan, /tasks, /implement), reviewing the proposed data model and the generated code along the way.
- Repository: github.com/AzureCosmosDB/spec-kit-cosmosdb
- GitHub Spec Kit: github.com/github/spec-kit
- Cosmos DB Agent Kit (best-practice skills for everyday coding): github.com/AzureCosmosDB/cosmosdb-agent-kit
Command names and behavior may change during preview. Try it on a workload you know and open an issue with examples of missing guidance, incorrect recommendations, or code that needed fixing. Include the agent and model you used so we can investigate.
About Azure Cosmos DB
Azure Cosmos DB is a fully managed and serverless NoSQL and vector database for modern app development, including AI applications. With its SLA-backed speed and availability as well as instant dynamic scalability, it is ideal for real-time NoSQL and MongoDB applications that require high performance and global distribution.
To stay in the loop on Azure Cosmos DB updates, follow us on X, YouTube, and LinkedIn.
Post Updated on September 21, 2026 at 08:00AM
Thanks for reading
from devamazonaws.blogspot.com
Comments
Post a Comment