> ## Documentation Index
> Fetch the complete documentation index at: https://vlyai-1c28d863.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Prompting fundamentals

> The mindset and structure of a good vly prompt. The three-line opening that handles most changes, plus the principles behind it.

export const PromptBlock = ({children, variant}) => <div className={`vly-prompt ${variant || ""}`}>{children}</div>;

A great prompt is a great spec. The prompt is the most important code you'll write — everything else flows from it. This page is the foundation; the [five-layer method](/prompting/the-five-layer-method) builds on it.

## The mindset

You are giving instructions to an agent that:

* **Has read your full project context** — schema, files, custom instructions, knowledge base. It knows what exists.
* **Will fill in unstated details** — defaults to vly conventions when you don't specify.
* **Won't ask for clarification mid-build** — once you submit, it commits to an interpretation. (Plan mode is the mid-stream clarification.)

So the goal isn't to over-specify. The goal is to be **specific where it matters and silent where the defaults are fine**.

## The three-line opening

For 80% of edits, this structure works:

> 1. **What** the user-facing change is.
> 2. **Where** in the app it lives.
> 3. **Anything special** — a constraint, an integration, a styling note.

A worked example:

<PromptBlock>
  Add a "Mark all as done" button to the task list. It lives in the header
  of the task list, to the right of the search box. Only show it when at
  least one task is open. Use the secondary button style.
</PromptBlock>

Three sentences. The agent has all it needs to write the right code.

## What makes a prompt land

<CardGroup cols={2}>
  <Card title="✅ Behavior, not implementation" icon="check-circle">
    "When a task is overdue, the row turns red." Not "Apply `bg-red-50` when `dueAt < Date.now()`."
  </Card>

  <Card title="✅ Concrete user actions" icon="check-circle">
    "Click the avatar to open a menu with Profile, Settings, and Sign Out." Not "Add an avatar menu."
  </Card>

  <Card title="✅ Named entities" icon="check-circle">
    "Add a `priority` field to `tasks`." Not "Add priority somewhere."
  </Card>

  <Card title="✅ Scope of effect" icon="check-circle">
    "On the dashboard only, not on the kanban view." Constraint = clarity.
  </Card>

  <Card title="❌ Implementation hand-holding" icon="x-circle">
    "Use Zustand for state and put it in `useTaskStore`." Trust the agent unless you have a strong reason.
  </Card>

  <Card title="❌ Vague qualifiers" icon="x-circle">
    "Make it modern" / "Make it fast" / "Improve UX" are unactionable.
  </Card>

  <Card title="❌ Multiple unrelated changes" icon="x-circle">
    Three small prompts beat one prompt with three unrelated changes.
  </Card>

  <Card title="❌ Asking for the impossible" icon="x-circle">
    "Make it work offline" — does it have a backend? Does it sync? Be specific about the offline model.
  </Card>
</CardGroup>

## Side-by-side examples

<PromptBlock variant="bad">
  Make the dashboard better.
</PromptBlock>

<PromptBlock variant="good">
  On the dashboard, group tasks by status (open / in progress / done) into
  three columns. Tasks within each column are sorted by due date ascending.
  Each task card shows title, due date, and assignee avatar. Clicking a
  card opens the task detail in a slide-over panel.
</PromptBlock>

The bad version asks for "better." The good version says exactly what better means.

<PromptBlock variant="bad">
  Add notifications.
</PromptBlock>

<PromptBlock variant="good">
  Add an in-app notifications system. When a task is assigned to a user,
  create a notification for them. Show a bell icon in the header with an
  unread count badge. Clicking the bell opens a dropdown with the recent
  ten notifications. Clicking a notification marks it read and navigates
  to the linked task.
</PromptBlock>

The bad version forces six unspecified design decisions. The good version makes them explicit.

<PromptBlock variant="bad">
  The list is slow. Fix it.
</PromptBlock>

<PromptBlock variant="good">
  The task list page is slow when there are 200+ tasks. Profile what's
  re-rendering on each task update. Then fix the worst offenders. Consider:
  memoizing TaskRow, paginating to 50 per page, splitting the query into
  smaller subscriptions. Don't change the visible behavior.
</PromptBlock>

The bad version is a guess-game. The good version names the symptom, the threshold, and the constraint ("don't change visible behavior").

## When to use markdown structure

For any prompt longer than \~5 lines, add structure:

<PromptBlock>
  **Goal**: a settings page where users can change their email and password.

  **Where it lives**: `/settings/account`. Add a "Settings" link in the avatar menu in the header.

  **Sections on the page**:

  * Profile (display name, avatar)
  * Email (change email; requires confirmation via the new address)
  * Password (change password; requires entering current password)
  * Danger zone (delete account)

  **Constraints**:

  * Email change shouldn't take effect until confirmed
  * Password change should sign out other sessions
  * Account deletion is two-step (confirmation modal with the user typing their email)
</PromptBlock>

The agent reads structured prompts faster and follows them more accurately. See [Structuring prompts](/prompting/structuring-prompts) for more.

## Iteration vs. rewriting

When something's not quite right, **iterate** — don't rewrite the prompt. Examples:

<Tabs>
  <Tab title="Refine the result">
    ```
    Almost — but the assignee dropdown should show avatars, not just
    names. Update it to show "[avatar] Name".
    ```
  </Tab>

  <Tab title="Add a constraint">
    ```
    Same change, but only allow assigning to people on the same team
    as the task creator. Block other assignments at the schema level.
    ```
  </Tab>

  <Tab title="Roll back and re-prompt">
    Use [version history](/building/version-history) to revert, then re-prompt with a clearer spec. Faster than fighting with the existing implementation.
  </Tab>
</Tabs>

## Tips that compound

<Tip>
  **Use [custom instructions](/building/custom-instructions) for preferences you'd repeat in every prompt.** Things like "always use named functions for top-level components" or "all currency is USD" don't belong in individual prompts — they belong in custom instructions.
</Tip>

<Tip>
  **Use [knowledge base](/building/knowledge-base) for project-specific reference material.** Brand voice, design system rules, schema patterns — drop them into knowledge once, and the agent uses them every time.
</Tip>

<Tip>
  **Read the agent's first response carefully.** If the first response misses the point, your prompt was probably the issue. Refine and resubmit before iterating on the wrong base.
</Tip>

## Next

<CardGroup cols={3}>
  <Card title="The five-layer method" icon="layers" href="/prompting/the-five-layer-method">
    The framework. Builds on these fundamentals.
  </Card>

  <Card title="Structuring prompts" icon="list-tree" href="/prompting/structuring-prompts">
    For longer prompts that need headers, bullets, and examples.
  </Card>

  <Card title="Debugging prompts" icon="bug" href="/prompting/debugging-prompts">
    When the agent gets it wrong, here's how to fix the prompt.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.