The Context Handshake: How to Onboard AI to a Legacy Codebase in 10 Minutes

You open a chat with your AI assistant, paste 2,000 lines of legacy code, and type "refactor this." The model responds with a beautiful rewrite that breaks every integration point in the project. The problem: you dumped context without framing it. The model doesn't know what matters, what's fragile, or what the implicit rules are. The fix is what I call a Context Handshake — a structured onboarding document you feed the model before asking it to do anything. The Template # Context Handshake: [Project Name] ## What This Project Does (2 sentences) An Express API that handles payment processing for our SaaS. Talks to Stripe, PostgreSQL, and a legacy SOAP billing service. ## Tech Stack - Node.js 18, Express 4, TypeScript - PostgreSQL 15 via Prisma ORM - Stripe SDK v14 - Legacy SOAP client (hand-rolled, do NOT touch) ## Architecture (3 bullet points) - Routes → Controllers → Services → Repositories - All DB access through Prisma (no raw SQL) - SOAP client is in `lib/legacy/` — treat as blac