Engineering
Coding agent loops
Coding agents work best when the repo gives them evidence: tests, logs, docs, diffs, browser checks, and a clean stop condition.
Engineering loop library
| Loop | Category | Difficulty | Cadence | Verification |
|---|---|---|---|---|
| API Contract Drift | Engineering | Intermediate | After API changes or SDK releases | Server behavior, client types, examples, and docs agree on request/response contracts. |
| Acceptance Scenario Lockstep | Engineering | Intermediate | Before and during ambiguous feature work | The same scenarios written before implementation pass after the change, and any scope expansion is explicitly approved. |
| Agent Instructions After-Action | Engineering | Beginner | After a successful or painful agent coding session | Repo instructions contain only reusable, source-grounded lessons and the next similar task can start without rediscovering the same trap. |
| Architecture Rubric Refactor | Engineering | Advanced | When architecture work has a defined scope | Scoped module meets the written rubric, tests pass, and unresolved objections are explicit. |
| Behavior Ladder TDD | Engineering | Intermediate | When implementing logic-heavy features | Each behavior test fails before implementation, passes after the smallest change, and remains green through final refactor. |
| Bug Report to Repro Kit | Engineering | Intermediate | Whenever a customer, teammate, or monitor surfaces a bug that is too vague to fix safely | The kit contains a minimal repro path, environment notes, expected versus actual behavior, captured evidence, and either a failing test/script or a clearly marked blocker; no customer reply, public issue, or production change is sent without approval. |
| CI Optimization | Engineering | Advanced | Monthly or when CI is painful | CI p50/p95 improves against the same workflow without weakening tests or hiding failures. |
| Claude Code Repo Readiness | Engineering | Beginner | Before major agent work | Repo has agent instructions, documented commands, architecture notes, risk areas, and a docs/loops scaffold. |
| Cold Load Trim | Engineering | Advanced | When first visit feels heavy | Initial screen downloads fewer bytes while screenshots and behavior remain unchanged. |
| Completion Promise Loop | Engineering | Intermediate | For scoped implementation tasks where half-finished output is the main risk | Every acceptance criterion is checked with tests, browser evidence, logs, screenshots, or a clear blocker report before the agent stops. |
| Feature Flag Retirement Sweep | Engineering | Intermediate | Monthly or after a rollout stabilizes | Each reviewed flag has an owner, purpose, current state, and retirement decision; removed flags pass tests and require approval before production config changes. |
| Fresh Clone Onboarding | Engineering | Intermediate | Before onboarding | A clean machine reaches the documented ready state using only the README. |
| Parallel Agent Worktree Sweep | Engineering | Advanced | When several independent repo improvements can run at once | Each agent branch has isolated scope, passing checks, a summary, and no conflicting files before integration review. |
| Project Docs Freshness | Engineering | Beginner | Nightly or after meaningful code changes | Changed behavior, APIs, CLI commands, config, and workflows are reflected in docs. Docs checks pass. |
| Reference Oracle Implementation | Engineering | Advanced | Before implementing tricky behavior with an external source of truth | Generated outputs match the reference oracle across the agreed fixture set, with tolerances documented for legitimate differences. |
| Schema Migration Dry Run | Engineering | Advanced | Before production database migrations or bulk data changes | Migration runs cleanly on a recent snapshot or staging clone, row counts and sample records match expectations, rollback is documented, and production execution remains approval-gated. |
| Spec to Task Shards | Engineering | Intermediate | Before multi-file feature work or migrations | A written spec, non-goals, acceptance checks, and ordered task shards exist before implementation begins. |
| Test Flake Stabilizer | Engineering | Intermediate | When tests are inconsistent | The repaired test and full suite pass for the required consecutive-run streak. |
| Test and Logging Coverage | Engineering | Intermediate | Weekly or before release | Critical flows have useful tests and structured logs for representative success and failure paths. |
| Trace-First Debugging | Engineering | Intermediate | When an agent is tempted to patch a bug from a hunch | The bug is reproduced, the root cause is evidenced by traces or tests, and the fix includes a regression check. |
| Webhook Replay Harness | Engineering | Intermediate | When webhook integrations fail, drift, or need safer changes | A captured or synthetic payload replays through a non-production handler, expected state changes match assertions, idempotency is proven, and live provider/customer side effects remain approval-gated. |
When to use a coding loop
- Before letting an agent edit a repo for the first time.
- When CI is slow, flaky, or hiding real failures.
- When a bug needs trace evidence rather than hunch patches.
- When multiple agents or branches need merge discipline.
- When an agent needs a completion promise so it cannot stop until every acceptance criterion has evidence.