ProtoNodeLabs Claude Workflow

This is the AI-assisted development workflow used at ProtoNodeLabs. It's built around Claude Code and a persistent second brain (ClaudeBrain) that gives Claude long-term context across sessions and machines.

We're sharing it because the pattern is genuinely useful and we think others should steal it.

---

What's in here

Path	What it is
CLAUDE.md.template	Global Claude Code configuration — the persistent system prompt for every session
claudebrain/	Folder structure + example files for your persistent knowledge vault
machine-setup/	Service auth checklist and dev workspace layout for a fresh machine

---

How it works

Claude Code reads ~/.claude/CLAUDE.md at the start of every session. That file is the persistent system prompt — it tells Claude who you are, how you work, what services are configured, and how to behave. Combined with ClaudeBrain (a private git repo of markdown files), Claude has context that survives across sessions and machines.

~/.claude/CLAUDE.md          ← global config (this template)
~/ClaudeBrain/               ← persistent knowledge vault (private git repo)
  brain/                     ← North Star, Key Decisions, Patterns, Gotchas
  dev/
    decisions/               ← architectural decisions
    projects/                ← per-project status files
    session-logs/            ← what happened each session
  inbox/                     ← quick captures, triaged at wrap-up

Claude is the sole interface to ClaudeBrain — no app, no dashboard. You ask it to surface, search, or write to it. It commits and pushes at session end.

---

Quick start

1. Copy CLAUDE.md.template → ~/.claude/CLAUDE.md
2. Replace all YOUR_* placeholders with your actual values
3. Delete sections that don't apply to your stack
4. Create a private repo named claudebrain, clone it to ~/ClaudeBrain
5. Copy the claudebrain/ folder structure into it
6. Run through machine-setup/auth-checklist.md on a fresh machine
7. Open Claude Code — it reads the config automatically

---

Config scope levels

The CLAUDE.md system supports multiple scope levels. More specific files override more general ones:

~/.claude/CLAUDE.md                     ← global (all projects, all machines)
~/dev-workspace/CLAUDE.md              ← workspace-level routing and conventions
~/dev-workspace/projects/CLAUDE.md     ← all projects in this folder
~/dev-workspace/projects/my-app/CLAUDE.md  ← single project

This lets you keep the global config lean while adding project-specific context where needed. See machine-setup/dev-workspace.md for the full layout.

---

Philosophy

• Claude should know your environment — not ask about it every session
• Long-term knowledge lives in ClaudeBrain; CLAUDE.md stays lean
• Every session ends with a wrap-up that commits new knowledge to ClaudeBrain and the project repo
• The config improves over time — /insights runs at session end and self-updates CLAUDE.md
• The more specific you make the config, the better Claude performs

---

Adapting it

Search-replace the YOUR_* placeholders in CLAUDE.md.template, then trim any sections that don't match your stack. The browser dashboard patterns, dev environment gotchas, and session management sections are the most universally applicable. The org/team sections are most useful if you're running a small agency or studio.

---

Built by ProtoNodeLabs. MIT licensed.