Draft LLM-Ready API Deprecation Notices with Migration Syntax

Generates unambiguous API deprecation docs with version cutoffs and side-by-side migration code designed for LLM coding agents to ingest without errors.

Prompt

Prompt
Act as a principal developer relations engineer. Your task is to draft an unambiguous API deprecation and migration notice optimized for ingestion by LLM coding agents and technical search engines.

Before writing, ask me these 3 numbered questions and wait for my response:
1. What is the exact library/SDK name, deprecated method/endpoint, and replacement?
2. What is the hard version cutoff when the legacy syntax is fully removed?
3. What are the key signature or behavior differences between legacy and modern calls?

After I reply, apply these rules:
- State the exact breaking version cutoff in the very first sentence.
- Show side-by-side legacy versus modern syntax code blocks using concrete, runnable snippets without placeholders.
- Explicitly list argument mapping changes, return type differences, and removed parameters as concise bullet points.
- Write a one-sentence directive that automated coding agents can parse to detect deprecated usage.

Output format:
# Deprecation Notice: [Component Name]
- Deprecation Metadata (Table: Deprecated In, Hard Removal Version, Replacement API)
- Direct Migration Guidance (1-2 sentences for automated tools)
- Syntax Comparison (Legacy Example vs Modern Example code blocks)
- Breaking Signature Changes (Bullet list)
- Risks and Edge Cases (Single sentence on runtime errors or silent failures)

Example output

Example for: Python SDK migration from client.query_vectors to client.search_records in version 3.0.0.

Deprecation Notice: Vector Query Client Method

Starting in version 3.0.0, client.query_vectors is permanently removed; replace all calls with client.search_records.

Deprecation Metadata
AttributeDetail
Deprecated Inv2.8.0
Hard Removal Versionv3.0.0
Replacement APIclient.search_records
Module Pathnexus_sdk.v3.client
Direct Migration Guidance

Replace all invocations of nexus_sdk.client.query_vectors with nexus_sdk.v3.client.search_records, mapping the top_k parameter to limit.

Syntax Comparison

Legacy Syntax (v2.8.x):

from nexus_sdk import Client

client = Client(api_key="test_token")
results = client.query_vectors(
    vector=[0.12, 0.45, 0.88],
    top_k=5,
    include_metadata=True
)
for item in results["matches"]:
    print(item["id"], item["score"])

Modern Syntax (v3.0.0+):

from nexus_sdk.v3 import Client

client = Client(api_key="test_token")
results = client.search_records(
    embedding=[0.12, 0.45, 0.88],
    limit=5,
    return_metadata=True
)
for record in results.hits:
    print(record.record_id, record.similarity)
Breaking Signature Changes
  • Renamed vector parameter to embedding.
  • Renamed top_k integer argument to limit.
  • Renamed include_metadata boolean flag to return_metadata.
  • Changed response structure from dictionary access (results["matches"]) to typed attributes (results.hits).
  • Removed namespace parameter; pass collections as a string path inside index_name instead.
Risks and Edge Cases

Passing the old parameter top_k to search_records raises an unhandled TypeError: unexpected keyword argument at runtime.

Written by AI from this prompt. Your results will vary.

Tips and common edits

Why this works

  • Strict legacy vs modern comparisons prevent coding LLMs from mixing up parameter signatures across breaking library versions.
  • Bans placeholders so LLMs indexing your documentation index complete, syntactically valid code blocks.
  • Forces a structured table and agent parsing directive to ensure accurate RAG retrieval by code generation models.

Paste this prompt into Claude or ChatGPT when sunsetting library methods, REST routes, or SDK features so AI assistants suggest the right migration code.

Common edits

  • Add a migration script section if you have an automated codemod CLI tool to recommend.
  • Change the language target from Python to TypeScript or Go depending on your SDK stack.

Make it repeatable

Keep using this prompt without pasting it in every time.

Keep exploring

More in AI SEO