Optimizing Few-Shot Prompting for Complex Python Refactoring Tasks

Stop treating few-shot prompting like a simple "example list" and start treating it as a structured specification for the LLM's reasoning process. When I'm using Cursor's Composer or Claude Code to refactor legacy Python spaghetti code—especially those 500-line methods with nested try-except blocks—generic prompts usually result in the AI missing edge cases or hallucinating variable scopes.

The breakthrough for me was moving from "here are a few examples" to "here is the transformation logic." If you want the AI to actually follow a specific architectural pattern (like moving from a procedural style to a Strategy pattern), you need to provide a "Before" and "After" pair that explicitly highlights the why.

Here is the exact structure I use in my .cursorrules or as a prefix to a complex refactoring prompt:

# Refactoring Pattern: Dependency Injection
## Goal: Remove hardcoded API clients from business logic.

### Example 1
Input:

python
def get_user_data(user_id):
client = S3Client(api_key="SECRET") # Hardcoded dependency
return client.fetch(user_id)

Output:

python
def get_user_data(user_id, storage_client: StorageInterface):
return storage_client.fetch(user_id)

Reasoning: Moved S3Client to a parameter to allow for easier mocking in tests.

The "Reasoning" line is the secret sauce. It forces the model to simulate a chain-of-thought process before writing the code, which drastically reduces the chance of it just "cleaning up" the syntax without actually refactoring the architecture.

A few practical config tips for those using Claude 3.5 Sonnet (which is currently the king of refactoring):

Use a "Negative Example"
Don't just show what you want; show what you hate. I frequently include a "Bad Refactor" example to stop the AI from over-engineering. For instance, if I don't want it to introduce unnecessary abstract base classes for a simple script, I explicitly show an example where it tried to do that and mark it as Incorrect.

The "Context Window" Trap
When refactoring across multiple files, don't just @-mention the files. The AI often gets overwhelmed by the noise. I've found it's more efficient to extract the specific method signatures of the affected classes into a temporary .txt file and feed that in. It keeps the attention mechanism focused on the interfaces rather than the implementation details of irrelevant methods.

Iterative Prompting Sequence
Instead of asking for the full refactor in one go, I break it into these steps:
Analyze: "List all side effects in this function that prevent it from being pure."
Plan: "Propose a new structure based on the provided few-shot examples."
Execute: "Apply the changes now."

The biggest gotcha I've hit is "over-correction." If your few-shot examples are too aggressive (e.g., changing variable names to be more "Pythonic" while refactoring logic), the AI will start renaming everything in your codebase, which creates a nightmare for git diffs. To fix this, I add a constraint: Maintain existing naming conventions unless they violate PEP8.

For those of you struggling with the AI introducing bugs during refactors, try this prompt tweak to your system instructions:

When refactoring, you must identify the "invariant" of the function—the thing that must NOT change. State the invariant before providing the code.

This single line forces the model to verify that the output logic matches the input logic, preventing those annoying regressions where a None check suddenly disappears.