Appendix B — Common Pitfalls and Solutions

When working with AI coding assistants, certain patterns of challenges tend to emerge. This appendix catalogs common pitfalls in the intentional prompting process and provides practical strategies for avoiding or addressing them.

B.1 Over-Reliance on AI

B.1.1 Symptoms

  • Accepting AI-generated code without critical evaluation
  • Inability to explain how your code works
  • Discomfort when working without AI assistance
  • Decreasing ability to solve problems independently

B.1.2 Root Causes

  • Convenience of immediate solutions
  • Pressure to deliver quickly
  • Gradual atrophy of independent problem-solving skills
  • Incomplete understanding of the problem domain

B.1.3 Solutions

B.1.3.1 Intentional Skill Building

  • Schedule regular “AI-free” coding sessions to maintain core skills
  • Implement a personal rule to solve problems manually first, then verify with AI
  • Create deliberate learning challenges in unfamiliar areas

B.1.3.2 Critical Evaluation Process

  • Establish a personal checklist for evaluating AI-generated code
  • Always trace through at least one test case manually
  • Ask “why” questions about design decisions in AI-generated code
  • Look for potential edge cases that might not be handled

B.1.3.3 Balance Strategies

  • Use the six-step methodology to ensure you understand the problem before seeking AI solutions
  • Distinguish between areas where you need to build expertise (limit AI use) and areas where you can leverage AI more heavily
  • Set clear boundaries for when and how you use AI assistance

B.2 Unclear Prompt Formulation

B.2.1 Symptoms

  • Receiving irrelevant or incorrect solutions
  • Needing many iterations to get useful responses
  • Finding yourself frustrated with AI “not understanding” what you want
  • Receiving overly generic or simplistic answers

B.2.2 Root Causes

  • Ambiguous problem descriptions
  • Missing context or requirements
  • Unexpressed assumptions
  • Imprecise terminology

B.2.3 Solutions

B.2.3.1 Structured Prompting Framework

  • Use the templates from Appendix A as starting points
  • Break complex requirements into clear, specific points
  • Include explicit constraints and edge cases
  • Specify the level of detail needed in the response

B.2.3.2 Context Enhancement

  • Provide relevant background information
  • Include code snippets that show the context
  • Specify the programming language and framework
  • Describe the broader system architecture when relevant

B.2.3.3 Iterative Refinement

  • Start with a basic prompt and refine based on initial responses
  • Use phrases like “Let me clarify…” to correct misunderstandings
  • Build upon partial successes rather than completely changing approach
  • Maintain a library of effective prompts for common tasks

B.3 Accepting Incorrect Solutions

B.3.1 Symptoms

  • Discovering bugs after implementation that were present in the AI suggestion
  • Receiving user reports of edge case failures
  • Finding that AI-generated solutions don’t integrate well with existing code
  • Code reviews identifying fundamental flaws in approach

B.3.2 Root Causes

  • Insufficient validation of proposed solutions
  • Misplaced trust in AI capabilities
  • Pressure to deliver quickly
  • Gaps in your own understanding of requirements

B.3.3 Solutions

B.3.3.1 Systematic Verification

  • Always test AI-generated code with multiple inputs, especially edge cases
  • Review security implications, particularly for input handling and data access
  • Check for performance issues with realistic data volumes
  • Verify integration points with existing systems

B.3.3.2 Understanding Before Implementation

  • Request explanations of unfamiliar patterns in generated code
  • Step through complex algorithms manually with example data
  • Compare against alternative approaches
  • Ensure you can explain every part of the solution yourself

B.3.3.3 Incremental Adoption

  • Integrate AI-generated code in small, testable chunks
  • Start with non-critical components to build confidence
  • Implement monitoring for new components to catch issues early
  • Create comprehensive tests before implementing AI suggestions

B.4 Losing Track of the Big Picture

B.4.1 Symptoms

  • Solutions that solve immediate problems but create architectural issues
  • Inconsistent patterns across different parts of the codebase
  • Difficulty explaining how components fit together
  • Growing technical debt from expedient but uncoordinated decisions

B.4.2 Root Causes

  • Focus on tactical code generation rather than strategic design
  • AI’s limited context window and understanding of full system
  • Solving problems in isolation without system-wide perspective
  • Missing architectural guidelines for AI collaboration

B.4.3 Solutions

B.4.3.1 Architectural Discipline

  • Establish clear architectural principles to guide AI prompting
  • Regularly review how individual components fit into the overall system
  • Maintain up-to-date architecture diagrams to reference during development
  • Use the six-step methodology to ensure each solution aligns with system goals

B.4.3.2 Documentation-First Approach

  • Document design decisions before implementing them
  • Create clear interface specifications before coding
  • Maintain a “source of truth” for architectural patterns
  • Implement an architecture decision record (ADR) process

B.4.3.3 System-Level Review

  • Periodically step back to assess the entire system
  • Schedule “architectural reviews” to identify drift from intended design
  • Use visualization tools to understand system evolution
  • Consider how individual changes affect system properties (performance, security, maintainability)

B.6 Prompt Pattern Case Studies

B.6.1 Case Study 1: Debugging a Complex Algorithm

B.6.1.1 Problematic Approach

Initial prompt:

Fix this sorting algorithm, it's not working correctly.

[code snippet]

Issues: - Vague problem description - No information about how it’s failing - No context about requirements or constraints

B.6.1.2 Improved Approach

Better prompt:

I'm debugging this merge sort implementation that fails when the input contains duplicate values.

[code snippet]

Specific issues:
1. When input contains duplicates (e.g., [3,1,3,2]), it produces [1,2,3] instead of [1,2,3,3]
2. It works correctly for inputs without duplicates

I suspect the issue is in the merging step, but I'm not sure exactly what's wrong.
Can you help identify the bug and explain how to fix it?

Improvements: - Specific algorithm identified (merge sort) - Clear description of the failure case - Example input and expected output provided - Indication of where the bug might be located

B.6.2 Case Study 2: Implementing a New Feature

B.6.2.1 Problematic Approach

Initial prompt:

Write a user authentication system for my web app.

Issues: - Extremely broad scope - No information about the technology stack - No specific requirements or constraints - No context about the existing application

B.6.2.2 Improved Approach

Better prompt:

I need to implement user authentication for a React/Node.js web application.

Requirements:
- JWT-based authentication
- Support for email/password login
- Password reset functionality
- Role-based authorization (admin and regular users)
- Integration with existing MongoDB user collection

Current user schema:
```json
{
  "email": String,
  "name": String,
  "created_at": Date
}

I’d like to: 1. Update the user schema to support authentication 2. Implement the backend endpoints for login, registration, and password reset 3. Create a middleware for protecting routes based on authentication 4. Set up the frontend components for the login flow

Can you help me with the schema design and backend implementation first? ```

Improvements: - Specific technology stack identified - Clear, detailed requirements - Existing schema provided for context - Scope broken down into manageable parts - Clear starting point specified

B.7 Confusing Prompt Engineering with Intentional Prompting

B.7.1 Symptoms

  • Focusing exclusively on crafting the perfect prompt to get complete solutions
  • Neglecting the manual work and understanding phases of the methodology
  • Measuring success solely by the quality of AI outputs rather than learning outcomes
  • Minimal critical evaluation of AI-generated solutions
  • Skipping the six-step methodology and moving directly to implementation

B.7.2 Root Causes

  • Misconception that intentional prompting is just about creating better prompts
  • Prioritizing short-term efficiency over long-term understanding
  • Not fully grasping the educational purpose of the intentional prompting methodology
  • Confusing the means (good prompts) with the end (developer understanding and growth)

B.7.3 Solutions

B.7.3.1 Clarify the Distinction

  • Remember that prompt engineering is a set of techniques while intentional prompting is a complete methodology
  • Recognize that prompt engineering focuses on getting optimal outputs while intentional prompting focuses on the human development process
  • Understand that prompt engineering is a component of intentional prompting, not a replacement for it

B.7.3.2 Balance Output and Process

  • Follow the complete six-step methodology even when it seems faster to skip steps
  • Evaluate success based on both the quality of the solution AND your understanding of it
  • Set aside time specifically for the “Work by Hand” and “Test with Data” steps, which are often neglected
  • Document your learning insights separate from code outputs

B.7.3.3 Adopt a Learning Mindset

  • Ask AI to explain its solutions rather than just accepting them
  • Challenge yourself to modify and extend AI-generated code
  • Practice explaining solutions to others without referring to AI explanations
  • Identify gaps in your understanding and use AI to fill them deliberately

B.8 Key Takeaways

  • Be intentional about balancing AI assistance with skill development to maintain your capabilities
  • Invest time in clear, detailed prompts to save time in iterative refinement
  • Always verify AI-generated solutions through testing and manual review
  • Maintain system-level perspective when implementing individual components
  • Address ethical and legal concerns proactively through documentation and transparent processes
  • Learn from failures by analyzing and improving your prompting approach
  • Distinguish between prompt engineering techniques and the intentional prompting methodology

By recognizing and addressing these common pitfalls, you can maximize the benefits of AI assistance while avoiding its potential drawbacks.