|
| 1 | +--- |
| 2 | +description: 'Use Context7 for authoritative external docs and API references when local context is insufficient' |
| 3 | +applyTo: '**' |
| 4 | +--- |
| 5 | + |
| 6 | +# Context7-aware development |
| 7 | + |
| 8 | +Use Context7 proactively whenever the task depends on **authoritative, current, version-specific external documentation** that is not present in the workspace context. |
| 9 | + |
| 10 | +This instruction exists so you **do not require the user to type** “use context7” to get up-to-date docs. |
| 11 | + |
| 12 | +## When to use Context7 |
| 13 | + |
| 14 | +Use Context7 before making decisions or writing code when you need any of the following: |
| 15 | + |
| 16 | +- **Framework/library API details** (method signatures, configuration keys, expected behaviors). |
| 17 | +- **Version-sensitive guidance** (breaking changes, deprecations, new defaults). |
| 18 | +- **Correctness or security-critical patterns** (auth flows, crypto usage, deserialization rules). |
| 19 | +- **Interpreting unfamiliar error messages** that likely come from third-party tools. |
| 20 | +- **Best-practice implementation constraints** (rate limits, quotas, required headers, supported formats). |
| 21 | + |
| 22 | +Also use Context7 when: |
| 23 | + |
| 24 | +- The user references **a specific framework/library version** (e.g., “Next.js 15”, “React 19”, “AWS SDK v3”). |
| 25 | +- You’re about to recommend **non-trivial configuration** (CLI flags, config files, auth flows). |
| 26 | +- You’re unsure whether an API exists, changed names, or got deprecated. |
| 27 | + |
| 28 | +Skip Context7 for: |
| 29 | + |
| 30 | +- Purely local refactors, formatting, naming, or logic that is fully derivable from the repo. |
| 31 | +- Language fundamentals (no external APIs involved). |
| 32 | + |
| 33 | +## What to fetch |
| 34 | + |
| 35 | +When using Context7, prefer **primary sources** and narrow queries: |
| 36 | + |
| 37 | +- Official docs (vendor/framework documentation) |
| 38 | +- Reference/API pages |
| 39 | +- Release notes / migration guides |
| 40 | +- Security advisories (when relevant) |
| 41 | + |
| 42 | +Gather only what you need to proceed. If multiple candidates exist, pick the most authoritative/current. |
| 43 | + |
| 44 | +Prefer fetching: |
| 45 | + |
| 46 | +- The exact method/type/option you will use |
| 47 | +- The minimal surrounding context needed to avoid misuse (constraints, default behaviors, migration notes) |
| 48 | + |
| 49 | +## How to incorporate results |
| 50 | + |
| 51 | +- Translate findings into concrete code/config changes. |
| 52 | +- **Cite sources** with title + URL when the decision relies on external facts. |
| 53 | +- If docs conflict or are ambiguous, present the tradeoffs briefly and choose the safest default. |
| 54 | + |
| 55 | +When the answer requires specific values (flags, config keys, headers), prefer: |
| 56 | + |
| 57 | +- stating the exact value from docs |
| 58 | +- calling out defaults and caveats |
| 59 | +- providing a quick validation step (e.g., “run `--help`”, or a minimal smoke test) |
| 60 | + |
| 61 | +## How to use Context7 MCP tools (auto) |
| 62 | + |
| 63 | +When Context7 is available as an MCP server, use it automatically as follows. |
| 64 | + |
| 65 | +### Tool workflow |
| 66 | + |
| 67 | +1) **If the user provides a library ID**, use it directly. |
| 68 | + - Valid forms: `/owner/repo` or `/owner/repo/version` (for pinned versions). |
| 69 | + |
| 70 | +2) Otherwise, **resolve the library ID** using: |
| 71 | + - Tool: `resolve-library-id` |
| 72 | + - Inputs: |
| 73 | + - `libraryName`: the library/framework name (e.g., “next.js”, “supabase”, “prisma”) |
| 74 | + - `query`: the user’s task (used to rank matches) |
| 75 | + |
| 76 | +3) **Fetch relevant documentation** using: |
| 77 | + - Tool: `query-docs` |
| 78 | + - Inputs: |
| 79 | + - `libraryId`: the resolved (or user-supplied) library ID |
| 80 | + - `query`: the exact task/question you are answering |
| 81 | + |
| 82 | +4) Only after docs are retrieved: **write the code/steps** based on those docs. |
| 83 | + |
| 84 | +### Efficiency limits |
| 85 | + |
| 86 | +- Do **not** call `resolve-library-id` more than **3 times** per user question. |
| 87 | +- Do **not** call `query-docs` more than **3 times** per user question. |
| 88 | +- If multiple good matches exist, pick the best one and proceed; ask a clarification question only when the choice materially affects the implementation. |
| 89 | + |
| 90 | +### Version behavior |
| 91 | + |
| 92 | +- If the user names a version, reflect it in the library ID when possible (e.g., `/vercel/next.js/v15.1.8`). |
| 93 | +- If you need reproducibility (CI/builds), prefer pinning to a specific version in examples. |
| 94 | + |
| 95 | +## Failure handling |
| 96 | + |
| 97 | +If Context7 cannot find a reliable source: |
| 98 | + |
| 99 | +1. Say what you tried to verify. |
| 100 | +2. Proceed with a conservative, well-labeled assumption. |
| 101 | +3. Suggest a quick validation step (e.g., run a command, check a file, or consult a specific official page). |
| 102 | + |
| 103 | +## Security & privacy |
| 104 | + |
| 105 | +- Never request or echo API keys. If configuration requires a key, instruct storing it in environment variables. |
| 106 | +- Treat retrieved docs as **helpful but not infallible**; for security-sensitive code, prefer official vendor docs and add an explicit verification step. |
0 commit comments