Claude Code Complete Guide

Claude Code Team Best Practices: Standardize with CLAUDE.md, Hooks & GitHub Actions

Target Audience

• Development leads familiar with Claude Code basics, considering team adoption
• Engineers facing productivity challenges with existing AI development tools

Key Points

1. Understand team configuration patterns based on official Claude Code best practices
2. Learn shared documentation strategies that target error reduction
3. Build continuous quality assurance systems via GitHub Actions integration

Why This Workflow Matters Now

Official Claude Code Best Practices Published: Based on best practices published on Anthropic Engineering Blog by Boris Cherny from the Claude Code team, we break down design patterns with reproducible team adoption. This represents a paradigm shift from "individual optimization" to "team-wide productivity maximization," now concrete at the implementation level.

(Our site's) GA4 analysis shows continuous searches for "claude code team setup" and "claude code workflow", confirming strong demand for team adoption guidance.

Core Approach: Docs-first (Documentation-First)

What to Decide When Adopting Claude Code for Teams (Checklist)

✓ CLAUDE.md placement and hierarchy design (user / project / org / rules)
✓ Local quality gate setup with Hooks
✓ CI quality gate integration with GitHub Actions
✓ TodoWrite sync and progress visibility mechanisms
✓ Team size optimization strategies

Correct CLAUDE.md Placement (user / project / org / rules)

Basic Hierarchy: Individual to Organization

Individual-Level Configuration:

Individual-Level Configuration:

# ~/.claude/CLAUDE.md
## Development Style
- Code quality: PEP 8 compliance, type hints required
- Commits: Conventional Commits format
- Testing: pytest + 90%+ coverage

## Frequent Patterns
- API design: FastAPI + Pydantic
- Database: SQLAlchemy + Alembic
- Async: asyncio/await

Project-Level Standardization:

# project/CLAUDE.md
## Project Prerequisites
- Python 3.11+, Poetry management
- Authentication: OAuth 2.0 + JWT
- Test environment: Docker Compose

## Forbidden Patterns
- Direct SQL string manipulation → ORM required
- print() debugging → use structlog
- Manual deployment → GitHub Actions automation

Scale Management (.claude/rules split):

# Official Docs recommended split pattern
.claude/
├── CLAUDE.md          # Main rules
├── rules/
│   ├── lint.md        # Code quality rules
│   ├── commit.md      # Commit conventions
│   ├── test.md        # Test requirements
│   └── api.md         # API design guide

Boris Cherny's Documentation Strategy

The revolutionary insight: "Onboard Claude Code as a new team member." Making human tacit knowledge explicit in Claude.md automatically ensures consistent implementation quality.

CLAUDE.md Templates (Minimal → Recommended → Large Scale)

TodoWrite Integration for Progress Visibility

Real-Time Sync Pattern:

# GitHub Issues → TodoWrite → Claude Code execution chain
gh issue list --assignee @me --json number,title | \
  jq '.[] | "- [ ] #\(.number): \(.title)"' >> todo.md

claude "Execute todo.md tasks sequentially, updating TodoWrite on completion"

Team-Wide Transparency: - Personal TodoWrite → Slack workflow auto-notifications - Completed tasks → Auto-generate PRs + review requests - Blocker detection → Automatic escalation

Create Local Quality Gates with Hooks (Pre/Post, matcher, examples)

Three-Layer Error Reduction

Defense Layer	Mechanism	Implementation
Prevention	CLAUDE.md constraints	Forbidden patterns, recommended libraries
Runtime Validation	Claude Code Hooks	yamllint, pytest auto-execution
Post-Verification	GitHub Actions validation	Build success, deployment verification

Create CI Quality Gates with GitHub Actions (from /install-github-app)

1. Auto-Review Flow on PR Creation

name: Claude Code Quality Gate
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  claude-validation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: CLAUDE.md Compliance Check
        run: |
          python validate_claude_md_compliance.py \
            --pr-files $(gh pr view ${{ github.event.number }} --json files -q '.files[].path' | tr '\n' ' ')

      - name: TodoWrite Sync Verification
        run: |
          if gh pr view ${{ github.event.number }} --json body -q '.body' | grep -q "TodoWrite"; then
            python sync_todowrite_status.py --pr ${{ github.event.number }}
          fi

2. Continuous Code Quality Monitoring

Boris Cherny's Quality Metrics:

# Weekly quality report generation
gh api graphql --paginate -f query='
  query($owner: String!, $repo: String!) {
    repository(owner: $owner, name: $repo) {
      pullRequests(last: 20, states: [MERGED]) {
        nodes {
          additions
          deletions
          changedFiles
          reviews { totalCount }
        }
      }
    }
  }' -f owner=OWNER -f repo=REPO | \
jq '.data.repository.pullRequests.nodes[] | 
  {
    changed_files: .changedFiles,
    additions: .additions,
    complexity_score: (.additions + .deletions) / .changedFiles,
    review_coverage: .reviews.totalCount
  }'

Team Size Optimization Strategies

Small Teams (2-5 people): Simple Unification

# .claude/team-config.toml
[shared]
claude_md_path = "docs/CLAUDE.md"
todowrite_sync = true
approval_mode = "interactive"

[hooks]
pre_commit = ["yamllint", "pytest --fast"]
post_task = ["git add -A", "git status --short"]

Medium Teams (5-15 people): Role Separation

{
  "roles": {
    "frontend": {
      "claude_md": "frontend/CLAUDE.md",
      "allowed_paths": ["src/components", "src/pages"],
      "auto_approval": ["npm run test", "npm run lint"]
    },
    "backend": {
      "claude_md": "backend/CLAUDE.md", 
      "allowed_paths": ["api", "database", "services"],
      "auto_approval": ["poetry run pytest", "poetry run mypy"]
    }
  }
}

Large Teams (15+ people): AI-Specialized Roles

• AI Workflow Engineer: Dedicated Claude Code optimization specialist
• Documentation Maintainer: CLAUDE.md version management
• Quality Automation Lead: Unified Hooks/Actions configuration management

Failure Patterns Collection (Symptom → Cause → Solution)

Symptom	Root Cause	Boris Cherny Solution
Variable Claude Code output quality	Insufficient context	Include 3+ concrete examples in CLAUDE.md
Inconsistent team styling	Reliance on tacit knowledge	Explicitly document all patterns in CLAUDE.md
Frequent GitHub Actions failures	Local/remote environment differences	Pre-validate with claude-validate.yml
Forgotten TodoWrite updates	Remaining manual operations	Full automation via Hooks sync

Next Steps

After implementing this workflow, achieve further efficiency through these development patterns:

1. AI Agent Integration: Claude Code + GitHub Copilot Enterprise parallel operation
2. Metrics-Driven Improvement: Weekly productivity data analysis and optimization
3. Cross-Project Standardization: Configuration template sharing across multiple repositories

---

Related Articles: - Claude Code TodoWrite Weekly Workflow Automation - Detailed task management procedures - Codex CLI × Claude Code Parallel Operation Guide - Tool differentiation strategies