Infrastructure for Collective Intelligence

This post describes a layered repo architecture for working with AI on real projects. The approach lets you bootstrap an AI session quickly, scope its context to just what's relevant, capture decisions and changes as you go, and iterate fast. A new contributor — human or AI — can read the Brain, review the design docs, and understand the project without a walkthrough.

The structure is simple: a few Git repos, loaded in order, each one narrowing context for the next. The human navigates. The AI drives. The repos are the map.

brain              → bootstraps the session, knows the landscape
{project}-docs     → design, ADRs, planning for that project
{project}          → the code (site repo)

The Layers

Four layers, each one narrowing context for the next.

The Brain is a private Git repo that bootstraps every AI session. It contains the contributor's working context: environment topology, project notes, playbooks, and daily logs. When the AI loads the Brain, it knows who you are, what you're working on, and how the pieces connect — before you've asked it to do anything.

The Design Docs are a project-level repo that describes what we're building and why. Architecture decisions, product specs, recipe plans, theme documentation, API design, module inventory, devops configuration. Organized by concern, numbered for sequence. The AI reads the relevant sections and understands the project's structure and constraints.

The Code Repos are where implementation lives. In our case, a GitLab group containing separate repos for the Cookbook, Module, Requirements metapackage, and Theme. The AI gets pointed into a specific repo to do a specific task — but only after the Brain and Design Docs have scoped the work.

The Shipped Product is the live site running on the code. The proof that the layers work. Design decisions flow into code, code deploys to production, and the running product validates the architecture.

A Session in Practice

In Claude Code, the Brain loads automatically — no manual step required. The ~/.claude/CLAUDE.md file is read at every session start. We symlink it to the Brain repo so a git pull is all it takes to keep every machine current.

From there, the session looks like this:

1. Pull the Brain and Design Docs. Two git pull commands bring everything current across all machines.
2. Read the Design Docs index. Each project-docs repo has a CLAUDE.md with a lightweight ADR index — topics and statuses, not full content. The AI knows what decisions exist without loading all of them.
3. Point the AI at the Code. Each code repo also has its own CLAUDE.md with repo-specific instructions: build steps, known constraints, release workflow. The AI arrives already scoped.
4. Load specific ADRs on demand. When working in a particular area, read the relevant ADR. Not all 29 — just the one that governs the work at hand.
5. The AI does the work — writes code, runs tests, opens a merge request. A human reviews and merges.

Each step narrows the context. By the time the AI reaches the code, it has what it needs and nothing it doesn't.

How It Wires Together

The Brain's context/CLAUDE.md is the machine-agnostic brief — who you are, priorities, architecture constraints, working style. But a real project spans multiple machines: a laptop, a workstation, a server. Each has different paths and a different role.

We handle this with a machines/ directory inside the Brain repo:

brain/
  context/
    CLAUDE.md          ← machine-agnostic brief
  machines/
    workstation.md     ← ~/.claude/CLAUDE.md symlinks here
    laptop.md
    linode.md          ← server-focused, deploy paths only

Each machine file is thin — just local paths and role — and uses Claude Code's @path import syntax to pull in the shared brief:

# Machine: Workstation

- Projects root: ~/projects/
- DDEV site: ~/projects/rsvp-system/

@../context/CLAUDE.md

~/.claude/CLAUDE.md on each machine is a symlink to its machine file. Pull the Brain repo and every machine gets the updated brief automatically on the next session.

The Design Docs repo follows the same pattern: a CLAUDE.md at the repo root gives the AI a compact ADR index — current highest number, topics, statuses — without loading every document. Individual ADRs get read on demand when work touches their area.

The result is a system where context is always current, always right-sized, and never stale.

Why This Matters

We invest heavily in code architecture — patterns, frameworks, CI pipelines. We invest almost nothing in managing the context that makes the code make sense.

This layered approach treats context as infrastructure. The Brain gives you the map. The Design Docs give you the rules. The Code is the territory. The Shipped Product is the proof.

No new tools. No vendor lock-in. Just markdown files in Git repos, loaded in the right order.