Prompt Engineering for AI Coding Assistants: Best Practices

Your Prompt
    │
    ▼
Token Encoding
(Convert to numerical representation)
    │
    ▼
Context Assembly
(Combine your prompt with project context, files, etc.)
    │
    ▼
Model Processing
(AI reasoning and generation)
    │
    ▼
Token Decoding
(Convert back to readable text)
    │
    ▼
Post-Processing
(Syntax highlighting, language detection)
    │
    ▼
Output to IDE

├── Your current prompt
├── Recent conversation history
├── Open files in your IDE
├── Highlighted/selected code
├── Project files and structure
├── Comments and documentation
├── CLAUDE.md (if present)
├── Git history and diffs
├── Error messages
└── Any explicitly provided context

Generate a React component for a product card that displays:
- Product image (from props)
- Product name (bold, 18px)
- Product description (max 2 lines, ellipsis)
- Price with currency symbol
- Add to cart button

The component should:
- Be fully responsive (mobile and desktop)
- Use Tailwind CSS for styling
- Follow this design pattern:

<div className="border rounded-lg overflow-hidden">
  <img src={image} alt={name} className="w-full" />
  <div className="p-4">
    ...rest of content...
  </div>
</div>

Return a TypeScript component with proper typing.

I need to build a checkout system. Let's do this step by step:

Step 1: Create the CheckoutForm component
- Should collect: shipping address, billing address, payment method
- Should validate addresses
- Should show loading state during submission

Step 2: Implement order creation API
- Should validate input
- Should handle payment processing
- Should create order in database

Let's start with Step 1. Here's the current form structure:
[include current code]

Please generate the complete form component with validation.

Add comprehensive tests for the login function with these requirements:
- Use Jest and React Testing Library
- Test successful login with valid credentials
- Test failed login with invalid credentials
- Test network error handling
- Test loading state during request
- Achieve minimum 90% code coverage
- Follow the testing patterns in src/tests/auth.test.ts

Before asking a question, provide:
1. The full file or function in question
2. Related files that provide context
3. Error messages or test failures
4. Recent git history or comments
5. Project README or documentation

Turn 1: "Here's my authentication flow. Does it look secure?"
Turn 2: "Thanks for the feedback. Can you help me add rate limiting?"
Turn 3: "Perfect. Now can we add audit logging?"

I'm redesigning my data layer. Currently using:
- Direct database queries in route handlers
- No abstraction layer
- Tightly coupled to Postgres-specific features

I want to:
- Add a repository pattern
- Support multiple databases eventually
- Improve testability

Can you recommend an architecture and show me how to refactor one route as an example?

// Good: Copilot understands the pattern
// src/services/userService.ts
export async function getUserById(id: string): Promise<User> {
  // Copilot now understands this pattern and can complete similar functions
}

export async function getPostsByUserId(userId: string): Promise<Post[]> {
  // Copilot continues the pattern
}

// Function to validate email format and check if already registered
function validateEmail(email) {
  // Copilot understands both requirements from comment
}

// Instead of long explanation, write clear function signature:
async function fetchAndProcessUserData(userId: string): Promise<ProcessedData> {
  // Copilot infers most of what you need from function name and return type
}

@codebase I see we have a pattern in PaymentService for retry logic.
Can I use the same pattern in the EmailService?

Looking at src/components/Form.tsx and src/hooks/useForm.ts,
can you refactor both to use React Hook Form instead of custom state?

# CLAUDE.md - Project Instructions

## Project Structure
- `/src/app` - Next.js App Router routes
- `/src/components` - React components
- `/src/lib` - Utilities and helpers
- `/src/types` - TypeScript type definitions

## Coding Standards
- Use TypeScript in strict mode
- Components use functional syntax with hooks
- Always include error handling
- Write tests using Jest + React Testing Library
- Use Tailwind CSS for styling only

## Code Review Checklist
Before shipping:
1. [ ] TypeScript compilation passes
2. [ ] Linting passes (eslint --fix)
3. [ ] Tests pass and coverage > 80%
4. [ ] No console errors or warnings
5. [ ] Responsive design tested
6. [ ] Accessibility checked (ARIA attributes, keyboard nav)

## Key Patterns
### API Route Pattern
All API routes use this error handling:
```typescript
try {
  // Do work
  return NextResponse.json({ success: true, data });
} catch (error) {
  console.error('API Error:', error);
  return NextResponse.json({ error: 'message' }, { status: 500 });
}

export interface ComponentProps {
  // Required properties
}

export function MyComponent({ ...}: ComponentProps) {
  // Implementation
}

### Why CLAUDE.md Works

Instead of repeating context in every prompt, CLAUDE.md establishes baseline understanding:

**Without CLAUDE.md**:

**With CLAUDE.md**:

### Creating an Effective CLAUDE.md

Include:
- Project purpose and philosophy
- Technology stack and versions
- Project structure
- Code style and patterns
- Testing requirements
- Common architectural patterns
- Key dependencies and their usage
- Deployment and environment info
- Error handling standards
- Security considerations
- Performance requirements

## Project-Level Context Strategy

### Structuring Context for Maximum Clarity

**Layer 1: Project Philosophy (CLAUDE.md)**
```markdown
# Philosophy
This is a minimalist AI prompt platform.
Design aesthetic: clean, white/black/gray theme.
Code quality: clarity, simplicity, accessibility.

src/auth/
├── hooks/          # useAuth, useProtectedRoute
├── components/     # LoginForm, LogoutButton
├── services/       # authentication API calls
├── types.ts        # TypeScript interfaces
└── constants.ts    # Auth-related constants

/**
 * Authentication hook for accessing current user and login/logout
 *
 * Usage:
 *   const { user, login, logout, loading } = useAuth();
 *
 * Features:
 *   - Automatically loads user from storage on mount
 *   - Handles token refresh
 *   - Persists auth state to localStorage
 */
export function useAuth() {
  // ...
}

I'm working on src/auth/hooks/useAuth.ts.
Current implementation: [show relevant code]
Problem: [describe issue]
Requirements: [what it must do]
Related files: [point to auth services]

Please review this code for [specific concerns]:

CONTEXT:
- Purpose: [What this code does]
- Framework: [React, Next.js, etc.]
- Pattern: [Follows pattern X from src/patterns/]

CODE:
[Paste code here]

SPECIFIC CONCERNS:
1. Security: Does it safely handle user input?
2. Performance: Any optimization opportunities?
3. Testing: Is it testable? What edge cases?
4. Maintainability: Follows project patterns?
5. Accessibility: ARIA attributes? Keyboard nav?

CONSTRAINTS:
- Must use React hooks, not class components
- Cannot add external dependencies
- Must maintain TypeScript strict mode

Review this authentication code for security vulnerabilities:
- Input validation
- Credential handling
- Token management
- CSRF protection
[Code]

Review for performance issues:
- Unnecessary renders?
- Inefficient queries?
- Memory leaks?
- Bundle size impact?
[Code]

Does this follow our architecture patterns?
Our patterns are defined in CLAUDE.md.
[Code]

PROBLEM:
[Error message or unexpected behavior]

REPRODUCTION:
[Steps to reproduce the issue]

EXPECTED:
[What should happen]

ACTUAL:
[What actually happens]

CONTEXT:
- Relevant code: [paste function/component]
- Related files: [list files involved]
- Recent changes: [what changed]
- Environment: [browser, Node version, etc.]

DEBUGGING STEPS TAKEN:
[What you've already tried]

PROBLEM: Form validation state not updating

REPRODUCTION:
1. Load /login
2. Enter email
3. Click outside input
4. Check console - no validation error

EXPECTED: Validation error displays

ACTUAL: No error shown

RELEVANT CODE:
[useForm hook implementation]
[FormInput component]

Has this ever worked? When did it break?

PROBLEM: POST /api/users returns 500

REPRODUCTION:
1. Call POST /api/users with valid payload
2. Check Network tab

EXPECTED: 201 Created with user ID

ACTUAL: 500 Internal Server Error

ENVIRONMENT: Node 20, PostgreSQL 15

SERVER LOG:
[Paste error from logs]

RECENT CHANGES:
[List recent commits]

CURRENT STATE:
[Paste current code]

DESIRED STATE:
[Describe what you want]

CONSTRAINTS:
[What must remain the same]

MIGRATION:
[How to handle existing usage]

PRIORITIES:
1. [Most important]
2. [Next important]
3. [Nice to have]

I want to refactor this class component to use hooks:
[Class component code]

CONSTRAINTS:
- Keep same public API
- Maintain prop compatibility
- All existing tests must pass

PATTERNS TO FOLLOW:
See src/hooks/ for our hook patterns

Can you generate the refactored version?

I have validation logic duplicated across 3 files:
- src/auth/validate.ts (email, password)
- src/forms/validate.ts (form fields)
- src/api/validate.ts (API responses)

Can you consolidate into a unified validation library
with these characteristics:
- Shared validation rules
- Easy to extend
- Type-safe (TypeScript)
- Composable validators

Generate documentation for [this code]:

FORMAT:
[JSDoc, Markdown, README section, etc.]

AUDIENCE:
[Developers, API users, contributors, etc.]

INCLUDE:
- [ ] Usage examples
- [ ] Parameter descriptions
- [ ] Return values
- [ ] Error handling
- [ ] Common patterns
- [ ] Edge cases

CODE:
[Paste the code to document]

Generate JSDoc for this authentication function:

[Paste function]

Include:
- Description of what it does
- Parameters with types
- Return value with type
- Throws (error cases)
- Usage examples

Generate OpenAPI/Swagger documentation for these routes:

[List/paste route handlers]

Include:
- Request/response schemas
- Success and error responses
- Authentication requirements
- Rate limiting info

Let's think through this authentication flow step by step:

1. User enters credentials
   - What validation is needed?
   - What could go wrong?

2. Credentials are sent to server
   - What security measures?
   - How to handle timeouts?

3. Token is returned
   - Where to store it?
   - When to refresh?

4. Token is used for requests
   - How to attach to requests?
   - How to handle expiration?

Now write the complete implementation following this logic.

I need to implement a file upload feature. Let's break it into steps:

Step 1: Frontend Upload Component
- File input
- Progress indicator
- Preview

Step 2: API Route for Upload
- Receive file
- Validate
- Store

Step 3: Error Handling
- Client-side validation
- Server-side validation
- User feedback

Step 4: Tests
- Happy path
- Error cases

Let's implement Step 1 first. [Provide current code]

I have two approaches to this problem:

APPROACH A:
[Show code]
Pros: Speed, simplicity
Cons: Limited scalability

APPROACH B:
[Show code]
Pros: Scalable, flexible
Cons: More complex

Which is better for my use case [describe project context]?
Can you show how to evolve A into B?

# Code Review Checklist Prompt

You'll use this when:
- Reviewing critical code
- Before production deployment
- Mentoring junior developers

Template:
```
Review [file] with these requirements:
- [ ] Type safety: All variables properly typed
- [ ] Error handling: Catches and handles errors
- [ ] Performance: No obvious inefficiencies
- [ ] Security: Proper input validation
- [ ] Testing: Code is testable
- [ ] Accessibility: ARIA, keyboard nav
- [ ] Performance: Follows [project] patterns

Focus areas:
[Include specific concerns for this review]