GBintz

we've been running AGENTS.md in production on helios (https://github.com/BintzGavin/helios) for a while now.

each role owns specific files. no overlap means zero merge conflicts across 1800+ autonomous PRs. planning happens in `.sys/plans/{role}/` as written contracts before execution starts. time is the mutex.

AGENTS.md defines the vision. agents read the gap between vision and reality, then pull toward it. no manager, no orchestration.

we wrote about it here: https://agnt.one/blog/black-hole-architecture

agents ship features autonomously. 90% of PRs are zero human in the loop. the one pain point is refactors. cross-cutting changes don't map cleanly to single-role ownership

AGENTS.md works when it encodes constraints that eliminate coordination. if it's just a roadmap, it won't help much.

I don't understand the hesitation with existing large codebases. Maybe everything I work on is just easy compared to yall.

It has been unimaginably helpful in getting me up to speed in large existing codebases.

First thing to do in a codebase is to tell it to "analyze the entire codebase and generate md docs in a /llmdocs directory". Do this manually in a loop a few times and try a few different models. They'll build on each other's output.

Chunk embed and index those rather than the code files themselves. Use those for context. Get full code files through tool calls when needed