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

# Prompt Crafting for Different Models

> Model-specific prompting techniques to get better results from Claude, GPT, and other models.

Different AI models respond better to different prompting styles. This guide covers model-specific techniques and provides ready-to-use prompt refiner skills.

<Info>
  **Works everywhere:** These prompting techniques apply to both CLI and [Factory App](/web/getting-started/overview).
</Info>

***

## Universal Prompting Principles

These principles work across all models:

<AccordionGroup>
  <Accordion title="Be specific about the outcome">
    **Weak:** "Fix the bug in auth"

    **Strong:** "Fix the login timeout bug where users get logged out after 5 minutes of inactivity. The session should persist for 24 hours."
  </Accordion>

  <Accordion title="Provide context before instructions">
    **Weak:** "Add error handling"

    **Strong:** "This API endpoint handles payment processing. It currently crashes silently on network errors. Add error handling that logs the error, returns a user-friendly message, and triggers an alert."
  </Accordion>

  <Accordion title="Include acceptance criteria">
    **Weak:** "Make it faster"

    **Strong:** "Optimize the search query. Success criteria: query time under 100ms for 10k records, no change to result accuracy, passes existing tests."
  </Accordion>

  <Accordion title="Specify constraints explicitly">
    **Weak:** "Refactor this code"

    **Strong:** "Refactor this code to use the repository pattern. Constraints: don't change the public API, maintain backward compatibility, keep the same test coverage."
  </Accordion>
</AccordionGroup>

***

## Claude Models (Opus, Sonnet, Haiku)

Claude models excel with structured, explicit instructions and respond particularly well to certain formatting patterns.

### Key Techniques for Claude

<Steps>
  <Step title="Use XML tags for structure">
    Claude responds exceptionally well to XML-style tags for organizing complex prompts:

    ```
    <context>
    This is a React application using TypeScript and Zustand for state management.
    The auth module handles user sessions and JWT tokens.
    </context>

    <task>
    Add a "remember me" checkbox to the login form that extends session duration to 30 days.
    </task>

    <requirements>
    - Store preference in localStorage
    - Update JWT expiration accordingly
    - Add unit tests for the new functionality
    </requirements>
    ```
  </Step>

  <Step title="Put examples in dedicated sections">
    When you want specific output formats, show examples:

    ```
    <example>
    Input: "user not found"
    Output: { code: "USER_NOT_FOUND", message: "The specified user does not exist", httpStatus: 404 }
    </example>

    Now handle these error cases following the same pattern:
    - Invalid password
    - Account locked
    - Session expired
    ```
  </Step>

  <Step title="Use thinking prompts for complex reasoning">
    For complex decisions, ask Claude to think through options:

    ```
    Before implementing, analyze:
    1. What are the tradeoffs between approach A and B?
    2. Which approach better fits our existing patterns?
    3. What edge cases should we consider?

    Then implement the better approach.
    ```
  </Step>
</Steps>

<Tip>
  Copy the prompt refiner skills below to `~/.factory/skills/` to use them. Learn more about skills in the [Skills documentation](/cli/configuration/skills).
</Tip>

### Claude Prompt Refiner Skill

Create `~/.factory/skills/prompt-refiner-claude/SKILL.md`:

```markdown theme={null}
---
name: prompt-refiner-claude
description: Refine prompts for Claude models (Opus, Sonnet, Haiku) using Anthropic's best practices. Use when preparing complex tasks for Claude.
---

# Claude Prompt Refiner

## When to Use
Invoke this skill when you have a task for Claude that:
- Involves multiple steps or files
- Requires specific output formatting
- Needs careful reasoning or analysis
- Would benefit from structured context

## Refinement Process

### 1. Analyze the Draft Prompt
Review the user's prompt for:
- [ ] Clear outcome definition
- [ ] Sufficient context
- [ ] Explicit constraints
- [ ] Success criteria

### 2. Apply Claude-Specific Patterns

**Structure with XML tags:**
- `<context>` - Background information, codebase state
- `<task>` - The specific action to take
- `<requirements>` - Must-have criteria
- `<constraints>` - Limitations and boundaries
- `<examples>` - Sample inputs/outputs if helpful

**Ordering matters:**
1. Context first (what exists)
2. Task second (what to do)
3. Requirements third (how to do it)
4. Examples last (clarifying edge cases)

### 3. Enhance for Reasoning
For complex tasks, add:
- "Think through the approach before implementing"
- "Consider these edge cases: ..."
- "Explain your reasoning for key decisions"

### 4. Output the Refined Prompt
Present the improved prompt with:
- Clear section headers
- XML tags where beneficial
- Specific, measurable criteria

## Example Transformation

**Before:**
"Add caching to the API"

**After:**
```

<context>
  The /api/products endpoint currently queries the database on every request.
  Average response time is 200ms. We use Redis for other caching in the app.
</context>

<task>
  Add Redis caching to the /api/products endpoint to reduce database load.
</task>

<requirements>
  * Cache TTL of 5 minutes
  * Cache invalidation when products are updated
  * Graceful fallback to database if Redis is unavailable
  * Add cache hit/miss metrics logging
</requirements>

<constraints>
  * Don't change the response format
  * Must pass existing integration tests
  * Use our existing Redis connection from src/lib/redis.ts
</constraints>

```
```

***

## GPT Models (GPT-5, GPT-5.1, Codex)

GPT models excel with clear system-level context and benefit from explicit role framing.

### Key Techniques for GPT

<Steps>
  <Step title="Frame the role explicitly">
    GPT models respond well to clear role definitions:

    ```
    You are a senior TypeScript developer reviewing code for a production e-commerce platform.
    Focus on: type safety, error handling, and performance.

    Review this checkout flow implementation...
    ```
  </Step>

  <Step title="Use numbered steps for procedures">
    GPT follows numbered instructions reliably:

    ```
    Complete these steps in order:
    1. Read the current implementation in src/auth/
    2. Identify all places where tokens are validated
    3. Create a centralized token validation utility
    4. Update all call sites to use the new utility
    5. Add unit tests for the utility
    6. Run the test suite and fix any failures
    ```
  </Step>

  <Step title="Be explicit about output format">
    Specify exactly what you want:

    ```
    Return your analysis as a markdown document with these sections:
    ## Summary (2-3 sentences)
    ## Issues Found (bulleted list)
    ## Recommended Changes (numbered, in priority order)
    ## Code Examples (if applicable)
    ```
  </Step>
</Steps>

### GPT Prompt Refiner Skill

Create `~/.factory/skills/prompt-refiner-gpt/SKILL.md`:

```markdown theme={null}
---
name: prompt-refiner-gpt
description: Refine prompts for GPT models (GPT-5, GPT-5.1, Codex) using OpenAI's best practices. Use when preparing complex tasks for GPT.
---

# GPT Prompt Refiner

## When to Use
Invoke this skill when you have a task for GPT that:
- Requires a specific persona or expertise
- Involves procedural steps
- Needs structured output
- Benefits from explicit examples

## Refinement Process

### 1. Analyze the Draft Prompt
Review for:
- [ ] Clear role/persona definition
- [ ] Step-by-step breakdown (if procedural)
- [ ] Output format specification
- [ ] Concrete examples

### 2. Apply GPT-Specific Patterns

**Role framing:**
Start with "You are a [specific role] working on [specific context]..."

**Numbered procedures:**
Break complex tasks into numbered steps that build on each other.

**Output specification:**
Be explicit: "Return as JSON", "Format as markdown with headers", etc.

**Chain of thought:**
For reasoning tasks, add: "Think through this step by step."

### 3. Structure the Prompt

**Effective order for GPT:**
1. Role definition (who/what)
2. Context (background info)
3. Task (what to do)
4. Steps (how to do it, if procedural)
5. Output format (what to return)
6. Examples (optional clarification)

### 4. Output the Refined Prompt
Present with:
- Clear role statement
- Numbered steps where applicable
- Explicit output requirements

## Example Transformation

**Before:**
"Review this code for security issues"

**After:**
```

You are a senior security engineer conducting a security audit of a Node.js payment processing service.

Context: This service handles credit card transactions and communicates with Stripe's API. It runs in AWS ECS.

Task: Review the code in src/payments/ for security vulnerabilities.

Steps:

1. Check for proper input validation on all endpoints
2. Verify secrets are not hardcoded or logged
3. Review authentication and authorization logic
4. Check for SQL injection and XSS vulnerabilities
5. Verify proper error handling that doesn't leak sensitive info

Output format:
Return a security report in markdown with:

* **Critical**: Issues that must be fixed before deployment
* **High**: Significant risks that should be addressed soon
* **Medium**: Improvements to consider
* **Recommendations**: General security enhancements

For each issue, include:

* File and line number
* Description of the vulnerability
* Recommended fix with code example

```
```

***

## Gemini Models

Gemini models handle long context well and work effectively with structured reasoning.

### Key Techniques for Gemini

<Steps>
  <Step title="Leverage long context">
    Gemini can handle extensive context—don't be afraid to include more background:

    ```
    Here's the full module structure for context:
    [include relevant files]

    Based on these patterns, implement a new service that...
    ```
  </Step>

  <Step title="Use reasoning levels effectively">
    Gemini supports Low and High reasoning. Use High for:

    * Architecture decisions
    * Complex debugging
    * Multi-step planning

    Use Low for:

    * Straightforward implementations
    * Code generation from specs
    * Routine refactoring
  </Step>
</Steps>

***

## Model Selection Strategy

Match the model to the task:

| Task Type                   | Recommended Model           | Reasoning Level |
| --------------------------- | --------------------------- | --------------- |
| **Complex architecture**    | Opus 4.7 or Opus 4.6        | High-Max        |
| **Feature implementation**  | Sonnet 4.5 or GPT-5.1-Codex | Medium          |
| **Quick edits, formatting** | Haiku 4.5                   | Off/Low         |
| **Code review**             | GPT-5.1-Codex-Max           | High            |
| **Bulk automation**         | GLM-5 (Droid Core)          | None            |
| **Research/analysis**       | Gemini 3 Pro                | High            |

***

## Creating Your Own Prompt Refiner

For team-specific needs, create a custom prompt refiner:

```markdown theme={null}
---
name: prompt-refiner-team
description: Refine prompts using our team's conventions and project context.
---

# Team Prompt Refiner

## Our Conventions
- We use the repository pattern
- All services have interfaces defined first
- Tests use our custom test utilities from @/test-utils

## Checklist for Prompts
1. [ ] References relevant existing code
2. [ ] Specifies which layer (API, service, repository)
3. [ ] Mentions related tests to update
4. [ ] Includes acceptance criteria

## Template
```

Context: \[What exists, what module/layer]
Task: \[Specific action]
Patterns to follow: \[Reference existing similar code]
Tests: \[What tests to add/update]
Done when: \[Acceptance criteria]

```
```

***

## Quick Reference Card

### Claude (Opus/Sonnet/Haiku)

* ✅ XML tags for structure
* ✅ Context before instructions
* ✅ Examples in dedicated sections
* ✅ "Think through..." for reasoning

### GPT (GPT-5/Codex)

* ✅ Role framing ("You are a...")
* ✅ Numbered step procedures
* ✅ Explicit output format
* ✅ "Step by step" for reasoning

### Gemini

* ✅ Extensive context inclusion
* ✅ Low/High reasoning levels
* ✅ Structured output requests

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Setup Checklist" href="/guides/power-user/setup-checklist" icon="list-check">
    Complete power user configuration
  </Card>

  <Card title="Token Efficiency" href="/guides/power-user/token-efficiency" icon="gauge-high">
    Reduce costs while maintaining quality
  </Card>
</CardGroup>