AI coding agents are getting better at writing application code, but writing the code is not always the difficult part.

The harder decisions often happen before implementation: How should the data be modeled? What should the partition key be? Which access patterns need to be supported? Should a query use a point read, a cross-partition query, or a different model altogether?

These decisions matter a lot with Azure Cosmos DB because a design that looks reasonable in code can still create unnecessary request-unit consumption, poor query performance, or difficult scaling problems later.

That is where the Azure Cosmos DB extension for GitHub Spec Kit becomes interesting. The extension brings Cosmos DB-specific guidance into a spec-driven development workflow, giving AI coding agents more context around database design before they start generating the implementation. Microsoft announced the extension as a public preview and described it as the first database extension in the Spec Kit ecosystem.

The important idea is not simply "AI can generate Cosmos DB code." It is that database decisions can become part of the specification and planning process instead of being left entirely to the coding agent during implementation.

What Is GitHub Spec Kit?

GitHub Spec Kit is designed around spec-driven development, or SDD.

Instead of immediately asking an AI coding agent to generate code, the workflow starts with the intended behavior and then moves through planning and implementation.

A simplified flow looks like this:

Requirement
    ↓
Specification
    ↓
Technical Plan
    ↓
Implementation Tasks
    ↓
Code
    ↓
Review

The purpose is to keep the developer's intent visible throughout the development process.

This matters with AI-assisted development because a coding agent can produce syntactically correct code while making assumptions that were never explicitly agreed upon.

For a normal application, those assumptions might involve class structure or API design.

For a Cosmos DB application, they can involve much more consequential decisions such as partitioning and data access patterns.

Spec Kit provides an extension mechanism so domain-specific guidance can be added to the core workflow. The current extension system supports commands, templates, hooks, and other capabilities, allowing specialized tooling to participate in the development process.

Why Cosmos DB Needs Design Guidance

Cosmos DB is flexible enough that developers can start building quickly.

That flexibility can also make poor design decisions easy to introduce.

Consider a simple document:

{
  "id": "order-1001",
  "customerId": "customer-42",
  "status": "Shipped",
  "items": [
    {
      "productId": "p100",
      "quantity": 2
    }
  ]
}

The C# model is straightforward:

public sealed class Order
{
    public string Id { get; set; } = string.Empty;
    public string CustomerId { get; set; } = string.Empty;
    public string Status { get; set; } = string.Empty;
    public List<OrderItem> Items { get; set; } = [];
}

public sealed class OrderItem
{
    public string ProductId { get; set; } = string.Empty;
    public int Quantity { get; set; }
}

Nothing looks particularly difficult here.

The more important question is how the application will use the data.

If most requests are:

Get orders for customer
Get a specific order for customer
Update an order for customer

then the partitioning strategy should reflect those access patterns.

An AI agent that only sees the C# classes may not understand why one partition key is preferable to another.

A specification gives the agent more context.

What the Cosmos DB Extension Adds

The Azure Cosmos DB extension adds Cosmos-specific commands and hooks to the Spec Kit workflow.

Microsoft describes the extension as providing guidance for application design before implementation, with the developer and coding agent working through specifications, plans, implementation tasks, and code review.

The extension is currently a public preview, so its commands and behavior can change as the project develops.

The basic idea is:

/specify
    ↓
Describe application requirements
    ↓
Cosmos DB design guidance
    ↓
/plan
    ↓
/tasks
    ↓
/implement
    ↓
Review generated implementation

The database is therefore considered during planning rather than being added after the application structure has already been generated.

A Practical Example

Imagine you are building a multi-tenant support application.

The initial requirement might be:

Customers can create support tickets.
Agents can view tickets belonging to their organization.
Tickets can be updated and searched by status.

A developer could immediately ask an AI agent to create the application.

That may produce controllers, models, repositories, and Cosmos DB code very quickly.

But several database questions remain unanswered:

What is the tenant boundary?
What should the partition key be?
How are tickets queried?
Which fields are frequently filtered?
Should ticket history be embedded?
Which operations require point reads?

Those questions are architectural decisions.

A spec-driven workflow gives the developer an opportunity to make those decisions explicit.

For example:

Requirement:
Tickets must always be accessed within a tenant.

Access patterns:
- Get ticket by tenant and ticket ID
- List tickets for tenant
- Filter tenant tickets by status

That information is much more useful to a database-aware coding agent than simply saying:

Create a Ticket entity in Cosmos DB.

Why Access Patterns Matter

One of the easiest mistakes in NoSQL development is designing the document first and the access patterns later.

Relational developers often start by thinking about entities and relationships.

With a distributed NoSQL database, you also need to think about how the application will actually read and write those entities.

For example:

GET /tenants/{tenantId}/tickets/{ticketId}

has a different access pattern from:

GET /tickets?status=Open

The second query may involve a much broader data set depending on the partitioning strategy.

This is why database guidance inside the planning stage is valuable.

The agent has an opportunity to reason about the intended workload before generating the repository and query code.

From Specification to Implementation

A useful workflow could look like this.

Step 1: Describe the Requirement

Start with the business behavior rather than the database implementation.

Build a support-ticket system for multiple organizations.

Each organization can create and manage its own tickets.
Users must not access another organization's tickets.
The application frequently retrieves tickets by organization and ticket ID.
Support agents also need to list open tickets belonging to their organization.

This gives the agent the important application context.

Step 2: Review the Plan

Before code is generated, review the proposed data model and access patterns.

Ask questions such as:

Why was this partition key selected?
Which operations are expected to be point reads?
Which queries may cross partitions?
How will tenant isolation be enforced?

These questions are more valuable than simply reviewing whether the generated C# compiles.

Step 3: Generate Tasks

Once the design is acceptable, implementation can be broken into tasks:

Create ticket model
Configure Cosmos DB client
Create container configuration
Implement ticket repository
Add tenant-aware queries
Add API endpoints
Add integration tests

The important distinction is that the implementation tasks now follow an explicit design.

Step 4: Review the Generated Code

AI-generated code still needs engineering review.

For example:

public async Task<Order?> GetOrderAsync(
    string customerId,
    string orderId)
{
    return await _container.ReadItemAsync<Order>(
        orderId,
        new PartitionKey(customerId));
}

The code is small, but the correctness depends on the data model.

If customerId is actually the partition key, this operation can be an efficient point read.

If the container was designed around a different partition key, the same method may be incorrect or require a completely different access strategy.

That is why the specification matters.

The Extension Is Not a Replacement for Database Expertise

This is an important distinction.

An extension can provide guidance and reusable patterns, but it does not remove the need for an engineer to review the design.

A coding agent can still make an incorrect recommendation.

For example, an agent might generate a partitioning strategy that works for today's dataset but performs poorly when one tenant becomes dramatically larger than the others.

The engineer still needs to ask:

What happens when the largest tenant grows 100x?

What happens if one partition becomes disproportionately hot?

What happens when the query pattern changes?

What happens when a new requirement needs a different access pattern?

AI assistance is useful here because it can make the design process faster. It does not make architectural judgment unnecessary.

Commands and Guided Workflows

The extension provides Cosmos DB-specific commands alongside the normal Spec Kit workflow.

The extension's current preview documentation describes both guided and explicit approaches. A guided command can help determine which Cosmos DB operation or pattern is appropriate, while explicit commands can be used when the developer already knows the desired pattern.

Conceptually, that gives developers two different workflows.

Guided

Describe what the application needs
        ↓
Ask the Cosmos DB extension for guidance
        ↓
Review recommendation
        ↓
Generate implementation

Explicit

Known requirement
        ↓
Select a specific Cosmos DB pattern
        ↓
Generate implementation
        ↓
Review code

The second approach is useful for experienced developers who already know the intended database pattern.

Hooks Are Useful, But Review Still Matters

The extension can participate in the Spec Kit process through hooks around implementation. Its preview documentation describes a before_implement hook for recommending relevant Cosmos DB guidance and an after_implement hook for reviewing the generated result.

That creates a useful quality-control loop:

Plan
 ↓
Cosmos DB guidance
 ↓
Implementation
 ↓
Cosmos DB review
 ↓
Developer approval

This is better than treating the database layer as an invisible implementation detail.

There is also an important limitation to understand. Spec Kit's current extension model does not guarantee that an autonomous agent will always invoke every available extension command. A current upstream issue specifically discusses the need for always-on instructions because an autonomous agent may complete work without invoking an extension's commands or hooks.

That means teams should not assume that simply installing an extension guarantees every generated piece of code will automatically follow its recommendations.

Security and Tenant Isolation

Cosmos DB design is not only about performance.

In a multi-tenant application, the data model can also affect security.

Suppose an API accepts:

tenantId
ticketId

The application should not trust a ticket ID alone to determine whether a user can access the document.

The request needs to remain scoped to the tenant.

A repository method might therefore intentionally require both values:

public async Task<Ticket?> GetTicketAsync(
    string tenantId,
    string ticketId)
{
    return await _container.ReadItemAsync<Ticket>(
        ticketId,
        new PartitionKey(tenantId));
}

The design makes the tenant boundary part of the data access operation.

This is the kind of decision that should appear in the specification and architecture, not be left to chance during code generation.

Common Mistakes

Starting With the C# Model

Creating classes first and deciding the Cosmos DB access model later can lead to a design that does not match the application's workload.

Start with requirements and access patterns.

Letting the Agent Pick Everything

An AI agent can propose a data model, but that does not mean the proposal should automatically become the production architecture.

Review partitioning, query patterns, data growth, and tenant isolation.

Treating Generated Code as the Specification

Generated code is an implementation artifact.

The specification should explain why the system behaves the way it does.

If the code changes later, the specification should still communicate the underlying intent.

Ignoring Preview Status

The Cosmos DB extension is currently a public preview. Commands and behavior can change, so teams should avoid assuming that today's extension interface is permanently stable.

Advantages and Disadvantages

Advantages

Database decisions move earlier in the workflow. Instead of generating application code first and fixing the Cosmos DB design afterward, developers can consider data modeling and access patterns during planning.

AI agents get domain-specific guidance. A general coding agent knows how to write C# but does not automatically know the reasoning behind every Cosmos DB design choice.

The workflow remains reviewable. Specifications, plans, tasks, and implementation provide checkpoints where an engineer can challenge the proposed design.

Reusable patterns reduce repetitive work. Common Cosmos DB development tasks can be expressed through extension commands instead of repeatedly explaining the same database patterns to an AI agent.

Disadvantages

The extension is still in preview. Commands and behavior can change, which matters for teams building standardized development workflows.

AI recommendations still need review. The extension provides guidance, not architectural authority.

Autonomous workflows can still bypass guidance. Current Spec Kit discussions around always-on extension instructions show that command-based guidance is not guaranteed to influence every agent run.

Teams need to understand both Spec Kit and Cosmos DB. Adding another development layer does not remove the underlying engineering knowledge required to evaluate the generated architecture.

When This Extension Makes Sense

The extension is most useful when a project combines AI-assisted development with meaningful Cosmos DB design decisions.

It is a particularly good fit for:

New Cosmos DB applications
Multi-tenant applications
AI-assisted application development
Teams standardizing database patterns
Projects with several coding agents
Applications where partitioning is important
Projects that want design review before implementation

It is less useful when the database model is already fixed and the work consists mostly of small, well-understood changes.

If a developer already has a mature data model and is changing one API endpoint, a full specification workflow may add more process than value.

Summary

The Azure Cosmos DB extension for GitHub Spec Kit is interesting because it moves database reasoning closer to the beginning of AI-assisted software development.

Instead of asking an AI coding agent to generate Cosmos DB code immediately, developers can describe the requirements, review the proposed data model and access patterns, create implementation tasks, and then generate the code.

That distinction matters.

The most expensive database mistakes are rarely syntax mistakes. They are usually design mistakes that become visible only after data volume, traffic, or query complexity increases.

Spec-driven development cannot eliminate those mistakes, and the Cosmos DB extension cannot replace an experienced database engineer. What it can do is give AI coding agents more structured context and give developers a better place to review important decisions before those decisions become production code.

For teams using AI coding agents to build Cosmos DB applications, that is probably the most useful part of the extension: making the database design part of the conversation before the code is written.