Comment by luodaint
1 month ago
There is an iterative kind which applies specifically to the code-writing agents. Accepting the output of your coding assistant without checking whether it is correct will cause the loss of knowledge about your codebase. Context files, such as CLAUDE.md, migration protocols, and authentication protocols, function correctly if you possess sufficient knowledge to be able to update them properly.
Sometimes I have had sessions in which I blindly accepted the code produced by the agent for two hours, but afterwards was not able to create a new context file, having forgotten how my codebase worked. Such skill debt does not appear in the diff – it becomes apparent in situations when you must guide the agent, but cannot do it. Such is the nature of the practice proposed by this skill.
Iterative, or recursive?
IMHO, if you're working on large feature changes, before nudging the agent to write any code, it's best to:
1. establish consensus, just in the chat, on the problem domain — i.e. the business-domain problem you're solving (as if the agent is your contact at a software-development contractor, and you're sitting down to pin down what you want from them)
2. co-write with the agent a hierarchical-bullet-pointed design document (this should be an actual .md file, not just in the chat) — letting the agent generate + edit most of this, but nitpicking it thoroughly for problems and decision-vagueness, forcing all design-level decisions to be made up-front here
3. tell it to translate the design spec into a skeleton for a BDD spec test suite, to be populated as it implements
4. let the agent free to actually do the impl — where the agent is free to add/modify/delete unit tests and integration tests and so on, but where it must keep the design-spec file and the structure of the derived BDD spec tests fixed (and, before considering itself done, ensure that A. the BDD spec tests are all fleshed out with proper logic reflecting their labels, and 2. they all pass.)
5. At this point you might be done. But if your project is absolutely huge, you might do another "sprint" at this point, starting again from the top by defining new business requirements, amending the design, getting the agent to add to the BDD suite, etc. (Or, if you want to talk everything out up front, you'd insert a step between 2 and 3 of "breaking the design down into milestones" — where the agent will only create BDD spec items for the current milestone, solve for them, gets approval, and then move onto the next milestone.)
Yes, I'm basically saying you should do waterfall with LLMs. Waterfall can actually be rather pleasant, when the whole process happens over the course of an hour.
And the key point here, for understanding: after the project (or after each milestone for a large project), you can have the agent walk you through the code it wrote, explaining it to you in the chat — with the constraint that it shouldn't bother to explain anything already "implied" by the design.
You can then have it turn this explanation of "the surprising parts" into code comments — and the resulting comments would actually be of the kind humans would write, rather than being pro-forma garbage!