cross-posted from: https://programming.dev/post/51247328

I use speckit, and while I like the spec/clarify/plan/task/analyze/implement loop (although it can get a bit overwhelming at times), I don't like that I have to start with writing a spec and implement it to begin with. I am looking for a more of a design phase before the spec phase, where I can talk about the overall application architecture, and then start writing specs for implementing pieces of it.

For instance, let's say I want to build a github repo provisioner that 1. creates repos with desired setup, and 2. bulk edit repos with secret updates, yaml updates, etc. I don't want to build both the features at the beginning. I want to first build only the create portion, and then do the bulk edit feature later on. With speckit, I can do this by only telling it to create the spec for the build portion, but later if I want to build the bulk edit portion, the whole application might need to be changed in important places, because it wasn't a 'planned' feature when it was first designed. I want instead to have a design phase where I describe and maintain a doc with the whole application, and when I start the spec for the create portion, the agent can understand that this create portion is only part of a bigger application and can design/implement the create portion accordingly.

Have you come across a situation like this? how do you handle your big applications? Please advise.

[Speckit] For decades, code has been king — specifications were just scaffolding we built and discarded

WTF? New devs seem to forget that, for decades, the waterfall style of coding was all about writing specs for months before any code was written.

how do you handle your big applications?

What is "big" to you? I don't think a 20 years old application that has 100 millions of lines of code can be vibe-coded like that.

In Kiro that sort of thing would go in project steering, rather than a specific task/feature spec.

I have been building a system, it's hitting 2m lines of code soon (backend + frontend).

Currently, I have landed in a flow where I maintain a roadmap of releases. Each release is a featureset that I can test, verify, and demo. Most releases are planned through a PRD document which contains user stories, other constraints, and implementation phases. Then, I create as many ADRs and TDs as necessary.

Tbh, all these are for me to keep track of what I am building. I am having agents write the bulk of these documents by rumbling to a microphone for a good deal of time and then reviewing ruthlessly. You have much more control over small and steady increments.

When I feel adequetly prepared, I start coding, most of the time I will lay the foundation and then have agents fill in the implementations.

I don't really worry about future proofing my architecture. It's not like I have a massive database that will take multiple days to create an index, most of the changes are cheap.

Nothing of the above is new, they are well established tools mostly used by larger organizations, the only thing that changes with AI is the scale in which you can use them.

The above apply only fo projects I am serious with (2 projects atm), the rest I just ask AI to build what I need and send it the bugs until it works as expected.

Big as in an application with more than one scope. Yeah don't go by their marketing material. I hate the agentic coding trend, but I'm not losing my job by not being able to adopt to it. I already have a reputation of AI hater in my company lol.

Is kiro platform agnostic, or tied into AWS? I'll check that out, thanks

Its very tightly coupled to AWS. I mention it merely because I'm not familiar with the tool you mentioned. Probably they all have similar functionality and techniques with different naming.

I've not used speckit and likely reinventing the bicycle, but here's my process.

Idea.md in the root with a pitch of the system
Readme.md in the root with technical information

Then I'm using moth (https://github.com/tailoredshapes/moth) to file ideas and track tasks. Those files are definitely not full specs, just several lines of the core of the issue.

Then I have a command /moth that instructs to read current moth, brainstorm design with me and when agreed, implement. Also as the agent works it should keep an up to date spec under ./spec describing the scope (explicitly no code details) as it evolves, decisions taken and rejected (adr like).
It underscores that the task is only done when I say so.
Superpowers skill is essential here.

Then there's the back and forth on development and testing.

Eventually another command /moth-done that instructs to run the full test suite and mark moth as done.

So the essence is that I don't expect to know the full specification beforehand, but I keep track of decisions and expect to refactor often and aggressively. Conveniently writing tests is now easy and I have plenty of both unit and e2e.

That's an interesting approach! I'll look into moth, thank you!

I'd be a bit careful with the assumption that a good enough overarching doc stops the create feature getting rewritten when bulk-edit turns up. In my experience it usually doesn't. Trying to design the whole thing up front so the later feature drops in cleanly is the old big-design-up-front problem, you end up guessing about the part you haven't built. souperk and doo are right that it's cheaper to expect the refactor and keep the steps small.

What the doc is genuinely useful for is the boundaries. Write down what the create part is allowed to depend on and hold it to that. If create only ever goes through a repo abstraction and never reaches into provisioning internals it doesn't need, then bulk-edit comes in as a new module against the same boundary instead of a rewrite. When you do find the second feature forcing changes deep in the first, that's nearly always the first one having coupled to something it never needed, and no amount of spec detail up front would have caught it. So I'd keep the design phase you're after, just spend it on those boundaries rather than trying to predict the features you haven't specced.

I wrote the boundaries idea up here if it's any use: https://prickles.org/tenet/bounded-contexts/A6

Wow, this is really interesting! Thanks for the insights, and the write up!