Software has long been great at storing, retrieving, and sharing a company’s knowledge. This is most SaaS apps, from Slack to GitHub to Notion.

But as easy as it is to store information, it’s hard to measure its accuracy. Or gauge its importance. Or promptly act on it. Or extract useful observations from an ocean of disorganized crap. Thus, most information goes unused. Heck, most information goes unrecorded.

So it’s been for many years.

Agents on the brain

A big upshot of the past year’s tooling improvements is that more information is worth recording and acting on.

AI-native teams are shifting away from Notion and Google Docs, toward more agent-friendly formats like Markdown for their business’ docs. They’re storing more info in team-accessible locations, and using it to move faster with agents.

A key contributor to the growing hype around this shift is Y Combinator. With the release of gbrain, a number of talks on the topic, and Tom Blomfield’s entry in this summer’s Request for Startups, they’ve turned “company brain” from viral idea to overused buzzword before most people have even heard the term.

While different treatises on the subject will center different goals, the core idea is that companies should make as much information as is practical usable by their team’s agents, because this contributes to positive flywheel effects.

When a company’s decisions, processes, and proprietary info are legible to agents, they can of course help automate things. But they can also route information – leaders and ICs should be able to get the facts they need without going through lossy and slow layers of middle management. And agents fed with enough knowledge to form a “closed loop”, where observation, decision, and outcome are captured, can help run self-improvement – helping you hill-climb measurable aspects of a business.

Now this is all very good in theory, but currently tricky to implement without descending into some mix of dystopia and AI psychosis. As much as spelunking the Claudese docs of GBrain is interesting, it’s a bit early for you to adopt 1M lines of company-brain machinery that evolved to run a startup accelerator (unless, perhaps, you run a competing startup accelerator.)

However, as I’ve worked to build our team’s own post-Notion data bus and repository of truth, I’ve found a few emerging-consensus principles and techniques worth considering, for those of you working to get more use out of agents for non-coding work.

1. Text files, synced with history

Agents are really good at working with folders of text documents, so that’s the default approach. Then, you need a way to sync these documents with your team, track changes, and resolve conflicts, so – big surprise – the nerdy early adopters of this pattern are mostly using git repos.

On one hand, this is kind of silly. Git is a weird sync layer for a system where you’re mostly editing one file at a time, and always want to pull before any view or edit operation, and immediately commit and push your changes. And it doesn’t provide for realtime multiplayer editing, which you want during meetings and the like.

But also, git is simple. And well-understood. And it works.

GBrain has some intense scripts that coordinate its sync engine on top of git, but you can get started by just instructing your AGENTS.md to pull frequently, and to push every change it notices on disk immediately to GitHub – with human edits and agent edits pushed up as separate commits. ¹

One problem working with folders of Markdown documents – synced or not – is that there isn’t AFAIK a great app for browsing these. What you’d want is something where each window shows a folder, with the file structure on the left side and rendered-but-editable Markdown on the right. Given the git backend, you’d also want some hooks to fire pull and push events on open and save, as well as some way to do all this on your phone too.

The closest Mac app for this I’ve found so far is Obsidian². Using git as a backing store can be improved with plugins on Mac, but AFAIK working with git-backed Obsidian on mobile is still rough. You could probably use Obsidian Sync for a small team (max collaborators is currently 20) instead of git, with a different set of pros and cons.

2. Separate maintained truth from source data

A classic failure of documentation is that it can become unclear what is actively maintained and trustable, vs. what was a one-off capture of a discussion, idea, fact, or plan at some point in time. A lack of clarity here is even more disruptive to agents than it is to humans, since the docs are their memory.

It seems most company brain systems formalize this distinction. For our team’s brain repo we distinguish between “point-in-time” docs that were true (e.g. meetings, plans, decisions), and a much smaller set of “evergreen” docs that we continuously review and maintain (e.g. core strategy, policies, who are we building for). GBrain calls its analogous concepts “Timeline” and “Compiled Truth” docs respectively.

3. Rigorously track provenance

Keeping a partially agent-maintained knowledge-and-action system from descending into mush requires discipline about where purported facts were sourced from. If a document was hand-authored by your Founding Engineer yesterday, and today your CTO edited and approved it, that’s probably a reliable document. If Steve had Sonnet 4.5 barf a novel of “load-bearing” analysis that was “quietly” incorrect last fall, that’s probably worse than nothing.

A coherent company memory needs some kind of metadata – e.g. headers in your markdown files – that track document history and state. When was this drafted? Last reviewed? Overhauled? Sanity-checked? Who did so? Is this mostly AI speculation, or is it a specific human’s own thoughts and words?

One useful instruction is to have agents (and humans) ensure they link underlying sources for every claim, and prefer attributed quotes of specific humans over paraphrases. Each transformation of text is usually lossy, so minimizing this (and making claims more auditable) makes the system more stable and clear.

4. Be queryable

The more your agents can fetch, consider, and route your company’s ground truth, the less time your team will need to spend relaying info for one another – and the more you can spend building and solving problems.

This can start with automatically putting your routine internal meetings and Slack decisions³ into point-in-time Markdown docs in your company brain, but you can go way beyond that. Ad campaigns should create an artifact about what was tried and what was measured. Customer feature requests should be documented in a standard queryable format. Signed contracts, lost deals, feature launches, policy decisions, recruiting leads – any interesting event in your org can be recorded and made usable, informing future improvements. Heck, some teams even make their agents’ prompts and traces visible to one another, in real time.

Of course, all of this is easier if you have a transparent company culture. Orgs that can work mostly in the open, avoiding DMs and secret docs except for rare HR or legal issues, are getting leverage out of these tools faster than companies that live in a world of need-to-know. But as the tools evolve, it will get easier to leverage strictly permissioned data too.

5. Automatically improve

While it’s early days, some agentic workflows can now recursively self-improve with supervision. The more mature software factories detect, draft, and land fixes for issues in the software factory itself. GBrain has a complex “dreaming” loop that looks for conflicts, synthesizes reports, and connects items into a knowledge graph. Every product analytics suite from PostHog to Amplitude is now selling a “self-driving” product loop.

For now teams are experimenting and, naturally, not all self-improvement attempts immediately bear fruit. But ultimately, improvement is what we’re all after. This might mean faster decisions, clearer processes, simpler workflows, better products, more leads – if it’s part of your loop and you can measure it, it could be optimized.

And of course, what can be optimized will get over-optimized. At least at first.

Which brings us back to, as always, judgement. All these newfangled brains still need to serve the hearts.

However, the story goes, capitalism doesn’t value quality. Businesses don’t fund software that is lovable. Thus, you need to make a career choice: do you want to be a craftsperson, or do you want to make money?

This dichotomy is nonsense.

I mean, yes, these two things are in some tension. You can easily make money maintaining EOL plumbing if you can motivate yourself to do it well, and you can easily make beautiful products if you can afford to give them away for peanuts.

But there absolutely exist businesses that are very large and successful in part because they invest in quality. Beauty, speed, and user experience can drive profits.

Patrick Collison spoke about this back in 2023:

My intuition is that more of Stripe’s success than one would think is downstream of the fact that people like beautiful things, and for rational reasons. Because what does a beautiful thing tell you?

Well, it tells you the person who made it really cared. And you can observe some superficial details, but probably they didn’t only care about those and did everything else in a very slapdash way. …

If someone really convinced me that the financial returns to craftsmanship and beauty – which I believe are greater – are not greater, I’d still do it. Life’s too short.

So you could try working at Stripe.

Even within Stripe, however, there are products and areas that don’t justify the level of care Patrick describes here. To get a real mandate for quality – to do great work, and earn a good income doing it – you need to ask yourself a question: is there a business case for quality here?

If you want the resources necessary to build something well, then choose to work on things worth doing well.

Things Worth Doing Well

There are a lot of reasons a product could be worth doing exceptionally well. Here are some:

• The product is used often – by many people, many times a week
• The motion is product-led – people self-serve, and refer by word of mouth
• The focus is retention – customers will vote with their feet
• The customers have high LTV – each buyer could grow into a huge account
• The buyers are users – quality impacts the decision-makers themselves
• The users are demanding – developers, designers, and other prosumers

There are many others, but even just the above attributes describe some of the most craft-centric companies out there: Linear, Figma, Stripe, Wealthsimple, Apple, and so on. The economic details vary, but if a large company is spending the surprisingly large amount of resources it takes to build exceptional products, there’s a business reason to do so.

Meanwhile, many of the most slapdash products out there are the inverse of this dynamic: imagine an internal control panel that an enterprise contract obliges you to deliver. A project like that shouldn’t be laboured over – it should be built to a minimum reasonable standard, then shipped. Its primary success factor is to exist.

So if your goal is to work on things that are worth doing well, how do you figure that out a priori? You need to get a sense of the business. Who are the customers, what makes them buy, and what makes them stick around? If you want to build a company that can justify making great stuff, ensure that you’re in a market where quality can confer an advantage.

The analysis is a bit easier if you’re being recruited, since you can simply ask.

Back when I ran Steamclock, occasionally I’d be approached by a prospective client that wanted to make a delightful app (excellent, that’s what Steamclock is all about) but for a use case that seemed… peripheral. Maybe it was an occasional-use product, or perhaps it was an internal tool.

Sometimes it was plainly obvious that hiring an A-Team for the project was overkill, but other times, I’d explicitly ask:

Thinking about what success looks like, how much do UX and quality for this product contribute to the success of the business overall?

Sometimes they’d quickly realize it was a bad fit. But other times, they’d make a compelling economic case for craft and UX – starting us off on the right foot to execute on that vision.

At the end of the day, there are countless ways to make a career building great software. The important thing to remember is that it’s not enough to care deeply about craft. It’s a great start, but if your customers won’t actually reward quality, you’ll be running uphill.

Instead, work on products that have a business case for craft. You’ll have a durable mandate to do great work – and make money doing it.

At the highest level, cross-platform UI technologies prioritize coordinated featurefulness over polished simplicity.

I’ve added a coda to that article about how coding agents actually strengthen the argument for Electron on large teams, at least for now.

The initial release of the new ChatGPT app has been clumsy – there’s a lot of work to do to get Electron ChatGPT (née Codex) as polished as it should be. But, like it or not, cross-platform code is the least-bad way to coordinate a massive team on a rapidly changing product.