Prompting fundamentals

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

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 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:

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

What makes a prompt land

✅ Behavior, not implementation

“When a task is overdue, the row turns red.” Not “Apply bg-red-50 when dueAt < Date.now().”

✅ Concrete user actions

“Click the avatar to open a menu with Profile, Settings, and Sign Out.” Not “Add an avatar menu.”

✅ Named entities

“Add a priority field to tasks.” Not “Add priority somewhere.”

✅ Scope of effect

“On the dashboard only, not on the kanban view.” Constraint = clarity.

❌ Implementation hand-holding

“Use Zustand for state and put it in useTaskStore.” Trust the agent unless you have a strong reason.

❌ Vague qualifiers

“Make it modern” / “Make it fast” / “Improve UX” are unactionable.

❌ Multiple unrelated changes

Three small prompts beat one prompt with three unrelated changes.

❌ Asking for the impossible

“Make it work offline” — does it have a backend? Does it sync? Be specific about the offline model.

Side-by-side examples

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

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

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:

The agent reads structured prompts faster and follows them more accurately. See Structuring prompts for more.

Iteration vs. rewriting

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

Refine the result

Almost — but the assignee dropdown should show avatars, not just
names. Update it to show "[avatar] Name".

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.

Roll back and re-prompt

Use version history to revert, then re-prompt with a clearer spec. Faster than fighting with the existing implementation.

Tips that compound

Use 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.

Use 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.

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.

Next

The five-layer method

The framework. Builds on these fundamentals.

Structuring prompts

For longer prompts that need headers, bullets, and examples.

Debugging prompts

When the agent gets it wrong, here’s how to fix the prompt.