Claude Code best practices for teams: a production workflow
The Claude Code practices that matter most for teams are: short, specific CLAUDE.md rules, guard hooks that block patterns behind past incidents, parallel agents in separate git worktrees, a restricted permission envelope for unattended runs, project memory, pull-request review of every change, and a scheduled LLM code audit in CI. Together they let one engineer run several agents safely. Shai uses this workflow on a production platform of about 237,000 lines of code.

Where these practices come from
Shai built and runs a two-sided marketplace platform almost alone: about 237,000 lines of code, 440 database migrations, iOS, Android and web apps from one codebase, and about 2,200 commits in 5 months. It is in production and handles real money. That pace is possible because most of the code is written by Claude Code agents working under rules.
The seven practices below are that rule set. Each one names the Claude Code feature it relies on, checked against the official documentation as of November 2026. Claude Code changes quickly, so confirm flags and setting names against the current docs before copying them.
1. Write CLAUDE.md as rules
Claude Code starts every session with a fresh context window. CLAUDE.md is the file it loads at the start of each session to learn your project. A project file lives at ./CLAUDE.md or ./.claude/CLAUDE.md and is shared through source control. A personal file at ~/.claude/CLAUDE.md applies to all your projects, and ./CLAUDE.local.md holds private project notes that you keep out of git.
What works in practice:
- Commands first. How to build, test, lint and run migrations.
- Architecture rules stated as rules. “All database access goes through the server functions in
/api. Client code never queries tables directly.” - Past mistakes. Each time an agent does something wrong that it could do again, add one line.
- Short. The documentation recommends under 200 lines per file, because longer files consume context and reduce adherence.
For rules that apply to part of the codebase, use .claude/rules/. Each Markdown file there covers one topic, and a paths field in its frontmatter limits it to matching files, so migration rules load only when Claude works on migrations. Running /init generates a starting CLAUDE.md from your codebase.
One limit to keep in mind: the documentation is explicit that Claude treats these files as context, not enforced configuration. For anything that must never happen, use the next practice.
2. Turn incidents into guard hooks
A hook is a command that Claude Code runs at a fixed point in its lifecycle. A PreToolUse hook runs before a tool call and can block it. The model cannot argue with it.
Shai’s rule is that every real incident becomes a hook. His project has guard hooks that block two SQL patterns that caused real incidents. After the hook exists, no agent can write that pattern into a migration again, whether it runs interactively, overnight or in CI.
Good candidates for guard hooks:
- Destructive shell commands, such as force pushes or dropping a database.
- Edits to files agents should not touch, such as applied migrations or lockfiles.
- Code patterns with a known failure history in your codebase.
- Any command that reaches production.
Hooks are configured in .claude/settings.json, so committing that file gives the whole team the same guards. The full mechanics, with a working script, are in Claude Code hooks and subagents.
3. Run parallel agents in git worktrees
Two agents editing the same checkout overwrite each other. A git worktree is a separate working directory with its own branch that shares the repository’s history. Claude Code has this built in:
claude --worktree feature-auth
This creates a worktree under .claude/worktrees/feature-auth/ on a new branch named worktree-feature-auth and starts a session in it. Run the command again with another name in a second terminal for a second isolated session. Add .claude/worktrees/ to .gitignore.
Practical points:
- A worktree is a fresh checkout. Dependencies must be installed in it. Files that git ignores, such as
.env, are not there unless you list them in a.worktreeincludefile, which copies them into each new worktree. - Give each agent a task that touches different files. Parallel agents on overlapping files produce merge conflicts that cost more than they save.
- The limit on parallel sessions is your review capacity, not the tool. Start with two and add more only while you can still read every diff.
Subagents can be isolated the same way, with isolation: worktree in their definition.
4. Set a permission envelope for unattended runs
An overnight run has nobody to answer permission prompts. The wrong fix is to switch off permission checks. The right fix is an envelope: a short list of what the run may do, with everything else denied.
Claude Code’s permission rules live in settings files under permissions, with allow, ask and deny lists. Rules are evaluated in the order deny, then ask, then allow, and the first match wins. An example envelope for a task that edits code and runs tests:
{
"permissions": {
"defaultMode": "dontAsk",
"allow": [
"Edit",
"Write",
"Bash(npm run test *)",
"Bash(npm run lint)",
"Bash(git add *)",
"Bash(git commit *)"
],
"deny": [
"Read(./.env)",
"Bash(git push *)"
]
}
}
In dontAsk mode, Claude Code denies every call that would otherwise prompt. Pre-approved tools and read-only actions still run. The agent can edit, test and commit on its branch. It cannot push, read secrets or run anything you did not list.
Non-interactive runs use claude -p "task", with --allowedTools and --permission-mode available as flags. Recent versions also accept --permission-prompts none, which tells Claude that nobody can approve requests so it does not retry them.
Three more layers make the envelope hold:
- Guard hooks still run. A hook that blocks takes precedence over allow rules.
- No production credentials on the machine. The documentation notes that Bash rules match command text and are not a security boundary around a program. For filesystem and network enforcement, use Claude Code’s sandboxing.
- A worktree. The run’s changes land on a branch, never on main.
In the morning, the output is a branch to review, which leads to practice 6.
5. Keep project memory
Two mechanisms carry knowledge between sessions. CLAUDE.md is the one you write. Auto memory is the one Claude writes: notes it saves on its own from your corrections and preferences, stored per repository and loaded at the start of each session.
Use them deliberately:
- When you correct an agent, tell it to remember the correction. If the lesson applies to the whole team, move it into CLAUDE.md or a rules file so it is versioned and reviewed.
- Keep decision records in the repository: why the ledger is append-only, why a table has no delete policy. Agents read them and stop proposing the thing you already rejected.
- Prune. Contradictory instructions make the model pick one arbitrarily.
6. Review everything as a pull request
Agents do not commit to main. Every change arrives as a pull request with a description, a passing CI run and a diff a person reads. This is ordinary engineering discipline, and it matters more with agents because they produce more code than a person can absorb without structure.
What makes agent PRs reviewable:
- Small scope. One task per PR. Ask for a plan first on anything large.
- Tests in the same PR. The agent writes the test and shows it passing.
- CI as the first reviewer. Type checks, lint, tests and migrations run before a person looks.
- A person merges. The reviewer is accountable for what ships.
7. Run a daily LLM code audit in CI
Review at PR time catches problems in the diff. A scheduled audit catches problems across the codebase: a permission opened three weeks ago, a pattern that drifted. Shai runs a daily LLM code review in CI alongside 10 CI workflows, plus a daily automated probe that calls sensitive database functions as an anonymous user and closes open permissions.
Claude Code runs in GitHub Actions through the official action anthropics/claude-code-action@v1. With a prompt input it runs in automation mode on any event, including a cron schedule. A minimal sketch:
on:
schedule:
- cron: "0 6 * * *"
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
prompt: "Review the commits from the last 24 hours for security and correctness issues. Report findings by severity."
Add the job permissions and tool allowances your report needs, following the action’s documentation. Keep the audit read-only, give it a narrow prompt and treat its findings as leads for a person to confirm.
The practices at a glance
| Practice | Claude Code feature | What it prevents |
|---|---|---|
| Rules in CLAUDE.md | CLAUDE.md, .claude/rules/ |
Repeated explanations and inconsistent code |
| Guard hooks | PreToolUse hooks |
Known incidents happening again |
| Parallel worktrees | claude --worktree |
Agents overwriting each other |
| Permission envelope | permissions, dontAsk mode |
Unattended runs doing unplanned things |
| Project memory | Auto memory, decision records | Relearning the same lesson |
| PR review | Branches and CI | Unreviewed code in production |
| Daily audit | claude-code-action on a schedule |
Slow drift between reviews |
Claude Code for teams and enterprises
For a team, the work is making these practices shared instead of personal. Commit CLAUDE.md, .claude/rules/, .claude/settings.json and .claude/agents/ to the repository. Larger organizations can set managed settings that users cannot override, for example disabling the mode that bypasses permission checks.
Speed without these controls has a cost. Our post on vibe coding security risks covers what goes wrong, and Claude Code vs Cursor compares the tools.
What to do next
Pick the two practices your team lacks and add them this week. CLAUDE.md and one guard hook are the usual starting pair. If you want the full workflow installed in your repositories with your engineers trained on it, our Claude Code training program runs 4 to 8 weeks at a fixed price, quoted after a 30-minute scoping call.