Every time I build anything new, it adds more complexity and the agent only seems to focus on the surrounding code within that session without keeping track of how it fits into the rest of the code base/product.
How do you all deal with this? Any suggestions for improving?
0. Use Opus 5.5 on high.
1. Have in your CLAUDE.md the rule that code changes go together with updates to the docs. For me, that's HTML files in docs/. (Could be .md as well, but for human consumption, HTML is nicer.)
2. Have the rule that only that should go into the docs that an experienced engineer would need to rebuild the system from scratch, ignoring how it would look.
3. Larger work gets a plan doc in docs/plan, i.e. multi-PR work. There is a template how plans look, and an important part of the template is that the last step of the plan is always to delete the plan and fold anything from it that makes sense as long-term documentation into the docs.
4. Have a rule that before creating a PR, a sub agent needs to review the code, and have Codex Sol 6.1 high review it as well. Then let the main agent iterate on their findings until they are happy.
5. Every now and then, ask for an audit of the code. I ask for DRY, YAGNI, and KISS. Let it produce a report. Then let it fix all findings. If a lot, use a plan.
6. If you're adding something straight forward, just ask for it directly. If it's not, ask for a brief first. Review it. Then decide whether to implement in one go or through a plan.
7. Get an ultra plan, so you (mostly) don't have to worry about token usage but can use agents to their full ability.
8. Bonus and plug: Ask your agent to hand over with a demo video. It often finds and fixes issues while recording it, and you're not degraded to the agent's QA team, but it has to put in the work to convince you. I built a UI for directing agents as described: obeya.si. Free, open-source, local.
A stronger version of this would be to make a separate gate. Fail the commit if the new code duplicates something already in a utility function, renames something that already had a name, uses for-loops instead of list comprehensions, whatever is bothering you.
I am currently testing a "too simple" gate. Claude loves to turn everything into helper functions, and if the helper function isn't actually helping (too short, doesn't perform enough actions, etc) the commit gets bounced and Claude gets told why it's wrong and what to do about it.
This has generally kept the worst of things out of the codebase.
1. Experiment and solidify architecture before adding features. I think this is the hardest step for top-down thinkers.
2. Heavy testing and benchmarking. Prefer to TDD as much as possible. The actual lines for my agent-written codebases are generally ~70+% tests, benchmarks, and experiments.
3. Full mutation test coverage after the code is written. Doing this as a human is miserable IMO, but robots make it reasonable. This step resolves SO MANY subtle bugs.
At that point my main role is ensuring alignment with the actual specs.
The trouble comes later when the "experimental features" actually start getting traction and we discover all the holes in our implementation.
By the time we need to "productionize" our experiment, it has already been patched all over the place to account for bugs.
I get a feeling that this is made worse by the fact that since a lot of what we're doing is rapid prototyping, our repo is cluttered with examples of bad code that the agent picks up on and then goes ahead to copy in its own implementation.
I get that we need to clean this up, but it's crazy trying to figure out where to start and what to tackle
> I get that we need to clean this up, but it's crazy trying to figure out where to start and what to tackle
Enumerate, then fix-or-nix all known examples of bad code first. If you clear the path first, you will advance more quickly. It can feel frustrating having to do that, but my experience is that paying off tech debt earlier will prevent hitting the wall at an inopportune time.
Pump out features and iterations as fast as you can until customers are buying your product.
Startups fail because they can’t find customers, not because their code quality is low.
Personally I review most of the code and I do understand the frustration. I'm leveraging https://orca.virtuslab.com to orchestrate an agent to do the development with a few others to review the code; besides this I also put extra reviewers that focus on specific details/patterns which get launched by Orca.
While this isn't perfect, it is the best approach I have got so far.
Recently I wrote a post about this approach: https://alexitc.com/blog/2026-11-02-trading-speed-for-correc...
I don't mind compromising on code quality. The part I don't want to compromise on is product quality. So far the two seem pretty closely tied together - like the more unmaintainable code there is, the more you lose track of the big picture and the worse your product gets, with slightly misaligned definitions of the same concept scattered throughout the code/product resulting in an inconsistent UX.
I'm down to have a state where i never have to look at code and worry about it at all. At this point, I think my issue is the fact that we don't have a super clear spec when we begin, since we're "exploring", and by the time the spec becomes more clear, there's too much bad code/product decisions that the agent is taking into context that ruin the results going forward.
1- Ensure you have Changelogs.md, Agents.md properly written to your likings.
2- Depending on what you are building there is always a way to add actual UI tests and takes screenshots of before and after. If its a related to web UI, you can use playwright and or similar but there is always an option to test UI. Worst case scnerio is when none of libs help you and in those cases, you can add automated tests for UI using computer control from agents and take screenshots.
3- When reviewing PRs, always use a totally different agent. For example if you use claude code for creating PR, then perhaps ask Codex or Cursor to review the PR in depth.
4- Prefer smaller multiple PRs over larger ones.
5- Last resort: If you don't have to review and check PRs yourself, perhaps consider hiring a QA engineer if you can afford one.
Last but not least, learn to freeze the scope and remember not all bugs and edge cases are worth covering.
Once the design is complete, I think the rest is less important. At least that's how I feel.
[0] - https://github.com/con-dog/clingon
Opus 5.5 has made it pretty effortless to get right the first time tbh. Usually it even lays things out better than I was thinking originally
So far, my most successful ventures have been tiny CLIs that do something I have been itching to write that one day when I'd had some free time (that never materialized).
Fixing these is exahusting. What I ended up doing was building a "feedback"[1] tool I can point to my agent.
Basically, I collect bugs/improvements and then tell codex to fix them.
Being able to gather a bunch of bugs in a working session has been a boost in productivity.
[1]. https://pecky.app
Additionally, .NET added a bunch of formatting rules in its static analyzer for .NET 11 that give greater control on the styling of the code the agent generates. For example you can ban `=>` function syntax using editorconfig. The build will fail and the agent has to adjust.
I wonder if there are people around who have stories to share about de-AI-Slopifying a codebase.
And the usual stuff any decent CI pipeline should have: tests, builds, linting, SQL breaking changes and potential heavy migration checks, etc.
It is an abstraction on top of code, turning your codebase into architecture diagrams and then keeping them up to date on each commit.
As a bonus you can do PR review and propose changes in it as well.
If you want to be focus more on quality than speed then software engineering may not be the right domain at this point of time.
LLMs can give you the API calls, and help you figure out how certain libraries work, but they're going to fail spectacularly on quality. I don't see any way around this for the next year or so.
The only positive suggestion I have is to keep the scope of your prompts tightly controlled. Be very, very specific in what you want, avoid wiggle room.