One of the challenges I’m facing as a tech lead while building and maintaining any service with AI is keeping live documentation up to date. It is mostly for humans, because more often than not, AI relies on code and points out the drift.
Another challenge is the amount and kind of document artifacts. Generating lots of prose based on code is a maintenance hell and downright dangerous, as outdated docs will mislead.
Ideally, we should try to have the following:
- Required behaviour / specification of the system - quite a broad term, but bear with me.
- C4 context/container diagrams
- C4 component diagrams
- Flow diagrams
I started with an initial AI prompt to build the skeleton of a composite Gradle project for a double-entry ledger. Once the core stack and layout were established, it was time to initialise OpenSpec:
! openspec init --tools claude
Then came some tweaking around the OpenSpec config and the AI agent:
- OpenSpec
config.yaml: says where living docs go and what’s in them (current state only, Mermaid, minimal, link to contracts instead of repeating them). Proposals must have a “Docs impact” section, designs must have diagrams, the last task updates the docs, and archive checks that the docs match the code. - Claude hook: a
PreToolUsehook blocks archiving if the docs listed in “Docs impact” weren’t updated or aren’t linked fromdocs/README.md.
Without the hook, these rules are somewhat of a recommendation for AI, not a must.
Setup done, next was the first API, together with its implementation:
/opsx:explore API for posting a transaction
As the command says, I explored multiple shapes of the API to finally settle on one, then went into more in-depth implementation details, like the table structure in the database, code flow, etc. Each decision was carefully weighed against pros and cons and the future evolution of the system.
Once I was happy with the shape of what was explored, I formally proposed this change. The exploration part is totally optional.
/opsx:propose add-transaction-posting
The AI agent produced a few Markdown files with the specs/requirements for the new feature and tasks. I reviewed them and made some corrections; as always, AI with too much or too little context adds something extra.
/opsx:update add-transaction-posting remove balance after
I repeated the cycle, and once I was happy with the outcome, I finally implemented it.
/opsx:apply add-transaction-posting
At any point, I could already open the PR and send it for review, be it when just the OpenSpec change was created or when the feature was fully implemented and its specs archived.
/opsx:archive add-transaction-posting
That done, the live documentation was also generated, as initially configured, and it needed a review as well.
Conclusion about Spec-Driven Development with AI
What I liked
- It gives structure to the exploration of a feature and to refining it incrementally. Before, I was always creating some kind of document, but it was haphazard in structure and content.
- In between OpenSpec commands, I was free to chat about the design, clarify some aspects, and harden the solution.
- I generated some minimal yet useful docs for the project that are easy to maintain automatically with the current setup.
- It writes scenarios beforehand, and I can validate from a business perspective whether the system will behave as expected.
- It documents the alternative solutions I considered - which is great for cutting short countless future discussions around “why this way?”, “did you consider …?”, etc.
What I liked less
- OpenSpec does not enforce the rules/guides I set; I had to use Claude hooks for that, and iterative review and tweaking to get the desired result.
- Some changes didn’t go through the OpenSpec flow, and thus the spec and live documents drifted again - but it is the duty of the dev to set the guardrails so they don’t.
Notes
- Full repo can be found here
- The live documentation
- The system specification