Vibe Coding Workflow: Brief to Verified Pull Request

A good vibe coding workflow does not end when the AI says, “Done.” It ends when you understand the change, the checks pass, and the deployed behavior matches the request.

The practical sequence is:

1. Define the outcome and boundaries.
2. Give the coding agent enough project context.
3. Establish a clean baseline.
4. Ask for a plan before edits.
5. Build one coherent slice at a time.
6. Run the real verification commands.
7. Review the diff and risk areas.
8. Open a pull request with evidence.
9. Pass CI, preview, approval, and merge gates.
10. Verify the deployed result.

This adds a little structure up front, but it is cheaper than discovering later that the agent changed the wrong component, skipped the tests, or invented a data model you did not ask for.

The pattern works directly with terminal agents such as Claude Code and Codex and editor agents such as Cursor when they can inspect the repository, edit files, and run commands. Browser and deployment checks may still require separate tools or manual verification.

Why Accepting the First Result Fails

AI coding tools produce plausible code quickly. Plausible is not the same as correct, but it can look convincing enough to skip the checks.

A weak workflow usually looks like this:

1. Describe a large feature.
2. Let the agent edit ten files.
3. Accept the result because the interface looks close.
4. Discover the broken state, authorization gap, or deployment failure later.

Nobody decided in advance what the change had to do or how to verify it.

A stronger workflow turns “done” into a set of observable checks:

• The requested behavior exists.
• Important non-goals stayed out of scope.
• Tests, linting, type checks, and builds pass.
• The browser shows the expected states.
• Required authorization and cross-user ownership tests pass.
• The diff is focused and understandable.
• The pull request explains what changed and how it was verified.
• The deployed page or feature works outside the local environment.

Step 1: Define the Outcome and the Boundaries

Before prompting for code, write a small task brief. It does not need to be a formal specification. It needs enough detail to stop the agent from making product decisions on your behalf.

A useful brief answers six questions:

1. What should change for the user?
2. What should stay unchanged?
3. Where in the product does this belong?
4. What edge cases matter?
5. What verification must pass?
6. What actions require approval?

Use this template:

Task: [one-sentence outcome]

User behavior:
- [what the user can do]
- [what success looks like]

Constraints:
- Use the existing [component/API/data model]
- Do not add new dependencies without approval
- Do not change [out-of-scope area]
- Preserve current mobile and keyboard behavior

Edge cases:
- [empty state]
- [loading/failure state]
- [permission or ownership rule]

Verification:
- Run [test command]
- Run [lint/typecheck/build commands]
- Check [specific browser behavior]
- Review the final diff

Approval required before:
- Database migrations
- New packages
- Deletes or destructive commands
- Production deployment

The brief makes assumptions visible before they turn into code.

If you regularly explain the same stack, commands, folders, and safety rules, move that stable context into an AGENTS.md file or the appropriate project instruction file. Keep the task brief focused on the current change.

Step 2: Make the Agent Inspect Before It Edits

The first useful action is usually repository discovery, not implementation.

Ask the agent to identify:

• the files that currently own the behavior
• related tests and schemas
• existing components or helpers it should reuse
• project commands for testing, linting, type checking, and building
• likely risk areas
• anything ambiguous in the request

A solid discovery prompt:

Inspect the repository before editing anything.

Find the files, components, routes, data models, and tests that currently control this behavior. Identify the project's verification commands and any existing conventions we should reuse.

Return:
1. Relevant files and what each one does
2. Current behavior
3. Proposed change boundary
4. Risks or unanswered questions
5. Verification plan

Do not modify files yet.

Otherwise, the agent may build a second version of behavior that already exists elsewhere in the repository.

For larger or unfamiliar repositories, a codebase knowledge graph can shorten discovery by showing which files, functions, and modules connect before the agent starts editing.

Step 3: Establish a Clean Baseline

You need to know whether the project was healthy before the AI touched it.

Start from a clean branch and run the checks that matter for the repository:

git status --short
npm test
npm run lint
npm run typecheck
npm run build

Those commands are examples, not a universal package script. Use the commands the project actually defines.

Record existing failures before editing. When the same command fails later, you can tell whether the change introduced the problem or merely exposed it.

For a small documentation edit, the baseline may be a clean Git status and a successful site build. For authentication, payments, database access, or deployment logic, the baseline should be much stricter.

Step 4: Ask for a Plan Before Code

Once the agent understands the repository, ask it to propose the smallest implementation that satisfies the brief.

The plan should name:

• files to modify
• files it expects to add
• data or API changes
• test changes
• user-visible states
• risks and rollback concerns

Do not accept a plan that says only “update the component and test it.” Expose the shape of the work before the agent has spread the change across the repository.

Use this prompt:

Based on the repository inspection, propose the smallest implementation plan that satisfies the task brief.

For each step, name the files involved, the behavior being changed, and how that step will be verified. Reuse existing patterns. Flag any migration, dependency, destructive action, external send, or deployment that requires approval.

Do not start implementation until the plan is complete.

A two-file change may need only five bullets. The plan should match the size and risk of the task.

Step 5: Build One Coherent Slice at a Time

Large one-shot prompts hide mistakes. Smaller slices give you places to inspect, test, and redirect.

A coherent slice is a piece of behavior that can be verified on its own. For example:

1. Add the data or state change.
2. Add the user-facing control.
3. Add loading, empty, and error states.
4. Add tests.
5. Polish responsive and accessible behavior.

After each slice:

• inspect the changed files
• run the narrowest relevant test
• check the visible behavior if one exists
• confirm the next slice still makes sense

This does not mean micromanaging every line. It means keeping the change small enough to inspect and redirect.

If the agent starts solving unrelated problems, stop and reset the scope. “While I was here” is how a focused feature becomes an unreviewable refactor.

Example: add CSV export without letting the task spread

Suppose an existing reports page needs a CSV export button.

A loose prompt—“add CSV export”—leaves the agent to decide which records to include, how to escape commas and quotes, what the filename should be, and whether export belongs in the browser or on the server.

A bounded workflow looks different:

1. Brief: Export the currently filtered report rows. Preserve visible column order. Use a date-stamped filename. Show a disabled state when there are no rows. Do not add a spreadsheet library without approval.
2. Discovery: Find the report table, filter state, existing download helpers, and tests. Confirm whether the browser already has the complete filtered dataset.
3. Plan: Reuse the current filtered rows, add one small serialization helper, add the button beside the existing report controls, and test escaping plus the empty state.
4. Implementation: Build the serialization helper first, then the button, then the browser behavior.
5. Verification: Run the focused tests and production build. Export rows containing commas, quotes, and line breaks. Confirm the filename, column order, disabled state, and mobile layout.
6. Review: Check that the diff did not introduce a new dependency, duplicate filter logic, or export data the user cannot currently see.
7. Pull request: Record the commands, edge cases, and downloaded-file checks.

The feature is small. The workflow still matters because the risky parts are hidden in the words “export the data,” not in the button itself.

Step 6: Verify With Real Tools

A verification prompt is useful only when the agent runs the checks and reports what happened.

Verification usually spans five layers. Use the layers that match the change:

• Static analysis: formatting, linting, types, and schema validation
• Automated behavior: unit, integration, end-to-end, authorization, and ownership tests
• Build: production build, generated artifacts, and migration dry runs when relevant
• Browser: the changed flow, failure states, mobile layout, keyboard behavior, console errors, and overflow
• Deployment: preview and production behavior, response status, metadata, redirects, and environment-dependent services

A copy edit may need only a build and rendered-page check. An authorization change needs tests that cross user and ownership boundaries.

A reusable verification prompt:

Verify the implementation instead of summarizing what should work.

Run the relevant test, lint, typecheck, and production-build commands. Exercise the changed user flow in the browser, including the important loading, empty, success, failure, mobile, and keyboard states from the brief.

Report:
- exact commands run
- pass/fail result for each command
- browser behaviors checked
- console errors or warnings
- anything not verified and why

Do not claim completion if a required check was skipped or failed.

When something fails, fix it and rerun the check. If the failure is not obvious, use a structured process for debugging AI-generated code instead of stacking more guesses on top of it.

Our AI coding workflow starter pack includes reusable review, debugging, security, and deployment checklists if you do not want to recreate this verification list for every project.

Step 7: Review the Diff Like a Maintainer

Tests cover only the behavior someone thought to test. The diff still needs a maintainer’s review.

Review the final diff and ask:

• Is every changed file necessary?
• Did the agent duplicate an existing helper or component?
• Did it add a dependency for something the project already supports?
• Are errors handled, or merely hidden?
• Are secrets, tokens, or personal data exposed?
• Did authorization stay on the server where it belongs?
• Did the change alter unrelated formatting or generated files?
• Are names and comments accurate?
• Can another person understand why the change exists?

Useful commands include:

git status --short
git diff --stat
git diff --check
git diff

For a large diff, review by risk rather than reading alphabetically:

1. Authentication and authorization
2. Database and migrations
3. Payments and billing
4. External sends and side effects
5. API and data validation
6. User-facing behavior
7. Styling and cleanup

If the task touches authentication, credentials, dependency changes, or user data, pair the diff review with the broader checks in our vibe coding security risks guide. For other sensitive areas, use a separate reviewer pass. A focused review agent can help, but it should inspect the actual diff and test evidence—not merely reread the original prompt. The same principle applies when using AI coding subagents: separate responsibilities, then keep one final owner.

Step 8: Open a Pull Request With Evidence

A pull request should let someone understand the change without replaying the entire AI session.

Include:

• what changed
• why it changed
• important implementation decisions
• commands run and their results
• screenshots for visible changes
• risks or known limitations
• deployment preview when available

A compact pull request template:

## Summary
- [change]
- [change]

## Why
[problem this solves]

## Verification
- `[command]` — passed
- `[command]` — passed
- Browser: [flows and states checked]

## Risk
- [migration, auth, API, or deployment consideration]

## Screenshots
[before/after or relevant states]

“Tests passed” is weaker than naming the tests. “Looks good” is weaker than naming the browser states. Be specific enough that another reviewer can rerun the checks and spot anything you missed.

Step 9: Pass the Merge and Release Gate

Opening the pull request creates a review boundary. It does not authorize the merge by itself. A verified pull request has passed its required CI checks, preview review, scope review, and owner approval.

Before merging:

1. Wait for every required CI and deployment-preview check to finish.
2. Treat failed or pending required checks as a stop, not a suggestion.
3. Open the preview and exercise the changed behavior there.
4. Confirm the pull request still matches the approved task boundary.
5. Obtain the required reviewer or owner approval.
6. Merge only after the evidence and approval are in place.

Define the rollback trigger before release when the change affects authentication, data, payments, external services, or high-traffic pages. If the preview is wrong, CI fails, or a reviewer finds a blocker, update the branch and rerun the gate. Do not merge first and promise to clean it up in production.

Step 10: Verify After Deployment

A green pull request is not the finish line if the change is meant for production.

After deployment:

1. Open the real URL.
2. Confirm the expected version is live.
3. Exercise the changed behavior.
4. Check the browser console.
5. Confirm mobile and keyboard behavior when relevant.
6. Check production-only services, redirects, headers, or environment variables.
7. Record known limitations honestly.

Local checks cannot tell you whether production has the right environment variables, whether the migration ran, or whether redirects and third-party APIs behave correctly from the deployed domain.

Use the vibe coding deployment checklist for the release pass and the AI-coded app launch audit when the change is large enough to affect real users or business operations.

A Practical Verification Matrix

Not every task needs the same ceremony. Match the workflow to the risk.

Change type	Minimum useful verification
Copy or content update	Build, rendered page, links, metadata, diff
Styling change	Build, desktop/mobile views, overflow, keyboard focus, console
Component behavior	Unit/integration tests, browser states, accessibility, build
API change	Validation tests, auth/ownership tests, error paths, integration test
Database change	Migration review, backup/rollback plan, isolated data tests, deployment check
Auth or payments	Dedicated security review, cross-user tests, failure paths, preview and production verification
Deployment/config change	Build artifact, environment checks, health check, logs, rollback path

The matrix is a floor, not a guarantee. Increase the checks when failure would affect money, private data, credentials, or client work.

Common Vibe Coding Workflow Mistakes

Approving dependencies automatically

A new package adds code you must trust, update, and eventually remove. Ask why the existing stack cannot handle the job before approving it.

Testing only the happy path

Users encounter empty data, slow networks, expired sessions, duplicate submissions, denied permissions, and small screens. Verify the states that are easiest to skip.

Shipping an unreadable diff

If you cannot explain the change, you are not ready to own it. Ask the agent to reduce unrelated edits and separate refactoring from behavior changes.

FAQ

What is a vibe coding workflow?

It is the process around AI-assisted implementation: define the task, inspect the repository, make bounded changes, run the project’s checks, review the diff, and verify the deployed behavior.

Should an AI coding agent open pull requests automatically?

It can prepare or open one when permissions allow it, but a human or designated final reviewer should own approval and merge decisions.

Do I need tests for every AI-generated change?

No. A copy edit may need only a build and rendered-page check; authentication, payments, APIs, and data access need stronger automated coverage.

Is reviewing the diff enough?

No. A clean diff can fail at runtime, while passing tests can still hide unnecessary or risky code. Review the implementation and run the relevant checks.

What if the agent cannot run the project?

Treat it as a blocker. Fix the environment, run the checks elsewhere, or keep the work in draft and state what remains unverified.

Can this workflow work with Cursor, Claude Code, Codex, or Copilot?

Yes, when the tool can inspect and edit the repository. Command, browser, and deployment checks may require separate tools.

Make the Workflow Reusable

Save the stable parts of the process: project commands, repository conventions, approval boundaries, and pull request expectations. Keep each task brief focused on the current change.

Tools will change. The useful habit is checking the work before you own and ship it.