影子双跑 Skill

---
name: shadow-traffic
description: Design and review read-path shadow dual-run plus progressive cutover for a legacy-to-new HTTP rewrite. Use when the user mentions 影子流量, 影子双跑, shadow traffic, or dual-run.
---

# Shadow Traffic

Prove the new stack matches the old stack on the **read path**, then split live requests. Never dual-write shared storage.

## Do first

1. Freeze HTTP contracts (status, headers, body, required DB side effects).
2. Recreate behavior; do not clean up the API during the migration.
3. Shadow-compare GET/HEAD only. User traffic stays on the legacy stack until a separate cutover approval.

## Hard rules

- Comparator allows GET/HEAD only. Reject writes in code.
- GET is not automatically safe. Block reads that create grants, sessions, or audit rows (example: token validate with `client_id`).
- Shared PG + Redis + token tables; one writer. Matching secrets. No rotation during a shadow window.
- Background jobs XOR: new worker stays empty until HTTP is 100% new.
- Target allowlist: refuse production hosts and ports.
- Persist redacted path templates only. Never store tokens, cookies, bodies, or DSN.

## Gate

`collect → summarize → summarize --gate`

Pass only if: allowlisted non-stale events ≥ 1, `gate_diff == 0`, `gate_unreachable == 0`. Internet probes are `ungated` and must not move the gate.

Stop if a registered route 501s, a write leaks into shadow, or the log cursor resets.

## Cutover

One request, one upstream (30/50/70 by request id). No nginx `mirror`, no retry onto the other stack. Rollback to legacy-only must not depend on the new worker.