It's a huge mistake to start building with Claude without mapping out a project in detail first, by hand. I built a pretty complex device orchestration server + agent recently, and before I set Claude to actually coding I had ~3000 lines of detailed design specs across 7 files that laid out how and what each part of the application would do.
I didn't have to review the code for understanding what Claude did, I reviewed it for verifying that it did what it had been told.
It's also nuts to me that he had to go back in later to build in tests and validation. The second there is an input able to be processed, you bet I have tests covering it. The second a UI is being rendered, I have Playwright taking screenshots (or gtksnapshot for my linux desktop tools).
I think people who are seeing issues at the integration phase of building complex apps are having that happen because they're not keeping the limited context in mind, and preempting those issues by telling their tools exactly how to bridge those gaps themselves.
> It's a huge mistake to start building with Claude without mapping out a project in detail first, by hand.
I agree with you in theory but in my opinion, it doesn't work so well when you don't even know what exactly you are looking for at the start. Yes I knew I wanted a formatter, linter, parse but which language should those be written in, should they be one project or many, how the pieces should fit together, none of that was clear to me.
As I pointed out in the article, in these sort of "greenfield projects" I work a lot better with concrete prototypes and code in front of me I can dissect instead of trying to endlessly play with designs in my head.
> It's also nuts to me that he had to go back in later to build in tests and validation.
I think this is a little misleading. Yes I did do some testing retroactively (i.e. the upstream validation testing) but I was using TDD + verifying outputs immediately, even during the vibe coding phase. The problem as I point out is that this is not enough. Even when I had unit tests written at the same time as they code, they had lots of holes and over time, I kept hitting SQL statements which failed which the testing did not cover.
> in these sort of "greenfield projects" I work a lot better with concrete prototypes and code in front of me I can dissect instead of trying to endlessly play with designs in my head
I'd really recommend separating prototyping work like that out into a pre-design phase. Do the prototypes and figure out the direction for the actual project, but then come back in with a clean repo and design docs built off the prototypes, for claude to work from. I started out using claude to refactor my old projects (or even my codex ones) before I realized it worked better starting fresh.
I think sometimes it silently decides that certain pieces of code or design are absolute constraints, and won't actually remove or change them unless you explicitly tell it to. Usually I run into this towards the end of implementation, when I'll see something I don't expect to and have to tell it to rip it out.
One example recently was an entire messaging queue (nats jetstream) docker image definition that was sitting in the deploy files unused, but claude didn't ever mention or care about it as it worked on those files; it just silently left it sitting there.
Another example was an auth-bypass setting I built in for local testing during prototyping, being not just left alone by Claude but actually propagated into other areas of the application (e.g. API) without asking.
Do you write anywhere else?
Really enjoy your style.
Thank you! Not anywhere but forums. I used to have a blog, but I haven't posted anything in years.