Microsoft shipped the Azure Cosmos DB Agent Kit to GA, and the easy reaction is to file it under "vendor-specific AI docs."
That would miss the interesting part.
The interesting part is not that Cosmos DB now has instructions for coding agents. Everyone is going to have instructions for coding agents. Every database, framework, cloud service, internal platform, security team, and API gateway will eventually ship some pile of "please do not generate the expensive broken thing" guidance.
The interesting part is that Microsoft says the kit now has 120+ rules across 12 categories, backed by more than 200 automated test iterations where agents build real applications from scratch.
That is not documentation in the old sense.
That is documentation being treated like software.
And honestly, this is where developer documentation had to go once coding agents started writing production-shaped code. A paragraph that says "use the right partition key" is nice. A tested rule that catches an agent repeatedly choosing the wrong one is better. A lot better. Fewer meetings too, which is almost always a sign of civilization.
agents do not need nicer docs, they need sharper constraints
Most developer docs were written for humans.
That sounds obvious, but it matters.
Human docs assume judgment. They assume the reader can notice when an example is simplified, when a default is dangerous, when a performance footnote matters, and when the code snippet is showing the happy path because explaining the ugly path would make the page unreadable.
Coding agents are not great at that. They are very good at absorbing patterns and very happy to apply a pattern one inch outside the place where it still works.
This is why cloud services are such a wonderful trap for generated code.
The generated application can look correct. It compiles. It has routes. It has a repository class. It has a neat little configuration file. The tests written by the same tool may even pass, because of course they do. Then production data arrives and you discover that the partition key is wrong, the query cannot use the index, the SDK default was not the default you thought, or the cost curve has developed a personality.
General-purpose models know a lot.
They do not automatically know your service's scar tissue.
That is the job of an agent kit: package the scar tissue in a form the agent can actually use before it creates the mess.
the useful rules are usually embarrassing
The Cosmos DB post has a few examples that I like because they are not grand architecture principles. They are small, domain-specific, extremely annoying mistakes.
One example: enum serialization. In a generated .NET e-commerce scenario, the SDK stored order status as integers while the generated queries filtered by strings like "Pending" and "Shipped". The application did not explode. It just returned empty arrays.
That is a beautiful kind of bug, if by beautiful we mean rude.
No stack trace. No dramatic failure. Just an application quietly lying with excellent posture.
Another example: TOP in Cosmos DB SQL has to be a literal integer. A normal SQL-trained developer, or a model trained on normal SQL examples, may try to parameterize it because parameterizing values is usually the right instinct. In this case the right generic instinct produces a 400 Bad Request.
Then there is the Python async client needing aiohttp, but not in a way that the generated code naturally discovers from a simple import. And composite indexes where the direction matters: ASC in one place, DESC in the query, works in tiny tests, falls over later when the data gets real.
This is exactly the sort of stuff humans learn after losing an afternoon.
Agents need it before the first draft.
testing the guidance is the actual product
The most important part of the announcement is not the count of rules.
Rule counts are easy to inflate. Every team with a wiki can produce 120 rules if you give them enough coffee and one passive-aggressive architecture review.
The important part is the closed-loop testing setup.
Microsoft describes five application scenarios: an e-commerce order API, a gaming leaderboard, an IoT telemetry pipeline, a RAG chat app, and a multi-tenant SaaS platform. For each scenario, they define an API contract, let GitHub Copilot generate the application with the skill loaded, run it against the Cosmos DB Emulator in CI, build the app, run it, and hit it with tests for API behavior, infrastructure setup, and data integrity.
Then they fix the rules based on what failed.
That is the move.
Not "we wrote better docs."
"We observed agents failing, converted the failures into rules, and tested whether the rules changed behavior."
That is a very different discipline.
It treats agent guidance like a product with feedback loops. It has scenarios. It has regressions. It has confidence levels. It has boring CI machinery. It has the wonderful humility of admitting that the first version of the rule was probably not precise enough.
This is also why I do not love the phrase "prompt engineering" for this kind of work. It makes the job sound like word magic.
This is closer to test engineering plus platform engineering plus documentation, all wearing one coat and pretending to be a simple markdown file.
local truth beats internet-shaped wisdom
The internet is full of examples. That is useful until the examples disagree with your production reality.
For a database service, the difference between "valid code" and "good code" is often service-specific:
- which partition key keeps the workload sane
- which query shape avoids a surprise bill
- which SDK pattern prevents connection churn
- which index definition survives real data volume
- which serialization setting matches the query examples
- which emulator behavior differs from the cloud service
- which retry pattern is safe and which one creates a small denial-of-service attack against your own account
The model can infer some of this from public code and docs.
But production systems are built out of details. Details have versions. Details have defaults. Details have "we changed that in June because customers kept doing the expensive thing."
That is why agent kits are going to become a normal part of serious developer platforms. Not only public cloud platforms. Internal ones too.
If your company has a golden path for services, your agents need it in machine-usable form. If your database team has five rules that prevent most bad schemas, your agents need those rules. If your SRE team has a runbook pattern for background workers, your agents need that pattern before they generate the fifth queue consumer that handles retries like a slot machine.
Otherwise the agent will use internet-shaped wisdom.
Internet-shaped wisdom is fine for a demo.
It is less fine when the monthly bill arrives wearing a little hat.
docs become something you can regress
Once guidance is executable enough for an agent to consume, it becomes something you can test.
That changes the maintenance model.
Old docs rot quietly. A page gets stale. A screenshot is wrong. A CLI flag changes. A best practice becomes a trap. Humans work around it because humans are excellent at muttering "this is outdated" and continuing anyway.
Agents are less graceful. They will follow stale instructions with the confidence of a project manager saying "quick sync."
So the documentation needs a regression suite.
That sounds absurd until you look at what the Cosmos DB team did. They did not merely update prose. They ran scenarios repeatedly, checked generated applications, and measured whether the rules actually improved outcomes.
This is where I think many internal platforms will end up.
The "docs" repo will not only contain markdown pages. It will contain:
- agent instructions
- example tasks
- expected generated artifacts
- validation scripts
- evaluation reports
- known failure cases
- rules tied to platform versions
Some teams will hate this because it makes documentation feel heavier.
Fair.
But the alternative is worse: agents generating code from outdated tribal knowledge at machine speed.
I will take the boring regression suite, thanks.
this is also a maintainer protection mechanism
There is another benefit here that is less glamorous but maybe more important.
Good agent rules protect maintainers.
If agents keep generating the same broken Cosmos DB query shape, someone has to review that code. Someone has to explain the problem. Someone has to request changes. Someone has to link the same doc again, with the emotional energy of a person who has become a human redirect rule.
Multiply that by every framework, every internal service template, every compliance rule, every "we do not do it that way here" convention.
That review load is real.
Turning repeated review feedback into tested agent guidance is one of the few ways to make AI coding scale without dumping the cleanup work on senior engineers.
This is also why the best rules will come from actual failures, not brainstorming sessions.
Do not start by asking, "what should the agent know?"
Start by asking:
- what mistakes did we correct in review last month?
- what generated code passed tests but failed later?
- what examples keep being copied wrong?
- what service-specific behavior surprises new developers?
- what expensive defaults need to be avoided?
- what should never be changed without a human?
That is the good material.
That is where the guardrails live.
the punchline
Azure Cosmos DB Agent Kit is interesting because it points at a future where developer documentation is not just text for humans.
It becomes executable guidance for agents.
It gets tested. It gets versioned. It gets measured against real tasks. It accumulates hard-won product knowledge in a form that can change generated code before a reviewer has to sigh at it.
This does not remove the human from the loop. Sorry. The human is still very much in the loop, probably with coffee and a suspicious look at the generated repository class.
But it moves some repeated judgment earlier.
That is the useful part.
Not "AI will read the docs."
More like: the docs will finally have to prove they work.
And if that sounds like extra work, yes.
Welcome to software.
references
To test my projects, I use Railway. If you want $20 USD to get started, use this link.
Top comments (0)