[FEATURE] Proactive Anthropic SDK best-practice suggestions when building against @anthropic-ai/sdk

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

• Claude Code doesn't have special awareness of Anthropic's own SDK. When generating code that uses @anthropic-ai/sdk, Claude Code misses opportunities to suggest SDK methods and API best practices that would prevent common mistakes.

• [Concrete example]: I was building a log analysis pipeline that calls the Messages API. Claude Code wrote a character-based token estimation heuristic

(serialized.length / 3.5) to decide whether to split API calls into chunks :/ This led to arbitrary fixed chunking at 600 items per call, using only ~15% of the 200k context window -
which introduced cross-call blindness and unnecessary latency for weeks.

• The SDK already had client.messages.countTokens() available for exact token counting. Claude Code imported @anthropic-ai/sdk at the top of the file but never suggested using this

method. It also didn't suggest prompt caching (cache_control: { type: 'ephemeral' }) or mention that the API response includes cache_read_input_tokens /cache_creation_input_tokens for monitoring cache hit rates.

These are core SDK capabilities that directly affect code quality.

Proposed Solution

When Claude Code detects that a project imports @anthropic-ai/sdk (or anthropic in Python), it should apply SDK-specific awareness:

1. Token counting: When it sees code estimating tokens via character math or hardcoded heuristics, suggest client.messages.countTokens() instead.

1. Prompt caching: When it sees repeated API calls with identical system prompts (e.g., chunked processing loops), suggest adding cache_control: { type: 'ephemeral' } to the system blocks.

1. Response usage fields: When building code that processes API responses, surface that usage.cache_read_input_tokens and usage.cache_creation_input_tokens are available for

monitoring.

1. Context window sizing: When it sees hardcoded chunk sizes or batch limits for API calls, flag if the math doesn't match the model's actual context window.

This could be implemented as a built-in awareness layer (similar to how Claude Code already knows about Next.js conventions) or as documentation that's automatically loaded when the SDK import is detected.

Alternative Solutions

• Dev can read the SDK docs, but the whole point of Claude Code is to reduce that overhead (I hope)
• Include SDK tips pre-project in CLAUDE.md files

Priority

High - Significant impact on productivity

Feature Category

Performance and speed

Use Case Example

• Dev creates a new file that imports @anthropic-ai/sdk
• They write a function that calls anthropic.messages.create() in a loop, splitting input into fixed-size chunks
• Claude Code recognizes this pattern and suggests:
• "The SDK has client.messages.countTokens() -> use it to size chunks based on actual token count instead of a fixed number" - "Your system prompt is identical across calls -> add cache_control: { type: 'ephemeral' } to avoid re-processing it"
• Dev avoids shipping under-utilized API calls and gets prompt caching for free
• This saves API cost, reduces latency, and produces better results (full dataset in one call vs. fragmented chunks)

Additional Context

Claude Code should be the best possible guide for its own SDK, which creates a flywheel:
better Claude Code → better apps built on Claude → more API usage → more feedback.:)