Comment by hombre_fatal | Hacker News Reader

Comment by hombre_fatal | Hacker News Reader

Parent Full thread

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.

Reply on news.ycombinator.com