logoalt Hacker News

kannanvijayan • today at 8:04 PM • 1 reply • view on HN

I'm similarly working on a complex project and have run into these issues.

There's typically a combination of issues that are occurring when the codebase goes off the rails.

One is that cruft builds up. Large vibecoded codebases need regular "review cleaning". Where you review the whole thing top down for hygiene, contradictions, bad comments, style, redundancy, design. It's a standard thing for me now. A full review and cleanup pass once every couple months.

The second thing that tends to go wrong is that after a certain complexity threshold, the models cannot keep track of the relevant details for a task very well. They lose sense of project directionality. Every task gets disconnected from other tasks and they start pulling the system apart at the seams, exacerbating the cruft issue above and accelerating collapse.

I've found that separating my documentation into three distinct lobes helps: goaling docs, guardrail docs, and implementation docs. Goaling docs describe in prose the goals of the project which includes scope, certain design targets, and other things that you are aiming towards. Guardrails are for design and implementation choices you have explicitly ruled out, the "what not to do" part. Impl docs describe the state of the system as it is.

The top-level agent documents refer to these and make their purpose explicit.

You'd think a ticketing system might capture this, but it doesn't really provide the richness of expression a collection of documents in a directory does.

These approaches aren't perfect. The process still has a tendency to wander off the rails, but it happens less often now and I catch it more quickly. Every session misses little bits of the goaling alignment, but they also find and address small issues missed by previous sessions. Overall it does a better job of keeping the codebase hovering around some threshold of coherency.

I'm having a lot of fun to be honest. Yes it's bizarre and nothing like what development used to be, but it finally feels like there's some new things to learn now.


Replies

kalcode • today at 8:13 PM

Yes! Codebase health review, drift and realignment are big!

These days they know how to handle their own context in review. So I will use that to find improvements too in retrospectivea and a small usage script hook it runs each push that alerts if high token usage. Hint the subagents are getting excessive context, which is also good hint of drift. So then I can measure when it starts happening typically via that script that Claude checks and readjusts when one goes over budget.