Designing AI Coding Loops That Actually Converge

How to Design a Loop: Using a Login Module as an Example

Part 2 of the series · Prerequisite: Part 1: Getting Started with Loop Engineering: Stop Commanding AI Step by Step

The previous article discussed the three questions of a Loop: what qualifies as passing, what to tell the AI when it fails, and when to stop. This article uses a real example—an Android login module—to walk through the complete design process for these three questions.

1. First, Choose a Carrier: Why a Login Module

As stated in Part 1: the evaluation criteria equals domain judgment. A login module is one of the most familiar modules, so the criteria can be listed with eyes closed.

Assume your app needs email + password login, and stores a token upon success. Now, let the AI automatically develop this module.

2. Card 1: What Qualifies as Passing? (Evaluation Criteria)

This is the most critical step. Many people get stuck here because they write "qualified" as an adjective.

Wrong Example (unexecutable):

Let the AI write a good login module

How do you score "good"? The AI can only say "I wrote it pretty well," claiming it meets the standard in the first round—false pass.

Correct Approach: Break "good" down into verifiable clauses.

Six criteria were set for the login module:

① Compilation passes            ./gradlew assembleDebug → BUILD SUCCESSFUL
② Architecture consistent        Follows the project's existing pattern: Interface + Provider + Repository + ViewModel + Dependency Injection
③ State correct                  Login state (idle/loading/success/error) is observable in StateFlow
④ Edge case handling             Empty input / email format / password length / error prompts
⑤ Token persistence              Token stored in local storage, persists after restart, automatically cleared upon expiry
⑥ View state only                UI does not maintain login judgment; everything is driven by ViewModel state

All six criteria share a common trait: they are verifiable. You can run a compilation, check the code, test a restart. Not a single adjective.

Two design points:

Criteria must be fixed before generation. If you set criteria after seeing what the AI wrote, the criteria will be led by it, which is equivalent to not setting any.
Criterion ⑥ is a judgment based on Android development experience—"scattered state sources" is the most common architectural pitfall in login modules. If the UI judges the login state itself, bugs are inevitable later.

3. Card 2: What to Tell the AI When It Fails? (Feedback Content)

When the AI's output doesn't meet the standard, how do you give feedback? This is the second biggest pitfall.

Wrong Example:

Revise it again, it's not well written.

The AI doesn't know what's wrong and can only make blind changes, going in circles—spinning its wheels.

Correct Format (Location + Problem + Severity):

[LoginRepository.kt:15] Token uses a memory variable, lost on restart | Critical
[MainActivity.kt:20] UI maintains its own login judgment, should rely on ViewModel state | Medium

Without evidence-based feedback, the AI cannot determine what it did wrong and will inevitably spin its wheels. Feedback must be specific down to "which file, which line, what problem, how severe."

4. Card 3: When to Stop? (Termination Conditions)

The final question. Three conditions used in combination:

① All six criteria met → Stop
② OR 2 consecutive rounds with no new issues → Stop
③ OR Maximum 5 rounds → Stop

Why combine them? Each has its own role:

① is the quality target: stop immediately when truly met, this is the most desired outcome.
② is the convergence safety net: two consecutive rounds without new issues means further runs won't yield progress, preventing meaningless spinning.
③ is a hard circuit breaker: a maximum of 5 runs prevents infinite loops caused by unreasonable criteria or tasks beyond capability.

Relying only on ① might cause an infinite loop; relying only on ②③ might truncate the process prematurely with insufficient quality. The combination means "quality first, while guaranteeing it will eventually stop."

5. Judgment Authority: The Easiest Pitfall to Miss

"Who judges if the standard is met?" Many people leave this blank, and those who fill it often fill it wrong.

Self-assessment (Toy-grade, unreliable):
  AI writes code → The same AI self-checks "Does it meet the standard?"
  → The same brain has fixed blind spots: what it thought was right when writing, it still thinks is right when checking.
  → Might stop at a "false pass" in the first round.

Independent Review (Industrial-grade):
  AI writes code (Generation Agent) → Another AI checks (Review Agent)
  → Different brains, no preset assumption of "what I wrote is correct."
  → Can discover real problems.

Letting the AI check itself is the biggest pitfall. It's like letting a student grade their own exam—either optimistically giving a false pass, or conversely, pretending to be strict and nitpicking randomly.

The practice of independent review:

The Generation Agent writes code according to the six criteria.
The Review Agent independently verifies: reads actual files, truly runs compilation, does not trust the generator's self-check.
The Generation Agent can appeal the review conclusion → the reviewer re-examines.

6. Deliverable Checklist: Preventing Structural Drift

Running a Loop encounters another problem—the AI's structure differs every round:

Round 1: Validation logic written in the UI layer.
Round 2: Feedback says "Validation should be in ViewModel" → AI moves it.
Round 3: You discover the UI from Round 1 has been messed up...
→ Structural drift, refactoring every round, never converging.

Solution: Define a deliverable checklist—fix the core files, so each round is judged against the same file structure.

Core files that must be generated:
  Login state / Login interface / Login implementation / Token storage / Repository layer
  ViewModel / Login UI / Dependency injection registration / Entry point navigation

But don't make the checklist too rigid, or it limits the AI's potential. Three tiers are defined here:

Tier 1: No restriction on file structure, AI has free rein, prone to structural drift.
Tier 2: Core files must be generated, additional files allowed (but require justification).
Tier 3: Strictly limited to files in the checklist, no new files allowed, overly rigid.

Tier 2 is the most reasonable, preventing structural drift while leaving room for the AI to perform reasonably.

7. Calibration: Run It, See Where the Design Breaks

The three cards designed on paper are just that—paper. Only by actually running a round can you see where it breaks. Three failure signals for self-diagnosis:

Failure 1: "False pass" in the first round.
  Review passes completely, but you can clearly see it's not good enough.
  → Criteria are too loose, or the review is cutting corners (self-assessment).
  → Fix: Tighten criteria / Separate generation and review.

Failure 2: Spinning wheels.
  Feedback is given each round, but after 5 rounds, the same spot is still being changed.
  → Feedback is not specific; the AI doesn't know how to fix it.
  → Fix: Feedback must include location + evidence.

Failure 3: Never meets the standard.
  Runs for 8 rounds, the score is stuck and won't go up.
  → Criteria are too high, or the task exceeds the AI's capability.
  → Fix: Lower the bar / Break down into smaller tasks.

Calibration mindset: Design intent ≠ Actual behavior. Finding that the standard isn't met when running doesn't mean the design is wrong; it means "your criteria contain clauses the AI cannot satisfy"—change the design, don't stubbornly stick to it.

8. Summary of This Article

Designing a Loop involves seven steps:

① Choose a familiar carrier (evaluation criteria = domain judgment)
② Define Card 1: Break "qualified" into verifiable clauses (six criteria)
③ Define Card 2: Feedback with location + problem + severity (ban "revise it again")
④ Define Card 3: Combine three termination conditions
⑤ Assign judgment authority to an independent reviewer (ban self-checking)
⑥ Define a deliverable checklist (prevent structural drift)
⑦ Run one round for calibration (adjust design based on actual failures)

Every step was learned from stepping into pitfalls: false passes, spinning wheels, structural drift, self-assessment—all are real pitfalls that have happened.

The next article covers the final piece: For a designed Loop, should you drive it with documentation or scripts? And how exactly to use the official /goal /loop /workflows /schedule commands.

Next Article: Documentation or Scripts? — A Complete Guide to Making AI Work Automatically