Debugging and Refactoring

Debugging strategies

Because things will break

As soon as databases, APIs, deployment, and environment variables enter the picture, bugs become more common. That is normal. What matters is how quickly you can turn "something broke" into useful evidence.

Start with built-in auto-fix flows only for small, obvious issues. If the first or second attempt does not work, stop. Repeated blind fixes often make the project harder to reason about, layering changes on top of a broken state.

When auto-fix is not working, roll back and rephrase. Return to a known-good state and ask for a diagnosis before asking for code changes. Splitting one broad change into several focused prompts is almost always faster than untangling a tangled state.

Investigate the root cause before asking for a fix. Use plan mode — or any read-only mode your agent offers — to ask why something is failing before it touches a file.

Trace this error through the codebase.
Which files are involved, what is the root cause,
and what is the smallest safe fix?
Do not edit files yet.

Why is this component undefined?

Share better evidence. A screenshot of the broken UI plus a console error is far more useful than "it does not work." Always explain what you were trying to do when the bug appeared, and what changed right before it.

I connected the trips table to Supabase. The page renders,
but saving a trip fails with this console error: [paste error].
Please explain the likely cause before changing code.

When in doubt, get a second opinion. Start a fresh session in the same agent — or open a different model entirely — turn on plan mode, share the context, and ask for an explanation and the safest fix. A clean session has no stake in the last five failed attempts, and another model often spots assumptions the first agent missed.

Browser Dev Tools: your evidence layer

Browser Dev Tools help you see what the app is actually doing. Open them with right-click → Inspect, or F12.

1. Inspect elements
   • See how HTML and CSS are structured.
   • Check applied styles, the box model, spacing, and responsiveness.
   • Temporarily edit styles before asking the agent to implement the change.
2. Console
   • Shows errors, warnings, and logs.
   • Useful for spotting missing files, incorrect variable names, failed client code, or runtime exceptions.
   • Copy errors into your prompt with context.
3. Network tab
   • Shows requests to Supabase, your own APIs, and external services.
   • Check the request URL, status code, response body, and timing.
   • Useful for auth, Row Level Security, CORS, missing environment variables, and failed API calls.
4. Performance and Lighthouse
   • Gives evidence about load time, accessibility, and best practices.
   • Helpful before handoff or before a larger refactor.

The important shift: Dev Tools are not just for developers. They are a way for designers to collect precise evidence that the agent can act on.

Debugging Supabase and environment variables

Supabase bugs often come from configuration rather than UI code.

Check these first:

• Is .env.local present on your machine?
• Is .env.local listed in .gitignore so it does not get pushed?
• Are the same variables configured in Vercel for Preview and Production?
• Does the variable name use the right framework prefix, such as NEXT_PUBLIC_ or VITE_?
• Is the code using the publishable key in the frontend, not a secret or service-role key?
• Is Row Level Security blocking the request?
• Does the code expect a table or column name that does not exist?
• Did you redeploy after changing Vercel variables?

If Supabase MCP is connected, ask the agent to inspect the schema before guessing:

Use Supabase MCP in read-only mode.
Compare the app's expected table/column names with the real Supabase schema.
Also check whether Row Level Security policies could block this request.
Do not make database changes.

This is where MCP earns its place in the workflow: it reduces the copy-paste between Supabase dashboard, browser errors, and code editor.

A practical debugging workflow

A simple loop works surprisingly well:

1. Reproduce the bug once.
2. Open Dev Tools.
3. Inspect the broken element or failed request.
4. Copy console and network evidence.
5. Share the evidence with the coding agent.
6. Ask for root-cause analysis before edits.
7. Apply one small fix.
8. Test the same path again.

Example prompt:

Here is the UI behavior I expected: [describe].
Here is what happened instead: [describe].
Console error: [paste].
Network request: [status, URL, response].

Explain the root cause and suggest the smallest safe fix.
Do not edit files yet.

Debugging is not about finding a magic prompt. It is about giving the agent the same evidence a developer would ask for.

Test and refactor early

Before the prototype collapses under its own weight

Refactoring means improving structure without changing behavior. It matters more in agent-built prototypes than people expect.

As prototypes grow, small inconsistencies multiply. Duplicate components appear, naming drifts, unused files pile up, styling patterns fork, and the agent has more context to misread. A few minutes of cleanup every session keeps the next prompt more reliable.

Why it pays off:

• Prevents code sprawl as the prototype grows.
• Makes bugs easier to isolate.
• Keeps the project easier for the agent to understand.
• Reduces technical debt before handoff to developers.

Refactoring best practices

1. Refactor regularly. Small cleanups beat one giant rewrite.
2. Clean up unused code and components as you go.
3. Rename variables and components for clarity — naming drift is the silent killer.
4. Consolidate duplicates. Merge similar components, deduplicate styles.
5. Keep changes small and verify after each one. Click through the app after every refactor.
6. Ask for an audit first — let the agent spot duplications you missed before it edits anything.

Good audit prompt:

Audit this project for refactoring opportunities.

Focus on duplicate components, unused files, confusing names,
repeated styling patterns, and large files that should be split.

Do not change code yet.
Rank the top 3 opportunities by impact and risk.

Good implementation prompt:

Apply only the first refactor you recommended.

Keep behavior and visual design unchanged.
After editing, summarize files changed, what behavior should be tested,
and any risk that remains.

Keep refactors small. Verify after each one. A tidy prototype is easier to extend and much easier to hand off.

Use documentation as part of your prompt

Do not assume the model knows everything

AI models and coding agents are often out of sync with the latest library versions. Library APIs change, framework defaults change, and docs move faster than training data.

Help the agent:

1. Link to official documentation.
2. Copy the relevant snippet.
3. Specify the library and version.
4. Name the framework and runtime.
5. State any constraints, such as "do not expose secrets in frontend code."

Examples:

Use Supabase's current publishable key pattern.
Follow this doc: [link].
Do not use a service-role key in browser code.

Check the Tailwind version in package.json and use that version's syntax.
Do not mix v3 and v4 patterns. Do not change the visual design.

Why documentation matters

• Reduces hallucinated APIs and made-up syntax.
• Keeps code aligned with current library versions and methods.
• Speeds up debugging when syntax has changed between versions.
• Gives the agent concrete boundaries.
• Keeps your prototype aligned with production-ready practices.

The mindset shift is simple: good prompting is not about clever phrasing. It is about sharing the same constraints, context, and references you would give to a human teammate. Treat the coding agent like a junior developer with very fast hands: give it docs, examples, constraints, and review points.

Debugging and refactoring are not one-off tasks. They are habits that keep your prototype usable as it becomes more real.