2.7 KiB

Raw Blame History

Playbooks

Application-profile-specific advice that shapes how recommendations are phrased and ordered. Playbooks never invent claims — every rec still traces to a verified candidate or finding. They tell the recommender what to emphasize when a project matches a profile.

How a playbook gets applied

Step 1 detects the project's stack + dependencies.
The recommender heuristics infer an application profile (best guess from frameworks + dep signals).
The matching playbook(s) are included in the recommender's context.
Recommendations are shaped: ordering tilts toward the profile's priority list; phrasing nods to profile-specific concerns.

Profile detection (best-effort heuristics)

Signals →	Profile
`@vercel/sandbox`, `@ai-sdk/*`, `ai`, `openai`, `@anthropic-ai/sdk` deps OR AI Gateway / Sandbox SKU active in `usage.services`	`ai-application`
`stripe`, `@shopify/*`, `react-stripe-js`, "cart"/"checkout" routes	`ecommerce`
`next-auth`, `clerk`, dashboard routes, multi-tenant headers	`saas`
Only `pages/api/` or `app/api/`, no UI routes	`api-service`
Heavy MDX / markdown, mostly static routes	`content-site`
Lots of `/(marketing)/` route groups, A/B test deps	`marketing`

ai-application is checked first — AI-shaped customers often share routes with SaaS/ecommerce surfaces, but the billing shape (AI Gateway dominant) and remediation set (provider failover, sandbox reuse, OIDC keyless) belong to this profile.

When detection is uncertain, no playbook is applied. The recommender works fine without one — the playbook is a tilt, not a requirement.

Playbook schema

Each playbook is a Markdown file with a fixed shape so the recommender can parse it reliably. Required sections:

# {Profile name}

## Typical billing shape
(Which dimensions dominate — e.g., "Edge Requests > Function Duration > Image Optimization")

## Priority patterns
(Ordered list of patterns this profile particularly benefits from)

## Frequent gotchas
(Anti-patterns specific to this profile)

## Cross-references
(Rec IDs from recommendations.md or rule names from vercel-react-best-practices)

Contributing a new playbook

Identify a clear application profile and one or two representative project profiles that exemplify it.
Create references/playbooks/<profile>.md matching the schema.
Add detection signals to the table above (the heuristics live in the recommender code; document them here).
Update the playbook selection matrix in references/scoring.md.
Run node --test packages/vercel-optimize-tests/test/support-topics.test.mjs packages/vercel-optimize-tests/test/investigation-brief.test.mjs. No tests directly cover playbooks (they're content), but the schema validator runs in CI.

2.7 KiB Raw Blame History