Troubleshooting

Reference intermediate

Common Prompting Problems and Solutions

Problem: AI Produces Generic/Tutorial-Quality Code

Symptoms: Output looks like a Stack Overflow answer or textbook example. Placeholder values, overly simple logic, missing production concerns.

Cause: Prompt reads like a learning question rather than a production request.

Solution:

  • Add context about your actual system: "This handles 10K requests/minute"
  • Include real data shapes, not foo and bar
  • Specify: "Production-ready, not example code"
  • Add constraints that force real-world thinking: "Handle network timeouts, partial failures, and concurrent access"
  • Provide your actual types/interfaces for the AI to implement against

Problem: AI Ignores Part of Your Prompt

Symptoms: Some requirements are implemented, others are silently skipped.

Cause: Prompt is too long or requirements are buried in prose. AI loses track of items in long paragraphs.

Solution:

  • Use numbered lists for requirements (easier to track)
  • Put the most critical requirement first
  • Break into multiple prompts if you have more than 5-7 requirements
  • After output, verify: "Did you address items 1-7 from my requirements?"
  • Bold or capitalize critical constraints: "MUST handle null inputs"

Problem: Output Is Correct But Wrong Style

Symptoms: Functionally correct code that uses different patterns, naming, or structure than your codebase.

Cause: No style reference provided; AI uses its own defaults.

Solution:

  • Paste an example function from your codebase and say "match this style"
  • List specific conventions: "camelCase, async/await, early returns, named exports"
  • Reference your linter config: "Follow the rules in our ESLint config"
  • Specify anti-patterns: "Do not use classes, use functions with closures"

Problem: AI Adds Unrequested Features

Symptoms: Output includes logging, error tracking, analytics, caching, or other features you never asked for.

Cause: AI infers "production code" means full-featured; tries to be helpful.

Solution:

  • Be explicit about scope: "Only [the thing I asked for], nothing else"
  • Add: "Do not add features I did not request"
  • Specify what is handled elsewhere: "Logging is handled by middleware, do not add it here"
  • Use the word "minimal": "Minimal implementation that satisfies these requirements"

Problem: AI Cannot Follow Multi-Step Logic

Symptoms: Later steps contradict earlier steps, or the AI loses track of state built up across the prompt.

Cause: Complex prompts exceed the model's reasoning capacity in a single pass.

Solution:

  • Split into separate prompts, building incrementally
  • After each step, confirm the output before proceeding
  • Provide explicit state: "Given that step 1 produced [this], now do step 2"
  • Use the chain approach: output of prompt 1 becomes input for prompt 2

Problem: AI Generates Code That Does Not Compile

Symptoms: Syntax errors, missing imports, undefined variables, type mismatches.

Cause: AI does not actually execute code; it predicts plausible tokens.

Solution:

  • Include the exact TypeScript/language version: "TypeScript 5.3 strict mode"
  • Provide the relevant imports and types it needs to reference
  • Ask: "Verify this compiles correctly with strict TypeScript"
  • Paste the compile error back and ask for a fix
  • Keep generated units small (easier to get right)

Problem: Same Prompt Gets Different Results Each Time

Symptoms: Running the same prompt produces inconsistent quality or different approaches.

Cause: Model stochasticity; ambiguous prompts have many valid solutions.

Solution:

  • Add more constraints to narrow the solution space
  • Specify the exact approach: "Use a Map for O(1) lookups"
  • Lower temperature if available in your tool settings
  • Include an example of desired output format
  • Accept that small variations are normal; focus on correctness

Problem: AI Produces Overly Verbose Explanations

Symptoms: You wanted code but got paragraphs of explanation. Or code is wrapped in excessive comments.

Cause: Default behavior is to explain; prompt did not specify otherwise.

Solution:

  • End prompt with: "Return only the code, no explanations"
  • Specify: "No comments unless the logic is non-obvious"
  • Use tool-specific features (e.g., Cursor's inline edit mode returns code only)
  • If you need explanation separately: "First show the code, then explain in a separate section"

Problem: AI Gets Defensive or Hedges

Symptoms: Responses full of "I'm not sure but...", "you might want to consider...", "this might not be exactly right..." without actually producing code.

Cause: Ambiguous prompt makes the AI uncertain; safety training causes hedging.

Solution:

  • Be more specific so the AI has confidence in what you want
  • Remove ambiguity from the prompt
  • Add: "Commit to a single approach and implement it fully"
  • Provide enough context that there is one clear right answer
  • If genuinely ambiguous, ask it to list assumptions then proceed

Problem: Prompt Is Too Long and Expensive

Symptoms: Hitting token limits, slow responses, high API costs.

Cause: Including too much context or repeating information.

Solution:

  • Include only the relevant 10-20 lines, not entire files
  • Summarize context instead of pasting everything
  • Use project rules files (.cursorrules, AGENTS.md) for persistent context
  • Remove pleasantries and filler words from prompts
  • Reference previous output: "Using the function from my last message..."
  • Extract shared context into system prompts where supported