Comment by sneak

I write a spec by speaking, not much thought given to grammar and sentence structure. I over-describe concepts, over-describe functionality. A lot of repetition of details and concepts. The audience is not a human. Whisper converts it to text.

Lightly manually edit for speech rec failures.

LLM takes that and converts it into a much much denser, much more structured technical spec in markdown. This is issue 1 in the repo.

I edit this directly extensively, adding detail, removing misconceptions, adding sections with more dictated text.

LLM takes this and further densifies it, closer to an actual implementor’s spec. I carefully note what got added, removed, edited in this step.

I edit this carefully and extensively again. Some removals get added back, some additions get removed. This is the first commit and closes issue 1.

I then have an LLM write an implementation plan and basic project scaffolding. Makefiles, smoke tests, logging, test framework, DI. I edit the plan, and the plan is the second commit. An LLM uses both plus scaffolding plus my repo policy documents (global) to write a README. We’re still single threaded.

An agent files the first n top level implementation tickets. These refer to and sometimes quote any interface contracts in the spec or implementation plan. These usually map 1-to-1 to a module/directory. These sometimes have stub commits to create the module directory and commit interface definitions. Some larger modules have a README in their module directory if their purpose or structure or inputs or outputs are complicated or non-obvious.

Parallel agents write commit level issues that are the task items for each top level implementation ticket. One agent per module.

Then, spawn parallel agents with detailed global instructions, the full spec+plan, and the full readme, and the full code from the module it is working in, plus the issue text. Its output is a single commit on the feature branch and a PR that closes out one feature ticket.

This spawns an adversarial reviewer which has detailed agent instructions as well as our code style guides and repo policies. The scaffolding includes tests and linting and checks. Any failures spawn rework agents until the feature branch is up to snuff.

I review the feature branch diff and merge it, having read the review and rework comments on the PR. I frequently add comments about the implementation (“don’t do x, do y”) and add WIP: back to loop it back for more rework. I don’t see anything that isn’t green, formatted, passes linting, passes tests, and a (dumb) bot thinks is ready to land. Most of the time, it is. Sometimes, it did it the wrong way and I correct it.

The more modular the code, the easier it is to parallelize (obviously). It is ridiculously easy to build large software quickly now, provided it is sufficiently modular so the implementation doesn’t have to cross modules very much. The detailed spec and implementation plan up front helps a lot with this. It’s a lot like writing multithreaded programs really.

Any bugs discovered are tackled with strict TDD, one commit with a failing test, one bugfix commit that must be green and not touch the test.

Individual modules must conform to good contracts, meet best OOP practices, and fit into context. Too big and they get broken down further. Context size is actually a useful constraint for code structure here.

This workflow, the code standards, the styleguide, the linter settings, the fmt settings (obviously only applicable to non-Go as the Go fmt is not configurable), everything is global and stored in another repo and is vendored into each AI managed project repo. It has a fair bit of “I shouldn’t have to say this, but…” stuff (in the style of “fire codes are written in blood” - each warning sign came from experience).

My results are quite good. It’s as the saying goes, much like managing a team of junior devs. It is easy to end up with a LOT of parallel implementors, reviewers, reworkers, and tons of CI, but it’s still so much vastly cheaper than humans that it doesn’t matter.

Someone will make a LOT of money wringing out the inefficiencies from this workflow, because I think the “agent as replacement for third-world contracted junior dev” model is the one almost everyone is using right now.