Great writeup!! I love the idea of the vector database with everything, including transcripts. Seems like an awesome foundation to improve prompting down the line.
Dex from Humanlayer recently gave a presentation where he argues against using folder-level documentation, as it gets out of date. The solution? Using subagents during the research phase to actually read the code itself, summarizing it into the research report. More like on-demand documentation. I will defer the details to his presentation, as he articulates it better than me. Would love to know your thoughts: https://youtu.be/rmvDxxNubIg?si=sE1Bn9DtO6JNbIvf&t=793
We do that too! The humanlayer guys are big inspirations of some of what we do at nori! We take a slightly different approach than them in that we pull more into the agent than what they do, but overall large amounts of agreement on agentic coding practice
To answer your specific question, we have both docs and the subagents that read the code. We find that the mix is beneficial right now, but its still all very greenfield. I have never really experienced that the docs fall out of sync, and I think that docs convey *intent* more than code ever could. That in turn is extremely helpful for guiding the code reading agents in their research. (Docs also capture invariants at the time they are created, which is extremely useful in large code bases. You can think of docs as a way of creating discrete lines in your code graph that are otherwise hidden but important)
This resonates deeply with my own experience building AI-powered workflows. The "distributed network" mental model is spot on - once you stop thinking of Claude Code as a single assistant and start treating it as a team you're orchestrating, everything changes. I've found that the bottleneck quickly shifts from "can the AI do this" to "can I context-switch fast enough to keep multiple threads productive."
Your point about institutional memory is what I've been obsessing over lately. The transcript database approach is clever - I went a different direction and built persistent memory systems directly into my agent setup, where it updates its own context files after every interaction. The difference is night and day compared to starting fresh each session. It actually remembers that I prefer bullet points over paragraphs, that I hate verbose explanations, and crucially - what it tried yesterday that didn't work.
The TDD insight is underrated. I've noticed the same pattern - giving Claude Code clear success criteria (whether tests, type checks, or even just "deploy this and show me the URL works") dramatically reduces the back-and-forth. It's the difference between "help me build X" and "build X, here's how we'll know it's done."
I've been documenting my own setup where I built a persistent AI agent called Wiz that runs scheduled automations, maintains its own memory across sessions, and routes tasks to specialized sub-agents. Similar philosophy to what you're describing, just taken further into autonomous territory. Wrote about it here if you're curious about the architecture: https://thoughts.jock.pl/p/wiz-personal-ai-agent-claude-code-2026
Great writeup!! I love the idea of the vector database with everything, including transcripts. Seems like an awesome foundation to improve prompting down the line.
Dex from Humanlayer recently gave a presentation where he argues against using folder-level documentation, as it gets out of date. The solution? Using subagents during the research phase to actually read the code itself, summarizing it into the research report. More like on-demand documentation. I will defer the details to his presentation, as he articulates it better than me. Would love to know your thoughts: https://youtu.be/rmvDxxNubIg?si=sE1Bn9DtO6JNbIvf&t=793
We do that too! The humanlayer guys are big inspirations of some of what we do at nori! We take a slightly different approach than them in that we pull more into the agent than what they do, but overall large amounts of agreement on agentic coding practice
To answer your specific question, we have both docs and the subagents that read the code. We find that the mix is beneficial right now, but its still all very greenfield. I have never really experienced that the docs fall out of sync, and I think that docs convey *intent* more than code ever could. That in turn is extremely helpful for guiding the code reading agents in their research. (Docs also capture invariants at the time they are created, which is extremely useful in large code bases. You can think of docs as a way of creating discrete lines in your code graph that are otherwise hidden but important)
This resonates deeply with my own experience building AI-powered workflows. The "distributed network" mental model is spot on - once you stop thinking of Claude Code as a single assistant and start treating it as a team you're orchestrating, everything changes. I've found that the bottleneck quickly shifts from "can the AI do this" to "can I context-switch fast enough to keep multiple threads productive."
Your point about institutional memory is what I've been obsessing over lately. The transcript database approach is clever - I went a different direction and built persistent memory systems directly into my agent setup, where it updates its own context files after every interaction. The difference is night and day compared to starting fresh each session. It actually remembers that I prefer bullet points over paragraphs, that I hate verbose explanations, and crucially - what it tried yesterday that didn't work.
The TDD insight is underrated. I've noticed the same pattern - giving Claude Code clear success criteria (whether tests, type checks, or even just "deploy this and show me the URL works") dramatically reduces the back-and-forth. It's the difference between "help me build X" and "build X, here's how we'll know it's done."
I've been documenting my own setup where I built a persistent AI agent called Wiz that runs scheduled automations, maintains its own memory across sessions, and routes tasks to specialized sub-agents. Similar philosophy to what you're describing, just taken further into autonomous territory. Wrote about it here if you're curious about the architecture: https://thoughts.jock.pl/p/wiz-personal-ai-agent-claude-code-2026