Hacker News Reader

Comment by hombre_fatal | Hacker News Reader

On the other hand, AI is good at following invariants and adversarially policing the system to pay back debt. The latter is too expensive for humans as a project grows.

Right now you can open Claude Code in your project and prompt it "start a workflow that fans out subagents, each with a narrow scope, to look for {simplifications, correctness by construction opportunities, <insert your goal>} ranked by impact vs confidence, and then collate the findings into result.md". If you have the tokens, do more workflows that find more issues and/or vet and polish the findings already in the file.

I do that every time my weekly usage is about the reset to spend me last tokens.

Maintenance is becoming trivial, and anyone who thinks AI dooms you to an ever growing mudball apparently hasn't considered using AI for anything other than appending more code to the mudball.

View on HN

And they're really good at adding more code to reduce complexity. In particular Claude is absolutely bonkers at the moment. I am having trouble taking this seriously especially because you mentioned Claude. Have you looked at anything it's done?

I use Claude model=fable effort=high to write most of my initial plans, especially the hard things like re-architecture.

I recommend putting time into figuring out the "soft infrastructure" of your projects, usually things you've never been arsed to do in your life (like me until this year).

Start with a docs/*.md folder that you link to from AGENTS.md where you can document things that would be important for you, any human, and especially AI to know. Start with a super basic ADR system where you document invariants over time, maybe a single DESIGN.md file that just lists them. Have a references/ directory that shallow clone all of the important deps you use for local agent reference (and tell the agents about them in AGENTS.md). Keep your plan files to higher level things like invariants, decisions, accepted risks, rejected ideas, that way you review the hard stuff, and sota models these days write crazy-good code.

Look at using AI as a skill that you have to learn and develop, not like how we see CSS where it's the technology's fault if we suck at it for life while putting zero effort into developing the skillset.

Or maybe there's some load bearing "make impossible states unrepresentable" platitude in my AGENTS.md I'm overlooking that's responsible for why I have such a great experience with AI and nobody else on HN apparently is.

I have a good experience too.

I do the same as you. I actively want to succeed with it, and therefore put time into making it work, and I have a good experience. As do the other 80+ developers at my company (it is a fintech). Pretty much every commit is written by claude currently, but I have to steer it constantly, and keep tweaking my setup.

I think the difference is probably that some people just don't really like the idea, therefore put in the minimum of effort, see that results are sub-optimal (which they definitely can be), and declare it useless.

Great advice and PoV. One nit: I recommend against the filename "DESIGN.md" for architectural invariants, in light of the emerging use of that filename for UI / design system / CSS tokens (colors, fonts, typography, etc).

See https://designmd.ai/ for examples.

Good point. "decisions.md" is a good starting spot.

The point, of course, is that you need some way to document decisions and pivots and eurekas (including rejected ones) over the lifetime of the project. It's a key part of invariant discovery and then committing to them.

> Or maybe there's some load bearing "make impossible states unrepresentable" platitude in my AGENTS.md I'm overlooking that's responsible for why I have such a great experience with AI and nobody else on HN apparently is.

We can notice that you're describing the work, but not any result that have derived it from it. I can explain to someone how to learn vim and tmux, but the best argument is to explain the benefits of doing so. I can't just say, take two weeks of your time and wait for the results.

I've been on HN seeing all kinds of comments like yours that promote spending more for tools (time and money) but never expand on WHY I should even do that or what's the proven benefits of doing so.

The context here is using AI agents to automate high-quality software development, something that is slow and expensive to do by hand which committed us to suboptimal maximas like "that subsystem is too gnarly and fragile to improve, so we won't" and "we used React Native in the Windows start menu because it's what the developer knew best".

This is the part people often miss: durable context matters more than the prompt. We are maintaining https://github.com/VoltAgent/awesome-design-md, an open-source collection of `DESIGN.md` files for coding agents.

It applies the same idea specifically to visual design, making things like typography, spacing, colors, layouts, and component patterns explicit and reusable. You can use the existing examples as a starting point or contribute your own.

Are they? Because my experience is they’re really, really bad at following them and as context grows they get worse at following them.

I think probably something like 90% of developers are web developers doing some kind of web app that uses some remote API provided by someone else.

This works great as long as you are not doing what the parent comment cautions you to not do: Let agents decide the architecture.

The moment you do that, why even bother producing a result.md? Just let the Bot execute on its findings, you realistically won't be able to judge them anyway.

I've built many things this year letting sota models design the architecture, and they've been well-reasoned about it.

I think what you describe is a lack of harness/infra/process around working with agents on a project. No effort to document ADRs. No effort to document invariants. No effort to design processes that ensure maintainable software even if it were five years ago and only humans were writing the code.

Just because you delegate important decisions to AI doesn't obsolete practices as trivial as maintaining a log of potential issues in your codebase that you'd want to work through, keep track of, and verify.

Reply on news.ycombinator.com