|
|
|
|
|
|
by kstenerud
36 days ago
|
|
|
> Relevant repos need to be discovered. They have to be set up correctly (some worktrees, most clones), dependencies installed, and the relationships between them made clear, etc.. This is what Sourcegraph and Github Code Search and Zoekt do, isn't it? > You'll have high-level documents you can reference, and they're useful for overviews. But only a tiny fraction of decisions ever make it into them. Most decisions get made in the act of implementing something. Er... In the age of AI the decisions need to be made (and documented) extensively before it starts writing any code. Otherwise you get slop. > But say I'm reviewing their PR. I can ask my agent why the PR ended up the way it did, and every decision they made along the way is in the session. That doesn't make the decision set good. And if the only documentation produced came from the implementation phase, then it's going to be self-defending regardless of how good the design actually is (and your review agent, lacking the context, won't know the difference). Multiply that with the many parallel PRs in parallel repos you get with some features, and that's just asking for trouble. |
|
|
Firstly, I think it's a misunderstanding of where the truth lies. The truth is in the code and in the process that produced it. The code isn't out of date. The written documentation always is (to some degree). It's a map vs. terrain situation. Maps are useful, but they aren't a replacement for the terrain.
On top of that, when I review a coworker's code I also get their session, ready to explore. I ask questions about the decisions they made, and I can interact with their version of the code if something wasn't captured in the session. It's like getting access to their whole environment: the code, the agents' state, and everything else.
You just can't do that with a markdown doc.
This doesn't mean markdown docs aren't useful. They are useful. Maps are useful. But it's simply not the same thing.
Secondly, let's imagine it's possible to document really well every nuance of every decision made. This assumes everyone will do it, so it requires effort from every eng on the team. This is different here cause you get episodic memory without any effort :)