DEV Community: AI Workspace Builder

Subagents and the iron triangle: when fanning out costs more than it saves

AI Workspace Builder — Tue, 03 Nov 2026 14:02:23 +0000

Spawning subagents is the feature everyone wants to show off. Hand the model a big task, split it into five, run them at once, done in a fifth of the time. On a demo it looks like free speed.

It is not free. It is the old project triangle — speed, cost, quality: pick two — wearing new clothes. Subagents buy you speed. The bill lands on the other two corners, and whether the trade is worth it depends entirely on one property of the work: does it share state.

What fan-out actually costs

Run five agents instead of one and you pay in two places that do not show up until later.

Cost. Each agent carries its own context and burns its own tokens. Five agents reading the same repo is roughly five times the input, not one fifth. For a short task the speed is worth the spend; for a long one you can quietly multiply your bill without multiplying the result.

Quality. This is the corner people miss. Agents running in parallel cannot see each other's work. Each one knows less than a single agent would, because the single agent accumulates everything it learns and the parallel ones each start cold. When their outputs have to fit together, nobody was holding the whole picture.

The line that decides it: shared state

The honest rule is not "subagents good" or "subagents bad." It is:

Fan out for reads. Stay single for writes.

Reads fan out cleanly. Searching a large codebase, running independent reviews from different angles, recon across many sources, summarising a pile of documents — the outputs do not touch each other. Five agents search five areas, you merge five answers. The triangle still charges you cost, but quality holds, because nothing collides. This is where parallel agents genuinely earn their keep.

Writes do not. The moment two agents edit related files, the collisions start. One rewrites a helper the other was depending on. Both touch the same config and the second silently clobbers the first. Commit and signing steps race each other and you end up with unsigned or conflicting commits on the branch. Each agent, missing what the others did, makes a locally sensible change that is globally wrong. We have watched a batch of parallel builders do exactly this — faster to the first commit, slower to a working result, because the time saved up front came back as untangling afterwards.

A missed review is slow. A bad parallel write is wrong, and it reports success while being wrong, which is the more expensive failure.

Encode it where the agent reads it

A mental model only helps if it is written down where the work happens. For a team, that is CLAUDE.md. One rule keeps everyone — human or agent — on the right side of the triangle:

## Fan out for reads, stay single for writes

- Subagents are for read-only work: search, independent review, recon,
  summarising many sources. Their outputs are merged, never written back
  in parallel.
- Build, edit and commit work runs in ONE agent in the main session —
  one change at a time. No parallel writers to shared files or the same
  branch.
- "Do them all" / "in parallel" means sequential in one session, not
  fanned out.

Now "do it in parallel" stops meaning "spawn five writers" and starts meaning "go fast, one thing at a time" — and the next person on the repo reads the same rule you did.

The triangle does not bend

Subagents are a throughput tool for independent reads, not a shortcut for shared-state writes. Fan out to search and review, and you get real speed at a fair price. Fan out to build, and you pay for the speed twice: once in tokens, once in untangling the mess. Pick the two corners you actually want before you spawn.

If your team runs Claude Code, the rule above is one paste into your CLAUDE.md. AI Workspace Builder turns the way your team already works into that file — and the agent configs around it — so decisions like this one live in the repo instead of in one person's head.

How we build AI Workspace Builder with Claude Code

AI Workspace Builder — Tue, 03 Nov 2026 07:08:55 +0000

AI Workspace Builder has no engineering team. It has a Claude Code workspace. Its repository has more than 100 commits since the first one in April 2026, and all but 3 are co-authored by Claude Code: the web app, the sign-in and billing, the generator, the command-line installer and this blog.

That doesn't mean the agent runs the company. It means the decisions, the rules and the review process are written down where the agent reads them. This post shows how that's set up, using our own repository as the example.

Three instruction files, one per area

The repository has three CLAUDE.md files, 325 lines in total:

The root file (115 lines) says what the product is, how the repository is laid out, the tech stack, how to build it, and the business context.
The web app's file covers the Next.js app: its stack, directory structure, authentication model, API routes and key conventions.
The installer's file covers the command-line tool.

Claude Code loads the root file in every session and each folder's file when it works in that folder, so a change to the web app doesn't carry the installer's rules around with it.

The business context is the part most teams leave out, and it changes the agent's decisions more than any coding rule. Our root file lists the gates the product has to pass and the top risks to keep in mind. One of them reads: "never tie architecture solely to CLAUDE.md format; core value is doc reading + structured extraction." An agent that has read that line doesn't hard-code one output format into the generator, even when that would be quicker.

Every change goes through a council

The root file has a section called "Mandatory council review". It says every change, whether a feature, bug fix, refactor or deployment script, goes to role profiles for review before it is implemented:

State the change and why.
Pick the relevant profiles for that kind of change.
Run each profile and record its concerns in its own words.
When profiles disagree, name the trade-off.
A CTO profile reviews everything and approves, modifies or blocks.
Implement only after approval.

Which profiles review depends on the change. A web page gets the frontend engineer and the product designer. Anything touching credentials gets the security analyst and the architect. A pricing change gets the revenue and finance profiles. Every completed build gets QA and a penetration tester. Critical findings block deployment.

Each profile is a folder with a description of the role, a prompt to run it as an agent, and a review checklist. They stay project-neutral; the change being reviewed is filled in each time. This is the same idea we sell: a profile for each role, installed into the workspace.

Nothing is done until it's verified live

The rule that matters most isn't about code. It's that the agent never reports something as done until it has checked the result where users see it.

This week is a good example. Our analytics showed that blog readers were arriving but almost none reached the product: in one week, about 20 visitors read a post, one opened the builder, and nobody clicked the call to action. Every route into the product ended at a sign-up page before the visitor had seen any output.

The change: let visitors fill in the questionnaire and download their CLAUDE.md without an account, with an optional "sign up to save" step afterward. The agent built it and deployed it. Then it opened the live site in a signed-out browser at phone width and walked the whole path: from a blog post, through the questionnaire, to a downloaded file named CLAUDE.md, to the sign-up link, checking that the answers were kept for later. Only then was it reported as done, along with the one part it couldn't test without a real new account.

That last line is the habit we care about most: saying exactly what was verified and what wasn't.

Corrections become rules

When the agent gets something wrong and is corrected, the correction is written down. If the same correction comes up twice, it becomes a standing rule in an instruction file, with a short note on why it exists. Most of the rules in our files started that way: build one change at a time instead of running agents in parallel, never guess a fact that can be checked, measure a fix before calling it fixed.

The rules keep the agent from repeating a mistake. The notes on why keep a future reader from deleting a rule that looks unnecessary.

What a person still does

Decides what to build. The agent proposes; a person picks what matters to customers.
Approves anything that can't be undone. Releases, pricing, anything a customer will see.
Reads the results. The analytics, the review findings, the live site.

The agent supplies the speed. The written workspace carries a person's judgment into every session.

Try it on your own team

The slow part of this was never the agent. It was writing the workspace: the instruction files, the business context, the role profiles. Most teams already have that knowledge in READMEs, onboarding guides and wiki pages.

AI Workspace Builder turns it into a workspace. Upload the docs your team already has, and it generates the CLAUDE.md, a profile for each role, and an install script in 15 to 30 seconds, using your own Anthropic API key. No docs yet? Answer a short questionnaire and download a starter CLAUDE.md, no signup needed.

Claude Code in GitHub Actions: a team setup that stays under control

AI Workspace Builder — Fri, 30 Oct 2026 07:08:23 +0000

Claude Code on a laptop helps one developer. Claude Code in GitHub Actions helps the whole team at once: anyone with write access can mention @claude in an issue or a pull request, and Claude Code works on the repository inside a workflow run, then answers in the thread.

That reach is also why it needs a little more care than a local setup. This post covers how to set it up, who can trigger it, the two ways it runs, and the settings that keep cost and scope under control.

Setup in one command

The quickest path is to open claude in the repository and run:

/install-github-app

Claude Code installs the Claude GitHub App, adds the authentication secret to the repository, pushes a branch with the workflow files you choose and opens GitHub with a pull request ready to create. Merge that pull request and @claude works in the repository.

Two details from the docs worth knowing before you start:

The command works only with github.com repositories. GitLab has its own CI/CD integration.
If you would rather do it by hand, install the app, add an ANTHROPIC_API_KEY secret, and copy examples/claude.yml from the anthropics/claude-code-action repository into .github/workflows/. The docs note that this file is a working workflow, not just an example.

A trimmed version of that workflow looks like this:

name: Claude Code
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
      actions: read
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 1
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

The if line keeps runners from starting on comments that don't mention @claude.

Two modes: mentions and prompts

The action decides how to run from your workflow file:

Interactive mode. With no prompt input, Claude waits for the trigger phrase, @claude by default, in a comment, a review or a new issue, and replies in that issue or pull request. Requests look like "@claude fix the TypeError in the user dashboard component."
Automation mode. With a prompt input, Claude runs on any GitHub event without waiting for a mention, including a schedule. Results go to the workflow run log unless the prompt tells Claude to post and it has a tool that can.

Start with interactive mode. A human asks, Claude answers in the thread, and a human reviews the result. Automated prompts are useful later for recurring jobs, such as a daily summary of commits and open issues, but they run without anyone asking, so add them once the team trusts the setup.

One detail matters for automated runs: with a plain-text prompt, Claude has no shell or GitHub API access until you grant the tools it needs, through --allowedTools in claude_args or a permissions.allow rule in the settings input. That is a good default. Grant what the job needs and nothing more.

Who can trigger a run

The action checks the triggering actor before Claude starts:

Write access. On issue and pull request events, the person who triggered the run must have write access to the repository. A drive-by commenter on a public repository cannot start a run. You can allow specific users without write access with allowed_non_write_users.
Human actor. Bots are rejected unless you list them in allowed_bots, which keeps bots from triggering Claude in a loop.

For most teams the defaults are right. Change them only for a specific, named reason.

The team rules come from CLAUDE.md

In CI there is no developer sitting next to Claude to explain the project's habits. The docs' first best practice is a CLAUDE.md file in the repository root: a Markdown file Claude Code reads at the start of every session, with the code style, review criteria, project rules and preferred patterns. Claude follows it when it opens pull requests and answers requests.

This is where the local setup and the CI setup meet. The same committed file guides a developer's session on their laptop and the @claude run on GitHub, so the answers are consistent wherever the work happens. The docs add one more reason to keep it short: Claude reads it on every run, so a long file costs tokens every time.

Keep cost and scope under control

Each run uses GitHub Actions minutes and API tokens. The docs list the levers:

Write specific @claude requests, so Claude needs fewer turns.
Use issue templates so the context is there up front.
Keep CLAUDE.md concise.
Set --max-turns in claude_args to cap how long a run can go on.
Set workflow-level timeouts so a stuck job ends.
Use GitHub's concurrency controls to limit parallel runs.

A sensible starting point for a team is a turn cap and a timeout on every Claude workflow, so no single request can run far past what the team expects.

Three things that trip teams up

The API key in the wrong place. Never commit an API key or OAuth token. Store it as a GitHub secret and reference it, as in anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}. Grant the workflow only the permissions it needs, and review Claude's changes before merging.

CI not running on Claude's commits. GitHub doesn't start workflows on commits made with the default GITHUB_TOKEN. If your workflow passes github_token: ${{ secrets.GITHUB_TOKEN }} to the action, remove it so the action authenticates as the Claude GitHub App, or pass a custom app token.

Claude not answering. Check that the app is installed, workflows are enabled, the secret is set, the commenter has write access, and the comment says @claude as a whole word, not /claude or @claude-bot.

Where to start

Install it with /install-github-app, keep interactive mode only for the first weeks, add --max-turns and a timeout, and try it on a few small issues: a failing test, a missing validation, a docs fix. Review every pull request it opens like any other.

The quality of those pull requests depends on the CLAUDE.md it reads. AI Workspace Builder generates one from the docs your team already has, along with a profile for each role and an install script, using your own Anthropic API key. No docs yet? Answer a short questionnaire and download a starter CLAUDE.md, no signup needed.

Claude Code subagents for teams: three reviewers worth committing

AI Workspace Builder — Wed, 28 Oct 2026 07:57:34 +0000

Most teams that use Claude Code start with one shared file: a CLAUDE.md with the build commands, the conventions and the things nobody should do. That covers what every session needs. It doesn't cover the specialist jobs, such as reviewing a change against the team's standards, running the test suite until it passes, or checking a diff for leaked secrets.

Those jobs are what subagents are for. This post covers what a subagent is, where a team should keep them, and three worth committing to your repository.

What a subagent is

A subagent is a Markdown file with a short header. The header names it, says when Claude should use it and which tools it may use. The body is its instructions.

---
name: code-reviewer
description: "Reviews changes against this team's conventions. Use proactively after any code change."
tools: Read, Grep, Glob
---

You review code changes in this repository...

The difference from a normal prompt is isolation. In the docs' words, each subagent "runs in its own context window with a custom system prompt, specific tool access, and independent permissions." It does its work, such as reading forty files or a long test log, and hands back only a summary. Your main session stays short and focused.

A subagent still reads your CLAUDE.md files when it starts, so it follows the same team rules as the main session. You don't have to repeat them in every subagent.

Commit them where the team gets them

Subagents live in one of two places:

.claude/agents/ in the repository, for the whole team. The docs recommend checking these into version control "so your team can use and improve them collaboratively."
~/.claude/agents/ in your home folder, for personal ones that follow you across projects.

If both define a subagent with the same name, the project one wins. That is the behavior a team wants: the shared reviewer is the reviewer, and a personal file with the same name doesn't quietly replace it.

Treat changes to .claude/agents/ like code. A subagent with write access and a vague prompt can do as much damage as a bad script, so put the folder under CODEOWNERS and review edits in pull requests.

Limit what each one can do

Without a tools line, a subagent inherits the tools of the main session. For a team file, be explicit. Two fields do the work:

tools is an allowlist. A reviewer that only needs to read gets Read, Grep, Glob, and nothing that edits files.
disallowedTools removes tools from what it would otherwise inherit, for example disallowedTools: Write, Edit for a subagent that should look but never touch.

Read-only reviewers are the safest place to start, as long as the tool list really is read-only. Leave Bash out: with it, "do not edit files" is only a sentence in the prompt, and a command such as sed -i can still change files. Permission modes don't close that gap either. When the main session runs in acceptEdits, auto or bypassPermissions, the docs say the subagent runs in that same mode and the permissionMode in its own file is ignored. If a reviewer needs a few shell commands, such as git diff, keep Bash and add a PreToolUse hook that blocks everything else. The docs show this pattern for a read-only database subagent.

Write descriptions Claude acts on

Claude decides when to delegate from the description field. Write it as a trigger, not a job title. "Security reviewer" says what it is. "Checks a diff for secrets, unsafe queries and missing auth checks. Use proactively before any commit that touches auth or payments" says when to use it.

The docs suggest adding phrases like "use proactively" when you want Claude to delegate without being asked. Keep descriptions short too: they all load into context, and Claude Code warns at startup when the combined descriptions pass 15,000 tokens.

Anyone can also call a subagent by name: "Have the code-reviewer subagent look at my recent changes", or with an @-mention such as @agent-code-reviewer.

Three subagents worth committing

1. A code reviewer that knows your standards. Read-only. Its prompt lists what your team rejects in review: the patterns you moved away from, the error handling you expect, the naming rules. It reads the diff and reports problems with file and line. Human reviewers then spend their time on design rather than on the same five comments.

---
name: code-reviewer
description: Reviews the current diff against this team's conventions. Use proactively after code changes, before a pull request.
tools: Read, Grep, Glob
---

Review the diff the main session passes you. For each problem, give the
file, the line and the rule it breaks. Check: error handling, naming,
tests for new behavior, and anything in the "Things to avoid" section of
CLAUDE.md. Report only. Do not edit files.

2. A test runner that fixes its own failures. This one needs to edit, so it gets the edit tools but a narrow job: run the suite, read the failures, fix the code or the test, and run again until it passes or it's stuck. The long test output stays in its context, not yours. Say in the prompt that it must never delete or skip a failing test to get green.

3. A security check for sensitive paths. Read-only, with a description that names the folders that matter: auth, payments, anything that handles personal data. It looks for secrets in the diff, queries built from user input, missing permission checks and new dependencies. It won't replace a security review, but it catches the obvious mistakes before a human sees them.

Two details that save trouble

Start read-only. A reviewer that reports is useful from day one and can't do harm. Give a subagent edit access only when its job requires it, and keep that job narrow.

One job per subagent. A "full-stack expert" with every tool and a long prompt is just the main session again with less context. Small subagents with sharp descriptions get picked for the right tasks.

Where to start

Look at your last ten review comments. The ones that repeat are your code reviewer's prompt. Write it, keep it read-only, commit it to .claude/agents/, and run it on your next change.

The subagents only work as well as the shared rules underneath them, so the CLAUDE.md comes first. AI Workspace Builder generates one from the docs your team already has, along with a profile for each role and an install script, using your own Anthropic API key. No docs yet? Answer a short questionnaire and download a starter CLAUDE.md, no signup needed.

Claude Code skills for teams: what to move out of CLAUDE.md

AI Workspace Builder — Tue, 27 Oct 2026 11:57:41 +0000

A team's CLAUDE.md tends to grow. Someone adds the release checklist, someone else adds the steps for a database migration, then the rules for writing API endpoints. Each addition makes sense. Together they push the file past the point where the agent follows it well.

The Claude Code docs suggest keeping each CLAUDE.md under 200 lines, because the whole file loads into every session and longer files get followed less reliably. Most of what makes a file long isn't needed in every session. A release checklist matters on release day.

That is what skills are for. A skill is a set of instructions that loads when it's needed instead of all the time. This post covers how a team should split the two and which skills are worth committing to a shared repository.

What a skill is

A skill is a folder with a SKILL.md file in it. The file has two parts: frontmatter that says what the skill does and when to use it, and the instructions Claude follows when it runs.

---
name: add-migration
description: "Creates a database migration for this repo. Use when a change needs a new table, column or index."
---

1. Generate the migration file with `npm run db:new -- <name>`.
2. Write the up and down steps. Every up needs a working down.
3. Run `npm run db:migrate` and then `npm run db:rollback` to prove both directions.
4. Add the schema change to docs/schema.md.

The folder name, or the name field, becomes a command: anyone on the team can type /add-migration. Claude can also load it on its own when a request matches the description. Until then, only the description sits in context, not the instructions.

If your team already has files in .claude/commands/, they keep working. Custom commands have been merged into skills, and a skill adds a folder for supporting files and more control over who can run it.

CLAUDE.md or a skill?

A simple test: does the agent need this in every session, or only for one kind of task?

Put it in CLAUDE.md	Put it in a skill
Build and test commands	The release checklist
Conventions that apply to every change	Steps for a database migration
What the product is and who it's for	How to write a new API endpoint
Things you'd reject in any review	How to debug the payment integration

CLAUDE.md is what everyone needs every day. A skill is a procedure someone needs on a particular day.

Commit them where the team gets them

Where a skill is saved decides who has it:

Project: .claude/skills/<name>/SKILL.md in the repository. Commit it and everyone who works there gets it. This is the one teams want.
Personal: ~/.claude/skills/<name>/SKILL.md on your own machine, for every project you work on.
Enterprise: deployed through managed settings to everyone in the organization.

One thing to know: when two skills share a name, enterprise beats personal and personal beats project. If a developer has an old personal deploy skill, typing /deploy runs theirs, not the one the team committed. Use names specific to the repository, such as deploy-web, for the shared ones.

In a monorepo, a package can have its own .claude/skills/ folder. Claude Code loads those skills the first time it reads or edits a file in that package. If the root and apps/web both have a deploy skill, both stay available, and /apps/web:deploy runs the package's one.

Decide who can run each skill

Two frontmatter fields control this, and for a team they matter more than anything else in the file.

Frontmatter	You can run it	Claude can run it on its own
(default)	Yes	Yes
`disable-model-invocation: true`	Yes	No
`user-invocable: false`	No	Yes

Anything with side effects, such as a deploy, a release or a message to a channel, should have disable-model-invocation: true. The docs put it plainly: you don't want Claude deciding to deploy because your code looks ready. With that field set, the description isn't loaded into context either, so the skill costs nothing until someone types its name.

user-invocable: false is for background knowledge, such as how a legacy system works. Claude should know it when relevant, but it isn't a command anyone would type.

Three skills worth committing

1. The release. The steps your team runs to ship, in order, with the checks between them. Set disable-model-invocation: true so it only runs when a person asks.

---
name: release-web
description: Releases the web app to production.
disable-model-invocation: true
---

1. Confirm the branch is main and the working tree is clean.
2. Run the full test suite and stop if anything fails.
3. Bump the version in package.json and update CHANGELOG.md.
4. Tag the release and push the tag.
5. Report the tag and the CI run link. Do not mark the release done until CI is green.

2. The task everyone gets slightly wrong. Every team has one: the migration, the new API endpoint, the feature flag. Write the steps once, including the one people forget. Leave it invocable by Claude so it loads when someone asks for that kind of change.

3. Your conventions for one area. API design rules, the error format, how to name events. These are reference content: Claude applies them alongside the work instead of running them as steps. They only matter when someone works in that area, so they don't need to be in CLAUDE.md.

Two details that save trouble

Review allowed-tools in shared skills. A skill can list tools that Claude may use without asking during the turn that runs it. That is useful for a release script, but the docs warn that a skill checked into a repository can grant itself broad access, and the field applies even in a non-interactive run in a folder you've never trusted. Review it in pull requests like any other permission change.

Keep the description sharp and the file short. Claude decides when to load a skill from its description, and the skill listing cuts the description off at 1,536 characters, so put the main use case first. The docs suggest keeping SKILL.md under 500 lines and moving long reference material into separate files in the skill's folder, which load only when needed.

Where to start

Read your CLAUDE.md and mark every section that only matters for one kind of task. Each of those is a skill. Move one, commit it, and check that the file the agent reads every session got shorter.

If you're starting from nothing, the shared part comes first: a CLAUDE.md the whole team agrees on. AI Workspace Builder generates one from the docs your team already has, along with a profile for each role and an install script, using your own Anthropic API key. No docs yet? Answer a short questionnaire and download a starter CLAUDE.md, no signup needed.

Claude Code in a monorepo: how to split CLAUDE.md files across teams

AI Workspace Builder — Mon, 26 Oct 2026 08:29:33 +0000

A single CLAUDE.md file works well for one team in one repository. In a monorepo it slowly turns into a problem. The payments team adds its rules, the frontend team adds theirs, the platform team adds a deployment section, and soon every session starts by loading three hundred lines of instructions, most of which have nothing to do with the task.

That costs more than context space. The Claude Code documentation recommends keeping each CLAUDE.md under 200 lines, because longer files consume more context and reduce how reliably Claude follows them. It also warns that when two instructions contradict each other, Claude may pick one arbitrarily. A file that four teams edit is where contradictions come from.

The fix is to stop treating instructions as one file and start treating them like code: split by owner, loaded only where they apply.

How Claude Code finds instruction files

Three loading rules matter for a monorepo.

Files above you load at launch. Claude Code loads CLAUDE.md (and CLAUDE.local.md) from the directory you start it in and every directory above it. Start a session in services/payments/ and you get services/payments/CLAUDE.md, services/CLAUDE.md and the root CLAUDE.md. They are concatenated, not overridden, ordered from the root down, so the most specific file is read last.

Files below you load on demand. CLAUDE.md files in subdirectories don't load at launch. Each one loads the first time Claude reads, writes or edits a file in that subdirectory. Start at the root and touch only the frontend, and the payments instructions never enter the session.

Rules can be scoped to paths. Markdown files in .claude/rules/ can carry a paths field in their frontmatter. A scoped rule loads only when Claude works with a file that matches one of its patterns:

---
paths:
  - "services/payments/**/*.ts"
---

# Payments rules

- Amounts are integers in minor units. Never use floating point for money.
- Every new endpoint needs an idempotency key.

Rules without a paths field load at launch like the root CLAUDE.md.

A layout that scales

Put that together and a monorepo can look like this:

repo/
├── CLAUDE.md                     # shared: build, test, git workflow, ownership
├── .claude/
│   ├── settings.json             # shared permissions and hooks
│   └── rules/
│       ├── security.md           # no paths field: always loaded
│       └── migrations.md         # paths: "db/migrations/**"
├── apps/
│   └── web/
│       └── CLAUDE.md             # frontend team: components, styling, state
└── services/
    ├── payments/
    │   └── CLAUDE.md             # payments team: money handling, idempotency
    └── search/
        └── CLAUDE.md             # search team: indexing, query conventions

What goes where:

Root CLAUDE.md: only what is true everywhere. How to install, build and test. The branch and commit conventions. A short map of the repository and which team owns which directory. Keep it short, because every session loads it.
Directory CLAUDE.md files: each team's conventions, owned and reviewed by that team. Payments rules load when Claude touches payments code and stay out of the way otherwise.
Path-scoped rules: concerns that cut across directories, such as database migrations, API contracts or test files, which no single team folder owns.
Unscoped rules: the few things that must always be in context, such as security requirements. Use these sparingly; they cost context in every session.

Add the per-directory files to your CODEOWNERS so each team reviews changes to its own instructions, the same way it reviews its code.

Imports: tidy, but not cheaper

A CLAUDE.md can pull in other files with @path/to/file, for example @docs/git-workflow.md. Paths are relative to the file that contains the import, and imports can nest up to four levels deep.

Imports are useful for reusing a document that already exists rather than copying it. But the documentation is explicit that they don't reduce context cost: imported files load at launch along with the file that imports them. If the goal is a smaller session, use directory files and scoped rules, not imports.

When other teams' instructions get in the way

Because files above your working directory always load, someone working deep in the tree still gets every ancestor file. If an ancestor file carries instructions that don't apply to your work, the claudeMdExcludes setting skips files by path or glob pattern:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Patterns match absolute paths, which differ from one machine to the next, so the documentation's example puts this in .claude/settings.local.json, the uncommitted personal settings file. Treat it as a personal escape hatch. If many people are excluding the same file, the real fix is to move that content down into the directory it belongs to.

One thing can't be excluded: an organization's managed CLAUDE.md, deployed by IT to a fixed system path. Company-wide policy stays in force regardless of individual settings.

Repositories that already have AGENTS.md

Many monorepos already carry an AGENTS.md for other coding tools. Recent versions of Claude Code read AGENTS.md as project instructions, but by default only when there is no CLAUDE.md in your working directory or above it. Once you add a CLAUDE.md, Claude reads that instead.

If you want one source of truth, the simplest option is a CLAUDE.md that imports it: put @AGENTS.md in your CLAUDE.md and add any Claude-specific instructions below the import.

Keeping it healthy

Check what actually loaded. Run /context in a session; the list under Memory files shows which instruction files are in context.
Audit for drift. Newer Claude Code versions include /doctor prompt-audit, which looks for contradictions, references to files that no longer exist, and outdated instructions across your CLAUDE.md files, rules and skills, and proposes edits without changing anything until you approve.
Move procedures out. A multi-step procedure that only matters sometimes, like cutting a release, belongs in a skill that loads when it is needed, not in a file that loads every session.
Add rules from real mistakes. The documentation's advice for when to add something is practical: when Claude makes the same mistake twice, when code review catches something Claude should have known, or when a new teammate would need the same context.

The short version

One root file for what is true everywhere. One file per team, next to that team's code. Scoped rules for the concerns in between. Each file small enough that its owner can read the whole thing in a minute.

Most teams already have this knowledge, spread across READMEs, onboarding guides and wiki pages. That is what we built AI Workspace Builder for. You upload the docs your team already has, and it generates the CLAUDE.md, a profile for each role, and an install script in 15 to 30 seconds, using your own Anthropic API key. There's one free trial workspace, no card required, and our free templates are a good starting point for the root file.

Claude Code hooks for teams: four hooks worth committing to your repo

AI Workspace Builder — Sat, 24 Oct 2026 14:17:20 +0000

Most teams start shaping Claude Code with instructions: a CLAUDE.md file that says "run the formatter," "never edit the lockfile," "use our logger." That works most of the time. But an instruction is something the model chooses to follow. On a long session, or a busy day, it sometimes doesn't.

Hooks close that gap. A hook is a shell command that Claude Code runs automatically at a fixed point, such as after every file edit or before every command. It runs every time, whether or not the model remembers the rule.

For a team, that changes what you can promise. "The agent should format its code" becomes "the agent's code is always formatted."

Want to see one fire first? In this two-minute video a hook blocks Claude Code from editing a generated migration, and Claude takes the safe route:

Where team hooks live

Hooks go in the same settings files as permissions. For a team, the one that matters is .claude/settings.json in the repository, committed like any other config. Everyone who clones the repo gets the same hooks.

Personal hooks belong in ~/.claude/settings.json or the uncommitted .claude/settings.local.json. Organizations can also set hooks centrally through managed settings.

Every hook has the same shape: an event, an optional matcher that narrows which tools it applies to, and the command to run.

1. Format every file the agent edits

The simplest hook, and the one that removes the most review noise. It runs your formatter after every edit, so formatting never shows up in a code review again.

This is the example from the Claude Code documentation, using Prettier:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

PostToolUse fires after a tool runs, and the Edit|Write matcher limits it to file edits. The hook receives details of the tool call as JSON on standard input, which is where jq reads the file path. Swap Prettier for whatever your team uses: ruff format, gofmt, rustfmt.

2. Protect files nobody should hand-edit

Lockfiles, generated code, .env files and anything in .git/ should never be edited by an agent. A PreToolUse hook runs before the tool does, and if the script exits with code 2, Claude Code blocks the action. The message the script writes to standard error goes back to Claude, so it can adjust its approach instead of just failing.

Save this as .claude/hooks/protect-files.sh and make it executable:

#!/bin/bash
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

Then register it:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

Because the script is committed in .claude/hooks/, the list of protected files is reviewed in pull requests like any other code.

3. Check risky shell commands with your own logic

Permission rules in settings can deny commands by pattern, but they match the command text, and the same command can be written many ways. A PreToolUse hook on the Bash tool lets you inspect the full command with real logic before it runs: block rm -rf outside the build folder, stop pushes to the main branch, refuse anything that touches production config.

The mechanics are the same as the file guard. Match on Bash, read .tool_input.command from the JSON input, and exit with code 2 and a reason to block it. Exit 0 means the hook has no objection; the normal permission rules still decide whether the command runs.

One caution: a hook that inspects command text is a strong guardrail, not a security boundary. For limits that must hold no matter how a command is written, pair it with Claude Code's sandboxing and with access control (an agent can't touch production if the machine has no production credentials).

4. Restore key context after compaction

When a session's context fills up, Claude Code compacts it: it summarizes the conversation to free space. Details can get lost in that summary, including the rule you stated an hour ago.

A SessionStart hook with the compact matcher runs right after compaction, and whatever the command prints is added to Claude's context. The documentation's example:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

Replace the echo with a command that prints something dynamic, such as git log --oneline -5 for recent commits. Keep the always-true rules in your CLAUDE.md file; use this hook for the few reminders that matter most after a long session.

A hook to be careful with: Stop

It is tempting to add a Stop hook that runs the test suite and makes Claude keep working until it passes. Know two things first. Stop fires whenever Claude finishes responding, not only when a task is done, so a slow test suite will run constantly. And Claude Code overrides a Stop hook that blocks eight times in a row, so the script should read the stop_hook_active field from its input and exit early when it is true.

For most teams, running tests in CI and in the pull request checks is simpler.

Rolling hooks out to a team

Start with the formatter hook. It is low risk and the benefit is visible on the first pull request.
Add the file guard next, with a short list. Grow it when someone finds a file the agent shouldn't have touched.
Commit scripts to .claude/hooks/ and register them in .claude/settings.json, so changes go through review.
Make sure everyone has the tools the hooks call (jq, the formatter). For most events, a hook that can't find its command fails as a non-blocking error, so the rule silently stops applying.
Use claude --debug when a hook doesn't seem to run; it logs each hook's execution.

Instructions and hooks together

Hooks are for the rules that must always hold. Everything else, such as how your codebase is organized, which patterns to follow and who owns what, belongs in the instructions the agent reads at the start of each session.

That is what we built AI Workspace Builder for. You upload the docs your team already has, and it generates the CLAUDE.md, a profile for each role, and an install script in 15 to 30 seconds, using your own Anthropic API key. There's one free trial workspace, no card required. Our free templates include a shared settings file you can add these hooks to.

Claude Code permissions for teams: a shared settings.json that is safe by default

AI Workspace Builder — Fri, 23 Oct 2026 10:50:43 +0000

When one developer uses Claude Code, permissions are a personal habit. They click "yes" on the commands they trust and "no" on the ones they don't, and over a few weeks their setup settles into something that works for them.

On a team, that habit doesn't scale. Every developer ends up with a different set of approvals, nobody knows what anyone else's agent is allowed to run, and the new hire clicks through prompts on day one without knowing which ones matter.

The fix is a shared permissions file, committed to the repository, that every developer's Claude Code session starts from.

This two-minute video commits a shared settings file and a hook to a sample repo, then runs a real Claude Code session against them:

The three files that matter

Claude Code reads settings from several places. For a team, three of them matter:

File	Who it applies to	Commit it?
`.claude/settings.json`	Everyone working in the repository	Yes
`.claude/settings.local.json`	One developer, in this repository	No
`~/.claude/settings.json`	One developer, in every project	Not in the repo

The shared file is where team rules go. The local file is for personal exceptions, so a developer who wants one extra command approved doesn't have to change the team file. When Claude Code creates the local file itself, it keeps it out of git; if someone creates it by hand, they need to add it to .gitignore.

Organizations that need rules nobody can override can also use managed settings, which sit above all three.

What goes in the shared file

A good starting point is short:

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "ask": [
      "Bash(git push *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

Replace the commands with your project's own. The pattern is what matters:

Allow the commands developers run dozens of times a day and that can't do damage: tests, lint, type checks, read-only git. Every prompt you remove here is a prompt nobody learns to click through without reading.
Ask for actions that are fine but deserve a human glance: pushing, publishing, running a migration locally.
Deny reads of secrets, and any command your team never wants an agent to run.

Lists from different files are combined, not replaced. A developer's personal allow rules add to the team's list; they don't remove the team's deny rules.

Rule order: deny wins

Claude Code checks deny rules first, then ask, then allow. The first match in that order decides, and a more specific rule doesn't change the order.

That means an allow rule can't carve an exception out of a deny rule. If the team file denies Bash(aws *), a developer adding Bash(aws s3 ls) to their local allow list still gets blocked. This is what makes the shared file safe to rely on: a team deny rule holds no matter what anyone adds locally.

Writing rules that match what you mean

A few details decide whether a rule does what you expect:

The * matches any text in its place. Bash(npm run test *) matches npm run test with any arguments.
The space before a trailing * matters. Bash(ls *) matches ls and ls -la but not lsof. Bash(ls*) matches lsof too.
Compound commands are split. An allow rule for Bash(npm run test *) does not approve npm run test && rm -rf build. Each part has to be allowed on its own, and a deny rule applies if any part matches it.
File rules use paths. Read(./.env) covers one file; Read(./secrets/**) covers everything under that folder.

Where permission rules stop

Permission rules shape what the agent does. They are not a security boundary on their own.

A Bash rule matches the command text the agent writes. The same program run a different way (through a variable, a script, or sh -c) may not match. The Claude Code documentation is direct about this: rules that try to restrict command arguments, such as limiting curl to one domain, are fragile.

For things that must never happen, add a second layer:

Sandboxing enforces filesystem and network limits that don't depend on how a command is written.
A PreToolUse hook runs your own check on every command before it executes, and can block it. Hooks live in the same shared settings file, so the whole team gets them.
Real access control still applies. If an agent should never touch production, the developer's machine shouldn't hold production credentials.

Rolling it out

Start with deny rules for secrets and allow rules for tests and lint. That alone removes most prompts and the riskiest reads.
Commit the file in a normal PR, so the team reviews it like code.
Ask developers to note any prompt they approve more than twice in a week. Those are candidates for the shared allow list.
Run /status in Claude Code to confirm the file loaded. It lists the settings sources in use.

Review changes to .claude/settings.json with the same care as changes to CI configuration. It decides what every developer's agent can do without asking.

Starting from the docs you already have

Permissions are one part of a team setup. The other part is the instructions: the commands, the conventions and the ownership rules your agent needs to follow. Most teams already have those written down in an onboarding guide or engineering handbook.

That is what we built AI Workspace Builder for. You upload the docs your team already has, and it generates the CLAUDE.md, a profile for each role, and an install script in 15 to 30 seconds, using your own Anthropic API key. There's one free trial workspace, no card required. If you'd rather start by hand, our free templates include a shared settings file.

Why your AI coding agent ignores your team's conventions (and how to fix it)

AI Workspace Builder — Thu, 22 Oct 2026 06:58:23 +0000

A pattern shows up in almost every team that adopts a coding agent. The first week is impressive. By the third week, review comments start repeating: "we don't use that logger here," "this should follow the orders service," "don't call the payments API directly." The agent writes good code. It just keeps writing it the way most projects do, not the way yours does.

That isn't a bug in the model. It is the predictable result of where conventions live.

Why it happens

A model learns its defaults from an enormous amount of public code. It knows how most Python projects name things, how most React apps lay out components, which HTTP client most people reach for.

Your team's conventions are, almost by definition, the places where you decided to do something different from the default. And those decisions rarely live in the code itself. They live in:

review comments from two years ago
a wiki page nobody opens
the head of the engineer who set up the service

When a coding agent starts a session, it sees the files it reads and the instructions it loads. If a convention isn't in either, the agent falls back to the average choice. Which is exactly the choice your team decided against.

Five fixes, in order of payoff

1. Write the rules where the agent reads them

Claude Code loads the repository's CLAUDE.md file at the start of every session. That file is the single highest-leverage place to put conventions, because every developer's agent reads the same one.

Write rules as short imperatives:

## Rules
- Log with `lib/log`. Never use `console.log` or the standard logging module.
- New endpoints copy the structure of `api/orders/`.
- Never call the payments API directly. Go through `services/billing`.
- Schema changes: write the migration and open a PR. Never apply it.

A paragraph about your logging philosophy changes nothing. "Log with lib/log" does.

If one part of the codebase has its own rules, put a CLAUDE.md in that folder. Claude Code picks it up when working there, and the root file stays short.

2. Point to an example instead of describing it

"New endpoints copy the structure of api/orders/" beats a page describing your architecture. Models copy examples far more reliably than they follow descriptions, and the example stays accurate as the code evolves.

Pick one reference implementation per kind of thing you build often: an endpoint, a component, a background job. Name it in the rules.

3. Name the banned alternatives

The agent's default is the popular choice, so a rule that only says what to use is half a rule. Say what not to use, too:

"Use httpx. Not requests."
"Dates are stored in UTC. Never store local time."
"Use the Customer model. Not Client or AccountHolder."

The last one matters more than it looks. Without a glossary, an agent will invent its own names for your domain concepts, and the codebase slowly fills with three words for the same thing.

4. Enforce what you can mechanically

Anything a linter, formatter, type checker, or architecture test can catch should be caught there, not in review. These checks don't care whether a human or an agent wrote the code, and they don't get tired.

Claude Code can also run commands automatically after it edits files (hooks, configured in the project's .claude/settings.json). Running the formatter or linter there means convention problems get fixed before anyone sees the diff.

5. Treat every repeated correction as a missing line

This is the habit that makes the other four stick. If you correct the agent on the same thing twice, the problem is not the prompt. It is a missing rule.

Add the line to CLAUDE.md in the same PR as the fix. Review changes to that file the way you review code, because it shapes every change the agent makes afterward.

What good looks like

After a few weeks of this, two things change:

Review comments shift from conventions ("wrong logger") to substance ("is this the right behavior?").
The CLAUDE.md file becomes the most accurate written description of how your team actually works. New hires read it. So does every agent.

Starting from the docs you already have

Most teams already have their conventions written down somewhere: an engineering handbook, an onboarding guide, a style guide, a page about who owns what. The slow part is turning that prose into short rules an agent will follow.

Either way, start with the three corrections you made most often this week. Write them down where the agent reads them, and watch how many review comments disappear.

How to onboard a new developer to a Claude Code team in one day

AI Workspace Builder — Wed, 21 Oct 2026 07:16:54 +0000

When a team uses Claude Code, a new developer joins twice. The person joins, and so does their agent. The person has weeks to learn how the team works. Their agent starts writing code on day one, and it only knows what the repository tells it.

That makes onboarding faster if the team's way of working is written down where the agent reads it, and slower if it isn't: the new hire's first PRs arrive quickly, look plausible, and ignore half the team's conventions.

Here is a one-day plan that gets both of them ready.

Before day one: make the repository explain itself

Most of the work happens before the new developer arrives. Check that the repository carries three things.

A shared CLAUDE.md at the root. Claude Code reads it automatically at the start of every session. It should hold the commands (install, run, test, lint), the folder layout, a reference implementation to copy, the ownership of each area, and the handful of rules the team actually enforces. If you don't have one, our CLAUDE.md template for teams is a starting point.

A committed .claude/settings.json. This is where shared permissions live: which commands Claude Code may run without asking, and which it must never run. Committing it means the new hire's agent starts with the same guardrails as everyone else's, instead of whatever they click through in the first hour.

Folder-level CLAUDE.md files where the rules differ. If the payments service or the data pipeline has its own conventions, put them in a CLAUDE.md inside that folder. Claude Code picks it up when working there, and the root file stays short.

A quick test: ask someone who has never seen the repository to open Claude Code and ask "how do I run the tests for one file?" If the answer is wrong, a new hire's agent will get it wrong too.

Morning: set up the machine and the personal layer

1. Install and sign in. Install Claude Code, sign in, and clone the repository. Run it once from the repository root so it picks up the shared files.

2. Read the shared CLAUDE.md together. Spend 20 minutes on it with the new developer. This is the fastest overview of the codebase you have, and it is the exact context their agent will work from. Anything they find confusing is probably confusing to the agent too, so fix it on the spot.

3. Set up the personal layer. Personal preferences belong in the developer's own ~/.claude/CLAUDE.md, not the shared file: how verbose they like answers, their editor habits, the language they prefer explanations in. Personal permission tweaks go in .claude/settings.local.json, which stays out of version control. Make the split explicit on day one, so team rules don't get edited to suit one person.

4. Show the team's commands. If the team keeps custom slash commands in .claude/commands/ (for example a /review or /new-endpoint command), walk through them. They are the team's habits in runnable form.

Midday: a guided first task

Pick a small, real task with a clear finish line: a bug with a reproduction, or a small endpoint that follows an existing pattern. Not a toy, and not anything that crosses team boundaries.

Have the new developer do it with Claude Code while a teammate watches for 30 minutes. The point is not the code. It is to see how the agent behaves in your repository:

Did it follow the reference implementation, or invent its own structure?
Did it run the right test command the first time?
Did it stay inside the files the task needed?
Did it stop and ask where the rules say to ask (schema changes, auth, billing)?

Every "no" is a gap in the shared files, not a mistake by the new hire. Write it down.

Afternoon: the first PR and the first fix to the instructions

1. Open the PR the normal way. Same template, same checks, same reviewers as everyone else. Agent-written code from a new hire gets the review any new hire's code gets.

2. Turn the gaps into edits. For each "no" from the guided task, add or fix one line in the right CLAUDE.md. Let the new developer make the edit and open it as a second small PR.

This is the most useful thing a new hire can do on day one. They are the only person on the team who sees the repository with fresh eyes, and their agent is the only one that shows exactly what the written instructions are missing.

End of day: what to check

By the end of the day the new developer should have:

Claude Code running against the repository with the shared settings
A personal ~/.claude/CLAUDE.md that holds their preferences, not team rules
One merged or reviewed PR for a real task
One PR that improves the team's instructions

If all four are true, their agent now works the way the team works, and the instructions are a little better for the next person.

Why this matters more as the team grows

On a team of three, conventions live in people's heads and spread in conversation. On a team of thirty, each developer's agent is making hundreds of small choices a day based on whatever the repository says. Onboarding is the moment the gap between "how we work" and "what is written down" is easiest to see, so it is the best moment to close it.

Starting from the docs you already have

The slow part is usually the first version of the shared files. Most of it already exists in your onboarding guide, your engineering handbook, and the page about who owns what. It just isn't in a form the agent reads.

Either way, the next new hire is the best test you have. Watch what their agent gets wrong on day one, and write it down.

A CLAUDE.md template for teams (copy it and adapt)

AI Workspace Builder — Tue, 20 Oct 2026 06:58:40 +0000

Most CLAUDE.md examples online are written for one person working on one side project. A team file has a different job: every developer's Claude Code session reads the same file, so it has to encode how the team works, not how one person likes to work.

Below is a template you can copy into the root of a shared repo. Replace everything in <angle brackets>, delete what doesn't apply, and keep it short. Notes on each section follow.

Prefer to start from a questionnaire instead of a blank file? This two-minute video fills one in for a sample project and saves the result as a starter CLAUDE.md:

The template

# <Project name>

<One sentence: what this repo is and who uses it.>

## Commands
- Install: `<command>`
- Run locally: `<command>`
- Test (all): `<command>`
- Test (one file): `<command> <path>`
- Lint and format: `<command>` (must pass before any commit)
- Never run: `<command>` (<why: e.g. resets the shared dev database>)

## Layout
- `<folder>/`: <what lives here>
- `<folder>/`: <what lives here>
- Reference implementation for new <services/components/endpoints>: `<path>`

## Ownership
| Area | Owner | Reviews required |
|---|---|---|
| `<folder>/` | <team> | <n>, at least one from <team> |
| `<folder>/` | <team> | <n> |

## Rules
- Follow the pattern in `<reference path>` for new <things>. Do not invent a new structure.
- <Database> schema changes: write the migration and open a PR. Never apply it directly.
- Anything touching <billing/auth/data deletion>: stop and ask before writing code.
- Dependencies: patch upgrades are fine. Minor or major upgrades need a separate PR.
- If you can't verify something (a command, an API, a config value), say "I haven't verified this" and stop.

## Standards
- Test coverage on new code: <n>% minimum
- <Language>-specific: <e.g. no `any` in TypeScript, type hints on all public functions>
- Commit messages: <convention, e.g. Conventional Commits>
- PR size: under <n> lines changed where possible

## Glossary
- **<Term>**: <what it means here>. Not "<banned synonym>".
- **<Term>**: <what it means here>.

## Definition of done
- Tests pass locally and the linter is clean
- The change follows the reference implementation
- The PR description explains what changed and why, in plain language

That's the whole file. If yours is much longer, read on.

What each section is for

Commands

This is the section that pays off fastest. Without it, Claude Code guesses the commands, and a plausible guess (npm test in a pnpm monorepo, pytest without the right flags) wastes time on every task.

The "Never run" line matters more than it looks. One destructive command that's easy to type, like a database reset or a deploy script, is worth naming explicitly.

Layout and the reference implementation

Don't describe the whole folder tree. The agent can read it. Name the folders whose purpose isn't obvious, and point to one existing file that shows the right way to do things.

"New endpoints follow the structure of api/orders/" gets better results than a page describing your architecture. Models copy examples far more reliably than they follow descriptions.

Ownership

In a team repo, the most expensive agent mistake is a change that crosses team boundaries: a refactor that touches three teams' code in one PR. An ownership table lets the agent notice the boundary and split the work, or ask first.

Rules

Write rules as short imperatives. "Never apply schema changes directly" is followed. "We generally prefer that schema changes go through review" is not.

Keep the list to the rules that are actually broken. A rule nobody would break anyway is noise that dilutes the ones that matter.

Standards

Numbers beat adjectives. "Clean, well-tested code" changes nothing. "80% coverage on new code" and "no any types" can be checked, by the agent and by your reviewer.

Glossary

This is the section most teams skip and most need. When the agent invents its own names for your domain concepts (a "customer" becomes an "account holder" in one file and a "client" in another), the codebase slowly fills with inconsistent vocabulary. A short glossary, including the synonyms you don't want, stops that.

Definition of done

Tell the agent what it has to check before it says it's finished. This turns "done" from a claim into something it verifies: tests ran, the linter passed, the change matches the reference.

What to leave out

Things the code already says. The agent can read your package.json and folder structure.
Personal preferences. Tone, verbosity, editor habits: those belong in each developer's own ~/.claude/CLAUDE.md, not the shared file.
Rules for one folder. Put them in a CLAUDE.md inside that folder. Claude Code picks it up when working there, and the root file stays readable.
Long prose. If a section needs paragraphs, it's documentation. Link to it instead of pasting it.

Keeping it true

A team CLAUDE.md fails quietly: it says one thing, the codebase moved on, and the agent confidently follows the old rule. Two habits prevent that:

Review it like code. Changes go through PRs, and any PR that changes a convention updates the file in the same PR.
Treat a bad agent suggestion as a bug report against the file. If the agent got something wrong because the rule was missing or stale, fix the file, not just the code.

Starting from your team's docs instead

Most of what goes into this template already exists somewhere in your team's documents: the onboarding guide, the engineering handbook, the page about who owns what. Turning that prose into short rules is the slow part.

That's what we built AI Workspace Builder for. You upload the docs your team already has, and it generates the CLAUDE.md, a profile for each role, and team-level files in 15 to 30 seconds, using your own Anthropic API key. There's a free trial workspace, no card required.

Either way, start small: commands, one reference implementation, and the three rules your team breaks most often. That alone changes how Claude Code behaves in your repo.

How to set up Claude Code for your whole team (not just your own laptop)

AI Workspace Builder — Mon, 19 Oct 2026 09:34:05 +0000

Most developers who try Claude Code start the same way: open a repo, ask for a change, and get something that is almost right. The code compiles, but it uses the wrong logging library, skips the test convention your team agreed on, and opens a PR against the wrong branch.

The model is not the problem. Context is. Claude Code knows nothing about your team unless you write it down, and the place you write it down is a file called CLAUDE.md.

This guide covers what goes in that file when a team shares it, not just one person, and the mistakes that make it stop working after a month.

Already have a handbook or README? This two-minute video turns one into a CLAUDE.md, a profile for each role and skills for the tasks the docs describe:

What CLAUDE.md actually does

Claude Code reads CLAUDE.md automatically at the start of every session. You do not paste it, reference it, or remind the agent. If the file is in your project root, it is in context.

There are three places it can live:

Location	Scope	Who edits it
`~/.claude/CLAUDE.md`	Every project on your machine	You only
`<repo>/CLAUDE.md`	Everyone working in this repo	The team, via PR
`<repo>/<folder>/CLAUDE.md`	Work inside that folder	The team that owns the folder

For a team, the repo-level file is the one that matters. It is checked in, reviewed like code, and every developer's agent reads the same rules.

If you have never made one, run /init inside Claude Code. It scans the repo and writes a starter file. That starter covers the code. It does not cover the team, and that is the part you need to add.

The five sections a team CLAUDE.md needs

1. Who owns what

The agent cannot ask "who reviews payments code?" unless the answer is in the file.

## Ownership
| Area | Owner | Reviews required |
|---|---|---|
| payments/ | Payments team | 2, one from payments |
| api/ | Platform team | 1 |
| web/ | Frontend team | 1 |

This alone stops a whole class of bad suggestions, like refactoring a module across a team boundary in one PR.

2. How decisions escalate

Write down what the agent should do when a task crosses a line: stop and ask, open an issue, or proceed.

## Escalation
- Schema changes: never apply directly. Write the migration, open a PR, tag the platform team.
- Anything touching billing: stop and ask before writing code.
- Dependency upgrades: allowed for patch versions only.

Short imperatives work better than prose. The agent follows "never apply directly" far more reliably than "we generally prefer that schema changes go through review."

3. The exact commands

List the build, test, and lint commands character for character. If you do not, the agent invents plausible ones, and plausible is not the same as correct.

## Commands
- Install: `pnpm install`
- Test one package: `pnpm --filter <pkg> test`
- Lint: `pnpm lint` (must pass before any commit)
- Never run: `pnpm db:reset` (wipes the shared dev database)

That last line has saved more than one team a bad afternoon.

4. What "good" means here

Every team has standards that are obvious to them and invisible to an outsider. Write the number down.

## Standards
- Test coverage on new code: 80% minimum
- API responses: p95 under 300 ms
- No new `any` types in TypeScript
- Commit messages: Conventional Commits (feat:, fix:, chore:)

5. The tools and systems

Which issue tracker, which CI, where logs live, which environments exist. The agent will reference these when it explains what to do next, so they should be real.

Per-role profiles: when one file is not enough

A single CLAUDE.md works until your team has people who need different defaults. A tech lead wants the agent to flag architectural risk. A new joiner wants it to explain conventions. A PM wants it to stay out of the code entirely.

A pattern that works well: keep the shared rules in CLAUDE.md, and add a short profile per role that someone loads when they start a session.

profiles/
  tech-lead/profile.md
  backend-engineer/profile.md
  product-manager/profile.md

Each profile covers how that role thinks, what they prioritize, and what they never compromise on. The shared file stays short. The profiles carry the difference.

Four mistakes that make it stop working

It grows until nobody reads it. Past a few screens, the important rules get lost among the trivia. If a section only matters for one folder, move it into that folder's CLAUDE.md.

It describes, instead of instructing. "Our team values clean code" changes nothing. "Functions over 40 lines need a comment explaining why" does.

It drifts from reality. The file says the tests run with Jest. The repo moved to Vitest in March. Now the agent is confidently wrong. Review the file when you review the code it describes.

It is written once by one person. The best CLAUDE.md files are edited by everyone who catches the agent getting something wrong. Treat a bad agent suggestion as a bug report against the file.

A faster way to write the first version

Most of what goes into a team CLAUDE.md already exists somewhere: an onboarding doc, an engineering handbook, a Notion page about who owns what. The slow part is turning that prose into short, enforceable rules.

That is the problem we built AI Workspace Builder to solve. You upload the docs your team already has (PDFs, markdown, Word files, or a Notion page), and it pulls out roles, processes, metrics, tools, and escalation paths, then generates the CLAUDE.md, a profile per role, and team-level files. It takes 15 to 30 seconds with your own Anthropic API key, and the free tier gives you one trial workspace with no card required.

Whether you use it or write the file by hand, the principle is the same: the agent is only as good as what you tell it about your team. Write it down once, keep it short, and keep it true.

What is the one rule in your CLAUDE.md that made the biggest difference? Drop it in the comments.