Best Practices

Answer two questions from current sources: what's the recommended way, and what bites people (the gotchas and pitfalls around it). A how-to without its pitfalls is half an answer.

Two-Phase Rule

• Phase 1: Research. Dispatch find-docs and/or web search queries (WebSearch in Claude Code, web_search in Codex).
• Phase 2: Synthesize and act. Starts only after Phase 1 results arrive.

The user's argument may be a question or an imperative. Imperatives ("refine X", "set up Y") determine what Phase 2 does, not whether Phase 1 happens. Phase 1 always runs.

Workflow

1. Break the topic into 2-4 specific queries. Dedicate at least one query to pitfalls ("common mistakes with X", "X gotchas in production"): pitfalls live in issue threads, migration guides, and post-mortems, not in getting-started docs. Dedicate one query to how leading open source projects or production teams do it, which can differ from what the docs recommend. For single-library lookups, call find-docs or web search directly without subagents.
2. Dispatch one subagent per query in a single message: in Claude Code, pass model: sonnet on each Agent call; in Codex, spawn them in one request, selecting a faster model in each spawn. Open each brief with the user's situation and constraints, so the findings fit their setup. Tell each subagent to use find-docs and web search, to settle questions about a tool, package, or script by reading it, to run one only when reading can't and only sandboxed (pass along the sandbox command your instructions name), and to report in under 400 words: the recommended approach, concrete code/config examples, and every pitfall it found with its consequence, including minor or uncertain ones (its job is coverage; you rank and filter), with each claim citing its source and publication date.
3. Present the recommended approach, key patterns, and gotchas covering every recommendation (not just the primary one), each claim keeping its source citation.