The Claude Code team setup we built so it actually works

We’d spent months learning to work with Claude Code individually, and the team had arrived, without any coordination, at the same conclusions. The next challenge was of a different order: building a Claude Code team setup that worked consistently across the whole organisation, instead of every session starting from scratch.

The moment that became obvious was when one of the engineers asked Claude to review an authentication module. Claude generated executable code that demonstrated how to exploit the vulnerability in production — without anyone explicitly asking for it. That afternoon, I understood that what the team needed was infrastructure.

What we’re documenting here is what we built from there: the architecture of the system, the decisions we walked away from, and the two problems that still don’t have a solution.

Claude didn’t just spot the vulnerability; it also generated the script that exploited it.

FELIPE POLO
CEO Orbitant

Team memory doesn’t fit in a single file

The first CLAUDE.md we dropped into the repository was reasonable: code conventions, common project commands, an architecture description. For individual use, it worked well, but the moment several engineers started working with Claude in parallel, the problem showed up fast. The file grew with no structure, contained instructions that only applied in certain contexts, and the maintenance kept landing on the same two people.

What changed how it worked was splitting the system into three layers with distinct purposes:

• Personal (~/.claude/CLAUDE.md): Each engineer’s individual preferences. Response language, communication style, personal workflow shortcuts. It doesn’t go into the repo: it lives on each person’s machine and isn’t visible to the rest of the team.
• Project (CLAUDE.md at the root): The conventions that apply to the whole team. Architecture, project commands, security rules, patterns Claude has to follow without exception. This file is reviewed in PRs like any other code.
• Conditional rules (.claude/rules/*.md): Instructions that only activate when Claude is working in certain paths. Endpoint validation rules only load if Claude touches app/api/. Test conventions only apply when it’s modifying test files.

Conditional rules solved the underlying problem: a CLAUDE.md longer than 200 lines starts becoming less reliable. Claude loads every file at the start of each session, and long files dilute the focus on what matters. When the file grows too big, that’s not a signal to keep stacking more context in the same place — it’s a signal to split it up.

The second lesson took longer to internalise: when Claude makes a mistake because of missing context, the correction has to end up documented in the right file if it applies to the team. Adjustments made mid-conversation don’t persist across sessions. Two weeks later, the next engineer working on that module will run into the same problem. We have the /memory command wired into our session close ritual for exactly this reason — so this step doesn’t get skipped.

Why a Claude Code team setup changes how you build skills

A skill is a reusable capability defined in a Markdown file that Claude detects and applies automatically when it recognises the context. The official documentation describes what they are and how they work well enough. What isn’t in there is the criteria for deciding when it’s worth building one.

Building a skill takes time: designing it, testing it, keeping it up to date as the workflow changes. That effort only pays off if the process it captures happens often enough and consistently enough. The token cost is the least relevant of the three criteria we use:

1. Is it a process that repeats frequently? If it happens once, it’s not worth investing time in. If it happens several times a week with the same steps, it’s already a candidate.
2. Are there steps where improvisation is expensive? Some workflows have points where variability introduces real risk: closing a development branch, opening a PR, a security review. A skill turns those steps into a protocol Claude follows the same way every time.
3. Does it generate context that would otherwise be lost between sessions? Some skills don’t accelerate execution — they preserve reasoning. The value is in not having to rebuild it in the next session, or explain it to someone who wasn’t in the previous one.

Of all the ones we’ve built, three skills are the ones that have changed how the team works the most: the systematic debugging one, which forces Claude to reproduce the bug and formulate verifiable hypotheses before touching code — without it, Claude tends to make blind changes until something works; the verification before completion one, which forces it to run tests and typecheck before declaring a task done; and the branch close one, which guarantees a narrative order in the commits and a PR opened against the right branch.

The security review I mentioned at the start ended up being a skill too, because it’s exactly the kind of process where the steps matter more than the speed: you have to reproduce the right context, review at the appropriate level of depth, and document the result in a way that’s useful for whoever comes next.

What this setup still doesn’t solve

The system works. And it has two blind spots we’ve been trying to solve for months without success. We mention them because they’re part of the full picture: knowing them before building something similar is worth more than discovering them once the system is already running.

Context across repositories

The CLAUDE.md system works well when everything lives in the same repository. Our stack isn’t structured that way: we have separate services, and Claude has no native way to coordinate context across different repositories in the same session. When a task touches several repos, the engineer has to manage that context manually: opening separate sessions, moving information between them, and keeping things coherent by hand.

We’ve explored several alternatives. All of them add more friction than they remove, whether through configuration complexity, context cost, or simply because the abstraction doesn’t fit how the project is structured. For now, the problem is still open and we manage it with manual discipline rather than architecture.

The grey zone of autonomy

The more you configure the system to let Claude act autonomously, the more important it becomes to define where that autonomy ends. We have auto-approved commands for read and test operations — the ones that are safe by definition — and an explicit deny list for destructive operations. But between those two extremes, there’s a middle zone: database migrations, infrastructure config changes, modifications to deployment files.

In that zone, the line isn’t clear and each engineer draws it differently depending on their experience and their risk tolerance. That produces inconsistencies we haven’t solved systematically. The most honest thing I can say is that Claude Code’s permissions configuration gives you the tools to define that line, but defining it well requires a team agreement we’re still building.

The return comes from knowing the limits too

A system like this doesn’t get built in a few weeks. The one we have today is the result of months of iteration: CLAUDE.md files that broke and had to be redesigned, skills we abandoned because they didn’t fit, workflows that worked locally and failed in production.

What differentiates a team that uses Claude Code from a team that works with Claude Code is exactly this: having a system where the learnings accumulate instead of disappearing. Where, when Claude makes a mistake, there’s an obvious place to save the correction so it doesn’t repeat. Where the limits are explicit before you hit them in production.

The next challenge we’re exploring is how to capture learnings across different projects without contaminating the context of any one of them. We don’t have an answer yet. But identifying precisely where the question lives is already part of the work.

Frequently asked questions

Where do you start if the team has never structured their CLAUDE.md files?
With the /init command in the repository. Claude analyses the existing code and generates an initial CLAUDE.md with the conventions it detects. It’s not the final system, but it’s an honest starting point that beats starting with an empty file or, worse, one imported from another project without adapting it.

How long does it take for a system like this to stabilise?
In our experience, the first three months involve a lot of iteration. The system starts to stabilise when engineers correct Claude and that correction ends up documented naturally, without anyone asking for it. When that happens regularly, the system is working.