ai-features

# AI Features & LLM Integration

AI features should make your product 10x better at its core job, not be a marketing checkbox. This skill helps you choose the right AI pattern, manage costs, and ship AI features that users actually value.

## Core Principles

- AI features should make your product 10x better at its core job, not be a marketing checkbox.
- Start with the API, not a custom model. You don't need to train anything.
- Cost per API call matters at scale. Design for it from day one.
- Prompt engineering is your product differentiator. The model is the same for everyone.
- Always have a fallback. AI features should degrade gracefully, not crash the app.

## When to Add AI Features

### Add AI When:

- Users do something repetitive that AI could automate (drafting, categorizing, summarizing)
- Users need help interpreting data (analysis, recommendations, insights)
- You can save users significant time on a task they do frequently
- AI makes your product dramatically easier for non-experts to use
- Competitors have AI features and users expect parity

### Don't Add AI When:

- It's just a chatbot wrapper with no product context
- You're adding it for marketing ("AI-powered!") without clear user benefit
- The task requires 100% accuracy (legal, medical, financial decisions)
- A simple rule-based approach would work just as well
- You haven't validated that users want it

---

## AI Feature Patterns for SaaS

### Pattern 1: Smart Drafts / Generation

**What:** AI writes a first draft that users edit and refine.

**Examples:** Email drafts, report summaries, product descriptions, social posts.

**Tell AI:**
```
Add an AI draft feature to [describe where in the app].
When the user clicks "Generate draft," call the Claude API with:
- Context from [what data the AI should use]
- A system prompt that produces [describe the output format]
- User can edit the result before saving
Include: loading state, error handling, and a "regenerate" button.
Use the Claude API with the claude-sonnet-4-5-20250929 model.
```

### Pattern 2: Summarization / Analysis

**What:** AI condenses or interprets data the user has collected.

**Examples:** Meeting notes summary, customer feedback themes, dashboard insights.

**Tell AI:**
```
Add an AI summary feature that analyzes [data type].
Input: [describe the data — e.g., "all customer feedback from the last 30 days"]
Output: [describe what you want — e.g., "top 5 themes with supporting quotes"]
Display the summary in a card on [page name].
Cache the result so we don't re-call the API on every page load.
```

### Pattern 3: Categorization / Tagging

**What:** AI automatically labels or categorizes incoming data.

**Examples:** Support ticket routing, lead scoring, content tagging.

**Tell AI:**
```
Auto-categorize incoming [items] using AI.
Categories: [list your categories]
When a new [item] is created, call the API to assign a category.
Store the result in the database. Allow users to override.
Use the cheapest model that works (start with claude-haiku-4-5-20251001).
```

### Pattern 4: Smart Search / Q&A (RAG)

**What:** Users ask questions and get answers based on their own data.

**Examples:** "Search my documents," knowledge base Q&A, internal wiki search.

**How RAG works (simplified):**
```
1. User's documents → Split into chunks → Store as embeddings in vector DB
2. User asks a question → Convert to embedding → Find relevant chunks
3. Send relevant chunks + question to LLM → Get answer
```

**Tell AI:**
```
Add a Q&A feature where users can ask questions about their [data].
Use RAG (Retrieval-Augmented Generation):
- Embed their [documents/data] using [embedding model]
- Store embeddings in [Supabase pgvector / Pinecone]
- On query, retrieve top 5 relevant chunks
- Send to Claude with context for answer generation
Include: source citations, "I don't know" handling, loading state.
```

### Pattern 5: AI-Powered Recommendations

**What:** Suggest next actions or choices based on user behavior and data.

**Examples:** "Try this feature next," product recommendations, workflow suggestions.

---

## Choosing a Model

| Model | Cost | Speed | Best For |
|-------|------|-------|----------|
| Claude Haiku 4.5 | Cheapest | Fastest | Categorization, short responses, high-volume tasks |
| Claude Sonnet 4.5 | Medium | Medium | Most features — drafts, summaries, analysis |
| Claude Opus 4.6 | Highest | Slowest | Complex reasoning, multi-step analysis |
| GPT-4o mini | Cheap | Fast | Alternative to Haiku for simple tasks |
| GPT-4o | Medium | Medium | Alternative to Sonnet |

**Rule of thumb:** Start with the cheapest model. Only upgrade if quality isn't good enough.

---

## Cost Management

### Estimating Costs

```
Cost per request = (input tokens × input price) + (output tokens × output price)

Example (Claude Sonnet):
- Input: ~1,000 tokens ($0.003)
- Output: ~500 tokens ($0.0075)
- Cost per request: ~$0.01

1,000 requests/day = ~$10/day = ~$300/month
```

### Reducing Costs

| Strategy | How |
|----------|-----|
| Use the cheapest model that works | Start with Haiku, upgrade only if needed |
| Cache responses | Same input = same output. Don't re-call |
| Limit output length | Set max_tokens to what you actually need |
| Batch requests | Combine multiple small requests into one |
| Rate limit per user | Prevent abuse with per-user daily limits |
| Use streaming | Better UX (users see progress) and same cost |

### Setting Usage Limits

```
Free plan: 10 AI requests/day
Starter plan: 50 AI requests/day
Pro plan: 500 AI requests/day
Enterprise: Unlimited (with fair use policy)
```

---

## Prompt Engineering for Product Features

Your prompts are your competitive advantage. Write them like product specs:

### System Prompt Template

```
You are [role] helping [user type] with [task].

Context about this user:
- [User's plan/tier]
- [Relevant user data]

Rules:
- [Output format requirements]
- [Tone and style]
- [What NOT to include]
- [Length constraints]

Output format:
[Exact format you want]
```

### Tips

- Be specific about output format — JSON, markdown, bullet points
- Include examples of good output in the prompt
- Set boundaries: what the AI should NOT do
- Test with edge cases: empty input, very long input, foreign languages
- Version your prompts and track which version performs best

---

## Implementation Checklist

```
Before shipping an AI feature:
- [ ] Clear user value defined (what does this save/improve?)
- [ ] Model selected (cheapest that meets quality bar)
- [ ] System prompt written and tested with 10+ examples
- [ ] Loading state shown while AI processes
- [ ] Error handling: API down, rate limited, bad response
- [ ] Fallback if AI is unavailable (manual mode still works)
- [ ] Usage limits per plan tier
- [ ] Cost monitoring set up (track spend per day/week)
- [ ] User can edit/override AI output (AI assists, user decides)
- [ ] Response cached where appropriate
```

---

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Using the most expensive model for everything | Start with Haiku. Upgrade per-feature only when needed |
| No cost monitoring | Track API spend daily. Set billing alerts |
| No usage limits | Rate limit per user and per plan tier from day one |
| AI output shown as "truth" | Always let users edit/override. AI assists, humans decide |
| No loading state | AI calls take 1-10 seconds. Show a spinner or stream the response |
| Generic chatbot instead of focused feature | Build specific AI features tied to user workflows, not a general chat |
| No fallback when API is down | App should still work. AI features degrade gracefully |
| Hardcoded prompts with no iteration | Version your prompts. A/B test them. Iterate based on user feedback |

---

## Success Looks Like

- AI features that users specifically mention as why they chose your product
- Cost per AI request tracked and predictable
- AI usage driving upgrades to higher tiers
- Users editing AI output 20-30% of the time (means AI is good but not blindly trusted)
- API costs are less than 10% of the revenue those features generate

---

## Related Skills

- **build** — Hand your AI feature spec to Claude Code or Lovable and build it
- **pricing** — Design tiers with AI usage limits as a value metric
- **analytics** — Track AI feature usage and its impact on activation/retention
- **secure** — Protect user data flowing through AI APIs