Test, Debug, and Recover
Build a layered safety net with checkpoints, Git, GitHub, browser tests, and practiced rollback instead of hoping each prompt works.
By the end
A reviewable change history, critical-journey test suite, App Testing evidence, and a recovery drill that preserves both code and data intentionally.
Use three kinds of history
Agent checkpoints save meaningful milestones and can preserve project context beyond source files. Git records code and configuration history in commits and branches. File history helps recover granular editor changes. These overlap, but they are not interchangeable. Use checkpoints for Agent-led milestone recovery, Git for durable review and collaboration, and file history for a narrow accidental edit.
GitHub is a remote home for the Git repository, not an automatic copy of every database or Replit project resource. A push can back up and share code history; it does not by itself preserve production data, secrets, Agent conversation, or the currently published release. Your recovery plan must name each state category separately.
Make history meaningful
A good checkpoint or commit represents one coherent outcome and says what changed. Review the diff before accepting it. Keep generated lockfile changes when they correctly reflect dependency updates, but question unrelated file churn. A large unexplained diff is a reason to pause, not proof of sophistication.
Create a branch for work that is experimental, risky, or expected to span several checkpoints. The default branch should remain a known integration line. Before merging or pushing, ensure the branch has the intended commits, tests pass from a clean state, and no secret or private data is included.
Codify project and workspace context
A root-level replit.md is the project's operating context for Agent. New Agent-created projects normally generate it automatically; an older project can add it manually at the project root. Keep it current and concrete: purpose, architecture map, approved package manager, exact run and test commands, data boundaries, coding patterns, must-preserve behavior, communication preferences, and release gates. Never put credentials or private records in it because it is project source and Agent context.
Use workspace customization for rules that truly apply to every project. In Workspace Settings → Customization, short custom instructions load on every message; workspace Skills load only when their description matches the task. Do not copy a long project specification into always-on instructions. Overloaded context makes important rules harder to follow and wastes room needed for the current task. Project-specific facts belong in replit.md; reusable specialized workflows belong in Skills; universal workspace policy belongs in short custom instructions.
- replit.md: this project's purpose, architecture, commands, boundaries, and decisions.
- Workspace custom instruction: a short rule that must apply everywhere.
- Skill: a focused workflow or reference Agent should load only for matching work.
- Source code and tests: deterministic enforcement when an instruction is not enough.
Extend Agent with Skills and MCP
Skills define how Agent should work. Try one for a single message from the + button beside chat → Use a skill. Install a project skill from the Skills pane when its behavior should persist across conversations; installed files live under /.agents/skills. A reactive skill is especially valuable after solving a non-obvious defect: capture the reproduction, correct pattern, deterministic check, and when the skill should or should not run. Read every external skill before installation, keep scopes narrow, and benchmark it against an example rather than assuming the prose works.
MCP defines what Agent can access or do in another system. Open replit.com/integrations and scroll to MCP Servers for Replit Agent. For a trusted pre-listed server, select Sign in and review the service's OAuth account and scopes. For a trusted custom server, select + Add MCP server, name it, enter its HTTPS endpoint, add authentication only through the supported configuration, then Test & save. Begin with a read-only request, inspect the tool result and any confirmation prompt, and disconnect access no longer needed. A useful tool is still an authority boundary: it can expose data or perform consequential actions.
- Use a Skill for repeatable instructions, conventions, and verified techniques.
- Use MCP for live tools, external data, and actions.
- Inspect external Skill source and MCP scopes before granting trust.
- Prefer a read-only proof before enabling writes.
- Record owner, account, scopes, environment, and revocation path for every connection.
Test at the right layers
A unit test checks a small rule, such as whether self-approval is forbidden. An integration test checks cooperating boundaries, such as a server route writing the expected database rows. A browser journey checks the real interface and network path. A production smoke test checks a small safe path at the published URL. Use the cheapest layer that can catch each risk, then cover the critical journey end to end.
Tests should assert outcomes, not implementation trivia. Seed deterministic users and records, isolate test data, and clean it up. Include invalid input, unauthorized access, duplicate submission, external failure, narrow screens, and reload behavior. An all-green suite can still miss the workflow if its examples never resemble real use.
Supervise App Testing
Replit App Testing currently supports Full Stack JavaScript and Streamlit Python web applications. Open the Agent settings dropdown in the chat input, choose Economy or Power, expand Advanced settings, and turn on App Testing; Lite keeps it off. Agent decides when enough has changed to test, so also state the exact critical journeys you expect. Testing is billed through Agent's effort-based pricing, and a longer browser session can consume more usage.
Watch the browser run, then open the interactive replay and inspect its sections rather than trusting the summary. Some flows pause for Begin take over when login or another human-controlled step is required. Use synthetic accounts and data. Never enter a sensitive production credential into a replay. If the project is not a supported stack, record App Testing as unavailable and use the project's own browser-test runner or a written manual journey; do not report a skipped platform feature as a passing test.
Debug with hypotheses and drill recovery
Reproduce the failure, preserve exact evidence, and form a hypothesis about the earliest incorrect boundary. Change one cause, then repeat the same check and relevant regressions. Avoid piling speculative fixes into one Agent prompt. If a change makes the app worse, compare with the known-good checkpoint before deciding whether to fix forward or roll back.
Practice recovery before launch. Roll back a development checkpoint with and without the database option and observe the difference. Revert a Git commit on a practice branch. Restore the intended version, rerun tests, and document the elapsed time and missing steps. Recovery is an operator skill, not a button label.
Working reference
Commands and patterns
Review working changes
git status --short git diff --stat git diff --check git diff
See scope, whitespace errors, and exact changes before committing, rolling back, or asking Agent for more work.
Create an isolated feature branch
git switch -c feature/approval-history git status --short
A branch isolates a coherent experiment in Git. Use a project-appropriate name and confirm existing changes before switching.
Run declared quality checks
npm run test --if-present npm run lint --if-present npm run build --if-present
These common JavaScript checks run only when declared. Use the actual stack's commands and do not treat a build as a browser-journey test.
Inspect recent history and remotes
git log --oneline --decorate -12 git remote -v
Confirm which commits exist locally and which remote repository is configured without changing or pushing anything.
Inspect Agent context without changing it
sed -n '1,220p' replit.md 2>/dev/null || true find .agents/skills -maxdepth 2 -type f 2>/dev/null | sort | head -80
Review project guidance and installed Skill files before relying on them. Keep secrets and private records out of both.
When the happy path breaks
Failure modes
Symptom
Rolling back code unexpectedly destroys wanted database changes, or leaves incompatible data behind.
Likely cause
The operator did not distinguish checkpoint project state, optional development database restore, Git history, and production data.
Recovery
Inventory state categories before rollback, preview the target, choose database scope deliberately, and verify both schema and known rows afterward.
Symptom
GitHub is current, but the team still cannot restore the running product.
Likely cause
The remote repository was treated as a backup for secrets, database contents, platform configuration, and deployments.
Recovery
Maintain separate recovery procedures for source, configuration, credentials, data, and published release state.
Symptom
App Testing reports success while a critical business rule is wrong.
Likely cause
The test journey checked navigation and visible elements but did not assert authoritative data or policy outcomes.
Recovery
Provide explicit Given/When/Then scenarios and pair browser evidence with database, audit, or API receipts.
Symptom
A fix for one defect produces repeated regressions elsewhere.
Likely cause
There is no permanent test for the original failure or must-preserve behavior.
Recovery
Add the smallest regression test that fails before the fix and passes after it, then run the broader critical suite.
Symptom
Agent repeatedly ignores current commands or architecture and produces inconsistent changes.
Likely cause
replit.md is absent, stale, generic, or contradicted by a broad workspace instruction or overlapping Skills.
Recovery
Update project facts and commands in root replit.md, narrow workspace instructions, remove conflicting Skills, and verify behavior with a small task.
Symptom
An MCP-assisted task reads or changes more external data than expected.
Likely cause
The server, signed-in account, tool list, scopes, or confirmation boundary was not reviewed before use.
Recovery
Stop writes, revoke or disconnect the server, inspect its authority and logs, reconnect least privilege if still needed, and begin again with a read-only proof.
Hands-on lab
Prove and recover the critical journey
Create durable history, test the app across layers, introduce one controlled defect, and return to a known-good state.
- 01Confirm a clean or understood working state, create a feature branch, and record the latest known-good checkpoint.
- 02Open root replit.md and add the real run, test, and build commands; project boundary; synthetic-data rule; server-authorization requirement; and must-preserve journey. Ask Agent to restate these rules, then verify its answer against the file.
- 03Identify the generated stack from package.json, pyproject.toml, and the running process. Ask Agent to select the project's existing test framework; add unit checks for one domain rule, an integration check for approval persistence/history, and a browser journey without replacing working tooling unnecessarily.
- 04If the app is Full Stack JavaScript or Streamlit Python, select Economy or Power in Agent settings, expand Advanced settings, enable App Testing, and request the exact happy, cross-user denial, reject, timeout, reload, and mobile scenarios. Review the replay and sections. If the stack is unsupported, record that fact and execute the project-native browser runner or the same written journey manually.
- 05Open + → Use a skill to inspect the interaction, then create a narrowly scoped reactive Skill from the eventual regression fix. Read the generated file under /.agents/skills, add when-to-use and when-not-to-use rules plus the deterministic test command, and replay one matching and one non-matching prompt.
- 06Open replit.com/integrations → MCP Servers for Replit Agent. Connect only a trusted, authorized server and account. Record tools and scopes, run one read-only request with synthetic or non-sensitive data, capture its confirmation/result, then disconnect it after the lab unless there is an approved ongoing need. If no server is authorized, document the denied connection decision instead.
- 07Introduce a controlled development-only defect, capture the failure, and add a regression test that detects it.
- 08Use the intended checkpoint or Git recovery path, make the database choice explicit, and verify code, schema, data, and behavior.
- 09Commit the coherent result, inspect the configured GitHub remote, and push only if the repository and branch are intentionally connected.
Deliverable: A branch with layered tests, reviewed App Testing evidence, one regression test, and a timed recovery record covering code and data.
Reusable artifact
Test and recovery matrix
Use one row per material risk before a release candidate is approved.
RISK / PROMISE: [what could fail or must remain true] UNIT CHECK: [small rule and expected result] INTEGRATION CHECK: [boundaries and authoritative receipt] BROWSER JOURNEY: Given [...] when [...] then [...]. APP TESTING: [supported stack? mode, Advanced setting, scenarios, replay, effort/cost note] AGENT CONTEXT: [replit.md rule and verified command] SKILL: [scope, source reviewed, matching/non-matching benchmark] MCP: [server, account, tools/scopes, read-only proof, revoke/disconnect path] PRODUCTION SMOKE: [safe read or reversible action] TEST DATA: [synthetic accounts and cleanup] KNOWN-GOOD CHECKPOINT / COMMIT: [identifier] ROLLBACK SCOPE: [code, project config, development DB, production DB] RECOVERY VERIFICATION: [source, schema, rows, workflow, publish] LAST DRILLED: [date, duration, gaps found]
Before you move on
Receipt checklist
- The Git diff contains one understood outcome and no credential or unrelated private-data changes.
- Unit, integration, and browser checks cover the critical journey and at least one denial or failure path.
- App Testing evidence records supported stack, Economy or Power mode, the enabled Advanced setting, reviewed replay, usage awareness, and an authoritative state receipt—or explicitly records why the stack requires another browser path.
- Root replit.md names real commands and boundaries; one reviewed Skill passes a matching and non-matching benchmark; one authorized MCP connection has a read-only receipt and revocation path, or its connection was deliberately denied.
- A regression test detects the controlled defect and passes after recovery.
- The recovery drill verifies code, configuration, schema, known data, and the user journey separately.
Primary sources
