logoalt Hacker News

kannanvijayantoday at 1:00 AM0 repliesview on HN

Yes I've found this to be the case as well. I've also found that it's useful to split these documents into three broad distinguished classes: goals, design, and idioms.

The goal docs provide directionality - helping the agent generally make consistent design decisions. Scoping constraints and stuff are useful to put here, but also feature goals a general idea of where the project is heading long-term (even if none of the items there are on the implementation roadmap anytime soon). It keeps more of the sessions aligned with each other.

The design docs specify the state of the project as it is, and are kept in sync during implementation sessions, by instructing the agents to treat their updates as part of the implementation plan for any work.

The idioms docs keep track of incidental decisions that don't relate to long term goals per se, but things like code style detail, specific project-related investigative techniques, code organization rules, build process guides, etc.

It's a single anecdote but I found that overall the work encountered fewer low-level design mismatches where one session doing work on one thing would make a design decision that didn't really mesh well with another session doing work on another thing. Overall hygiene took less work to maintain.

There are likely a variety of superior ways of organizing things, but at the very least it seems there's a ton of value to be squeezed from just organizing your project meta-information in certain ways. Definitely worth spending some time experimenting with.