The AGENTS.md File Changes Everything
A practical look at AI-assisted .NET development. From empty folder to running Blazor app, without vibe coding.
Recently I sat down with a completely empty folder, a terminal, and a simple idea: a little app for rating books.
No starter template. No pre-built architecture. No existing codebase to fall back on. Just that blank slate feeling every developer knows, where the first decision is somehow always the hardest one.
Where do you even start?
I have been building .NET applications for a long time.
And for most of that time, the answer to that question was the same: crack your knuckles, set up your folder structure, create your base entities, write your first service, and slowly, carefully, build your way up from the ground floor.
It works. It has always worked. But it is slow.
And honestly, a lot of it is repetitive work that does not really require your best thinking.
So this time I tried something different.
I kept the thinking for myself, the architectural decisions, the conventions, the overall structure, and handed the repetitive implementation work to AI.
What happened next genuinely surprised me.
Not because the AI was magic.
It was not.
There were errors. There were decisions I would have made differently. But in about thirty minutes, I had a running Blazor Server app with real architecture, real features, and a codebase I actually understood and owned.
Here is exactly how I did it.
Where we start
No templates. No starter kit. Just a fresh folder called BookRatings and a terminal.
The first step is as simple as it gets:
dotnet new blazorThat gives us a Blazor Server app with all the default scaffolding. Components, pages, the basic layout. Nothing special yet. But from here things get interesting, because before we write a single line of application code, we need to make a decision that most developers skip entirely.
What architecture are we actually using?
Deciding on architecture before writing code
This is where AI-assisted development differs from vibe coding. You don’t just start prompting. You think first.
For this project we go with vertical slice architecture. The idea is simple: instead of organizing code by technical layer (controllers, services, repositories), you organize by feature. Every use case gets its own folder, its own command or query, its own handler, its own response objects. Everything that belongs to a feature lives together.
It scales well. It keeps things focused. And it maps very naturally to how AI generates code, one feature at a time.
But here is the thing. If you just start prompting Claude or Copilot without telling them about your architectural decisions, they will make their own. And you might not like what you get.
So we define things upfront.
Let’s build this together
Would you like to build an app like that together with me? That is exactly what we are going to do in the upcoming live Blazor AI workshop.
Two hours, hands-on, building together from an empty folder to a real deployment. If you are serious about making AI-assisted development part of your workflow, this is the most practical way to get there.
The AGENTS.md file: your AI’s instruction manual
The AGENTS.md file is a markdown file that lives in your project root.
Both Claude and GitHub Copilot can read it, and it acts as a persistent set of instructions for how code in this project should be written.
You can prompt Claude to generate it for you:
“Please create an agents.md file with general instructions on how to implement features. Use vertical slice architecture with feature folders. I want a folder for every entity and then for every use case. Inside the use case folder I want commands, queries, and the corresponding handlers, response objects and so on. Use individual files for everything. Also use dependency injection with interfaces and best practices in general.”
What comes back is a solid starting point. Folder structure conventions, naming rules, how to handle results instead of throwing exceptions, where Blazor components live relative to their feature slice, and more.
This file now travels with your codebase. Every time you or your AI touches this project, the conventions are right there.
Going further with AI skills
Once you have the AGENTS.md file, you can go one step further: AI skills.
Skills are small, focused markdown files that live in a .claude/skills folder. Each skill has a name, a description that acts as the trigger, and a checklist of steps.
The idea is that instead of cramming everything into one big instructions file, which gets read in full every time you prompt and costs you tokens, you split things up into on-demand instructions.
For this project we create two skills.
One for creating a vertical slice, covering the backend side. Command, query, handler, response, all of it.
One for creating the corresponding Blazor Server UI. The page, the component, the wiring.
Now when you want to add a new feature, you can simply say “create a vertical slice for X” and Claude will pick up the right skill, follow the checklist, and generate code that matches your conventions.
This is the setup work that pays off every single time you add a feature. Invest fifteen minutes here, save hours later.
Scaffolding the first feature
With the AGENTS.md and skills in place, open a fresh context window and give Claude its first real task:
“Create a vertical slice for reading a list of books. Also create a simple book entity with ratings included. Use EF Core with an in-memory database and seed some books.”
Watch what happens. Claude reads the AGENTS.md file, picks up the vertical slice skill, and starts scaffolding. It creates:
A
Bookdomain entity with aRatingrelationshipA
ListBooksquery and handlerA response DTO and a
BookListItemDTOA Blazor page that renders the list
A
DbContextwith EF Core in-memory configuredA seed method with a handful of sample books
Is every decision perfect?
No.
In this case Claude generates a repository layer that is not really necessary here since the handler could talk to the DbContext directly. But that is a conversation for your AGENTS.md file (or the skill). Define your preferences once, and the AI will follow them.
The point is: in a few minutes, we have a running list of books rendered in a Blazor page.
From scratch.
Adding the create and rate features
From here we keep going in the same rhythm. One prompt per feature, one vertical slice at a time.
“Implement the create book feature.”
Done. A form, a command, a handler, a redirect back to the list.
“Now also enable adding ratings to books.”
Done. A rate button, a simple form, a command, a handler that adds the rating to the book.
Each time Claude follows the conventions we defined. Each time the output lands in the right folder, with the right structure, with the right naming.
This is what it looks like when AI is working with your architecture instead of inventing its own.
When things go wrong
Here is where things get honest.
When we try to submit a rating, we get an unhandled exception:
“Attempt to update or delete an entity that does not exist in the store.”
A year ago this would have sent most developers straight to Stack Overflow. Now we paste the error into Claude and ask what is going on.
The explanation is actually quite good. In Blazor Server, the DbContext is scoped to the WebSocket circuit, not to individual requests. When you create a book in one operation and then try to add a rating in another, they share the same long-lived DbContext instance. The change tracker carries state between operations, and the in-memory provider gets confused.
The fix is to use IDbContextFactory instead of injecting the DbContext directly, creating a fresh context per operation rather than sharing one across the circuit.
Claude implements the fix. We run the app again. It works.
This is a real lesson worth internalizing.
AI-assisted development does not mean error-free development.
It means you have a very capable debugging partner available at all times. But you still need to understand what is happening. You still need to read the output, review the changes, and know enough to catch the things Claude gets wrong.
That is the line between skilled AI-assisted development and just hoping for the best.
What we ended up with
Starting from nothing, in roughly thirty minutes, we have:
A Blazor Server app with vertical slice architecture
A book entity with ratings
EF Core with an in-memory database and seed data
A list view, a create form, and a rating form
A working AGENTS.md file and two reusable AI skills
A git history with meaningful commits along the way
Is it production-ready?
Not quite.
There are things to clean up: the repository layer, the placement of Blazor pages, a few conventions that could be tightened up in the AGENTS.md file.
But as a foundation it is solid. And more importantly, it is yours. You understand every part of it because you designed the architecture. AI just helped you build it.
Want to go further?
If you want to take this from a local in-memory app all the way to a deployed application on Azure, that is exactly what we cover in the live Blazor AI workshop.
Two hours, hands-on, building together from an empty folder to a real deployment. If you are serious about making AI-assisted development part of your workflow, this is the most practical way to get there.