From 8b6f291e11dc2a68c4126c45e6c005afa5af62cd Mon Sep 17 00:00:00 2001 From: Ame Date: Mon, 1 Jun 2026 12:12:37 +0800 Subject: [PATCH] =?UTF-8?q?docs(claude):=20add=20demo-mode=20subsystem=20g?= =?UTF-8?q?uide=20=E2=80=94=20check=20handlers=20when=20changing=20/api/*?= =?UTF-8?q?=20surfaces?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three recent demo crashes (#235 / #238 / #240) all came from the same pattern: a refactor changed what production code returns or expects, but the parallel demo handler in `ui/src/demo/handlers/` kept the old (or invented an ad-hoc) shape. `pnpm test` doesn't catch it because esbuild doesn't enforce types. Adds demo mode to the existing "Subsystem guides" section alongside the event/listener/producer guide. The text names the two cheap habits that prevent the failure mode: 1. Import the canonical type from `ui/src/api/types.ts` (or wherever the contract lives) when writing a demo handler, instead of inlining an ad-hoc shape. 2. Run `pnpm -F open-alice-ui dev:demo` and walk the affected surface before declaring the refactor done. The catchAll's `[demo] unmocked …` warn surfaces missing endpoints; visible crashes surface shape mismatches. Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index b0ce4095..82d553c7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -81,6 +81,23 @@ wiring. When working on one of these, read its guide first: list of files to touch for each kind of change, plus a "common pitfalls" section for the kinds of things AI sessions have historically half-done. +- **Demo mode** — `ui/src/demo/` (MSW handlers + fixtures, deployed to + Vercel as the marketing demo). When you change a frontend surface that + uses `/api/*` — new endpoint, modified response shape, new UI page, + new sidebar item, retired surface — check that the corresponding + `ui/src/demo/handlers/.ts` still matches. Three recent crashes + (PRs #235, #238, #240) all came from this pattern: a refactor changed + what production code returns / expects, but the demo handler kept the + old (or invented an ad-hoc) shape, and `pnpm test` didn't catch it + because esbuild doesn't enforce types. Cheap habits that prevent this: + - When writing a demo handler, import the canonical type from + `ui/src/api/types.ts` (or wherever the contract lives), don't inline + an ad-hoc shape. + - `pnpm -F open-alice-ui dev:demo` and walk the affected surface + before declaring the refactor done. The `[demo] unmocked …` catchAll + `console.warn` log will surface endpoints you've added but not + mocked; visible crashes will surface shape mismatches. + ## Surfacing future work — Linear, not TODO.md When a session notices something worth fixing later but **out of scope