FIELD NOTE 01 / RELEASE DELIVERYOBSERVED / PREVIEW URL
The build shipped.
The URL didn't.
A preview deployment completed an asset upload, yet its deployment result showed no active preview URL. The mistake would be to read “deployment succeeded” as “a person can now use the application.” Those are different pieces of evidence.
THE SIGNALGreen-ish deployment output
The system produced a preview artifact, but opening the expected route was a separate concern. Publication and routing were not the same verified event.
THE FALSE SHORTCUTTrust a status message
It is tempting for a coding agent to summarize a finished deploy command as a completed user journey—even though no browser visited the actual address.
THE CORRECTIONName the delivery states
Distinguish built, uploaded, deployed, routable and smoke-tested. Require the deployed URL as evidence, not an inferred URL.
THE ACCEPTANCE CHECKTest the destination
Open the exact preview address, confirm expected HTML and assets, then complete one core user action. Report any step that remains blocked.
THE HARNESS RULENever mark a feature “deployed and verified” from a command exit code alone. Separate what changed in source from what was observed in the runtime.
TRY IT / STARTER → SENIORBeginner: after deploying, load the page on a second device. Experienced: add a route-level browser smoke test that confirms content, assets, and the top user interaction at the exact release URL.
FIELD NOTE 02 / RUNTIME PARITYOBSERVED / DIFFERENT BEHAVIOR
Local works.
Production doesn't.
A browser confirmation interaction worked in local development but did not open correctly on production. Even when dependency package versions appeared the same, the experience still diverged. The exact root cause was not established by that observation alone.
THE SIGNALOne interaction, two outcomes
Identical-looking application code and dependency reports can still sit inside different bundles, caches, runtime configuration or request paths.
THE FALSE SHORTCUT“Both versions match”
A matching package version is a useful check, not a complete diagnosis. An agent should not guess which layer failed simply because the easy comparison passed.
THE CORRECTIONCompare observed execution
Reproduce the same action, inspect the loaded assets, console behavior and relevant runtime conditions, then form one falsifiable hypothesis at a time.
THE ACCEPTANCE CHECKVerify in production-like reality
Check the specific user interaction in the target environment. Record the observed pass/fail and the remaining unknowns instead of claiming the root cause without evidence.
THE HARNESS RULE“Works locally” is a test result scoped to local. Require production-relevant reproduction before claiming a production bug is resolved.
TRY IT / STARTER → SENIORBeginner: ask your coding agent to write a minimal step-by-step reproduction. Experienced: add an environment-parity checklist and a browser test that asserts the interaction, not just that the bundle exists.
FIELD NOTE 03 / SERVICE BOUNDARIESDESIGN RISK / CONTRACT DRIFT
Two agents.
Two different truths.
When frontend and backend live in different repositories, each coding agent can make individually plausible choices that are incompatible at the API boundary. This was identified as a critical architecture risk during active product planning—not described here as a confirmed production outage.
THE FAILURE CLASSMatching screens, mismatched payloads
A UI can look complete on mock data while assumptions about auth, errors, resources or lifecycle states drift from the backend contract.
THE FALSE SHORTCUT“The agent knows the endpoint”
Separate AI coding sessions don't share unspoken agreements. A prompt summary is not an authoritative API contract unless both sides test the same rules.
THE CORRECTIONPut the contract in one place
Give one repository or artifact explicit ownership of API definitions, version the changes and make client expectations reviewable.
THE ACCEPTANCE CHECKSmoke the full boundary
Run agreement checks for successful responses, validation errors, permissions and malformed data. Check the frontend against the documented contract rather than inventing fallback results.
THE HARNESS RULELLM agents may implement on both sides, but neither side gets to improvise the same interface independently. Choose one source of API truth and test both consumers.
TRY IT / STARTER → SENIORBeginner: draw one request and response for your main button. Experienced: create a contract fixture plus negative tests for unauthorized, malformed, stale and retried requests.
FIELD NOTE 04 / DATA MOVEMENTOBSERVED / IMPORT INTERRUPTION
Imported.
But reconciled?
During a database migration, duplicate-key problems interrupted an import before a subsequent import reported success. That kind of experience teaches a durable rule: “command completed” and “authoritative data is safely reconciled” are different claims.
THE SIGNALInterrupted migration
Data movement can fail after some writes have already happened. Blindly rerunning the same import can create duplicates or obscure whether anything was lost.
THE FALSE SHORTCUTTrust the final success log
A completion message may report an import step, but it doesn't establish identity mapping, relationship integrity, active workflows or readiness for cutover.
THE CORRECTIONMake recovery repeatable
Define a clean target state, an idempotent/recoverable import, source-to-target count checks and relationship integrity verification before switching live traffic.
THE ACCEPTANCE CHECKReconcile and test operations
Compare authoritative counts and selected records, check constraints, exercise the important workflows, and keep a rollback plan. The specifics must be validated in the actual system.
THE HARNESS RULEFor consequential changes, ask an agent to show a reconciliation report and recovery evidence—not only its final command output.
TRY IT / STARTER → SENIORBeginner: try an intentionally duplicated CSV import in a disposable dataset. Experienced: run an interrupted/replayed migration rehearsal with count, integrity and idempotency assertions.