Establishing a Claude Code Workflow for Teams

1. Why teams need a consistent Claude Code workflow

As soon as more than one developer uses Claude Code on the same project, different usage patterns emerge almost inevitably. One developer lets Claude Code refactor entire feature branches in auto-accept mode, another only uses it for individual function signatures, a third copies suggestions into production code without review. Without shared guardrails, this produces a patchwork of code quality, commit history, and review effort that cannot be traced back to the AI itself, but to missing agreements within the team.

The problem intensifies as the team grows and the codebase ages. A module built according to one developer's personal conventions with Claude Code can become hard for colleagues to follow if naming, PHPDoc depth, or architectural decisions diverge from the rest of the codebase. A documented workflow does not solve this problem through stricter control of the AI, but through clear, versioned rules that both humans and the model follow equally. The sections below show how such a workflow is built in practice.

2. CLAUDE.md as a shared contract for the team

The CLAUDE.md file at the project root is the central place where a team records its conventions for Claude Code. Unlike a wiki page, it is loaded automatically on every session and therefore has an immediate effect on every interaction, regardless of who starts it. That makes it a living contract between the team and the tool: tech stack, directory structure, coding standards, forbidden patterns, and deploy order all live in one place instead of scattering across Slack messages or individual developers' memory.

What matters is that CLAUDE.md is versioned in the repository and therefore goes through the same pull request process as any other code change. An addition to the file, say a new rule about service contracts or a changed deploy order, gets reviewed by colleagues before it takes effect for the whole team. Personal preferences that shouldn't apply to everyone belong instead in non-versioned, local configuration files. That separation keeps the central convention from being diluted by individual special requests.

#!/usr/bin/env bash
# setup-dev-environment.sh: verify the shared Claude Code workflow is in place
set -euo pipefail

echo "[1/4] Checking for project CLAUDE.md ..."
if [[ ! -f "CLAUDE.md" ]]; then
  echo "[ERROR] CLAUDE.md is missing at project root. Team conventions are not loaded." >&2
  exit 1
fi

echo "[2/4] Checking for shared permission settings ..."
if [[ ! -f ".claude/settings.json" ]]; then
  echo "[WARN] .claude/settings.json not found, developer runs with default prompts only"
fi

echo "[3/4] Checking for shared slash commands ..."
command_count=$(find .claude/commands -type f -name "*.md" 2>/dev/null | wc -l || echo 0)
echo "Found ${command_count} shared slash commands"

echo "[4/4] Validating CLAUDE.md is tracked by git ..."
git ls-files --error-unmatch CLAUDE.md >/dev/null 2>&1 || {
  echo "[ERROR] CLAUDE.md exists but is not committed to the repository" >&2
  exit 1
}

echo "Workflow setup looks consistent with team conventions."

3. Documenting coding standards and project context

A CLAUDE.md that only contains general pleasantries or vague goals doesn't achieve much. It only becomes effective through concrete, verifiable rules: which architectural patterns are mandatory, which PHPStan level must be reached without exceptions, which Magento interface gaps are known and how to handle them. The more concretely a rule is phrased, the more reliably Claude Code follows it, and the easier it becomes in review to check whether a change matches the documented convention.

At the same time, the file shouldn't grow into an unwieldy reference that gets loaded in full into context on every request and therefore eats into the space available for the actual code. A lean CLAUDE.md with the most important project-wide rules, supplemented by module- or directory-specific CLAUDE.md files in subfolders that only load when Claude Code actually works in that area, has proven effective. That keeps context relevant without forcing teams to constantly trade off completeness against context size.

4. Setting review expectations for AI-assisted changes

One of the most common misconceptions on teams is that code created with Claude Code needs less review because it was "already checked by an AI." The opposite is true: a reviewer still has to assess functional correctness, security implications, and architectural decisions, regardless of who or what wrote the code. A clearly stated review standard therefore establishes that AI origin does not reduce review depth, and in certain areas should even increase it, for example with generated database migrations or security-relevant checks.

In practice, a labeling requirement works well: commits mostly produced with Claude Code carry a recognizable marker in the commit message, such as a Co-Authored-By trailer. That creates transparency without stamping the code with distrust, and it makes it possible to later investigate whether AI-assisted changes show different error rates than purely manual ones. Reviewers should also specifically watch for typical AI patterns, such as unnecessarily broad try-catch blocks, plausible-sounding but incorrect API calls, or comments that merely describe the code instead of explaining its reasoning.

{
  "commitConventions": {
    "aiAssistedTrailer": "Co-Authored-By: Claude <noreply@anthropic.com>",
    "requireTrailerWhenAiGenerated": true,
    "reviewChecklist": [
      "Verify functional correctness regardless of code origin",
      "Manually verify generated database migrations against the schema",
      "Never merge security-relevant changes (auth, payment, access rights) unreviewed",
      "Check comments for pure restatement of code instead of actual reasoning",
      "PHPStan level 5 and phpcs must be green locally before review"
    ],
    "escalation": {
      "highRiskPaths": [
        "app/code/*/Model/Payment/**",
        "app/code/*/Setup/Patch/Data/**",
        "app/code/*/Observer/**"
      ],
      "requiresSecondReviewer": true
    }
  }
}

5. Onboarding: bringing new developers into the workflow

New team members often bring their own habits around AI assistants, shaped by previous projects. Without structured onboarding, they transfer those habits unreflectively to the new project, which quickly reintroduces the inconsistent patterns a shared CLAUDE.md is meant to prevent. A short, mandatory entry point pays off: clone the repository, read CLAUDE.md, understand the shared permission rules in .claude/settings.json, and run through the workflow once fully on a small, low-risk task before any production changes are due.

It also helps to pair a new team member with an experienced one directly with Claude Code: work on a task together, show when plan mode makes sense, how to sharpen a prompt so it accounts for project conventions, and where a suggestion needs to be challenged despite sounding plausible. This hands-on experience conveys the rules written in the document far more durably than reading alone, and it shortens the time until new developers are productive within the shared standard.

#!/usr/bin/env bash
# onboard-developer.sh: guided first run for a new team member
set -euo pipefail

echo "Welcome. This script walks through the shared Claude Code workflow."

read -rp "Have you read CLAUDE.md end to end? [y/N] " read_claude_md
[[ "$read_claude_md" == "y" ]] || { echo "Please read CLAUDE.md before continuing."; exit 1; }

echo "Starting Claude Code in plan mode for a small warm-up task ..."
claude --permission-mode plan -p "Explain the module structure under src/app/code/Mironsoft and suggest where a new logging service belongs, following CLAUDE.md conventions"

echo "Review the plan output above with a senior team member before making edits."
echo "Once comfortable, switch to the default permission mode for actual changes."

6. Prompt conventions and shared skills and slash commands

Beyond file conventions, it also pays off for teams to align prompting practice itself. If every developer phrases the same recurring task, say "generate a new Magento module following our dual-vendor scheme," differently, results still diverge despite an identical CLAUDE.md, because the level of detail and the order of instructions vary. Reusable slash commands in the .claude/commands directory solve this problem: a team defines a command like /new-module once, encapsulating the full checklist of namespace, ACL, system.xml, and Abrams copy in a fixed prompt.

These shared commands are treated like code: versioned in the repository, reviewed in pull requests, and refined as needed. That reduces not only variance between developers but also repetitive effort, since nobody has to rewrite the same lengthy context every time. A short internal convention on prompt structure also helps, for example stating the goal first, then context, then constraints, so that even free-form requests not wrapped in a command are structured similarly across the team and produce comparable results.

#!/usr/bin/env python3
"""validate_commands.py: check that shared slash commands follow team conventions.
Run in CI to catch undocumented or malformed commands before merge.
"""
import pathlib
import re
import sys

COMMANDS_DIR = pathlib.Path(".claude/commands")
REQUIRED_SECTIONS = ["## Purpose", "## Context", "## Constraints"]

errors = []

for command_file in sorted(COMMANDS_DIR.glob("*.md")):
    content = command_file.read_text(encoding="utf-8")

    for section in REQUIRED_SECTIONS:
        if section not in content:
            errors.append(f"{command_file.name}: missing required section '{section}'")

    if not re.match(r"^# /[a-z][a-z0-9-]*\n", content):
        errors.append(f"{command_file.name}: missing a valid '# /command-name' heading")

if errors:
    print("Shared slash command validation failed:", file=sys.stderr)
    for error in errors:
        print(f"  - {error}", file=sys.stderr)
    sys.exit(1)

print(f"All shared slash commands in {COMMANDS_DIR} follow team conventions.")

7. Consistency across the CLI, IDE plugins, and CI

In many teams, Claude Code is used not only from the command line but also through IDE integrations and, occasionally, automated calls in CI pipelines. Each of these usage forms fundamentally reads the same CLAUDE.md and the same .claude/settings.json rules, but in practice, default behavior differs by integration, for example around auto-accepted edits or a visible diff preview before a change. A team should therefore explicitly define which permission level counts as the minimum in each environment, rather than relying on each tool's own defaults.

Especially in CI pipelines, where Claude Code runs headless in plan mode or with a tightly scoped allow-list, the configuration must exactly match the local team policy so that automated reviews apply the same standards as a manual invocation on a developer machine. A simple but effective test: run the same task once locally and once through the CI configuration, and compare the results. If they diverge structurally, there is usually a discrepancy in the loaded rules that should be fixed before production use.

8. Metrics and feedback loops for the workflow

A team's Claude Code workflow is not a document set once and forgotten, but a rule set that should evolve with the team's experience. A short, regular retrospective helps here, say every two sprints: which changes created with Claude Code needed repeated rework in review, which rules in CLAUDE.md are visibly ignored or misunderstood, and which new patterns keep showing up in prompts without being captured as a slash command yet. These observations flow directly back into configuration adjustments.

Where available, session logs and simple counts of tool calls provide additional, more objective signals than pure impressions from reviews: a notably high number of denied Bash commands can indicate overly strict deny rules, a high number of manual reworks on generated code can point to gaps in CLAUDE.md. It's important not to misread this analysis as an individual performance evaluation, but as a tool to deliberately improve the shared workflow instead of leaving it unchanged.

// analyze-sessions.js: summarize Claude Code session logs for the team retro
const fs = require('node:fs');
const path = require('node:path');

const logDir = process.argv[2] || '.claude/logs';
const files = fs.readdirSync(logDir).filter((f) => f.endsWith('.jsonl'));

const stats = { totalSessions: 0, deniedBashCommands: 0, manualEditsAfterAi: 0 };

for (const file of files) {
  const lines = fs.readFileSync(path.join(logDir, file), 'utf-8').trim().split('\n');
  stats.totalSessions += 1;

  for (const line of lines) {
    const event = JSON.parse(line);
    if (event.type === 'tool_denied' && event.tool === 'Bash') {
      stats.deniedBashCommands += 1;
    }
    if (event.type === 'manual_edit' && event.followsAiEdit) {
      stats.manualEditsAfterAi += 1;
    }
  }
}

console.log(`Sessions analyzed: ${stats.totalSessions}`);
console.log(`Denied Bash commands: ${stats.deniedBashCommands}`);
console.log(`Manual edits after AI edits: ${stats.manualEditsAfterAi}`);
console.log('High denial counts suggest overly strict deny rules.');
console.log('High manual-edit counts suggest gaps in CLAUDE.md conventions.');

9. Common pitfalls and anti-patterns in team use

The most common mistake is a CLAUDE.md that gets written once and never updated again, while the project's actual conventions have long since moved on. Claude Code reliably follows what is documented, not what has quietly become customary within the team in the meantime. A second widespread pattern: individual developers maintain their own, non-shared rules in local configuration files that effectively diverge from the team policy, without this becoming visible in review, because local settings aren't part of the commit.

Equally risky is the opposite extreme: a team that distrusts every AI-assisted change on principle and therefore reviews it twice as strictly as manually written code, regardless of the actual risk of the specific change. That slows down the workflow without demonstrably improving code quality, and it undermines acceptance of clear rules within the team. The overview below contrasts common anti-patterns with the recommended alternatives.

10. Summary

A resilient Claude Code workflow for teams comes not from stricter control of the AI, but from clear, versioned rules that everyone involved follows. A shared CLAUDE.md in the repository documents the tech stack, coding standards, and project context, and is maintained through the regular pull request process rather than written once and forgotten. Review expectations for AI-assisted changes ensure that the code's origin doesn't lower review depth, but rather raises it depending on risk.

Structured onboarding, shared slash commands, and consistent configuration across the CLI, IDE integrations, and CI pipelines prevent every team member from using Claude Code in their own way. Regular retrospectives based on session data and review experience keep the workflow alive instead of treating it as a static document. The biggest lever here isn't any single tool feature, but the consistent, shared application of the workflow across the whole team.

11. FAQ: Claude Code Workflow for Teams