Agentic programming, but more specifically Claude Code, has changed my life.

Specs file

Like “everyone”, I vibe-code a bit for small tools or parts of programs that don’t require a lot of thought, but what I mostly do is discuss with the model.

If it’s something that requires some extensive research, I use Claude (web) to discover the state of the art around the topic. But for most features, I skip this part.

What I always do now is:

  1. Write a spec file in spec/$YYYY-MM-DD-$FEATURE_NAME.md : Sometimes it’s 2 lines, sometimes it’s 40 lines with some examples.
  2. Ask Claude to update it to make it clearer, to make sure we understand each other
  3. Edit it and sometimes come back to step 2
  4. Ask Claude to update it to make it ready to be implemented
  5. Edit it and sometimes come back to step 4. This part is crucial and the most difficult one. Because there’s a lot of things to read and this is where you might find misunderstandings. I usually ask Claude to modify the spec to make the changes I want without having to edit them again.
  6. Then I ask Claude to implement it and test it.

Once the specs are implemented, I move them into a specs/past folder to make sure it doesn’t clutter my context.

MCP? Not so much

I started to use MCP a lot at some point but I realized it makes the model dumb because of the amount of context it uses. And it’s not very natural as you don’t really know how they work.

I found it to be much more straightforward to use a CLI. At stonal, we have a CLI (stn) that helps us handle lots of tasks regarding deployment. Allowing Claude Code to use it was just a matter of telling it “discover the stn CLI”. It then sends a series of --help commands.

As you can guess, if it works with tools it has never heard of, it works for pretty much anything. Handling JIRA issues through the JIRA CLI is a breeze.

Agent documentation

I keep agent_docs/ files as concise as possible to describe the overall architecture of the code. This can be:

  • Code Architecture / REST APIs / SQL conventions
  • CLI tools
  • Business logic rules
  • Entities in-depth documentation

Target audience

I feel like I’m the perfect target for Claude Code. Because as a tech manager, I’m used to having to write and review a lot of specifications around various topics. And I’m used to having to deal with the consequences of misalignments/misunderstandings.

Not just code

What I just wrote doesn’t just apply to code, it works for pretty much anything that is written. Here are some sample use cases I’ve found it to work quite gracefully:

  • Writing blog posts
  • Writing documentation around code
  • Writing OpenAPI or JSON Schema specifications
  • Setting up and upgrading the CI/CD infrastructure of your server
  • Testing and optimizing SQL queries on live servers
  • Deploying Kubernetes components
  • Diagnosing (Linux or even Windows by installing Claude Code on them) servers and Kubernetes pods

It makes the tech world better

Maintaining up-to-date documentation, creating programs that have a good UX (whether it’s a CLI, a web interface, or a mobile app), building the CI/CD, updating dependencies, testing code, takes a lot of time and effort. By handling all these little tasks, you can focus on the big ones.

Bad ways to use it

  • Don’t write full specs from scratch: It often writes low-quality specs with lots of useless but good-looking sentences.
  • Don’t make it write code you wouldn’t be able to write yourself and possibly don’t understand: It’s very hard to diagnose and fix afterwards.