You don't need spec kit or humanlayer per se, though they are good reference points for starting out, but you do need your own CLAUDE/AGENTS, README, ARCHITECTURE, SDRs, policies, research docs and planning docs all nicely organized in files and folders to work well with AI agents.
Particularly in a brownfield development context, using AI to research issues, gaps, bugs, tech debt, reusable patterns etc. as research files is really useful. I find the sweet spot is ~750 lines for each file. Planning files can max out at 1,500 lines if needed or otherwise broken up into individual phases. You can always ask an LLM to create a starter set of docs to get you going and then maintain as you go along.
For the management nerds, none of this is new. See: Writing Effective Use Cases by Alistair Cockburn and Agile Specification-Driven Development by Ostroff, Makalsky and Paige. The fundamentals remain the same and I'd say become even more important in a brownfield context with a high degree of tech debt or complexity. Greenfield is a different story.
What's important with spec driven development is that the LLMs dramatically reduce the cost of both good documentation and good technical specifications. Once you have a good plan and good references, you can build anything with a high degree of accuracy.
I'd add caution about drift. The more documentation you shove into the context, the worse things can get. You can also create a beautiful and perfect functional spec that becomes a swiss cheese of gaps when you create your technical implementation plan. Always check and use different AI models adversarially to ensure you are actually getting the plan you want. Usually ChatGPT can spot Claude's blind spots, for example. And always test manually.
I just looked up what it was and I heard people talk about it. I just realized I was doing something close without realizing it.
Every new project (cloud consulting + app dev), I feed in the contract, transcripts of my discovery sessions, my labeled architecture diagram, transcript of the design review discussion and any other artifacts.
First I have to create Epics and stories anyway for the PMO even if I am working on it by myself.
Then I ask ChatGPT what the phases should be, I tweak it , break it down, give it more details, etc
Finally, I ask it to give me unrendered markdown with the details and a checklist and that’s the starting point of my repo.
As I’m using Codex (I never seem to hit limits with my $20 a month plan) and Claude (better at troubleshooting), I tell them to update my document with what’s done, guidance I’ve given it etc.
I treat both of them like junior devs and keep my hands on the wheel and test and verify each phase.
Yes I know I’m fortunate that all of my work is greenfield -> empty repo and empty AWS account that I ask the client for.
"I want to implement <XYZ oftentime I use the mic and just ramble[0]>.
Please explore the codebase and figure out how things work.
Write down any questions you have.
Then write an implementation plan.
Do all of this in a dedicated markdown file."
The questions are usually 80% useless but those 20% often do point me to stuff I have not considered.
Then I edit the markdown manually or discuss some parts with the agent.
Personally, I still find tools like spec kit give reliably good results in brownfield codebases, but that as I’ve improved my ability to break apart work and describe it, straight prompting has come back as a viable method to perform simple changes.
You don't need spec kit or humanlayer per se, though they are good reference points for starting out, but you do need your own CLAUDE/AGENTS, README, ARCHITECTURE, SDRs, policies, research docs and planning docs all nicely organized in files and folders to work well with AI agents.
Particularly in a brownfield development context, using AI to research issues, gaps, bugs, tech debt, reusable patterns etc. as research files is really useful. I find the sweet spot is ~750 lines for each file. Planning files can max out at 1,500 lines if needed or otherwise broken up into individual phases. You can always ask an LLM to create a starter set of docs to get you going and then maintain as you go along.
For the management nerds, none of this is new. See: Writing Effective Use Cases by Alistair Cockburn and Agile Specification-Driven Development by Ostroff, Makalsky and Paige. The fundamentals remain the same and I'd say become even more important in a brownfield context with a high degree of tech debt or complexity. Greenfield is a different story.
What's important with spec driven development is that the LLMs dramatically reduce the cost of both good documentation and good technical specifications. Once you have a good plan and good references, you can build anything with a high degree of accuracy.
I'd add caution about drift. The more documentation you shove into the context, the worse things can get. You can also create a beautiful and perfect functional spec that becomes a swiss cheese of gaps when you create your technical implementation plan. Always check and use different AI models adversarially to ensure you are actually getting the plan you want. Usually ChatGPT can spot Claude's blind spots, for example. And always test manually.
I just looked up what it was and I heard people talk about it. I just realized I was doing something close without realizing it.
Every new project (cloud consulting + app dev), I feed in the contract, transcripts of my discovery sessions, my labeled architecture diagram, transcript of the design review discussion and any other artifacts.
First I have to create Epics and stories anyway for the PMO even if I am working on it by myself.
Then I ask ChatGPT what the phases should be, I tweak it , break it down, give it more details, etc
Finally, I ask it to give me unrendered markdown with the details and a checklist and that’s the starting point of my repo.
As I’m using Codex (I never seem to hit limits with my $20 a month plan) and Claude (better at troubleshooting), I tell them to update my document with what’s done, guidance I’ve given it etc.
I treat both of them like junior devs and keep my hands on the wheel and test and verify each phase.
Yes I know I’m fortunate that all of my work is greenfield -> empty repo and empty AWS account that I ask the client for.
"I want to implement <XYZ oftentime I use the mic and just ramble[0]>. Please explore the codebase and figure out how things work. Write down any questions you have. Then write an implementation plan. Do all of this in a dedicated markdown file."
The questions are usually 80% useless but those 20% often do point me to stuff I have not considered.
Then I edit the markdown manually or discuss some parts with the agent.
"go ahead and implement"
[0] - https://github.com/cjpais/Handy
It's not one or the other. Those fit in spec driven development already. I have skills that integrate writing and implementing specs.
Personally, I still find tools like spec kit give reliably good results in brownfield codebases, but that as I’ve improved my ability to break apart work and describe it, straight prompting has come back as a viable method to perform simple changes.
I do the same, spec-kit is very helpful for both green/brown field projects.
id there really a development without a spec?
even though u not write it there is still a specification in ur brain when you type the code/prompt right?