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

# Build with Agent

> Learn five practical habits for working with Agent: be specific, plan the work, add context, review and test, and use checkpoints.

Agent is Replit's AI builder and your companion for turning ideas into software. Agent can plan changes, write code, explain behavior, debug issues, and improve your app.

[Vibe coding 101](https://docs.replit.com/learn/foundations/vibe-coding-101.md) explains the mindset, while this page explains how to work with Agent in practice. [Effective prompting](https://docs.replit.com/learn/effective-prompting.md) explains how to write clearer instructions.

Think of Agent as the quarterback on the field: it reads the situation, chooses a path, and moves the work forward. You are the coach: you set the strategy, call the play, review what happened, and decide the next move.

Agent can do a lot, but it works best when you lead the process: be specific, plan the work, add context, review and test, and use checkpoints when you need to recover.

## Five tips for building with Agent

Use these habits when you work with Agent:

1. Be specific.
2. Plan the work.
3. Add context.
4. Review and test.
5. Use checkpoints.

## Be specific

Agent can handle complex work, but it needs clear direction.

A useful request explains what you want, what matters, and what should stay the same. It does not need to describe every implementation detail, but it should give Agent enough direction to make good decisions.

Instead of:

Make my app better.

Try:

Improve the signup page so visitors understand what the product does before
creating an account.

Keep the current color palette, keep the form fields the same, and make the
primary button more obvious.

The second prompt gives Agent a goal, a focus area, and constraints.

When your request has several parts, say what matters most.

Add a simple admin view for managing catering requests.

The most important part is being able to see new requests, mark them as
contacted, and filter by status.

Keep the first version simple.

Agent can break that work into steps, but your direction tells it what success looks like.

For more examples of specific instructions, see [Effective prompting](https://docs.replit.com/learn/effective-prompting.md).

## Plan the work

Planning helps when the work has uncertainty, multiple steps, tradeoffs, or anything you want to approve before files change.

You can ask Agent to make a plan in the conversation:

Before making changes, create a plan for adding online ordering.

Include the user flow, data needed, pages or components that will change,
risks, and how I should test it.

Use [Plan mode](https://docs.replit.com/features/agent/plan-mode.md) when you want Agent to think first and wait for your approval before changing files. Toggle **Plan** in the prompt composer before submitting.

![The Replit home prompt box with a running app prompt typed in and the Plan checkbox toggled on](https://mintcdn.com/replit/63zH0ZBPWnbQaqFI/images/fitstart/work-with-agent/agent-plan-mode-prompt.png?fit=max\&auto=format\&n=63zH0ZBPWnbQaqFI\&q=85\&s=4eb27dd607f04e5559b2acb80d4489bf)

Add attachment

Plan

Start voice input
Start

When Agent finishes thinking, you will see a **task plan is ready for review** banner with a **Review now** button.

![A task plan is ready for review banner with a Review now button at the bottom of the Agent panel](https://mintcdn.com/replit/63zH0ZBPWnbQaqFI/images/fitstart/work-with-agent/agent-plan-ready-banner.png?fit=max\&auto=format\&n=63zH0ZBPWnbQaqFI\&q=85\&s=b2082775cc2f4da9243a88589eac5ab5)

## Add context

Context helps Agent understand what matters.

You can add context with text, screenshots, sketches, files, data, errors, or Canvas annotations. Use the format that best explains the problem.

Use text when the change is about behavior, goals, or constraints:

Context: this app is for parents ordering birthday cakes.

Keep the form short, make pickup details obvious, and avoid anything that
feels corporate.

Use screenshots or sketches when layout is hard to describe in words:

Use this screenshot as layout direction for the request form.

Match the overall structure, but keep the existing fields and submission
behavior.

Use [Canvas](https://docs.replit.com/design/canvas.md) annotations when the change is visual and you want to point to a specific part of the app.

![A fitness app frame on the Canvas with a rectangle, arrow, and text label pointing at the progress card, plus a pen sketch and label on the form area](https://mintcdn.com/replit/63zH0ZBPWnbQaqFI/images/fitstart/work-with-agent/agent-canvas-annotations.png?fit=max\&auto=format\&n=63zH0ZBPWnbQaqFI\&q=85\&s=db21c9df13df76c84d98d99cf7fc9730)

Use my Canvas annotations to update the hero section.

Apply the notes to the headline, image, and primary button only.

Do not change the catering request form.

Good context also includes what should not change. That helps Agent improve one area without accidentally rewriting another.

## Review and test

Agent may propose a plan before building, and it may summarize what changed afterward. Read both.

Open the plan by selecting **View** on the task plan card. The expanded plan shows what Agent intends to build, the success criteria, what is out of scope, and the steps Agent will follow.

![Expanded task plan showing What and Why, Done looks like criteria, Out of scope items, and numbered build steps](https://mintcdn.com/replit/63zH0ZBPWnbQaqFI/images/fitstart/work-with-agent/agent-plan-content.png?fit=max\&auto=format\&n=63zH0ZBPWnbQaqFI\&q=85\&s=5106f59ceb7b41aa26e3bb8c22daa6bf)

Before Agent builds, review the plan:

* Does this solve the right problem?
* Is anything missing?
* Is anything out of scope?
* Is there a smaller version to build first?
* Does it explain how you should test the result?

If the plan is too broad, ask Agent to reduce it.

This plan is too broad.

Reduce it to the smallest version I can test today.

Move everything else into a future improvements list.

After Agent builds, test the app yourself. Open Preview and use it like the person it is for.

Check:

* Can someone complete the main action?
* Did the requested change happen?
* Does the app still work on mobile?
* Did any important behavior break?
* Did Agent change something unrelated?
* Is the result good enough to keep building on?

If something is wrong, describe what you saw.

Instead of:

Fix the form.

Try:

When I submit the catering request form, the success message appears, but the
form still shows the old text.

Clear the form after submission and keep the success message visible.

Specific feedback helps Agent fix the right issue.

## Use checkpoints

Checkpoints help you recover when a change goes in the wrong direction.

Use focused feedback when the result is close:

This is close, but the form is now too long.

Keep the new visual style, remove the optional notes field, and make the
pickup date easier to scan.

Use a checkpoint when the app is worse than before, important behavior broke, or Agent changed more than expected.

Open **History** in the Agent panel to see checkpoints. Each checkpoint shows what changed, with **Rollback here** and **Changes** controls.

![The Agent History panel showing a checkpoint labeled 'Transitioned from Plan to Build mode' with Rollback here and Changes buttons](https://mintcdn.com/replit/63zH0ZBPWnbQaqFI/images/fitstart/work-with-agent/agent-checkpoints-history.png?fit=max\&auto=format\&n=63zH0ZBPWnbQaqFI\&q=85\&s=fdc1aa8d372341fae140542f3adebad1)

When you select **Rollback here**, Agent confirms what will be restored before applying the rollback.

![The Rollback to checkpoint confirmation dialog listing the target checkpoint and what will be impacted: files, Agent memory, tasks, and a Database checkbox](https://mintcdn.com/replit/63zH0ZBPWnbQaqFI/images/fitstart/work-with-agent/agent-checkpoints-rollback-dialog.png?fit=max\&auto=format\&n=63zH0ZBPWnbQaqFI\&q=85\&s=cb8fc415dac91353f209eea5f85aa06a)

If you are unsure whether to fix forward or roll back, ask Agent to help compare.

The last change made the app worse.

Compare the current version to the previous working version.

Tell me whether it is safer to fix forward or roll back, and explain why.

Wrong turns are normal. Checkpoints let you explore without losing the ability to return to a safer version.

For more recovery guidance, see [Checkpoints and rollbacks](https://docs.replit.com/features/version-control/checkpoints-and-rollbacks.md).

## What good Agent collaboration feels like

You are on the right track when:

* Your requests explain the goal and constraints
* Agent's plan is clear enough to review
* You add screenshots, files, or Canvas notes when words are not enough
* You test important flows after changes
* You give focused feedback when something is off
* You use checkpoints instead of trying to untangle a bad change forever

## Next step

> [card]
>
> Learn how to write clearer instructions that Agent can act on confidently.
>
> [Open](https://docs.replit.com/learn/effective-prompting.md)

> [card] [Build your first app](https://docs.replit.com/build/your-first-app.md)
>
> Practice working with Agent from the first prompt through a focused
> refinement.

> [card] [Checkpoints and rollbacks](https://docs.replit.com/features/version-control/checkpoints-and-rollbacks.md)
>
> Learn how to return to a safer state when needed.
