Run a Claude Code Team Workshop

To set up a Claude Code workshop for your development team, pick one real repo, define shared CLAUDE.md conventions, run one issue end-to-end, and review the result together. Keep it hands-on: participants should leave with a review-ready PR, not a slide deck.

Claude Code, Anthropic's coding agent, works best for teams when the repo carries the team's context and the review rules are obvious. A Claude Code workshop is a short, hands-on session where engineers practice the same workflow, memory files, integrations, and review expectations they will use in production.

Good hands-on AI coding workshops are really convention workshops. The goal is not to make everyone prompt the same way; it is to make the team's Claude Code workflow repeatable enough that reviews stay calm. This is the practical home for the related training topic.

Start with one repo and one workflow

Use a repository people already know. A toy app hides the hard parts: flaky tests, weird folder structure, old migrations, half-documented product rules, and review norms that live in people's heads.

Prerequisites:

• One real repository with a safe development branch.
• Four to eight engineers, ideally from the same codebase.
• Claude Code installed and authenticated before the session.
• One small issue that touches code, tests, and docs.
• A named reviewer who can say what “good” looks like.

Step 1: name the boundary. Choose one workflow, such as “fix a bug and add the regression test” or “add one API field and update docs.” The trap is trying to teach planning, refactors, MCP, hooks, and review all in the first 20 minutes.

Step 2: write the starting context. Add a tiny CLAUDE.md before anyone opens a prompt. This matters because Claude Code memory should carry durable repo rules, not every detail from today's task.

Step 3: run one task in pairs. One engineer drives Claude Code and one watches for assumptions, risky edits, and missing tests. Pairing slows the room down just enough for people to notice the workflow.

Step 4: review the diff like a normal PR. Ask the team to review tests, error handling, naming, and unnecessary churn. The trap is praising the agent transcript while ignoring the patch.

Verification: open a review-ready PR. The workshop worked if a teammate who did not sit with the pair can understand the diff, run the tests, and apply the checklist without extra oral context.

Write team memory before clever prompts

CLAUDE.md is the always-on repository context Claude Code reads so it can follow your team's conventions without being re-taught on every task. Start with boring rules: how to run tests, where architecture decisions live, what files not to edit, and what review evidence is expected.

Keep it short. A root CLAUDE.md can describe global repo habits, while scoped CLAUDE.md files can carry local rules for apps/web, packages/api, or infra/terraform.

The trap is turning CLAUDE.md into a policy landfill. If a rule only matters for one task, put it in the prompt. If it should survive into next month, put it in memory.

A useful starter rule looks like this:

## Review evidence

Before opening a PR, summarize:
- files changed and why
- tests run, including exact commands
- known risks or follow-up work
- any generated code that needs extra human review

For a deeper team adoption path, see Learn Claude Code as a Team.

Add MCP and hooks only where they reduce friction

MCP is an open protocol for connecting AI applications to external tools and data. In Claude Code teams, MCP is useful when the agent needs repeatable access to systems like GitHub issues, internal docs, design references, or ticket metadata.

Start read-only where you can. A workshop is a bad place to discover that a broad integration can mutate production data, post in the wrong channel, or fetch secrets the agent does not need.

Hooks are similar. Use Claude Code hooks to make local workflow checks visible, such as blocking a commit when tests were not run or reminding the user to include review evidence.

The trap is treating integrations as maturity. A team with one clear CLAUDE.md and one review checklist will usually learn faster than a team with six MCP servers and no shared standard for the final diff.

Make review expectations part of the exercise

Teach engineers to ask Claude Code for plans, diffs, tests, and risk notes in the same shape your reviewers expect. This makes the workshop feel like real engineering work instead of a demo.

A good review convention is small enough to remember. For example: no broad refactors during bug fixes, tests must be named in the PR, generated migrations need human inspection, and security-sensitive changes require a second reviewer.

The trap is letting speed become the only metric. In Claude Code for teams, the useful measure is whether the patch is easier to review, safer to merge, and simpler to maintain.

As of June 2026, versioned Claude Code changelog entries such as Claude Code 2.1.195 are best treated as a prompt to re-check team habits against the official docs. Do not build a workshop around rumors or screenshots; build it around the workflow your team can verify.

Copy the team rollout plan

Paste this into your repo or workshop doc, then trim it to fit your team. It gives you one artifact for a Claude Code training session and one checklist you can reuse afterward.

# Claude Code team workshop rollout plan

## Goal
Ship one review-ready PR using Claude Code, with shared repo context, safe integrations, and visible review evidence.

## Repo
- Repository:
- Branch:
- Workshop issue:
- Reviewer:

## Team conventions
Add or update `CLAUDE.md` with:

```md
# CLAUDE.md

## Project shape
- Main app code lives in `apps/web`.
- Shared server code lives in `packages/api`.
- Do not edit generated files directly.

## Commands
- Install: `pnpm install`
- Unit tests: `pnpm test`
- Type check: `pnpm typecheck`

## Working rules
- Prefer small diffs over broad refactors.
- Ask before changing public API contracts.
- Add or update tests for behavior changes.
- Summarize risks and test commands before PR review.

## Review evidence
Before requesting review, include:
- what changed
- why it changed
- tests run
- files that need careful human review

MCP boundary

• Allowed during workshop: read-only project docs and issue metadata.
• Not allowed during workshop: production databases, secret stores, write access to external systems.
• Any new MCP server needs an owner, a permission note, and a rollback plan.

Hook boundary

• Use hooks for reminders and local checks.
• Do not make a hook block work unless the team knows how to fix or bypass it safely.
• First hook to consider: remind the user to list tests before opening a PR.

Slash command idea

Create /review-ready to ask Claude Code for:

• diff summary
• test evidence
• risky files
• missing docs
• suggested PR description

Workshop agenda

1. Ten minutes: explain CLAUDE.md and review expectations.
2. Fifteen minutes: inspect the chosen issue and agree on scope.
3. Forty minutes: pair on the implementation with Claude Code.
4. Twenty minutes: run tests, inspect the diff, and prepare the PR.
5. Fifteen minutes: group review and convention updates.

Done means

• PR is open or ready to open.
• Tests are named with exact commands.
• Reviewer can understand the change without the transcript.
• CLAUDE.md has one improvement learned from the session.

## Common questions

- **How can I set up a Claude Code workshop for my development team?**

  Set up a Claude Code workshop by choosing one real repo, one small issue, one CLAUDE.md update, and one PR review exercise. Keep the group small, ideally four to eight engineers, and finish with a concrete artifact: a reviewed diff, updated team memory, or a reusable checklist.

- **What should we put in CLAUDE.md first?**

  Put durable repo rules in CLAUDE.md first: commands, architecture boundaries, generated files, review evidence, and local testing expectations. Keep the first version under one page if possible, because engineers are more likely to maintain a short memory file than a perfect handbook nobody reads.

- **Should we teach MCP on day one?**

  Teach MCP on day one only if an integration is needed for the chosen workflow. Start with read-only access to project docs, issues, or design context, and write down the permission boundary. Skip write-capable integrations until the team has a clear owner and rollback habit.

- **Do we need hooks before the team starts using Claude Code?**

  You do not need hooks before the team starts, but one simple hook can make conventions stick. Use hooks for visible reminders or local checks, not as a substitute for review. The first useful hook is often a pre-PR reminder to list tests and risky files.

- **How do we know the workshop worked?**

  The workshop worked if the next PR is easier to review because the repo context, commands, risks, and tests are visible. Use one concrete signal: a reviewer who missed the live session can inspect the PR and understand the change without reading the Claude Code transcript.

## Further reading

- [Claude Code — getting started](https://code.claude.com/docs/en/getting-started)
- [Claude Code — skills](https://code.claude.com/docs/en/skills)
- [Claude Code — hooks](https://code.claude.com/docs/en/hooks)
- [Claude Code — permissions](https://code.claude.com/docs/en/permissions)
- [Model Context Protocol — specification](https://modelcontextprotocol.io/specification/2025-11-25)
- [Anthropic — Claude Code product page](https://claude.com/product/claude-code)
- [GitHub — anthropics/skills](https://github.com/anthropics/skills)
- [Claude Code — changelog](https://code.claude.com/docs/en/changelog)

## Next step

Run the workshop on one low-risk issue this week. After the PR review, make exactly one improvement to CLAUDE.md and schedule the next team convention you want to practice.

## One methodology lens

One useful way to read this through our [methodology](/methodology) is the **Plan** step: delegate first-pass decomposition and dependency mapping, review the sequencing and assumptions, and keep ownership of scope and priorities. If that split is still fuzzy, the workflow usually is too.