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

# Writing Effective Prompts

> How to communicate effectively with Specode's AI agents to get the best results.

## How Prompting Works in Specode

Specode's guided workflow handles the heavy lifting for you. When you start a new project, you describe your idea in plain language and the **Planning Agent** asks clarifying questions to scope your app. You don't need a detailed spec upfront — the AI guides you through the details.

Where prompting skills matter most is during **iteration** — after your first build is ready and you're refining features, fixing layouts, or adding new functionality.

<Tip>
  **Starting a new project?** Just describe your idea simply and let the Planning Agent guide you. Save the detailed prompts for when you're iterating on a working app.
</Tip>

## Understanding Specode

Think of the Specode AI as a highly skilled developer who:

<CardGroup cols={2}>
  <Card title="Healthcare Expertise" icon="puzzle-piece">
    Understands healthcare workflows like EMR, scheduling, and intake
  </Card>

  <Card title="Healthcare Knowledge" icon="stethoscope">
    Understands healthcare regulations and best practices
  </Card>

  <Card title="Custom Development" icon="code">
    Can build features based on your descriptions
  </Card>

  <Card title="Visual References" icon="image">
    Can use uploaded screenshots and mockups to understand what you want
  </Card>
</CardGroup>

## Core Principles for Effective Prompts

### Be Specific, Not Vague

<CodeGroup>
  ```text ✅ Effective theme={null}
  I need to add a preferred pharmacy field to the intake form. It should include pharmacy name, address, and phone number so providers know where to send prescriptions.
  ```

  ```text ❌ Too Vague theme={null}
  Add a preferred pharmacy field.
  ```
</CodeGroup>

### Describe User Journeys, Not Technical Implementation

<CodeGroup>
  ```text ✅ Effective theme={null}
  When patients cancel an appointment, they should select a reason from a dropdown.
   If they choose "other", show a text box for details. 
   Then send this information as a notification to the provider.
  ```

  ````text ❌ Too Technical theme={null}
  Render a dropdown list of predefined reasons. If the user selects 'Other', conditionally display a 
  text input field for free-form entry. Capture the selected reason (and text input if applicable), 
  then include this data in the cancellation event payload and dispatch it as a notification to the 
  assigned provider.```
  ````
</CodeGroup>

### Build Incrementally, Not All at Once

<CodeGroup>
  ```text ✅ Effective theme={null}
  I want to implement a "View Availability" button that patients can view.
  First create the button, located right above the "Book" button on the provider card. 
  It will be non-functional for now.
  ```

  ```text ❌ Too Ambitious theme={null}
  Create a "View Availability" feature that allows patients to view provider availability.
  ```
</CodeGroup>

**Follow Up Prompts**

```
Now let's make the button functional. When the user click's on "View Availability", open a new modal.
```

**Follow Up Prompts**

```
In this new modal, add the calendar ui component. Above it, include the title text "Select a date".
```

Then  continue to iterate incrementally until you achieve your desired functionality.

### Include Context and Requirements

Always specify:

<AccordionGroup>
  <Accordion title="User Roles">
    Who will use this feature (patients, doctors, staff, administrators)
  </Accordion>

  <Accordion title="Data Requirements">
    Specific fields or data that need to be collected or displayed
  </Accordion>

  <Accordion title="Compliance Needs">
    Any specific healthcare compliance requirements beyond basics
  </Accordion>

  <Accordion title="Integration Points">
    How this feature connects with other parts of your system
  </Accordion>
</AccordionGroup>

## Effective Request Patterns

### Creating New Features

**Template:**

```text theme={null}
I need a [feature type] that allows [user type] to [action]. It should [specific requirements] and [integration needs].
```

**Example:**

```text theme={null}
I need a no-show fee waiver request form that allows patients to explain why they missed
their appointment. It should include:
- A dropdown with common reasons (emergency, transportation issues, illness, work conflict, other)
- A required text field for detailed explanation (minimum 50 characters)
- The patient's contact information pre-filled from their profile
- A checkbox to acknowledge the fee policy
- Submit button that routes the request to the patient's primary provider for approval
- The provider should receive an in-app notification with approve/deny options
```

### Modifying Existing Features

**Template:**

```text theme={null}
Can you modify the [existing feature] to [new behavior]? Currently it [current behavior], but I need it to [desired behavior].
```

**Example:**

```text theme={null}
Can you modify the patient intake form to include a visual allergy severity scale?
Currently it just has a text field for allergies, but I need it to:
- Display a 1-5 severity scale with visual indicators (1=mild to 5=severe/life-threatening)
- Use color coding: green (1-2), yellow (3), orange (4), red (5)
- Include icons for common allergens (medications, foods, environmental, latex)
- Allow multiple allergies with different severity levels
- Show a warning banner if any allergy is marked as severe (4-5)
- Make the allergy section required if the patient indicates they have allergies
```

### Fixing Issues

**Template:**

```text theme={null}
The [feature] is [problem description]. When [steps to reproduce], 
it [what happens]. It should [expected behavior].
```

**Example:**

```text theme={null}
The provider notes are not saving properly. 
When I type notes during a video call and click save, the notes disappear. 
It should save them to the patient's record and show a confirmation.
```

### Adding API Integrations

Adding an integration is a conversation with the AI. Here's the typical flow:

**Step 1: Request the integration**

```text theme={null}
I want to integrate Twilio to send SMS appointment reminders. 
When an appointment is booked, send a confirmation text to the patient's phone number.
```

**Step 2: Ask what credentials you need**

```text theme={null}
What API keys do I need to add in Project Settings for Twilio to work?
```

The AI will tell you exactly which keys to get (e.g., Account SID, Auth Token, Phone Number).

**Step 3: Add credentials and confirm**

After you get your keys from the external service and add them to Project Settings:

```text theme={null}
I added my Twilio credentials to Project Settings. Here are the values:
- TWILIO_ACCOUNT_SID: AC1234...
- TWILIO_AUTH_TOKEN: abc123...
- TWILIO_PHONE_NUMBER: +1555...

Can you verify the integration works?
```

The AI will execute or test the integration with your credentials.

<Note>
  See our [Integration Setup Guide](/overview/configuration-deployment/integrations) for step-by-step instructions on adding credentials to Project Settings.
</Note>

## What Specode Handles Automatically

You don't need to specify:

<CardGroup cols={2}>
  <Card title="Technical Implementation" icon="gear">
    Databases, APIs, server configuration
  </Card>

  <Card title="Basic Security" icon="shield-check">
    Encryption, secure connections, authentication
  </Card>

  <Card title="Standard Compliance" icon="certificate">
    Basic HIPAA requirements and healthcare standards
  </Card>

  <Card title="Responsive Design" icon="mobile">
    Mobile optimization and cross-device compatibility
  </Card>
</CardGroup>

<Note>
  **Ready to start building?** Try your first prompt with Specode, or continue to [Theming & Design Changes](/overview/getting-started/theming-design-changes) to learn about visual customization.
</Note>