Claude Code Second Brain: What Broke When a Team Wrote to It

A Claude Code second brain is a folder of markdown files with a CLAUDE.md at the root. The CLAUDE.md tells Claude what’s in the folder, where new things go and which rules to follow. Add a few slash commands for the jobs you repeat, like turning a meeting transcript into notes, and you have one. If you already keep an Obsidian vault, the vault is the folder: open Claude Code inside it and write the CLAUDE.md.

That setup works well for one person. Ours stopped being one person’s a while ago. It’s the git repository my company runs on (the full tour), and two founders, a rotating set of teammates and about a dozen scheduled jobs all write into it. This post covers what we added once more than one writer was involved, and the part that still isn’t working.

The one-person version

Start with three things.

A folder layout you can explain in a paragraph. One folder per project or client, raw sources (transcripts, emails, clippings) kept apart from your own notes, and a drafts folder. If you can’t describe the layout in a paragraph, Claude can’t follow it either.

A CLAUDE.md that describes the layout. Claude Code reads it at the start of every session. Put the folder map in it, plus the rules you’d tell a new assistant: raw sources are never edited, drafts go in drafts, file names start with a date.

A few commands. A slash command is a markdown file of instructions in .claude/commands/. Write one for each thing you do weekly. Skip the rest, because commands you write for imagined tasks rot (we deleted 52 of ours).

When you’re the only writer, a misfiled note is one you misfiled, and you remember where it went.

What changed with more writers

Every writer has a slightly different idea of where things go. People do, and so does every Claude session, which picks whatever path looks reasonable at the moment. Scheduled jobs are worse, because they write the same wrong thing every night until someone notices.

In June we audited the repo against the folder layout we’d documented. The layout itself was fine. Nobody was following it consistently. The audit found 186 transcripts sitting loose in the top of references/ folders instead of the transcripts subfolder, more than 1,100 code files with no declared home, and 37% of client engagements missing the PROJECT.md that’s supposed to describe them.

Most of it was historical backlog. So the plan had two parts: a one-time cleanup, and enforcement to keep it clean afterward. Both shipped on June 11.

Folder rules a machine can read

The first piece was writing the layout down twice. STRUCTURE.md is the version people read. structure.toml is the version the tools read, and the tables at the bottom of STRUCTURE.md are regenerated from it by the janitor so the two can’t drift apart.

The rules are specific. A transcript goes in references/transcripts/ and its name starts with the meeting date. Working drafts live in drafts/ and nowhere else. Zips and packaged deliverables go in artifacts/. The repo root has an allowlist of 15 folders, and anything else at the top level is a finding.

When a path legitimately needs to break a rule, it gets an entry in an overrides file with a reason and an expiry, 14 days by default. Exceptions that never expire become the new rules without anyone deciding they should.

A hook that checks every write

Claude Code lets you run a script before any tool call. Ours runs before every file write or edit, checks the target path against structure.toml, and either lets it through, warns with a suggested path, or refuses.

The version before June 11 taught me something. It was a plain text match that blocked every write under references/, because raw sources are supposed to be immutable. The agents in our end-of-day command (/strategy:day-end-process) needed to save new transcripts there, got blocked, and started writing the files with shell commands instead, which the hook didn’t watch. A rule that blocks legitimate work gets routed around, and the routing-around is invisible. The new hook allows creating new files in the right subfolders and only blocks editing existing ones.

The rest of the rules shipped in a two-week “soak” mode, where everything warns and nothing blocks, so we could catch false positives before they stopped anyone’s work. Four months later the mode is still soak. Only the immutability rule actually blocks. It’s an easy way for enforcement to die: nobody turns it off and nobody turns it all the way on, so it settles into a warning people learn to scroll past.

A janitor, and the honest numbers

The third piece is a nightly janitor. It scans the whole repo, regenerates the folder indexes, and moves a misplaced file only when the move is zero-risk: one obvious destination, untouched for 48 hours, committed, and not linked from anywhere. Everything else gets flagged for a maintenance command where a person approves the move.

The deleted-skills post mentions its first big report: 218 findings, zero files moved. Here’s the rest of the curve, from its own pull requests:

• June 13: 191 findings
• July 8: 218
• July 17: 237
• August 6: 252
• Today, scanning a clean copy of main: 245

So the count climbed through the summer and has sat in the high 240s since. The janitor isn’t winning, and the reason is in the breakdown. 165 of the 245 are file names that don’t follow the convention, almost all of them emails and transcripts added in May and June. Some other file in the repo cites 148 of those 165 by name, usually a summary. The janitor’s own safety rule says never move a file something links to, so it won’t touch them. They sit in the human approval queue, and nobody has spent the afternoon working through it. The nightly run also hasn’t opened a pull request since August 6.

The one-time cleanup did work. Loose transcripts went from 186 to 2. Engagements missing a PROJECT.md went from 37% to two engagements. The continuous part is what stalled, because fixing a well-linked file means updating every file that points at it, and that’s still a judgment call we haven’t automated.

Personal memory is the other trap

There’s a second way a personal setup breaks when a team shares it. Claude Code keeps a private memory per user, and it’s easy to let real rules accumulate there. When we started logging company decisions, six of the first ones came straight out of one person’s private memory, including the rule that the AI never sends client email. That rule had been governing one person’s sessions and nobody else’s. Anything a second person depends on has to live in a file everyone’s Claude reads (how we log them now).

Two people processing overlapping inboxes into the same folders creates its own duplicate problem, which took a shared table and some careful keys to fix (that story).

If yours is about to get a second writer

Write the folder rules down before the second person arrives, in a form a script can check. Make every scheduled job name its files correctly at the source, because cleanup after the fact is where our janitor got stuck. Start the hook in warning mode, put a date on the calendar to flip it to blocking, and actually flip it. Keep the janitor’s moves conservative, and budget a person’s time for the queue it can’t clear.

If you want help setting yours up, that’s what coaching is for. A 45-minute session ($99) is enough to build the folder layout, the CLAUDE.md and your first command on your own files, with you doing the typing. If the brain is going to be shared, book the half-day with your team ($599) instead, because the folder rules only hold if everyone who writes to it agreed on them.