I've been using Cursor and Claude Code for a few months now, and somewhere around week six I noticed something weird. The tools got faster, the models got smarter, but my output didn't improve at the same rate. I'd feed a vague prompt like "refactor this auth flow" and get back something plausible but misshapen, then spend twenty minutes arguing with the agent. The bottleneck wasn't the AI. It was the input I was giving it.
So I tried something a little unhinged: I started writing actual documentation before opening Cursor. Not specs for a human reviewer, just Mermaid diagrams, table layouts, endpoint contracts, the kind of thing that would normally live in a README nobody reads. I told myself if it felt like overkill I'd stop. A few weeks in, the diff between my AI-generated code and the human-written code on our older branches got noticeably smaller. Honestly, I haven't measured this properly with any kind of controlled test, so take it with a grain of salt, but the trend is hard to argue with.
The trick that worked for me was treating the doc itself as the prompt. When I dump a rough ER diagram and three API shapes into Cursor's composer, it doesn't just pattern-match on the words, it seems to hold the relationships in mind across the whole file. The opposite happens when I just chat: Cursor happily writes a beautiful model and then forgets the column I mentioned in the previous turn, so I end up with a foreign key pointing at nothing. Same story with Claude Code, which is supposedly the heavyweight reasoner, but it can't reason about what's not in its context window. Documenting first isn't a silver bullet, more like shifting where you spend your attention, and for a solo dev juggling a small Next.js side project it has saved me probably a couple of hours a week, though I haven't clocked it.
Worth trying if you're already paying for Cursor or Claude Code and feel like the tools have stopped paying off. The other thing I haven't figured out is when not to bother, small bug fixes and one-file tweaks still feel faster with a sloppy prompt. Anyway, write the doc first, then let the model chew on it. It won't make you ten times faster, but it might make AI-generated code stop feeling like a coin flip.
