Agentic Engineering

Appearance

Scope and Context Failures ​

These five modes are failures of attention and memory, not of syntax. The context window is finite; the latest user message is overweight; unwritten constraints evaporate; coupling the agent never saw still breaks. Treat them as one cluster with shared prevention: tight scope in the spec, durable constraints in the repo, and blast-radius review before merge.

1. Changes unrelated files ​

Symptoms ​

  • PR for "add CSV export" also reformats auth/middleware.ts and "cleans up" unrelated utils.
  • Drive-by renames, dependency bumps, or lint autofixes across the monorepo.
  • Review noise hides the real behavior change.
  • Regressions in files nobody intended to touch.

Root cause ​

Agents optimize for local neatness and will expand the diff when lint/type errors appear adjacent — or when the prompt said "improve" without a fence. No mandate boundary = infinite surface.

Early detection ​

  • First review pass is file list only (Verification Strategy).
  • git diff --stat against the paths named in the spec.
  • Unexpected lockfile or workflow changes.

Prevention ​

  • Spec / prompt: "touch only these paths; stop if you need others."
  • Builder role mandate: no drive-by (Agent Roles).
  • Reject PRs that mix feature + mass reformat; split them.

Recovery prompt ​

text
Revert all changes outside <allowed paths>. Keep only the
diff required for docs/specs/<feature>.md. If a change outside
those paths is truly required, list it and wait — do not keep it
in this branch. Re-run tests after the revert.

Review checklist ​

  • [ ] Every changed file maps to a spec/task bullet
  • [ ] No unrelated reformat/rename/dep bump
  • [ ] Workflow and config files untouched unless that is the task

2. Overfits to the latest instruction ​

Symptoms ​

  • Mid-task "also make it faster" causes the agent to abandon the carefully approved design.
  • Earlier constraints (idempotency, tenancy) disappear after a narrow follow-up.
  • The PR satisfies the last chat message and violates the spec written yesterday.
  • Oscillating implementations across consecutive prompts.

Root cause ​

Recency bias in the context window. Chat instructions overwrite durable specs unless you force hierarchy: spec > CLAUDE.md > current message. See Context and Instruction Hierarchy.

Early detection ​

  • Diff against the spec, not against the last message.
  • Agent summary that cites chat but not spec lines.
  • Sudden deletion of previously green tests after a "quick fix" prompt.

Prevention ​

  • Put load-bearing rules in files; treat chat as ephemeral steering.
  • Prompt footer: "spec wins over this message if they conflict; call out conflicts instead of choosing."
  • After any pivot, update the spec before more coding (Keeping Specs Alive).

Recovery prompt ​

text
Ignore the last chat turn's improvisation. Re-read
docs/specs/<feature>.md and CLAUDE.md. Diff the branch against
those artifacts. Restore any constraint the latest instruction
caused you to drop. List conflicts between chat and spec for
human decision — do not silently pick chat.

Review checklist ​

  • [ ] Behavior matches spec, not only the latest comment
  • [ ] Earlier constraints still evidenced in tests
  • [ ] Spec updated if the latest instruction was an intentional product change

3. Forgets previous constraints ​

Symptoms ​

  • Session 1: "never log PII." Session 4: debug logging of request bodies with emails.
  • Rate limits, feature flags, or migration expand/contract rules vanish mid-project.
  • Agent apologizes and re-applies the constraint — then forgets again after /clear.

Root cause ​

Constraints in chat are not memory. /clear and new sessions drop them. Only repo artifacts persist. This is the same mechanism as missing invariants in Why Agents Fail.

Early detection ​

  • Constraint checklist in the PR template for sensitive work.
  • Grep for known forbidden patterns (PII logs, bypass flags).
  • Ask the agent to restate constraints before coding; compare to CLAUDE.md.

Prevention ​

  • Move every survived constraint into CLAUDE.md, spec, or ADR the same day.
  • Hooks / lint for high-value forbids (secret scan, PII log rules).
  • Handoff notes point to files, not "as we discussed."

Recovery prompt ​

text
Restate all constraints from CLAUDE.md and docs/specs/<feature>.md
that apply to this branch. Audit the diff for violations.
Fix violations minimally. Propose CLAUDE.md one-liners for any
constraint that existed only in chat.

Review checklist ​

  • [ ] Sensitive constraints restated and checked
  • [ ] New durable constraints written into repo docs
  • [ ] No "temporary" bypasses left enabled

4. Breaks hidden flows ​

Symptoms ​

  • Green unit tests; webhook consumer, mobile client, or ETL breaks.
  • Cron job depended on column type / enum / JSON key order.
  • Removing an "unused" field that a report still selects.
  • Change looks correct in every file the agent opened.

Root cause ​

Hidden coupling is invisible to local reasoning. Agents cannot respect what they cannot see. Blast radius lives outside the touched package.

Early detection ​

  • Require a blast-radius list in the plan: callers, consumers, jobs, clients.
  • Contract tests at boundaries (Verification Strategy).
  • Search for symbol/API usages across the monorepo and sibling repos when relevant.

Prevention ​

  • Document cross-system contracts in-repo.
  • Prefer additive changes; expand/contract for schema.
  • Integration/contract tests the agent is not allowed to delete.

Recovery prompt ​

text
Something outside the touched files depends on the old behavior.
Given symptom <paste>, identify consumers (code search + docs).
Restore compatibility (additive fix or feature flag) before any
cleanup. Add a contract/regression test that fails without the fix.
Do not remove the old shape until consumers are confirmed.

Review checklist ​

  • [ ] Blast-radius list reviewed
  • [ ] Contract/integration coverage for changed boundaries
  • [ ] No removal of fields/endpoints without consumer audit

5. Removes important edge cases ​

Symptoms ​

  • "Simplified" validation drops empty-string / unicode / leap-year handling.
  • Agent deletes a regression test that was "in the way" of a green build.
  • Rare branch in production errors after a "cleanup" PR.
  • Comments say edge case handled; code path gone.

Root cause ​

Under pressure to fix or green CI, agents reduce surface area. Edge cases look like complexity, not value — especially if not named in the current prompt. Related to stuck-loop thrash and mock/false confidence.

Early detection ​

  • Diff test files for deletions/skips first.
  • Grep for historical regression names / issue IDs.
  • Compare edge-case list in spec to remaining tests.

Prevention ​

  • Forbid deleting or skipping tests without explicit approval (Quality Gates).
  • Name edge cases in the spec so absence is greppable.
  • Separate cleanup PRs from behavior PRs.

Recovery prompt ​

text
Restore edge-case handling and tests removed in
git diff <before>...<after>. Enumerate each restored case.
If an edge case is intentionally dropped, it must be removed
from the spec first with human approval — do not silently delete.

Review checklist ​

  • [ ] No test deletions/skips without explicit approval note
  • [ ] Spec-named edge cases still present
  • [ ] "Cleanup" did not reduce domain strictness

A field manual for AI-native software engineering.