Your AI-built app
works on localhost. Does it actually work
for real users?

⚡ Impact

The AI invents product decisions you never made — wrong users, wrong data, wrong success criteria.

🔥 Why it breaks

Without a target, the agent guesses, and every guess is a decision you have to either accept or rebuild later.

🛠️ Quick fix

1. 1 Define the user, the data, the action, and what "done" looks like.
2. 2 Replace the one-line prompt with a short feature spec.
3. 3 Push back when the agent makes assumptions you did not approve.

🏆 Senior move

Treat every prompt as a spec. If the agent has to guess, the spec is too vague.

⚡ Impact

You get a huge unreviewable diff that nobody — including you — can verify, debug, or trust.

🔥 Why it breaks

Large diffs hide bad decisions, mismatched assumptions, and broken pieces inside something that almost works.

🛠️ Quick fix

1. 1 Break the app into small implementation units.
2. 2 Build one feature, one spec, one diff.
3. 3 Verify each unit before the next.

🏆 Senior move

One unit at a time, one verifiable result, one reviewable diff.

⚡ Impact

The feature looks finished, but behavior is wrong, missing, or different from what you actually wanted.

🔥 Why it breaks

Without a checklist, both you and the agent declare victory the moment something runs.

🛠️ Quick fix

1. 1 Add a "Verify when done" checklist to every spec.
2. 2 Test the listed behaviors before closing the unit.
3. 3 Update the progress tracker with what was actually verified.

🏆 Senior move

Done means verified — not running, not compiled, verified.

⚡ Impact

The agent rewrites or contradicts decisions, breaks patterns, and recreates files you already had.

🔥 Why it breaks

Without context files and a progress tracker, every session starts from zero.

🛠️ Quick fix

1. 1 Create the six context files: project-overview, architecture, code-standards, ai-workflow-rules, ui-context, progress-tracker.
2. 2 Update progress-tracker.md after every meaningful change.
3. 3 Have the agent read those files before writing any code.

🏆 Senior move

Context is memory. The progress tracker is the memory of yesterday's decisions.

⚡ Impact

The codebase enters a regression cycle where each patch creates a new bug somewhere unrelated.

🔥 Why it breaks

You are treating symptoms, not root causes — and the agent has no scope discipline to limit the blast radius.

🛠️ Quick fix

1. 1 Stop and identify the actual root cause before changing code.
2. 2 Define the smallest scoped fix and protect unrelated files.
3. 3 Roll back if the diff keeps growing.

🏆 Senior move

Scope every fix. If you cannot describe the root cause in one sentence, do not patch yet.

⚡ Impact

Automation breaks unpredictably the moment the model rewords its answer.

🔥 Why it breaks

Free-form text is a contract you cannot rely on; small phrasing changes cascade through your pipeline.

🛠️ Quick fix

1. 1 Use a strict JSON or schema-validated output for any machine-consumed result.
2. 2 Validate the schema and fail loudly when it does not match.
3. 3 Add small evals so future model changes do not silently break it.

🏆 Senior move

Treat AI output as untrusted until validated against a schema.

⚡ Impact

Nobody else can open the app. You have not deployed anything yet.

🔥 Why it breaks

localhost points to the current machine. On someone else's laptop it means their laptop, not yours.

🛠️ Quick fix

1. 1 Deploy to a real host: Vercel, Netlify, Railway, Render, or Fly.io.
2. 2 Replace hardcoded localhost API URLs with environment variables.
3. 3 Test the deployed URL from a different device or browser.

🏆 Senior move

Local proves possibility. Deployment proves it can leave your laptop.

⚡ Impact

The page loads in production but every API call fails. Users see a blank or broken app.

🔥 Why it breaks

The browser tries to call the user's own machine on port 3000 — which has nothing on it.

🛠️ Quick fix

1. 1 Move the API base URL into an environment variable.
2. 2 Set the variable separately for local, preview, and production.
3. 3 Search the codebase for localhost before every deploy.

🏆 Senior move

Environment-driven URLs always — no "it works on my machine" hardcoding.

⚡ Impact

The app fails to start in production because a required key, URL, or secret is undefined.

🔥 Why it breaks

Local .env files are never deployed. Production needs its own variables, set on the host.

🛠️ Quick fix

1. 1 List every required variable in a single config file or schema.
2. 2 Validate them at boot — fail loudly with the missing key name.
3. 3 Set the production values on the host before deploying.

🏆 Senior move

Env validation at startup. No silent undefined.

⚡ Impact

Users hit a broken release because preview and production were not actually equivalent.

🔥 Why it breaks

Preview often points at a different database, secrets, or domain than production — divergence hides bugs.

🛠️ Quick fix

1. 1 Treat preview as a real environment with its own variables and database.
2. 2 Test the same flows in preview and production before each release.
3. 3 Promote a single build artifact from preview to production where possible.

🏆 Senior move

Three real environments: local, preview, production — each with its own config.

⚡ Impact

Deploys go green, but the first real request fails — usually on missing runtime config.

🔥 Why it breaks

The build only checks compilation. It does not exercise runtime config, database access, or external services.

🛠️ Quick fix

1. 1 Validate environment variables on app boot.
2. 2 Add a smoke test that hits one real endpoint after deploy.
3. 3 Use health checks that exercise the database and key services.

🏆 Senior move

Green build is necessary, not sufficient. Smoke-test the real flow.

⚡ Impact

The container or VM is technically running, but bound to the wrong interface or port.

🔥 Why it breaks

Defaults like 127.0.0.1 only accept connections from inside the container.

🛠️ Quick fix

1. 1 Bind the server to 0.0.0.0 inside containerized or hosted environments.
2. 2 Match the port the host expects (often $PORT).
3. 3 Test connectivity from outside the container, not just inside.

🏆 Senior move

Read your host's deploy doc once. Bind correctly, expose correctly.

⚡ Impact

API routes never run. The frontend works; everything that needs server logic 404s.

🔥 Why it breaks

Static hosting only serves files. It does not run server functions, edge functions, or persistent processes.

🛠️ Quick fix

1. 1 Pick a host that supports your runtime: Node, edge, serverless functions, containers.
2. 2 Or split into static frontend + a separate API host.
3. 3 Verify a server route works in production before adding more.

🏆 Senior move

Match hosting to runtime. Static, serverless, and persistent are different products.

⚡ Impact

A broken release stays live until you manually rebuild and redeploy from a working commit.

🔥 Why it breaks

Without versioned deployments, "go back" requires guessing what was last good.

🛠️ Quick fix

1. 1 Use a host with versioned deployments and one-click rollback.
2. 2 Tag releases in Git so you can redeploy a known-good commit.
3. 3 Test rollback once before you actually need it.

🏆 Senior move

Every deploy assumes a rollback exists. If it does not, the deploy is not safe.

⚡ Impact

Anyone viewing the page can pull the key out of the JavaScript bundle and use it.

🔥 Why it breaks

Frontend code runs on the user's browser. There are no real secrets there.

🛠️ Quick fix

1. 1 Rotate the exposed key immediately.
2. 2 Move the API call to a backend route that holds the key.
3. 3 Inspect the built bundle to confirm no keys remain.

🏆 Senior move

Secrets stay on the server. The browser never holds the credentials.

⚡ Impact

The credential is now in Git history. Even if you delete the file, it lives on in old commits.

🔥 Why it breaks

Public or scanned repos leak credentials within minutes — bots check constantly.

🛠️ Quick fix

1. 1 Rotate the leaked key immediately.
2. 2 Remove it from history with git filter-repo or BFG (or accept history rewrite).
3. 3 Add .env to .gitignore and enable secret scanning.

🏆 Senior move

Treat any committed secret as already compromised. Rotate first, clean history second.

⚡ Impact

Users can bypass row-level security and access or mutate data they should not see.

🔥 Why it breaks

Service-role keys are designed to skip access control. They belong only to trusted server code.

🛠️ Quick fix

1. 1 Rotate the service-role key.
2. 2 Use the public/anon key in the frontend, with row-level security enabled.
3. 3 Move privileged operations to a backend route that holds the service key.

🏆 Senior move

Two key tiers: anon for the browser, service for the backend. Never mix.

⚡ Impact

If your app is compromised, the attacker inherits everything you asked for — far beyond the feature's actual need.

🔥 Why it breaks

OAuth scopes are a blast-radius decision. Broad scopes mean broad consequences.

🛠️ Quick fix

1. 1 List the minimum scopes the feature actually requires.
2. 2 Re-request consent with the narrowed scope set.
3. 3 Audit existing tokens and revoke ones with excessive permissions.

🏆 Senior move

Least-privilege scopes. Ask for read-only first; escalate only when the feature demands it.

⚡ Impact

The agent may send, charge, delete, or deploy without anyone reviewing the action.

🔥 Why it breaks

Tool calls are real side effects. Without a permission layer, the agent's mistakes become production incidents.

🛠️ Quick fix

1. 1 Define which tools require human approval.
2. 2 Add an approval step in the workflow before risky tools fire.
3. 3 Log every tool call with inputs, outputs, and approver.

🏆 Senior move

Approvals on side effects. Read-only tools auto-fire; write tools wait for a human.

⚡ Impact

Malicious content can hijack the agent — exfiltrate data, send messages, or call dangerous tools.

🔥 Why it breaks

Prompt injection works because models cannot reliably distinguish data from instructions.

🛠️ Quick fix

1. 1 Treat all external content as untrusted data, not instructions.
2. 2 Wrap and label external text clearly in the prompt.
3. 3 Add input/output guardrails and review tool calls triggered by external sources.

🏆 Senior move

Untrusted in, validated out. The agent never acts on raw external text.

⚡ Impact

A bad command, malicious dependency, or prompt injection can read secrets, delete files, or call out to attackers.

🔥 Why it breaks

Unsandboxed agents have the same blast radius as you do.

🛠️ Quick fix

1. 1 Run the agent in an isolated workspace (container, VM, dev container).
2. 2 Limit network access and protect secret files.
3. 3 Approve risky commands instead of auto-running them.

🏆 Senior move

Agents work in a sandbox by default. Production access is granted, not assumed.

⚡ Impact

The backend may still be wide open — anyone calling the API directly bypasses your login form entirely.

🔥 Why it breaks

Auth lives on the server, not on the screen. UI is decoration around it.

🛠️ Quick fix

1. 1 Protect API routes with server-side session or token checks.
2. 2 Verify protected routes return 401 when called without a valid session.
3. 3 Test from a tool like curl, not just the browser.

🏆 Senior move

If a route is not protected on the server, it is not protected.

⚡ Impact

Any user can call the API directly and perform the action you tried to hide in the UI.

🔥 Why it breaks

Frontend code is not a security boundary. The browser is fully under the user's control.

🛠️ Quick fix

1. 1 Re-check permissions on the backend for every protected action.
2. 2 Return 403 from the API when not allowed, regardless of UI state.
3. 3 Test by calling the API directly without the UI.

🏆 Senior move

UI hides things for usability. The backend enforces them for safety.

⚡ Impact

Data leaks across users. Person A loads person B's invoice, profile, or chat by guessing IDs.

🔥 Why it breaks

Authentication checks who you are. Authorization checks what you can touch — those are different.

🛠️ Quick fix

1. 1 On every read and write, check that the record belongs to the current user or team.
2. 2 Use random, non-sequential IDs to make guessing harder.
3. 3 Test the API as user B with user A's IDs.

🏆 Senior move

Every query includes ownership. "Whose data is this" is part of the query, not a separate check.

⚡ Impact

Cross-user bugs — leaks, permission gaps, role mistakes — survive into production unseen.

🔥 Why it breaks

Single-user testing cannot reveal what happens between users.

🛠️ Quick fix

1. 1 Create at least two test users plus an anonymous case.
2. 2 Test that user A cannot see or change user B's data.
3. 3 Test what unauthenticated requests get.

🏆 Senior move

Two users plus anonymous, on every protected feature.

⚡ Impact

When a teammate joins, leaves, or your email changes, admin access breaks or sticks around incorrectly.

🔥 Why it breaks

Hardcoded checks are not access control — they are a sticky note pretending to be a system.

🛠️ Quick fix

1. 1 Add a roles or permissions table.
2. 2 Assign roles to users in the database.
3. 3 Replace email checks with role checks everywhere.

🏆 Senior move

Access control lives in data, not in code branches.

⚡ Impact

Confidential pricing, internal notes, costs, or PII leak into the wrong UI.

🔥 Why it breaks

Returning the whole object to every role is the easy default — and the wrong one.

🛠️ Quick fix

1. 1 Define what each role is allowed to read.
2. 2 Filter response fields by role on the server.
3. 3 Never trust the client to hide sensitive fields.

🏆 Senior move

Shape the API response per role, not per UI screen.

⚡ Impact

The data model breaks as the app grows — wrong relationships, missing fields, painful migrations.

🔥 Why it breaks

Schema decisions outlive features. A bad model cascades into bad APIs and bad UI for months.

🛠️ Quick fix

1. 1 Sketch the entities, relationships, and ownership before code.
2. 2 Review every AI-proposed schema and challenge it.
3. 3 Document the data model in architecture.md.

🏆 Senior move

You own the data model. The agent helps you implement it, not invent it.

⚡ Impact

Any user can read or modify any row. The app's privacy is whatever the client decides to ask for.

🔥 Why it breaks

Without RLS or backend authorization, every record is effectively public.

🛠️ Quick fix

1. 1 Enable row-level security on every exposed table.
2. 2 Or move database access behind a backend that authorizes per request.
3. 3 Verify with a second user account that data is properly isolated.

🏆 Senior move

Default-deny on the database. Open up access intentionally, per table, per role.

⚡ Impact

Local and production drift apart. Every deploy is a guess about what columns exist where.

🔥 Why it breaks

Without migration files, schema changes are tribal knowledge — and tribal knowledge does not deploy.

🛠️ Quick fix

1. 1 Use a migration tool (Prisma, Drizzle, Alembic, Flyway, etc.).
2. 2 Commit migrations to Git.
3. 3 Run them automatically on deploy.

🏆 Senior move

Schema lives in migrations. The database is just where they end up.

⚡ Impact

Data does not persist between cold starts, or different instances see different data.

🔥 Why it breaks

Serverless containers are ephemeral. A local file is local to the container, which can vanish.

🛠️ Quick fix

1. 1 Use a managed Postgres, MySQL, or hosted SQLite that supports your runtime.
2. 2 Verify data persistence across deployments and cold starts.
3. 3 Plan backups and connection pooling for the new database.

🏆 Senior move

Pick a database that matches your runtime's persistence model.

⚡ Impact

Real production data slows queries to seconds — or causes timeouts under load.

🔥 Why it breaks

Without indexes, the database scans the whole table for every filter or join.

🛠️ Quick fix

1. 1 Add indexes on columns used in WHERE, JOIN, and ORDER BY.
2. 2 Inspect query plans for slow endpoints.
3. 3 Re-test performance with realistic data volume.

🏆 Senior move

Indexes are part of the schema, not a performance afterthought.

⚡ Impact

A bad migration, accidental delete, or disk failure can wipe out user data with no recovery.

🔥 Why it breaks

"Probably" is not a backup strategy. Untested backups often fail to restore.

🛠️ Quick fix

1. 1 Confirm and configure automated backups for your database.
2. 2 Set the retention window your business actually needs.
3. 3 Test a real restore at least once.

🏆 Senior move

A backup you have not restored is a guess. Test the restore.

⚡ Impact

Bad data slips in via API calls, scripts, or other clients — and stays forever.

🔥 Why it breaks

Forms are one of many ways to write data. Without DB constraints, every other path is unprotected.

🛠️ Quick fix

1. 1 Add NOT NULL, UNIQUE, FK, and CHECK constraints to enforce invariants in the database.
2. 2 Validate on the server before writes.
3. 3 Treat the form as the friendly layer, not the boundary.

🏆 Senior move

The database is the last line of defense for data integrity.

⚡ Impact

Anyone who knows the success URL can grant themselves a paid plan without paying.

🔥 Why it breaks

Redirect URLs are not proof of payment. They can be opened directly, bookmarked, or guessed.

🛠️ Quick fix

1. 1 Grant access only after a verified webhook event from your payment provider.
2. 2 Check the event signature and the customer's actual subscription state.
3. 3 Make the success page a UX confirmation, not a permission grant.

🏆 Senior move

Money confirms via webhook. The success page just says "thanks."

⚡ Impact

Anyone can fake a payment event and unlock features, refunds, or admin actions.

🔥 Why it breaks

Webhook URLs are reachable from the internet. Without signature verification, they trust the world.

🛠️ Quick fix

1. 1 Verify the signature on every webhook using the provider's secret.
2. 2 Reject unsigned or invalid requests.
3. 3 Rotate webhook secrets if they have ever been logged.

🏆 Senior move

Treat webhook bodies as untrusted until the signature is verified.

⚡ Impact

Users get double-charged, double-granted access, or double-emailed when retries happen.

🔥 Why it breaks

Webhooks retry by design. Without idempotency, every retry is a new side effect.

🛠️ Quick fix

1. 1 Store processed event IDs and skip duplicates.
2. 2 Use idempotency keys for outbound charges and writes.
3. 3 Make handlers safe to run twice.

🏆 Senior move

Idempotent by default for any external trigger or retry.

⚡ Impact

Real charges fail, or test events leak into production state.

🔥 Why it breaks

Test and live are separate worlds with separate webhooks, secrets, and product IDs.

🛠️ Quick fix

1. 1 Use entirely separate keys, secrets, and product IDs per environment.
2. 2 Validate which mode the app is in at boot.
3. 3 Run a real end-to-end live transaction in staging before launch.

🏆 Senior move

Test mode and live mode are different products. Treat them that way.

⚡ Impact

Customers pay and lose access — or stop paying and keep access. Both are bad.

🔥 Why it breaks

Without webhook-driven state, your app's subscription field is just a stale copy.

🛠️ Quick fix

1. 1 Listen to subscription created, updated, canceled, and renewed events.
2. 2 Update your local subscription state from those events.
3. 3 Reconcile on login as a safety net.

🏆 Senior move

Subscription state mirrors the payment provider, not the other way around.

⚡ Impact

Real users hit empty states, errors, slow networks, and edge cases — and the app falls over.

🔥 Why it breaks

The happy path is the smallest slice of real usage.

🛠️ Quick fix

1. 1 Test empty, loading, error, retry, and "too much data" states.
2. 2 Try the app with a slow connection.
3. 3 Test with realistic data, not just clean demo data.

🏆 Senior move

Build the unhappy paths on purpose. They are most of production.

⚡ Impact

Mobile users see broken layouts, unreachable buttons, and forms that cannot be submitted.

🔥 Why it breaks

Most users browse on phones. "Looks fine on my laptop" is a sample of one.

🛠️ Quick fix

1. 1 Open the app on your phone over real mobile data.
2. 2 Test responsive breakpoints in DevTools.
3. 3 Verify tappable areas, scrolling, and keyboard behavior.

🏆 Senior move

Mobile is the default viewport. Desktop is a wider variant.

⚡ Impact

Real users paste, fat-finger, or attack inputs — and the app crashes or accepts garbage.

🔥 Why it breaks

Validation only against valid data tests nothing. Bad input is the test.

🛠️ Quick fix

1. 1 Try empty, very long, special characters, and clearly invalid values.
2. 2 Add server-side validation in addition to client-side.
3. 3 Show clear errors instead of silent failures.

🏆 Senior move

Validate on the server. Treat client validation as UX, not a guarantee.

⚡ Impact

When sessions expire in production, users see broken pages, lost work, or confusing errors.

🔥 Why it breaks

Expired sessions are a common state your code rarely handles by default.

🛠️ Quick fix

1. 1 Manually expire a session and walk through the app.
2. 2 Handle 401 responses by redirecting to login.
3. 3 Preserve in-progress work where possible across re-auth.

🏆 Senior move

Expired and refreshed sessions are part of the supported lifecycle.

⚡ Impact

Real users double-click, retry, and refresh — creating duplicate records, payments, or emails.

🔥 Why it breaks

Without idempotency or UI guards, every duplicate click is a duplicate action.

🛠️ Quick fix

1. 1 Disable submit buttons after the first click until the response returns.
2. 2 Use idempotency keys on backend writes that must not duplicate.
3. 3 Test with rapid clicks in DevTools.

🏆 Senior move

Assume every action is triggered twice. Make it safe to be triggered twice.

⚡ Impact

Model updates, prompt edits, or tool changes silently regress behavior — and you find out from users.

🔥 Why it breaks

AI features look stable until inputs vary. Without evals, regressions are invisible.

🛠️ Quick fix

1. 1 Pick 10–30 representative inputs with expected behaviors.
2. 2 Run them automatically on every prompt or model change.
3. 3 Watch trends, not single results.

🏆 Senior move

Eval suites are tests for AI features. Treat them like unit tests.

⚡ Impact

Debugging becomes guessing. Real incidents take hours instead of minutes.

🔥 Why it breaks

Without logs, you only know what users tell you — which is usually "it broke."

🛠️ Quick fix

1. 1 Add structured logs with timestamps and request IDs.
2. 2 Log key events: incoming requests, errors, external calls.
3. 3 Send logs to a host you can actually search.

🏆 Senior move

Logs are the first feature of production-readiness.

⚡ Impact

When an agent takes a wrong action, you cannot reconstruct why.

🔥 Why it breaks

Agents make many model calls, tool calls, and handoffs. Without traces, the inner loop is opaque.

🛠️ Quick fix

1. 1 Trace model calls, tool calls, handoffs, and approvals.
2. 2 Persist traces with run IDs.
3. 3 Inspect failed runs end to end before patching.

🏆 Senior move

If you cannot trace the agent, you cannot improve it.

⚡ Impact

Bad releases stay live until users complain.

🔥 Why it breaks

"Build succeeded" only proves the build, not the app.

🛠️ Quick fix

1. 1 Add a /health route that exercises the database and key dependencies.
2. 2 Hook it into your host's health check.
3. 3 Alert when it goes red.

🏆 Senior move

Health checks measure the app, not the build.

⚡ Impact

Runaway costs, surprise bills, and no idea which feature is responsible.

🔥 Why it breaks

AI calls compound: retries, tool loops, large contexts. Costs blow up quickly.

🛠️ Quick fix

1. 1 Track tokens and calls per feature.
2. 2 Cache where you can; cap retries and context size.
3. 3 Alert on daily spend thresholds.

🏆 Senior move

Spend is a metric. Watch it like latency.

⚡ Impact

External APIs return 429s under load, breaking flows that worked single-user.

🔥 Why it breaks

Rate limits are a feature, not an error. Without backoff and queues, they cascade.

🛠️ Quick fix

1. 1 Add exponential backoff on retryable errors.
2. 2 Queue work that exceeds per-second limits.
3. 3 Surface partial progress instead of failing the whole job.

🏆 Senior move

Treat rate limits as part of the API contract, not an exception.

⚡ Impact

Slow incident response, lost trust, and a backlog of unseen errors.

🔥 Why it breaks

Without alerts, observability data sits unread.

🛠️ Quick fix

1. 1 Set alerts on error rates, downtime, and key business metrics.
2. 2 Route them to a channel you actually watch.
3. 3 Tune thresholds so they signal, not spam.

🏆 Senior move

Alerts on outcomes you care about. Quiet otherwise.

⚡ Impact

When something breaks, you cannot roll back to a known-good state.

🔥 Why it breaks

Without commits, every change is permanent and entangled.

🛠️ Quick fix

1. 1 Commit after each working unit, not at end of day.
2. 2 Use clear, scoped commit messages.
3. 3 Push often so work is not stuck on your laptop.

🏆 Senior move

Every working unit is a commit. The agent helps you keep them small.

⚡ Impact

Hidden bad changes, broken patterns, and unwanted edits ride along into the codebase.

🔥 Why it breaks

Accept-all reverses the architect-engineer relationship: the agent decides, you ratify.

🛠️ Quick fix

1. 1 Review the diff before accepting.
2. 2 Reject changes outside the spec scope.
3. 3 Ask the agent to redo when the diff is wrong, not patch what it produced.

🏆 Senior move

Diff review is the moment you stay in charge.

⚡ Impact

Reviews become rubber stamps. Bugs hide in the noise.

🔥 Why it breaks

Beyond a certain size, humans stop reading and start trusting.

🛠️ Quick fix

1. 1 Split work into small units before implementation.
2. 2 Ask the agent to keep diffs scoped to one unit.
3. 3 Reject PRs that grew beyond their stated scope.

🏆 Senior move

Small PRs you read line by line; big PRs you only pretend to.

⚡ Impact

Bad code goes live with no second pair of eyes.

🔥 Why it breaks

Branch protection exists because humans (and agents) make mistakes.

🛠️ Quick fix

1. 1 Protect the main branch.
2. 2 Require PRs and basic checks (build, tests) before merge.
3. 3 Use preview deploys to verify before merging.

🏆 Senior move

Main is the final state. It is reached, not edited.

⚡ Impact

Supply-chain risk: malicious or abandoned packages enter your build.

🔥 Why it breaks

Many packages have similar names. Some are typosquats. Some are abandoned. Some are malicious.

🛠️ Quick fix

1. 1 Review every new dependency before installing.
2. 2 Run audit tools and pin versions.
3. 3 Prefer well-known, maintained packages.

🏆 Senior move

Dependencies are decisions. Review them like code changes.

⚡ Impact

Debugging regressions becomes archeology.

🔥 Why it breaks

Without a record, every "when did this break" turns into a git bisect.

🛠️ Quick fix

1. 1 Tag releases.
2. 2 Keep a short changelog or notes per release.
3. 3 Update progress-tracker.md after each unit.

🏆 Senior move

The progress tracker is your changelog.

⚡ Impact

Behavior is unpredictable. Edge cases produce wildly different paths every run.

🔥 Why it breaks

Open-ended agency is hard to test, hard to constrain, and hard to debug.

🛠️ Quick fix

1. 1 Replace open-ended agency with a state machine of explicit steps.
2. 2 Use the model only where decisions are actually fuzzy.
3. 3 Write tests for the workflow paths you support.

🏆 Senior move

Workflows for the predictable parts. Agency only where it earns its keep.

⚡ Impact

A small mistake becomes a real-world incident with money or data on the line.

🔥 Why it breaks

Side effects are not reversible the way edits are. Agents need help knowing where the line is.

🛠️ Quick fix

1. 1 Identify the risky tools: send, charge, delete, deploy, post.
2. 2 Require human approval before they fire.
3. 3 Show the action's payload before approval, not after.

🏆 Senior move

Approvals on side effects, every time, until the workflow has earned trust.

⚡ Impact

Bad inputs mutate systems, leak data, or trigger expensive actions.

🔥 Why it breaks

Tool inputs come from model output, which can hallucinate or be steered by prompt injection.

🛠️ Quick fix

1. 1 Validate inputs before running the tool.
2. 2 Validate outputs before returning them to the model or user.
3. 3 Add allowlists for high-risk parameters.

🏆 Senior move

Tool wrappers enforce contracts. The model proposes; the wrapper validates.

⚡ Impact

Long-running tasks fail mid-way and either repeat work or lose progress.

🔥 Why it breaks

Agents that hold state in memory die with their process.

🛠️ Quick fix

1. 1 Persist task state at meaningful checkpoints.
2. 2 Use a queue or workflow engine for durable execution.
3. 3 Make tasks resumable from the last checkpoint.

🏆 Senior move

Long tasks are workflows, not one-shot calls.

⚡ Impact

When something goes wrong, there is no record of the decision trail.

🔥 Why it breaks

Agentic systems make many small decisions. Without an audit trail, accountability is impossible.

🛠️ Quick fix

1. 1 Log approvals, tool calls, and state transitions with run IDs.
2. 2 Record the inputs and outputs of risky actions.
3. 3 Keep logs long enough for incident review.

🏆 Senior move

Audit logs make agentic systems reviewable, not just runnable.

⚡ Impact

More complexity, more failure modes, more cost — and no extra reliability.

🔥 Why it breaks

Multi-agent systems multiply latency and bugs without multiplying capability.

🛠️ Quick fix

1. 1 Start with one workflow.
2. 2 Introduce specialist agents only when a clear need appears.
3. 3 Measure whether each agent earns its keep.

🏆 Senior move

One agent until proven necessary. Coordination is its own bug surface.