How I Recovered Design Understanding After Speedrunning Approval Buttons

TL;DR

• In AI-agent-assisted development, the risky part was not generation itself. It was approving changes without carefully reading them.
• To recover not only the What but also the Why, I use a fixed prompt that asks the agent to reconstruct the design intent.
• Reading is not enough to deepen understanding. Small experiments that intentionally break behavior are effective.

Introduction

Development with AI agents is fast. But if I approve proposals by momentum, I am the one who pays for it later.

"It works, but I cannot explain why it was designed this way."

Once I reach that state, every follow-up feature and refactor starts to feel risky. In practice, the hard part was not reading the code. It was the missing design intent.

What Disappears Is Not What, but Why

I can usually trace what the code does. What I really need, though, is the context for the next decision:

• Why this structure was chosen
• Why the other options were rejected
• Where future debt is likely to appear

When that context is vague, each feature addition becomes another change that "happens to work."

The Fixed Prompt I Use to Recover Understanding

So I use a prompt that asks the AI to act as an experienced tech lead and the real designer of the system, then dissect the implementation. The important parts are these four:

1. First read README.md, AGENTS.md, and docs/ to find the specs and constraints.
2. Summarize the architecture in one minute.
3. Explain the implementation Why and the alternatives that were rejected.
4. Propose a menu of breakage experiments.

The goal is not just to receive a code explanation. The goal is to get back to a state where I can make the next decision myself.

Why I Go as Far as Experiments

When I only read the code, it is easy to feel like I understand it. To make the understanding stick, intentionally breaking small parts and observing the behavior and errors is usually the fastest route.

Examples of small experiments:

• Remove one validation rule and confirm where the guardrail actually exists.
• Change a dependency setting and make unexpected side effects visible.
• Make error handling one layer shallower and observe the blast radius during failure.

The hands-on feedback from those experiments becomes the resolution of my design understanding.

Summary

The failure point in AI-agent-assisted development was not implementation speed. It was approval speed. That is why, whenever I notice that I approved too quickly, I insert a reverse-engineering step.

To turn "working code" back into "code I can explain."