Copilot — Claude × Codex Collaborative Development Workflow

English | 中文

A workflow framework for AI-assisted software development, where Claude and Codex collaborate as designer, implementer, and reviewer.

What This Is

A set of Claude Code commands and skills that automate the full feature development lifecycle:

/copilot-flow "auth module with OAuth"

  Design → Review → Implement → Test → Check → Review → PR → Review Fix
    ↑        ↑         ↑          ↑      ↑       ↑       ↑        ↑
  Claude   Codex     Codex      Codex  Claude   Codex  Claude   Codex

Run the whole pipeline with one command, or use individual commands for granular control.

Commands

Command	Purpose
/copilot-flow	Full automated pipeline with checkpoints
/copilot-branch	Create a properly named branch from main
/copilot-design	Create technical design document
/copilot-review-design	Review a design and append findings
/copilot-dev	Implement code according to design
/copilot-ut	Write unit tests
/copilot-check	Run typecheck + lint + format
/copilot-review-code	Local code review before PR
/copilot-pr	Create standardized PR (with quality gate)
/copilot-review-fetch	Fetch and summarize PR review comments
/copilot-review-fix	Fix PR review issues

Quick Start

1. Prerequisites

• Claude Code installed
• Codex CLI installed (npm i -g @openai/codex)
• GitHub CLI installed and authenticated (gh auth login)
• OPENAI_API_KEY set in your environment

Install GitHub CLI:

brew install gh          # macOS
winget install GitHub.cli # Windows
# Linux: see https://github.com/cli/cli/blob/trunk/docs/install_linux.md

2. Set Up GitHub Actions Review (optional)

To enable @claude review and @codex review in PRs, you need GitHub Actions workflows:

Claude Review — Run /install-github-app in Claude Code terminal for auto-setup, or manually create .github/workflows/claude.yml using anthropics/claude-code-action. Requires ANTHROPIC_API_KEY in repository secrets.

Codex Review — Either enable Code Review in Codex settings, or create .github/workflows/codex-review.yml using openai/codex-action. Requires OPENAI_API_KEY in repository secrets.

3. Install Commands

Copy the commands and skill into your project:

cp -r .claude/ /path/to/your-project/.claude/

4. Configure CLAUDE.md

Copy the template and customize it for your project:

cp CLAUDE.md.example /path/to/your-project/CLAUDE.md

Edit CLAUDE.md to fill in:

• Project Overview — your tech stack and structure
• AI Role Assignment — which AI handles which commands (defaults provided)
• Coding Standards — your rules and conventions
• Banned Patterns — what AI reviewers should flag as blocking
• Quality Check Commands — the actual commands for typecheck, lint, format

The AI Role Assignment table in CLAUDE.md controls how /copilot-flow delegates work. By default:

Task	Default Agent
Design, Check, PR, Review Fetch	Claude (runs locally)
Review Design, Dev, UT, Review Fix	Codex (via codex exec)

Adjust this table to match your preference. All commands except copilot-flow can be assigned to any supported agent.

5. Run

# Full automated flow
/copilot-flow auth module with OAuth login

# Or step by step
/copilot-design auth module with OAuth login
/copilot-review-design docs/specs/auth-flow
/copilot-dev docs/specs/auth-flow
/copilot-ut packages/src/features/auth
/copilot-check
/copilot-review-code
/copilot-pr implement OAuth auth flow

---

Workflow Details

Roles

Role	Responsibility
Claude	Technical design, Code review, Pipeline orchestration
Codex	Design review, Code implementation, Review fix
GitHub Actions	Automated review (claude-code-action / codex-connector)

Branch Naming

With Issue:  feat/{ISSUE_ID}-{slug}    fix/{ISSUE_ID}-{slug}
Without:     feat/{slug}               fix/{slug}

• All development happens on branches — never commit directly to main
• Branches are created from main

---

Spec Files

Each feature creates a docs/specs/{feature}/ directory:

docs/specs/{feature}/
  design.md          ← Technical design (living doc, task checkboxes)
  review-design.md   ← Design review log, append-only
  review-code.md     ← Local code review log, append-only
  review-pr.md       ← PR review log, append-only
  decisions.md       ← Implementation decision log, append-only
  flow.md            ← Pipeline state (enables resumability)

These files form a complete task context snapshot. Any model or agent can reconstruct the current state by reading this directory — enabling seamless handoffs between model switches or session interruptions.

All review files are append-only — never modify existing entries. Each round appends new content, preserving full traceability.

---

Feature Development Flow

Step 1: Create Branch

Choose the naming convention based on whether an Issue exists. Branch off from main.

Step 2: [Optional] Local Design

When to do this: Use your judgment — recommended for new features or large changes, skip for small fixes.

design.md contents:

• Background & Goals
• Technical Approach (architecture changes, data models, API design)
• Key Flows
• Edge Cases & Risks
• Task Breakdown (checkbox format — checked off during implementation)
• Out of Scope

Task breakdown format:

## Task Breakdown

- [x] Define data models User, Session
- [x] Implement /api/auth endpoint
- [ ] Add rate limiting middleware
- [ ] Add integration tests

Implementer checks off each item upon completion. If tasks need to be added or modified during implementation, first append an explanation to review-design.md, then update design.md.

review-design.md rules:

• Append only — never modify existing content
• Each entry includes author and round number:

## [Codex] Round 1

- Issue 1: ...
- Suggestion: ...

## [Claude] Round 1

- Agreed with suggestion, design.md updated accordingly

## [Codex] Round 2

- Confirmed, looks good ✅

Design convergence rules:

• When review is complete, append an explicit approval marker:

## --- DESIGN APPROVED ---

approved_by: [Claude, Codex]
date: 2026-03-01

• Implementation begins only after this marker is present
• Maximum 3 review rounds. If blocking issues remain after round 3, pause and escalate to human decision

Step 3: Implement Code

• Implement strictly according to design.md — do not expand scope
• Check off task checkboxes in design.md as each item is completed
• Log non-obvious implementation decisions to decisions.md (append-only)
• Add corresponding tests

When design issues are discovered during implementation:

• Append an Implementation Feedback section to review-design.md
• The reviewer decides whether to update design.md
• For architectural-level issues, stop and return to Step 2 for re-review

Step 4: Local Code Review

Before opening a PR, run /copilot-review-code to review the diff locally.

Findings are appended to docs/specs/{feature}/review-code.md:

## [Claude] Round 1

### Blocking

1. [file:line] Issue description

### Suggestions

1. [file:line] Suggestion

### Looks Good

- Things done well

review-code.md rules:

• Append only — never modify existing content
• Auto-detection: if the latest commit contains "fix review", review scope narrows to --last (only changes since last review) instead of the full branch diff
• Large diffs (>500 lines) are split by file and reviewed per-file
• When no blocking issues remain, the reviewer appends:

## --- CODE REVIEW APPROVED ---

approved_by: [Claude]
date: 2026-03-01

Fix loop:

/copilot-dev "fix review: {feature}"   ← reads review-code.md for blocking issues
/copilot-review-code                   ← auto --last, appends Round N+1

Repeat until CODE REVIEW APPROVED appears, then proceed to Step 5.

Step 5: Open PR

Title format:

feat(scope): description          # with scope
feat(#42 scope): description      # with Issue
fix(scope): description

PR description must include:

• What changed
• Why it changed
• Points that need reviewer attention
• How to test

PR starts as Draft. Convert to Ready when review-ready.

Step 6: Trigger GitHub Actions Review

Manually trigger via PR comment:

@claude review     → triggers claude-code-action
@codex review      → triggers codex-connector

Either can be triggered independently — choose one or both as needed.

Step 7: Fetch Review Results & Fix Issues

Run /copilot-review-fetch to pull comments and append to review-pr.md:

## [Round 1] — 2026-03-01

### Blocking (must fix)

1. [file:line] Issue — by @reviewer

### Non-blocking (suggestions)

1. [file:line] Suggestion — by @reviewer

Run /copilot-review-fix to address blocking issues. It reads only the current round's blocking issues from review-pr.md — not historical rounds — keeping the fix scope minimal. Appends a fix report after committing:

## [Fix Report] Round 1 — 2026-03-01

### Fixed

- [x] Issue 1: how it was fixed

Push fixes, re-trigger review (back to Step 6). When approved, review-pr.md gets a final marker:

## --- PR REVIEW APPROVED ---

Step 8: Merge

• All blocking issues resolved, approval received
• Convert to Ready (if still Draft)
• Squash merge → delete branch
• Post-merge check: Review whether new architectural decisions should be synced to CLAUDE.md

---

Bug Fix Flow

Lighter than Feature flow — typically skips the Design phase:

1. Create branch: fix/{ISSUE_ID}-{slug} or fix/{slug}
2. [Optional] Brief root cause analysis (no full design.md needed)
3. Fix + add regression tests
4. Open PR — description includes: bug symptoms, root cause, fix approach
5. @claude review or @codex review
6. Fix review issues
7. Approve → Merge → delete branch

---

Automated Flow (/copilot-flow)

The /copilot-flow command orchestrates the full pipeline with human checkpoints. It maintains a flow.md state file so the pipeline can be resumed after interruption or model switches:

/copilot-flow "auth module with OAuth"

  ┌─ Phase 1: Design ──────────────────────────┐
  │ Auto: create design.md                       │
  │ Auto: Codex reviews ←→ Claude updates        │
  │ Auto: loop until APPROVED (max 3 rounds)     │
  │ ⏸ Pause: confirm design before implementing  │
  └──────────────────────────────────────────────┘
                       ↓ user confirms
  ┌─ Phase 2: Implement ────────────────────────┐
  │ Auto: implement code + commit (no push)      │
  │ Auto: generate tests + commit (no push)      │
  │ Auto: run quality checks + auto-fix          │
  │ Auto: review → fix → commit loop (3x)        │
  │      (tracked in review-code.md)             │
  │ ⏸ Pause: confirm code before opening PR      │
  └──────────────────────────────────────────────┘
                       ↓ user confirms
  ┌─ Phase 3: PR & Review ──────────────────────┐
  │ Auto: create Draft PR                        │
  │ ⏸ Pause: wait for CI review completion       │
  │ Auto: fetch → fix → push loop (3x)           │
  │      (tracked in review-pr.md)               │
  │ ⏸ Done: report ready to merge                │
  └──────────────────────────────────────────────┘

Options:

• --from {phase} — Force resume from design, implement, or pr
• --skip-design — Skip design phase for small changes

If interrupted, simply re-run the command — flow.md contains the current state and the pipeline resumes automatically.

---

CLAUDE.md Maintenance

CLAUDE.md is the primary context source for both GitHub Actions reviews and local AI development. Keep it up to date:

• Code style and standards
• Naming conventions
• Banned patterns
• Key architectural decisions with rationale
• Test requirements
• AI Role Assignment table

When to update:

• After each feature merge — check if new architectural decisions need syncing
• When introducing new technologies or dependencies
• When AI repeatedly makes the same category of mistake — add a corresponding ban rule

---

Regression Prevention

After multiple iterations, AI may inadvertently modify code that was intentionally written to fix a specific issue. Two mechanisms prevent this:

Regression Tests — All bugfixes must include a test that reproduces the original bug. /copilot-dev enforces this automatically. If a future change breaks the fix, the test fails and /copilot-check or /copilot-pr catches it.

Protection Comments — Critical fixes are marked with IMPORTANT: Do not change in the source code:

// IMPORTANT: Do not change. Fixes #42 — null check prevents crash on empty session.
if (session == null) return fallback;

AI reviewers treat modifications to protected code as blocking issues. /copilot-review-fix is explicitly instructed to never touch these lines unless the review specifically addresses them with clear rationale.

Add Modifying or removing code marked with IMPORTANT: Do not change to the Banned Patterns section in your CLAUDE.md.

Parallel Development (Optional)

When working on multiple features simultaneously, use --worktree to create isolated working directories:

# Session 1
/copilot-branch --worktree feat #42 auth-flow
# → creates $MAIN_WORKTREE/.worktrees/feat-42-auth-flow
cd $MAIN_WORKTREE/.worktrees/feat-42-auth-flow

# Session 2 (another Claude Code window)
/copilot-branch --worktree fix #88 session-crash
# → creates $MAIN_WORKTREE/.worktrees/my-app--fix-88-session-crash
cd $MAIN_WORKTREE/.worktrees/my-app--fix-88-session-crash

Each worktree has its own directory, branch, and node_modules. Multiple sessions can commit and push in parallel without interference. After PR is merged, clean up:

cd ~/projects/my-app
git worktree remove $MAIN_WORKTREE/my-app--feat-42-auth-flow
git branch -d feat/42-auth-flow

---

Important Notes

1. All review files are append-only: review-design.md, review-code.md, review-pr.md — each round appends only, never modifies existing content. This ensures full traceability.
2. Any model can resume: The docs/specs/{feature}/ directory is a complete context snapshot. Reading it is sufficient to understand current state and continue work.
3. PR description drives review quality: The clearer the description, the more accurate the Actions review.
4. Keep CLAUDE.md current: Sync after every architectural decision or standard change.
5. Design review max 3 rounds: Escalate to human if blocking issues persist beyond round 3.
6. Design flaws found during implementation: Feed back through review-design.md — don't silently work around them.

---

License

MIT