Claude Code in your workspace: how to roll it out without it collapsing

Claude Code scores 80.8% on SWE-bench and ships with a one-million-token context window. It reads entire codebases, runs shell commands, edits files in place, and chains multi-step tasks through an agent loop. The tool is production-ready. The org rollout is where teams stall.

I ran a Claude Code rollout across a ~50-person fintech earlier this year. Six stakeholders, eighteen repos, six MCP server integrations, role-specific workflows for engineering, marketing, BD, and DevRel. The rollout took three weeks. The structural work — CLAUDE.md files, agents.md standards, MCP wiring, a knowledge canon, two written lists — is what made it land. Without that structure, it would have been one engineer using Claude Code well and everyone else using ChatGPT for the same tasks they always used it for.

Three layers of a Claude Code deployment

A colleague on the engineering team described the architecture cleanly: model at the center, harness around it, business application context around that.

The model and the harness are already built by Anthropic. You install Claude Code with npm install -g @anthropic-ai/claude-code and it works immediately on any codebase. The part that takes weeks and determines whether the org-wide rollout succeeds is the outer ring — the business application context.

Every repo needs a CLAUDE.md. The team needs a shared agents.md standard. MCP servers need to be configured in .mcp.json. A knowledge canon needs to exist so the model has institutional memory. Two lists — what data can never go in a prompt, what actions always need human approval — need to be written down. None of that ships with the tool. All of it has to be built.

What a CLAUDE.md actually contains

Every repo in the rollout gets a CLAUDE.md at the root. Claude Code reads this file automatically on session start. It is the primary mechanism for giving the model context about your codebase.

The convention we established: every CLAUDE.md opens with a communication style directive (typically "be extremely concise and sacrifice grammar for concision"), then an architecture overview, then build/test commands for quick validation, then module structure and route patterns. The file replaces the first twenty minutes of every onboarding conversation where someone asks "how does this repo work?"

Here is what the actual structure looked like across eight repos:

The CLAUDE.md also enforces design principles across every agent session:

"State your assumptions explicitly. If uncertain, ask. If a simpler approach exists, say so. Push back when warranted."

"Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions). If something goes sideways, STOP and re-plan immediately."

"Simplicity First. No Laziness. Find root causes. No temporary fixes. Senior developer standards. Minimal Impact — changes should only touch what's necessary."

These directives apply to every Claude Code session in every repo. Without them, the model defaults to verbose, over-engineered, under-tested output. With them, every session starts from the same baseline that a senior engineer would expect.

The agents.md standard

The agents.md file is the org-level context map. It lives in a central location (we used a shared Google Drive synced to a dedicated canon repo) and tells Claude Code where to find information across the organization.

The master agents.md indexes four data sources, all auto-synced:

Source	Sync cadence
Google Shared Drive (docs, specs, PRDs)	Real-time
GitHub (18 repos, CLAUDE.md + codebase summaries)	Daily
Linear (full org — issues, cycles, projects)	Every 2 hours
Fathom meeting transcripts (per-user)	Every 6 hours

The agents.md gives Claude Code navigation instructions for the whole org: "For codebase context, go to agent-config/codebase/_index.md. For work state, go to agent-config/linear/_index.md. For product specs, go to 50 Product/52 Specs & PRDs/." This transforms Claude Code from a tool that knows one repo into a tool that knows the company.

The canon repo itself is structured by domain:

MCP wiring: six servers in .mcp.json

Claude Code's MCP (Model Context Protocol) integration lets it call external tools during a session. Each tool is a server defined in .mcp.json at the project root. The rollout wired six servers, each serving a different surface of the org's data.

Figma MCP

The Figma server connects via HTTP to mcp.figma.com. Claude Code calls get_design_context with a Figma URL and receives frame layouts, component hierarchies, and design token values. The design-to-code workflow: paste a Figma URL into the Claude Code session, Claude reads the component structure, then reads the existing codebase components, adapts the Figma output to the project's stack (React + Tailwind + shadcn/ui in this case), and implements the component. The Figma MCP eliminates the manual step of translating a design spec into a ticket description that an engineer then re-interprets. Claude reads the source directly.

Google Workspace MCP

This is a local Python MCP server running through uv with OAuth credentials scoped to the org's Google Workspace. It exposes five surfaces: Gmail (search, draft, send), Drive (search files, read documents, create files), Calendar (check schedule, create events), Docs (read and write directly), and Sheets (read data, modify values). For the BD lead, the workflow is: "Pull all email threads with Animoca from the last 30 days and summarize the open items." Claude searches Gmail, extracts the threads, reads any attached Drive documents referenced in the emails, and produces a one-page briefing with key facts, open items, and talking points. For the marketing lead: "Draft a campaign brief based on the brand voice doc in Drive and last quarter's campaign performance in Sheets." Claude reads both sources and generates a draft that follows the established voice guidelines with real performance numbers.

Discord + Slack MCPs

Discord runs via a bot token with read/write access to the org's server. Claude Code can search message history across channels, monitor community conversations for patterns, and post responses. The community management workflow: "What are the top three questions in #support this week?" Claude searches the channel, clusters the messages by topic, and drafts FAQ entries. Slack serves internal comms — Claude reads team threads, posts standup summaries, and operates as a bot that ingests Fathom meeting transcripts and makes them searchable within the team's Slack workspace.

Linear MCP

Linear is built into Claude Code's MCP ecosystem. Claude can create and update issues, track sprint progress, search the full workspace, and manage initiatives and milestones. The sprint management workflow: "What are my overdue tasks?" Claude lists issues, checks statuses, identifies blockers from linked issues, and optionally updates priorities or creates follow-up issues. For engineering leads, Claude reads the current cycle, identifies which PRs map to which Linear issues, and generates a sprint review summary with completion rates and carry-over items.

Internal RAG (the knowledge canon as an MCP server)

The custom RAG server wraps the knowledge canon and a Supabase pgvector instance. It runs as a local Python MCP server and exposes semantic search over the entire org's documentation. The embedding model is text-embedding-3-small (1536 dimensions). Chunks are 500 tokens with 50-token overlap. Retrieval pulls the top 10 from 30 candidates at a similarity threshold of 0.3. Each chunk carries a tier label:

The tier system means Claude Code weights sources appropriately when generating answers. A question about token economics pulls tier-1 verified specs first, then tier-2 internal analysis, and only references tier-3 community sentiment if the first two tiers have insufficient coverage.

Chained workflows: what this looks like in practice

The MCP servers are most powerful when chained together in a single Claude Code session. Each workflow touches 2-4 data sources in sequence without the user switching tools.

Research → Plan → Execute (engineering)

Linear MCP pulls the current issue and its linked spec. Claude reads the spec, reads the relevant codebase via CLAUDE.md context, generates a plan, asks for confirmation, implements the change, runs tests, and updates the Linear issue status. A ticket that previously required reading the spec in Google Docs, switching to the IDE, coding, running tests, and updating Linear manually now runs as a single Claude Code session.

Design → Code (frontend engineering)

Figma MCP reads the component design from a URL. Claude maps the Figma component structure to the project's existing component library. Claude generates the implementation, runs the dev server, and (if a screenshot MCP is wired) validates the output against the Figma frame. The handoff from design to implementation collapses from a multi-day ticket to a single session.

Partner briefing (BD/operations)

Google Workspace MCP searches Drive for partner proposals and agreements, searches Gmail for recent threads with the partner, and Linear MCP checks for partner-related issues and timelines. Claude synthesizes all three sources into a one-page briefing with key facts, open items, and talking points. The BD lead walks into a partner call with a briefing generated fifteen minutes before the meeting from live data across three systems.

Content generation (marketing)

The RAG MCP server searches the knowledge canon for the factual base. Claude reads the brand voice doc from Drive via Google Workspace MCP. Claude generates a draft that follows the voice guidelines and is grounded in verified tier-1 sources. The marketing lead reviews and publishes. Content that previously required a researcher, a writer, and a brand reviewer to touch the draft at three different stages now runs as a single workflow with one human review gate at the end.

Sprint review (engineering lead)

Linear MCP pulls all issues from the current cycle with their statuses and linked PRs. Claude calculates completion rates, identifies carry-over items, reads the Fathom meeting transcript from the last standup via the canon sync, and generates a sprint review document. The engineering lead reviews the generated summary and posts it to Slack via the Slack MCP. A weekly report that used to take 45 minutes of manual aggregation takes five minutes of review.

What the rollout delivered

The structural outcome: every Claude Code session across the org starts with full codebase context (CLAUDE.md), full org context (agents.md + canon), and access to the org's live data via MCP servers. The model produces output that is organizationally correct — right code patterns, right naming conventions, right architecture assumptions, right brand voice — because the application context layer gives it the institutional memory it needs.

The five-phase rollout

Three weeks. Five phases. Each with a concrete output.

Phase 1 — Audit. Survey every person for what AI tools they already use, what data they have pasted in, what their workflow looks like. You will discover ChatGPT accounts you did not know existed and prompts containing customer data you did not authorize. Build one reference implementation — your own Claude Code setup — and document it end-to-end as the template for everyone else.

Phase 2 — Knowledge canon. One repo holding the institutional memory Claude Code needs to be useful. Product docs, architecture decisions, voice guides, customer profiles, runbooks, the Slack threads where someone explained how the billing system works. Auto-sync to a vector DB on PR merge. Without this, Claude Code is generic. With this, it knows your company.

Phase 3 — CLAUDE.md seeding. Every active repo gets a CLAUDE.md. The shared agents.md goes into the canon. MCP servers are configured in .mcp.json for each role's setup. The org-level behavioral contract ("state assumptions, push back, enter plan mode for non-trivial tasks") gets written once and inherited by every repo.

Phase 4 — Leadership deck. Five slides: the gap, the architecture, the rollout, the budget, the ask. Sponsorship is the difference between a rollout that survives the next quarterly priority shuffle and one that does not.

Phase 5 — Rollout. Onboard the highest-leverage non-technical role first — typically the CMO or head of operations. Engineers will adopt Claude Code on their own once they see the CLAUDE.md convention and the MCP wiring. Non-technical teams require direct onboarding with their role-specific MCP configuration and a walkthrough of what the tool can do with their specific data sources.

What went wrong (and what to fix first)

The rollout surfaced five gaps that existed at the start and should have been closed before onboarding anyone:

The agents.md gap is the most damaging. Without it, every Claude Code session starts with zero org context. The agent generates output that is technically correct and organizationally wrong — right code, wrong patterns, wrong naming conventions, wrong architecture assumptions. Seeding agents.md and the per-repo CLAUDE.md files is the single highest-ROI task in the rollout.

Guardrails: the two lists

Two lists need to exist on paper before anyone else opens Claude Code.

Claude Code can execute shell commands, write files, and call MCP tools. The human-in-loop gates listed above are the places where the agent must stop and wait for explicit approval. Without these lists written down, every team member makes their own classification call every time they start a session. Writing the lists is what lets the team move fast on the 80% of work that is safe, because the 20% that requires human review is enumerated.

What I'd do if I were starting tomorrow

Install Claude Code. Write the CLAUDE.md for your most active repo. Seed the agents.md with your org's data sources. Wire one MCP server (Google Workspace is the highest-leverage starting point for non-engineers). Write the two lists. Run the audit. Get the deck in front of the founder. Onboard the CMO.

Three weeks. The structure determines whether Claude Code produces value across the org or stays one engineer's private tool. The tool is already built. The application context is your job.

---

If you are running this rollout and want someone who has done it before to skip you past the gaps listed above, book a call. First call is free.