Try this:
1. Break it down by job type. Instead of "refactor the codebase to make use of the new JobDefinition.create", identify each distinct job type and refactor them one at a time. This keeps the context focused and prevents the agent from getting overwhelmed.
2. For many jobs, script it. If you have dozens/hundreds of jobs to refactor, write a shell script that:
for job_type in "EmailJob" "DataProcessingJob" "ReportJob"; do
claude --dangerously-skip-permissions -p "Refactor only ${job_type} to use the new JobDefinition.create signature: make it async, pass databaseClient at creation, remove return value and 'Job created' logs. Change ONLY ${job_type} files."
git add -A && git commit -m "Refactor ${job_type} to new signature"
done
3. Consider a migration shim. Have Claude create a compatibility layer so jobs can work with either the old or new signature during the refactor. This lets you test incrementally without breaking everything at once.
4. Your prompt needs clarity. Here's a clearer version:
Refactor ONLY [SpecificJobName] class to match the new JobDefinition.create signature:
- OLD: create(batch) returns result, synchronous
- NEW: create(queue, databaseClient) returns void, async
- Remove any "Job created" console.log statements
- Do NOT modify unrelated code, reorder parameters, or rename variables
Pro tip: Use Claude itself to improve your prompts! Try:
claude -p "Help me write a clearer prompt for this refactoring task: [paste your original prompt]"
The key insight is that agentic tools excel at focused, well-defined transformations but struggle when the scope is too broad or the instructions are ambiguous. "Don't do anything else" is not an instruction that Claude does a good job of interpreting. The "going off the rails" behavior you're seeing is Claude trying to be helpful by "improving" code it encounters, which is why explicit constraints ("ONLY do X") are crucial rather than specifying a broad directive concerning what it shouldn't do.