A system, not a document

Or: My obsession with finding AI ~~~leverage~~~ beyond code.

This is a bit of a professional journal entry, and not exactly a post, please forgive.

The other day I built a customer onboarding playbook for Swarmia, with Claude Code doing the heavy lifting. The whole thing — research, synthesis, structure, a polished PDF with LaTeX typesetting — in an afternoon and evening.

This playbook might not have existed otherwise. The knowledge was there — scattered across Google Docs, slide decks, Notion pages, and the kind of legacy knowledge that lives in people’s heads because nobody ever wrote it down. Everyone knew we needed to pull it together. Nobody had, because the manual cost of gathering all of that, synthesizing it into something coherent, and keeping it maintained always seemed too high.

When I decided to work on this, I thought about opening a doc. Instead, I created a repository — the same kind of structure I’d use for a software project. Not because I wanted to be fancy, but because I needed chapter documents alongside source material, a styleguide, scripts for producing different output formats, and agent definitions that shape Claude’s behavior. Most of my time went to styling the PDF output, not writing content — Claude handled the synthesis.

A Google Doc can’t do that. Neither can a Notion doc.

A repo with Claude Code can.

—

A few days after I shared the first draft, our CS team gave me feedback over Slack. Topics I’d missed, gaps they’d spotted from talking to customers.

An example: Surveys are a key part of Swarmia’s value, and the first draft hadn’t addressed them at all. Eeep! That kind of gap — not a typo or a weak section, but an entire missing topic — is the kind of thing that’s hard to fix in a long document. You have to figure out where it belongs, write it, and make sure it connects to everything around it.

I summarized the CS notes and gave them to Claude Code. In a couple of minutes, Claude had updated multiple existing chapters and created a new one — new content, language aligned across chapters, cross-references added where the new material connected to existing topics. All consistent with the styleguide, all drawing on the source material already in the repo. Doing this in Notion would have taken me significantly longer, and I’d have been less confident nothing fell through the cracks.

The people who actually use the playbook see a Notion page that updates as the repo changes. They don’t need to be anywhere near the system. The system lives in Git; the output meets people where they are.

—

As “simple” as this all feels to me, I have to remember that I can do this without a second thought because I have a background in software engineering. I know how to set up a repo, configure agents, write the instruction files that shape Claude’s behavior, structure information so a tool can reason about it. At Swarmia that’s more normal — we sell an engineering tool, the whole company skews technical. But most organizations? Think about who would benefit most from this approach — the sales team that needs playbooks, the CS team that maintains knowledge bases, the ops team running recurring analyses. They can’t access it. And basic GitHub fluency is actually quite an extreme expectation for those roles.

I also know I’ve created a bus factor. Right now I’m the only person who can maintain this system. That’s fine for a first version, but it’s the same single-point-of-failure problem I’d flag in any engineering architecture. Docs are one thing — and I’ve done my best with them! — but a system needs an owner far more than a Notion page does.

I wrote a few weeks ago about giving non-engineers access to agentic tools. That was about efficiency — doing existing work faster. This is different. The repo as workspace isn’t a more efficient way to do existing work. It’s a different way of working entirely. The gap between “use a chat tool” and “build a system” is wide. Yes, chat tools have memory now — but there’s a difference between a chat remembering what you said last time and a system that knows how a document is organized, what a styleguide requires, what source material exists.

A repo has architecture. A chat history just grows. As of early 2026, the bridges that exist — Anthropic’s Cowork, Google’s Conductor — are moving in this direction, but they’re still closer to “chat that can touch files” than “a system you develop and maintain over time.”

I do think tools will emerge to close this gap — there’s too much value on the other side for it to stay locked behind a terminal forever. To the extent that the implementation is a repo, that will be a detail invisible to users. What’s on the other side isn’t just efficiency, but a different relationship to knowledge work — one where you build and maintain a system rather than produce and forget a document. That’s the part I don’t think chat tools are going to replicate, no matter how good their memory gets.