Build a Team OS with Claude Code

Author: Aakash Gupta (featuring Hannah Stulberg) | Published: 2026-04-07

A five-part framework for building a “Team OS” – a shared GitHub repo as a team’s single source of truth, queryable by Claude Code so team members self-serve instead of routing every question through the PM.

1. The Team OS Structure

Problem: The PM is the human router. Every question goes through them. Doesn’t scale.

Solution: One shared repo where every function checks in their work. Everyone self-serves.

Three Components

1. Root CLAUDE.md – loaded every session. Contains exactly three things:

   • Doc index mapping where every type of info lives
   • Team roster with Slack and GitHub handles
   • Key Slack channels mapped to IDs/purposes
   • Keep it under one page

2. Nested doc indexes – every major folder gets its own CLAUDE.md as a navigation map (not content). Enables precise navigation without burning context

3. Folder architecture – three top-level sections:

   • .claude/ for shared agents, commands, skills
   • Product development folders (customers, competitive, PRDs, strategy, analytics, engineering)
   • Team folder (onboarding, retros)

Key insight: Every level of nesting is a context-saving decision.

2. Token Efficiency Framework

Three Failure Modes

1. Flat repo, no CLAUDE.md files – Claude runs expensive explore agents
2. Overstuffed root file – everything loaded every session, kills thinking room
3. Full transcripts instead of summaries – 10,000+ tokens vs 500 for structured summary

3. Scaling Analytics Across Functions

Layer 1: Metrics, Queries, and Schemas

• Organized by product area, then by data type (metrics.md, queries/, schemas/)
• Can connect to Snowflake MCP for live analysis using verified queries

Layer 2: Playbooks and Verified Approaches

• The analyst’s investigation process checked into the repo as a playbook
• Claude follows the same methodology. Critical: analyst must audit the playbooks

Layer 3: Feature Launch Gate

• A feature is not launched until the repo is updated
• Checklist: metric definitions, verified SQL, table schemas, dashboard links, investigation playbooks

4. Writing 10x Docs with Planning

Three Prompting Tiers

Full Planning Process (Five Phases)

1. Load context – Claude reads research, docs, writing guides in parallel
2. Ask user questions – Claude clarifies audience, focus, scope
3. Build plan file – section-by-section structure for review
4. Push your thinking – tell Claude to challenge assumptions
5. Review agent prompts – verify what files each agent will read

Parallel Agents and Temp Files

• Split complex documents across agents, each writing to a temp file
• Orchestrating agent compiles final doc
• Must explicitly prompt Claude to use temp files

Key insight: “Most people under-plan. The plan is not overhead. The plan IS the work.”

5. The Learning Flywheel

1. Automate one task -> free up time
2. Use freed time to learn -> improve your repo
3. Better repo -> more automation possible
4. More automation -> even more time freed

Five Mistakes That Stall Progress

1. Giving up after day one (commit to 30 days)
2. Copying without understanding (can’t fix what you don’t understand)
3. Treating it as a coding tool (most PM time is writing docs, analysis, prototypes)
4. Not clearing between tasks (leftover context pollutes results)
5. Context rot (not updating the repo means Claude uses outdated intel)