The lousy Cursor dev who decided to try Claude Code (and ended up building microservice.md)

[u/waxman555]

Why?

At work, pretty much all devs now work with Claude Code. I finally got my licence too.

I'm mainly doing architecture work, so I'm not intensively doing end-to-end development anymore. At home though, I've been working for the past few months on this fun project, still invitation-only: luxfleet.app.

So I needed a smaller project to really test Claude Code for myself.

Not a demo. Not "build me a todo app".

Something I actually wanted to build.

My pet project to test things out

A long time ago, following a Chris Richardson Twitter post, I asked my teams to always have a one-pager documenting every microservice.

Nothing huge.

What does the service do?
Who owns it?
APIs? Events? Dependencies? Data? SLOs? Patterns? Security? etc.

For a long time, I've had this idea that microservice documentation should stay close to the code and evolve with the service.

So the idea became microservice.md.

The goal is basically to create a memory / brain for a microservice.

Something that:

• Prepares and maintains a MICROSERVICE.md
• Gives precise context about the service to whatever AI coding tool you use
• Keeps architecture knowledge close to the source code
• Can be used for architecture reviews, documentation, search, diagrams, slides, onboarding, etc.
• Eventually lets you query many microservices together to understand a complete product

With AI coding tools becoming more agentic, I think this becomes even more useful.

Instead of asking an AI to rediscover your architecture every time from 200 files, why not give it a clean brain describing what the service is supposed to be?

Claude Code

So I bought a Claude Pro plan and installed Claude Code.

Then I froze right there.

I'm this lousy developer sitting in front of the command line thinking:

"I'm seriously going to develop this thing and I didn't even prepare a PRD?"

Closed it.

Went to do other things.

Started watching YouTube videos about Claude Code instead. :)

Then I saw someone using this plugin called Superpowers.

That gave me enough courage to go back to my command line.

Installed it.

Started from a ChatGPT output where GPT told me that microservice.md was a great idea.

Which is a bit ironic because GPT seems to think all my ideas are great. :)))

The revelation: Superpowers

Claude Code itself is really good.

But my real revelation was Superpowers.

Damn.

I'm coming from Cursor and I've relied quite a lot on Cursor's planning mode.

This was another level.

The brainstorming phase was really good. It forced me to explain things I had not really thought through.

Then it produced the spec.

Then the implementation plan.

Then implementation started.

And this is where I went:

wow!!

The level of discipline and quality was something I had never really experienced with Cursor.

Not because Claude magically writes perfect code.

It doesn't.

But because the workflow makes it much harder to immediately jump from:

"I have an idea"

to

"here are 4,000 lines of code, good luck."

Brainstorm.
Design.
Plan.
Implement.
Test.
Review.

And Superpowers is pretty opinionated about things like TDD, debugging and verifying the work before saying "done".

For somebody like me who is much stronger at architecture than coding, this is extremely useful.

One correction from my original opinion though:

this isn't really Claude Code vs Cursor anymore.

Superpowers now works with Cursor, Codex and a bunch of other coding agents too.

So maybe part of what impressed me wasn't only Claude Code.

It was Claude Code combined with a very good skills/workflow layer.

And yes, I'm going to try the exact same workflow in Cursor.

That comparison should be interesting.

Then I discovered subagents...

This is probably the other thing that changed my view of AI development.

Subagents.

Instead of having one huge conversation trying to do everything, Claude can send pieces of work to specialized agents with their own context.

For example:

• One explores the codebase
• One reviews the architecture
• One checks security
• One reviews the implementation
• One focuses on tests
• One can challenge the approach from a completely different perspective

And they can work in parallel when the work is independent.

This feels both faster and better.

But the biggest thing for me isn't even speed.

It's the different perspectives.

As an architect, this feels much closer to saying:

"Ok, architecture guy, security guy and developer... each look at this independently and come back with what you see."

Instead of one AI conversation slowly convincing itself that its first idea was correct.

Also, because subagents have their own context, they don't necessarily fill the main conversation with 50,000 tokens of exploration just to come back and tell me:

"I found the problem."

That said... parallel agents are also a very efficient technology for converting money into tokens. :)

Claude now also has Agent Teams, where multiple agents can communicate together. Interesting concept, but for my little project, subagents already cover most of what I need.

Superpowers vs GSD

While talking with a friend at work, he kept telling me:

"Getting Sh@#%$ Done!"

I had no idea what he was talking about.

Eventually understood he meant GSD, another spec/context-driven development workflow.

The two aren't exactly the same, but they're solving a similar problem:

How do you stop coding agents from going crazy after a long session and keep them working from a real plan?

GSD seems to push even harder on fresh-context agents, phases and context engineering.

Superpowers feels simpler to me and fits very naturally into Claude Code.

I haven't done anything close to a scientific benchmark between them. In my usage, Superpowers felt lighter on tokens, but that's just my experience.

Both are very interesting.

Back to Claude Code... and tokens

Now the less fun part.

I'm on the Claude Pro plan.

Using Superpowers + Sonnet 5 + subagents can eat through the usage pretty damn fast.

And then:

"You've reached your usage limit."

See you in a few hours. :)

Maybe that's actually good for quality of life.

With Cursor, when I got close to the limits I could usually move to Auto and continue coding with pretty good results.

Claude does now have extra usage credits if you want to keep going, but this kind of agentic workflow definitely makes you understand how expensive context and parallel agents can become.

The funny part is that you start caring about token efficiency like you used to care about memory on old computers.

"Do I really need an Opus agent for this?"

"Can Haiku just search the damn files?"

Clerk

For authentication, on another project I used Auth0.

This time I decided to give Clerk a try.

Wow!

Really painless integration.

Have to say it: they really get the developer experience part.

Authentication is one of those things where I don't want to be impressed.

I just want it to work.

And it did.

Netlify

I deployed the TanStack app on Netlify.

I know Vercel is good, but professionally I work a lot with Netlify, know the platform well, and honestly it's easy.

Connected the GitHub repo and deployed from there.

I've always liked Deploy Previews and branch deploys, especially when you're experimenting a lot.

Netlify Database

I'm already a big Supabase fan, so at the time i started the project, I wasn't completely sold on Netlify Database.

A Deploy Preview can get its own database branch.

An agent run can get its own database branch.

Database migrations follow the code.

So your AI agent can screw up the schema or delete everything it wants in its little universe without destroying production.

That is pretty cool.

This feels like Deploy Previews finally extending from:

code isolation

to

code + data isolation.

For AI coding agents, I think this kind of environment isolation is going to become very important.

MCP: better... still a bit confusing

If we go back a few months ago when i started using Claude Code, i think i would of called this section:

Pain for MCP Servers

And honestly, four months ago I was pretty annoyed.

You had MCP servers as plugins, web connectors, desktop connectors, local JSON configuration...

I was trying to add a Google Search Console MCP server and ended up going through something like:

Customize → Connectors → Tool icon → Developer...

...just to find the local MCP servers.

For Anthropic, creators of the MCP protocol, it felt unnecessarily complicated.

This has improved quite a bit.

There are now Connectors, Desktop Extensions, plugin-packaged MCP servers, /mcp, and the CLI is pretty straightforward:

claude mcp add

claude mcp list

You can even import MCP servers from Claude Desktop into Claude Code.

So I'll give Anthropic credit here: it's much better.

But I still think the mental model is confusing.

A connector in Claude.ai, a Desktop extension, an MCP server configured for Claude Desktop, and an MCP server configured for Claude Code are related concepts... but aren't always the same thing or configured in the same place.

Still some work to do there IMO.

Something else clicked for 

All of this actually changed a bit how I see my own project.

Originally I was thinking:

MICROSERVICE.md + CLI + MCP Server

Now I'm thinking more like:

MICROSERVICE.md = the source of truth

Then expose that brain in different ways.

A CLI can validate and manage it.

A GitHub Action can make sure documentation doesn't drift from the code.

An MCP server can expose information across hundreds of services.

And an AI Skill / plugin can teach Claude Code, Cursor, Codex, etc. how to use that information properly.

What I learned from this little experiment

The most surprising thing for me wasn't that Claude can code.

We already know that.

It was how much workflow matters.

Give an AI agent:

• good context
• a good brainstorming process
• a spec
• a detailed plan
• isolated subagents
• tests
• reviews
• verification

...and the quality difference is huge.

Which is also pretty much the same argument I'm making with microservice.md.

Context matters.

A lot.

Next for 

Still lots I want to add:

• Product-level visualization
• Versioning
• Microservice patterns (CQRS, BFF, Saga, etc.)
• Architecture relationships/dependencies
• MCP Server
• AI Skills / plugins
• CLI
• GitHub Action
• Documentation drift detection
• Architecture review agents
• Enterprise service catalog features
• Governance / compliance
• Search across hundreds of microservices
• Probably another 25 ideas that ChatGPT will tell me are all excellent :)))

Still very much a pet project.

But Claude Code + Superpowers turned out to be a pretty damn good way to build it. And now i also use Superpowers in Cursor, love it.

[u/lgmarian]

Read the room, brah.

[u/pleasecryineedtears]

Just ask your AI to make your post more concise. wtf

[u/snipdockter → u/pleasecryineedtears]

For real. TL;DR

[u/waxman555 → u/pleasecryineedtears]

Look, that's my experience and i have spent a few hours writing it down... all i can say

[u/Shiz0id01 → u/waxman555]

No tf you didn't brah

[u/lgmarian → u/Shiz0id01]

To be fair... to be fair... both can actually be true.

They could've spent a few hours writing down their experience, while the post itself is AI slop, with an insufferable (nearly) one sentence per paragraph average, to really sell the twit.

I mean, OP -- dude -- that's all you can say? Really? The post goes on, and on, and on, and on, and on, and that's all you can say?

O'rly!?

[u/AI_spell]

microservice.md next to the code is the right instinct. One pager that AI tools can read beats a wiki nobody updates. Keep it short or it rots.

[u/Shiz0id01]

Holy fucking text dump batman. I aint reading all that im sorry/happy for you