chore: progressive-disclosure rules restructure + fix silently-broken Vercel docs fetch#47
Merged
Conversation
The Phase 4 block in /updating-deps was a silent no-op — its AWK extraction was anchored on '# AI SDK UI' / '# AI_APICallError' section headers that Vercel removed from llms.txt when they restructured the index around guides. AWK printed nothing → '>' truncated the file. Replaced with a sitemap-filtered fetch of Fumadocs' documented .md raw-markdown variant (x-matched-path: /[variants]/llms.mdx/[type]/[...slug]), plus loud assertions for empty sitemap filter, missing 'useChat', and unexpectedly small output. Mirrors LukeMainwaring/cortexdj#43. CLAUDE.md previously re-inlined the same broken one-liner; now points to the skill block with a one-line note on why the old command failed, so future-me doesn't restore it. docs/vercel-ai-sdk-ui.txt refreshed as a side-effect of verifying the new script end-to-end: 99 KB → 271 KB across 28 source pages, now reflects the AI SDK 5/6 transport API (sendMessage, DefaultChatTransport, parts-based messages) instead of the pre-v5 handleInputChange/handleSubmit/input pattern. Migrating chat.tsx to the new surface is deferred to its own PR (Vercel ships 'pnpm dlx @ai-sdk/codemod v6' for the bulk rewrite). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Mirrors the structure that landed in cortexdj — same routing pattern, project-specific content. CLAUDE.md (11 KB → 7.6 KB): - Hoist 'all commands run from repo root' to the top of Common Commands - Fix stale frontend paths: app/page.tsx → app/(chat)/page.tsx, app/api/chat/route.ts → app/(chat)/api/chat/route.ts; the (chat) route group has been in place for a while but the doc never caught up - Trim the per-component file list from ~14 to ~6 entries (chat, message with DataPartRenderer note, sample-browser + sample-detail-panel, elements/, api/hooks/, components/ui/) — dropped files are still discoverable by name - Replace inline paragraphs about Pydantic AI / Vercel AI SDK docs with router pointers into .claude/rules/ — each pointer is 'when to read it' + a one-sentence preview of what's inside - Drop the '95% confidence — ask via AskUserQuestion' rule; it's behavioral guidance about how Claude works, not a samplespace fact - Keep samplespace-specific facts not derivable from code: Rubber Band on PATH, CLAP/CNN mock-in-tests, SAMPLE_LIBRARY_DIR, manual git, and the regenerate-client reminder .claude/rules/ — frontmatter on every file: - All four rule files now open with paths: globs (machine-readable scope; also documents intent for readers) - backend/code-conventions.md: backend/**/*.py - backend/pydantic-ai.md: agents/**/*.py + tests/evals/**/*.py - frontend/code-conventions.md: components/app/hooks/api-hooks/lib - frontend/vercel-ai-sdk.md (NEW): same scope as frontend conventions minus app/ subset, narrowed to app/(chat)/ .claude/rules/frontend/vercel-ai-sdk.md (new) captures samplespace-specific chat-surface facts that aren't in cortexdj's equivalent: - UI-only / no Core server-side; route.ts is a proxy - ChatMessage<CustomUIDataTypes> generic threaded through useChat - Interactive blocks render off part.type === 'data-<name>' in message.tsx::DataPartRenderer (NOT 'tool-<name>' like cortexdj — samplespace agents emit data parts, not tool-typed parts) - ChatActionsProvider supplies sendMessage to descendants - Heads-up: chat.tsx still uses pre-v5 useChat shape while the local docs now document v5/v6 — don't pattern-match new code off the docs without checking what chat.tsx does. Migration is its own PR. No Modal rule mirrored — samplespace doesn't use Modal. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Code-review findings from the rules-setup branch: 1. The 'chat surface still uses the pre-v5 useChat shape' heads-up was factually wrong — that line was pattern-matched from cortexdj's PR description, which described cortexdj's codebase, not samplespace's. samplespace's chat.tsx already uses DefaultChatTransport + sendMessage (no handleInputChange / handleSubmit / 'input' field from useChat). Replaced the bullet with a positive description of the actual API in use so future Claude can pattern-match safely off chat.tsx. Same fix applied to the CLAUDE.md router pointer. 2. ChatMessage signature drift: 'UIMessage<never, CustomUIDataTypes>' → 'UIMessage<Record<string, never>, CustomUIDataTypes>' (matches lib/types.ts). Added a parenthetical explaining the metadata slot is intentionally empty, not 'never', so a future Claude doesn't 'fix' the type to match a stale rule. 3. CustomUIDataTypes has six entries, not five — 'chat-title' is a non-rendering data part handled by data-stream-handler.tsx for sidebar refresh. Reworked the 'two places' rule to scope to *renderable* blocks and note where non-rendering deltas go. 4. Backend route is /api/agent/chat, not /agent/chat (API_PREFIX='/api' plus router prefix='/agent'). Fixed in three places: CLAUDE.md Frontend section, CLAUDE.md Data Flow #1, and vercel-ai-sdk.md's 'AI SDK UI only' bullet. 5. 'render them as code-fence-style blocks' was legacy framing — DataPartRenderer invokes block components directly with a JSON-stringified code prop, no markdown fence parsing involved. Changed to 'render inline in the message stream'. Verified against chat.tsx, lib/types.ts, message.tsx, data-stream-handler.tsx, core/config.py, and routers/agent.py. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
/updating-depsPhase 4 was a silent no-op for weeks — its AWK extraction was anchored on# AI SDK UI/# AI_APICallErrorsection headers Vercel removed when they restructuredllms.txtaround guides. AWK printed nothing →>truncated the file. Replaced with a sitemap-filtered fetch of Fumadocs' documented.mdraw-markdown variant, plus loud sanity assertions. Mirrors cortexdj#43.paths:frontmatter on every.claude/rules/**.md, router pointers inCLAUDE.mdinstead of inline doc paragraphs, newfrontend/vercel-ai-sdk.mdcapturing samplespace's chat-surface conventions. CLAUDE.md drops from 11 KB → 7.6 KB without losing samplespace-specific facts.docs/vercel-ai-sdk-ui.txtrebuilt as a side-effect of verifying the new Phase 4 script: 99 KB → 271 KB across 28 source pages, now reflects the AI SDK 5/6 transport API the codebase is already using.Changes
Skill fix (
.claude/skills/updating-deps/SKILL.md)set -eo pipefail,mktemp+trapcleanup,curl -fsSL, empty-sitemap assertion,useChat-presence assertion, >100 KB size assertion). Catches each realistic upstream-restructure failure mode distinctly.useChatmentions across 28<!-- source: -->markers.Rules restructure (
.claude/rules/**,CLAUDE.md)paths:YAML frontmatter on all four rule files — machine-readable scope globs that also document each rule's intended file scope..claude/rules/frontend/vercel-ai-sdk.mdcapturing samplespace-specific chat-surface facts:app/(chat)/api/chat/route.tsis a thin proxy toPOST /api/agent/chatuseChat<ChatMessage>is on the v5/v6DefaultChatTransport+sendMessageshape — nohandleInputChange/handleSubmit/inputfrom useChatChatMessage = UIMessage<Record<string, never>, CustomUIDataTypes>— metadata slot intentionally empty, notnevermessage.tsx::DataPartRendererviapart.type === "data-<name>"; adding a new block islib/types.ts+DataPartRenderercasechat-title) go todata-stream-handler.tsx, notDataPartRendererChatActionsProvidercarriessendMessageto descendants via contextCLAUDE.md:## Common Commandsapp/page.tsx→app/(chat)/page.tsx,app/api/chat/route.ts→app/(chat)/api/chat/route.ts, drop nonexistentaudio-player.tsx; backend route is/api/agent/chatnot/agent/chat.claude/rules/SAMPLE_LIBRARY_DIR, manual git,pnpm -C frontend buildskipped for validationDifferences vs. cortexdj's verbatim layout
backend/modal.md— samplespace doesn't use Modalfrontend/vercel-ai-sdk.mddocumentsdata-<name>part dispatch, nottool-<name>like cortexdj — samplespace agents emit data parts, not tool-typed partsAdditional Instructionsitems cortexdj has no analog forCode review
Reviewed by the
code-reviewersubagent. One material correctness issue caught and fixed in commita0644a5: the originalvercel-ai-sdk.mdcarried a "chat surface still uses pre-v5 API" heads-up that was pattern-matched from cortexdj's PR description but is false here — samplespace already usesDefaultChatTransport+sendMessage. Replaced with a positive description of the actual API surface. Also correctedChatMessagesignature drift, the missing 6thCustomUIDataTypesentry (chat-title), and three/agent/chat→/api/agent/chatroute references.Test Plan
backend/src/samplespace/agents/**.pyfile, confirm Claude finds.claude/rules/backend/pydantic-ai.mdquickly/updating-depsrun: confirm the new Phase 4 block actually runs anddocs/vercel-ai-sdk-ui.txtregenerates with all four assertions passingvercel-ai-sdk.mdagainstfrontend/components/chat.tsx— every claim in the rule should match the code (this is the file the code-review pass fixed)🤖 Generated with Claude Code