> ## Documentation Index
> Fetch the complete documentation index at: https://alexcode.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Guidelines for effective code assistance and documentation usage in Alex Sidebar

## Writing Effective Prompts

<CardGroup cols={2}>
  <Card title="Clear Objectives" icon="target">
    * Be specific about your goals
    * State what you want to achieve
    * Provide clear success criteria
  </Card>

  <Card title="Contextual Details" icon="layer-group">
    * Share relevant code snippets
    * Include error messages
    * Mention project requirements
  </Card>
</CardGroup>

## Using Think First Mode

<CardGroup cols={2}>
  <Card title="When to Use" icon="brain">
    * Complex architectural decisions
    * Bug investigation
    * Performance optimization
    * Security considerations
  </Card>

  <Card title="When to Skip" icon="forward">
    * Quick syntax questions
    * Simple code completions
    * Documentation lookups
    * Basic refactoring
  </Card>
</CardGroup>

### Tips for Think First Mode

* Allow extra time for the dual-model processing
* Provide detailed context for better analysis
* Use it for mission-critical code changes
* Consider disabling for rapid prototyping phases

### Examples

<Note>
  ❌ **Ineffective**: `My code isn't working. Can you help?`
</Note>

<Note>
  ✅ **Effective**: `I'm getting a 'Thread 1: Fatal error: Unexpectedly found nil' when trying to unwrap an optional UIImage in my custom UICollectionViewCell. Here's my cellForItemAt implementation...`
</Note>

<Note>
  ✅ **Feature Request**: `I need to implement a custom tab bar in SwiftUI that shows a circular progress indicator around the selected tab icon. The progress should be animated. Here's my current TabView implementation...`
</Note>

## Managing Context

<CardGroup cols={2}>
  <Card title="File Context" icon="folder">
    * Use @ Files to add specific files
    * Include related dependencies
    * Share configuration files
  </Card>

  <Card title="Codebase Context" icon="code">
    * Use @ Codebase for framework-level questions
    * Reference specific components
    * Share relevant modules
  </Card>
</CardGroup>

### Examples

<Note>
  ❌ **Limited**: `How do I update this delegate method?`
</Note>

<Note>
  ✅ **Complete**: `I need to update this UITableViewDelegate method to handle custom swipe actions. Here's my current implementation (@Files TableViewController.swift) and the custom SwipeActionView (@Files Views/SwipeActionView.swift) I want to integrate.`
</Note>

<Note>
  ✅ **Framework**: `I'm building a custom networking layer (@Codebase Networking/*). Can you help me implement proper retry logic with exponential backoff?`
</Note>

## Using Documentation

<CardGroup cols={2}>
  <Card title="Apple Documentation" icon="apple">
    * Use @ Apple Docs for framework reference
    * Reference specific APIs
    * Include version information
  </Card>

  <Card title="Individual Docs" icon="book">
    * Use @ Apple Docs (Individual) for specific methods
    * Reference specific classes
    * Include parameter details
  </Card>
</CardGroup>

### Examples

<Note>
  ❌ **Vague**: `How do I use Core Data?`
</Note>

<Note>
  ✅ **Specific**: `I need help implementing NSFetchedResultsController (@Apple Docs NSFetchedResultsController) with multiple sections based on dates. Here's my current Core Data model (@Files Model.xcdatamodeld)...`
</Note>

<Note>
  ✅ **API Reference**: `Can you explain how to use URLSession's (@Apple Docs URLSession) background download tasks with proper delegate handling (@Apple Docs URLSessionDownloadDelegate)?`
</Note>

## Platform-Specific Best Practices

<CardGroup cols={2}>
  <Card title="Swift Best Practices" icon="swift">
    * Use Swift-specific terminology
    * Reference Swift documentation
    * Include Swift version
  </Card>

  <Card title="UIKit/AppKit" icon="code">
    * Reference UI frameworks
    * Include view hierarchy
    * Share layout constraints
  </Card>
</CardGroup>

### Examples

<Note>
  ❌ **Ambiguous**: `How do I create a button?`
</Note>

<Note>
  ✅ **SwiftUI**: `I'm using SwiftUI (iOS 16+) and need to create a custom button with a gradient background, dynamic shadow, and haptic feedback. Here's my current Button implementation...`
</Note>

<Note>
  ✅ **UIKit Integration**: `I need to embed this SwiftUI view (@Files CustomView.swift) into my existing UIKit navigation stack. Here's my current UIHostingController setup...`
</Note>

## Common Scenarios

<CardGroup cols={2}>
  <Card title="Debugging" icon="bug">
    * Share error messages
    * Include stack traces
    * Reference relevant code
  </Card>

  <Card title="Refactoring" icon="code-branch">
    * Explain current structure
    * Describe desired outcome
    * Share relevant files
  </Card>
</CardGroup>

### Examples

<Note>
  ❌ **Unclear**: `The app crashes sometimes.`
</Note>

<Note>
  ✅ **Detailed**: `The app crashes when switching between tabs while a network request is in progress. Here's the crash log and relevant networking code (@Files NetworkManager.swift). The issue started after implementing async/await...`
</Note>

<Note>
  ✅ **Refactoring**: `I want to refactor this massive view controller (@Files ProfileViewController.swift) into smaller components using MVVM. Here's my planned architecture diagram...`
</Note>

### Examples

<Note>
  ❌ **Too Much**: `Sharing entire project files for a simple UI fix`
</Note>

<Note>
  ✅ **Just Right**: `Continuing from our previous chat about the networking layer (see chat history), I need to add request caching. Here's the specific RequestCaching protocol I want to implement...`
</Note>

<Note>
  ✅ **Breaking Down**: \`I need to migrate this UIKit project to SwiftUI. Let's break it down:

  1. First, let's handle the navigation structure
  2. Then, convert each view controller individually
  3. Finally, implement the data flow with @StateObject and ObservableObject\`
</Note>

## Working with Build Errors

<CardGroup cols={2}>
  <Card title="Build & Fix Errors Button" icon="hammer">
    * Use for automatic error resolution
    * Alex handles the entire build-fix cycle by using Xcode's build system
    * No manual intervention needed
    * Continues until build succeeds
  </Card>
</CardGroup>

### When to Use Automatic Build & Fix

<AccordionGroup>
  <Accordion title="Ideal Scenarios">
    * Multiple compilation errors
    * Missing imports or protocols
    * Type mismatches
    * Initialization errors
    * Access control issues
  </Accordion>

  <Accordion title="Manual Intervention Needed">
    * Complex architectural decisions
    * Business logic errors
    * Performance optimizations
    * Custom framework integration
  </Accordion>
</AccordionGroup>

### Examples

<Note>
  ✅ **Automatic Fix**: `Click "Build & Fix Errors" when you see multiple red errors in Xcode. Alex will handle missing imports, protocol conformance, and type issues automatically one by one until the build succeeds.`
</Note>

### Build Error Best Practices

1. **Let Alex Work**: Do not interrupt the build-fix loop unless necessary
2. **Review Changes**: Always review the final working code
3. **Save Progress**: Use checkpoints after successful builds

## Community Resources

<Note>
  Need more help? Join the [Discord community](https://discord.gg/T5zxfReEnd)
  for support and tips from other developers.
</Note>