Content
67%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A well-structured, highly actionable body packed with platform-specific knowledge Claude cannot infer, with genuine validation checkpoints and a clean one-level reference bundle. Its weaknesses are verbosity from duplicated warnings and repeated region lists, the fully inlined WebSocket section that breaks the otherwise good progressive-disclosure pattern, and a few undefined helper functions in otherwise executable code.
Suggestions
Deduplicate repeated content: state the supported-region list and the missing-env-value warning (empty-string coercion deleting live keys) once and cross-reference them, and consolidate the pooled/unpooled DATABASE_URL guidance.
Move the WebSocket cross-isolate playbook (three fan-out strategies, heartbeat, and reconnect client) into a references/websocket.md, mirroring how the SSE pattern is split into references/sse.md.
Define or explicitly flag the undefined helpers in code examples (cors(request), verifyToken, persist) so the snippets are copy-paste ready, and prefer relative reference paths over full neon.com URLs where the bundled file exists.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with non-obvious, platform-specific facts (15-minute TTFB/heartbeat/waitUntil limits, env-var coercion deleting live keys, JWKS issuer verification, cross-isolate fan-out pitfalls), so most tokens earn their place — above the verbose anchors. But it is not 4: the supported-region list is repeated three times, the "never coerce a missing process.env value to an empty string / KEY= is also \"\"" warning appears nearly verbatim in both "Develop Locally and Deploy" and "Environment Variables", and pooled/unpooled connection-string guidance is duplicated between the env table and "Connecting to Postgres" — several sections could be tightened or consolidated. | 3 / 5 |
Actionability | Mostly fully executable guidance: complete Hono+Drizzle setup, JWT verification with jose, WebSocket upgrade via upgradeWebSocket, heartbeat keepalive, Postgres polling fan-out, LISTEN/NOTIFY, SSE ReadableStream endpoint, and exact CLI commands (neon dev, neon deploy --env, neon functions get <slug>, neon config plan). Falls short of 5 on minor gaps: the cors(request) helper in the JWT snippet, verifyToken in the WebSocket snippets, and persist in the broadcast example are used but never defined, so those examples are not copy-paste complete. | 4 / 5 |
Workflow Clarity | A clear overall sequence (availability precondition → setup in neon.ts → local dev → deploy → env vars → connecting → limits → workload patterns) with real checkpoints: "Check this precondition before setting anything up" (region), neon config plan dry-run before apply, "add --update-existing only after reviewing those changes", and explicit auth validation ("Exercise two users: each can access their own data; cross-user access is denied. Repeat after restarting the Function"). Not 5 because the deploy workflow is spread across several sections without a single ordered procedure, and validation feedback loops (validate → fix → retry) are implied rather than explicit. | 4 / 5 |
Progressive Disclosure | Good structure scored against the actual bundle: eight one-level-deep reference files exist in references/ and are each clearly signaled from the body (native-binaries, production-hardening, function-triggers, ai-sdk, mastra-studio, mcp, sentry, sse). Not 5 because the ~120-line WebSocket playbook (three fan-out strategies plus a reconnect client) is fully inline while its SSE counterpart is properly split into references/sse.md — an inconsistency showing content that should be separate is inline — and half the reference links point to full neon.com URLs rather than the bundled relative paths. | 4 / 5 |
Total | 15 / 20 Passed |