like with most agentic dev I do these days, I go between "I need this" to "I used to need this when humans were involved but is it just vestigial" a lot. In this case, why am I documenting at all if the agent is pretty good at understanding things quickly via the context and indexes it creates from the code itself.

...on the other hand... since we still have humans using the features and interacting with them, knowing what is going on and why it made a decisions (for better or worst) doesn't seem like something to let go of.

I approach this by always asking Opus to send an agent to explore and trace how a pipeline works. Even better if I have an integration test. Once it's fully mapped out I might ask it to dump everything it discovered on a markdown doc, clear the context and start the task. The docs folder keeps the information intact for future development.

Managing context is by far the most important skill to be effective with LLMS, in addition to having already existing clean code on the codebase.

As they read your files, you are one shot training the LLM in how to write code and how you structure it and it will adapt. With clean codebases, I found the LLMs were outputting well documented, well logged, and even tested functions by default because the other files it interacted with were like this, 'it learns'.

Additionally you have to think how they train and evaluate the model, there are so many use cases to cover, I'm pretty sure in the Reinforcement Learning part they are not going in huge long threads, but are actually benchmarking and optimizing from fresh context starts, and you should do that as much as possible in your tasks.