Originally published on NextFuture

Claude Code /advisor Recipes: 5 Use Cases with Real Output (May 2026)

TL;DR: Five copy-paste recipes for /advisor with the exact invocation and a trimmed sample of what Claude Code actually returns. Covers refactoring, Vitest test gen, JSDoc emission, Express→Hono porting, and flaky test debugging.

The /advisor command is the lowest-friction way to put the right Claude tier on the right job. Below are five recipes I've run on shipping repos in April-May 2026. Outputs are trimmed for brevity but preserve the structure.

Setup

You need Claude Code v2.6+ and an active Anthropic API key or Pro subscription:

claude --version
# claude-code 2.6.3 (build 2026.04.18)

claude config get advisor.enabled
# true

For all recipes below, run claude from the repo root, then issue the slash command shown.

Recipe 1: Refactor a 600-line file

💡 Gợi ý tool: Nếu bạn đang triển khai tương tự, Ranked.ai — AI-powered SEO & PPC service — fully managed, white hat, and built for modern search engines. Starting at $99/month..

> /advisor refactor apps/worker/src/scheduler.ts \
    --goal "split into per-job modules, no behavior change"

[advisor] file: 612 lines, 14 imports, 9 exported fns
[advisor] picked: opus-4-5  (complexity=high, edits>200)
[advisor] plan:
  1. Extract job registry → jobs/registry.ts
  2. Move cron parsing → utils/cron.ts
  3. Split run loop → core/run-loop.ts
  4. Keep scheduler.ts as thin orchestrator (~80 lines)
Apply? [y/N]

Lesson: /advisor escalates to Opus when edits cross multiple files. It also emits a plan you can edit before applying — that single prompt saved roughly 20 minutes of manual chunking.

Recipe 2: Generate Vitest tests for an API route

> /advisor test apps/nextfuture/src/app/api/v1/posts/route.ts \
    --framework vitest --coverage 80

[advisor] picked: sonnet-4-6  (complexity=medium)
[advisor] generated: 7 tests
  ✓ POST returns 401 without X-API-Key
  ✓ POST returns 429 after 60 req/min
  ✓ POST validates body via zod schema
  ✓ POST inserts row and returns 201
  ✓ GET paginates with default limit=10
  ✓ GET respects ?page=&limit= params
  ✓ GET returns empty array on no rows
[advisor] coverage: 86% lines, 78% branches

Lesson: Pin --framework explicitly. Without it, /advisor guesses Jest if it sees jest.config.js in any ancestor directory, which can mismatch your real test runner.

Recipe 3: Write JSDoc for a utility lib

> /advisor docs packages/database/src/dm-v2/*.ts --style typedoc

[advisor] picked: haiku-4-5  (complexity=low, mechanical)
[advisor] modified 6 files, +218 lines of JSDoc
[advisor] sample (canonical-key.ts):
  /**
   * Compute the canonical key for a product variant.
   * @param raw - Untrimmed product name from retailer feed.
   * @returns Lowercase, slug-safe identifier (≤64 chars).
   * @example
   *   canonicalKey("iPhone 17 Pro Max — 256GB")
   *   // → "iphone-17-pro-max-256gb"
   */

Lesson: Documentation is the killer Haiku 4.5 use case — three times cheaper than Sonnet, and quality is indistinguishable for @param/@returns emission. /advisor recognizes this and demotes automatically. See the Claude Code /advisor command deep-dive for the full demotion rule table.

Recipe 4: Port an Express route to Hono

> /advisor port apps/worker/src/routes/trigger.ts \
    --from express --to hono

[advisor] picked: sonnet-4-6
[advisor] diff preview (truncated):
- import { Router } from "express";
- const router = Router();
- router.post("/trigger/:jobId", async (req, res) => {
-   const { jobId } = req.params;
-   ...
-   res.status(200).json({ ok: true });
- });
+ import { Hono } from "hono";
+ const app = new Hono();
+ app.post("/trigger/:jobId", async (c) => {
+   const jobId = c.req.param("jobId");
+   ...
+   return c.json({ ok: true });
+ });
[advisor] also rewrote: middleware (3), error handler (1)

Lesson: Framework ports are deterministic enough that Sonnet 4.6 nails them. /advisor won't pick Opus here unless the file imports a framework-specific plugin Sonnet doesn't recognize.

Recipe 5: Debug a flaky test

> /advisor debug \
    "Vitest 'auto-publish picks oldest pending' fails 1/10 runs" \
    --file apps/worker/src/jobs/auto-publish.test.ts

[advisor] picked: opus-4-5  (complexity=diagnostic)
[advisor] hypotheses ranked:
  1. (0.71) Date.now() mocked in fixture but not awaited
  2. (0.18) Postgres index scan order non-deterministic
  3. (0.08) Redis SCAN cursor reset between runs
  4. (0.03) Vitest concurrent=true reorders setup
[advisor] suggested fix:
  - vi.useFakeTimers({ now: new Date("2026-05-01T00:00:00Z") })
  - await vi.runAllTimersAsync() before assertion

Lesson: For diagnosis, Opus 4.5's deeper reasoning is worth the cost. /advisor's ranked hypotheses gave the right root cause first try; the fake-timer fix landed in one commit.

When recipes break

• Monorepos with workspace aliases: if tsconfig.json paths aren't resolvable from the file, /advisor may misclassify complexity. Run from the workspace root.

• Files > 2000 lines: /advisor truncates at the context limit; pre-split first.

• Generated code: if the file has a // AUTOGENERATED banner, /advisor refuses by default. Override with --allow-generated.

• Hooks blocking edits: a PreToolUse hook that blocks Write will block /advisor's apply step. Check ~/.claude/settings.json when you see BLOCKED in output.

FAQ

Does /advisor work without internet access?

No. /advisor calls the Anthropic API to score complexity. There is no offline mode as of May 2026.

How do I stop /advisor picking Opus 4.5 too often?

Set "advisor": { "maxTier": "sonnet-4-6" } in ~/.claude/settings.json. /advisor will cap recommendations at Sonnet and warn when a turn would benefit from Opus.

Can /advisor run inside CI?

Yes. Use claude --advisor=auto --task "..." with ANTHROPIC_API_KEY set as a secret. CI runs are non-interactive and write the chosen tier to stdout for logging.

What if /advisor returns nothing?

Usually a context-window overflow or an MCP server holding stale state. Run /clear, restart the CLI, and retry. If it persists, --debug will print the rejection reason.

---

This article was originally published on NextFuture. Follow us for more fullstack & AI engineering content.