[visarga]

> This article is far off the mark. The improvement is not in the user-side. You can write docs or have the robot write docs; it will improve performance on your repo, but not “improve” the agent.

No, the idea is to create these improved docs in all your projects, so all your agents get improved as a consequence, but each of them with its own project specific documentation.

[selridge]

But they're not your agents.

[visarga]

You can't improve the agents but you can improve their work environment. Agents gain a few advantages from up to date docs:

1. faster bootstrap and less token usage than trashing around the code base to reconstitute what it does

2. carry context across sessions, if the docs act like a summary of current state, you can just read it at the start and update it at the end of a session

3. hold information you can't derive from studying the code, such as intents, goals, criteria and constraints you faced, an "institutional memory" of the project

[normalocity]

Agree, this is the point the article makes. I don't think the article claims that it's the agent that is directly improved or altered, but that through the process of the agent self-maintaining its environment, then using that improvement to bootstrap its future self or sub-agents, that the agent _performance_ is holistically better.

> ... if the docs act like a summary of current state, you can just read it at the start and update it at the end of a session

Yeah, exactly. The documentation is effectively a compressed version of the code, saving agent context for a good cross-section of (a) the big picture, and (b) the details needed to implement a given change to the system.

Think we're all on the same page here, but maybe framing it differently.