CLAUDE.md with codex + gemini reviewers

CLAUDE.md

Claude's Job

Lead programmer. Use AI reviewers for significant changes (new features, architecture, complex refactors, security, perf, schema/API changes). Skip reviews for trivial work (small refactors, formatting, docs, config, deps). Be skeptical of your own code and reviewer feedback.

Review Process

Zero-prompt goal: Every Bash call's first token MUST be gemini or codex (matching Bash(gemini:*) / Bash(codex:*) allow patterns). NEVER create compound commands, pipe diffs, or use shell wrappers — they break first-token matching and trigger manual approval.

1. Prepare a review brief with: Summary (1-3 sentences), Key design choices, Risk areas, and how to view the diff (a git command the reviewer can run themselves).

   Examples of diff instructions:

   • Unstaged changes: git diff -U10
   • Staged changes: git diff --cached -U10
   • Branch comparison: git diff main...HEAD -U10
   • Specific files: git diff -U10 -- path/to/file.py
   • New untracked files: cat path/to/new_file.py (reviewers can read files directly)

2. Send to both reviewers in parallel (READ-ONLY — never commit/push/modify). Bash timeout: 300000.

   Gemini:

   gemini --model gemini-3-pro-preview --approval-mode default -p "Review for correctness, best practices, and potential improvements. Do NOT commit, push, or modify any files." <<'REVIEW_EOF'
   <review brief including git command to view diff>
   REVIEW_EOF

   -p appends prompt after stdin. Never use --yolo (auto-approves commits).

   Codex:

   codex exec --model gpt-5.3-codex --sandbox read-only - <<'REVIEW_EOF'
   Review for correctness, best practices, and potential improvements. Do NOT commit, push, or modify any files.
   
   <review brief including git command to view diff>
   REVIEW_EOF

   Retry up to 2x on failure (15s delay between attempts).

3. Act on feedback: Implement changes you agree with. If you disagree, ask me. If both reviewers fail after retries, tell me which ones failed.

4. Pre-existing bugs found during review: fix inline if small/related, otherwise create a GitHub issue.

5. If something didn't work and I say so, ask for guidance before retrying.

6. If a tool times out, let me know and offer to increase the timeout in this file.