Chapter 10: Structural Milestones and Complete Rebuilds

Adapted public course. Concepts, procedures and examples are adapted from the internal textbook. Case sizes, timings, improvement figures and target thresholds are illustrative, not site delivery results or universal standards. Verify tools, platforms and skills in your environment. Prompts do not grant permissions and retry counts do not authorize recovery. Preserve work and verify targets, sharing and external-state effects first.

Lesson explanation

10.1 Structural Milestones: Independently Verifiable Engineering Nodes, Not “Requirement-Dimensional Feature Points”

In Chapter 7, we defined a milestone as “an independently verifiable functional unit.” Now we go one step further: in an AI development flow, milestones should not be “requirement-dimensional” but “engineering-dimensional.”

In traditional development, milestones are “requirement-dimensional”—completing the user registration feature is a milestone. But in AI coding, requirement-dimensional milestones are too coarse. A single “user registration feature” may include: database migration, API interface, parameter validation, email sending, frontend form, and error handling. If you let AI write all six parts in one go before verification, you may find that the API’s return format does not match what the frontend expects, the database field naming differs from the backend code’s naming style, and the email sending configuration is hardcoded instead of using environment variables. At that point, the cost of fixing is enormous—because the six parts are already coupled, changing one may drag in five others.

What qualifies as a structural milestone? It does not mean “finished writing a certain file” or “cobbled together 500 lines of code.” It is an intermediate state that runs independently, is testable, and forms a fully self-contained logical loop. It is the equivalent of “topping out a single-floor node” in construction engineering.

For example, completing “the definition of the User Model and its database migration script” is a standard structural milestone. Even if it has no frontend interface at this moment and provides no routing endpoint, its data structure is clear, its field types and relationships are complete, and you can run an insertion operation through a simple unit test or script. Only when this closed-loop milestone is thoroughly locked in and no longer randomly modified can it become a solid foundation for the next milestone (such as developing the login API).

Wrong decomposition (requirement-dimensional) vs. correct decomposition (engineering-dimensional):

Example type: pseudocode. Pseudocode; it is not executable. It expresses decision order only, so implementation must supply real interfaces, authority and error handling.

❌ Wrong decomposition (requirements):
Milestone 1: user registration (database + API + frontend + email)
→ AI writes 800 lines in one go
→ Acceptance finds architectural drift (frontend calls the database directly)
→ Discard this failed implementation; all 800 lines need reassessment or rebuilding

✅ Correct decomposition (engineering):
Milestone 1: Prisma schema for User (10 lines, independently verifiable)
Milestone 2: registration API routing and validation (30 lines, independently verifiable)
Milestone 3: password encryption and JWT issuance (50 lines, independently verifiable)
Milestone 4: registration form (80 lines, verifiable with mock data)
Milestone 5: frontend/backend integration (20 lines connecting both sides)
If acceptance finds drift in one milestone, rebuild that milestone only:
for example, 30 lines of route validation instead of all 800 lines.

Structural milestones also have an important psychological effect: they make “complete rebuild” an easy decision. If AI writes 800 lines of code and then architectural drift is found, your instinctive reaction is “try to fix it”—because the sunk cost of discarding 800 lines of code is too high. But if AI only wrote 30 lines of code, saying “rebuild” carries almost no psychological burden. And “effortless rebuilding” is precisely one of the disciplines that keeps a project healthy.

Systematic dimensional reduction: The first step in the collapse of most projects stems from the developer making a “one-shot wish” to AI. For example, tossing AI a single sentence like “help me write an e-commerce product management system”—this kind of instruction is equivalent to handing a contractor a grand blueprint rendering of a building and telling them to figure it out on their own. An unconstrained AI will inevitably “start work at will” based on intuition, only to discover later that the underlying database table structure fundamentally cannot support complex multi-SKU operations.

Therefore, “systematic dimensional reduction” must be enforced. Before writing any code, the architect must construct the system’s “dependency tree” in mind or in documentation, clarifying the absolute order of implementation:

• Phase one engineering must be laying the foundation—defining database table structures and core data models;
• Phase two engineering is building load-bearing walls—writing core business logic and service-layer interfaces;
• Phase three engineering is running utilities—handling cross-cutting concerns such as authentication, caching, and third-party APIs;
• Phase four engineering is the finish work—handling frontend UI and interaction.

It is absolutely forbidden to let AI skip layers and prematurely implement upper-layer business when the underlying model is not yet established and dependencies are not sorted out.

10.2 The Compute-and-Labor Economic Account: Using It in a Branch Decision

Section 7.5 provides the complete repair/rebuild total-cost calculation, teaching assumptions, and applicability limits, including work protection, human review, and regression verification. This chapter keeps only its operational meaning: at a structural milestone, first identify the failed scope and work that must be preserved, then use Chapter 9’s decision tree to choose NEEDS_FIX or REBUILD. Do not mistake cheap generation for permission to skip acceptance or discard unverified work.

10.3 Three-Step Correction Method: Escalate Instructions → Halt Implementation → Complete Rebuild

When you find that AI’s code does not run or its logic has drifted, firmly avoid “manual patching” and strictly execute the following “three-step correction method”:

Step one: Escalate the instruction (point out the design flaw).

When you spot an error, absolutely do not act like a bricklayer scolding “you misspelled the variable name on line 42” or “that if statement is missing a condition.” You must strike at a higher level in the architect’s language and point out its structural flaw.

• ❌ Bricklayer-style (micro-management): “You misspelled the variable name on line 45” “The if statement here is missing an equals sign” “Add a null check.”
• ✅ Architect-style (escalation): “Your just-completed implementation coupled database operations with network requests, violating the single-responsibility principle. Please extract the data logic into a Repository layer and rewrite it.”

Through this approach, give AI one limited chance to self-correct; use Chapter 9’s acceptance decision tree to decide whether to continue fixing or escalate to rebuilding.

Step two: Halt the implementation.

When Chapter 9’s acceptance decision tree has determined that the work must escalate to REBUILD, do not keep arguing or add more patches. Immediately halt the implementation; stop any attempts on this erroneous branch.

Step three: Complete rebuild (Rollback).

This is the crucial step: identify the failed milestone and the work to preserve, then choose a recovery path from Section 10.4 to return to an accepted foundation. Rebuilding does not always mean running a destructive command; shared faulty commits should be undone with new commits. Then review the clarity of the blueprint (Prompt), revise it, and resume generation.

To ensure that “rebuilding” can happen at any time without psychological burden, we need the weapon in Section 10.4.

10.4 Git’s New Mission: Time Machine and High-Frequency Safety Net

In the past, Git was often used as a collaboration tool for teams to merge code before leaving work each day. But in architect mode, Git is no longer just version control—it is your “time machine and high-frequency safety net.”

This demands an extremely high-frequency Commit discipline: whenever you pass acceptance criteria and lock in even a tiny “structural milestone” (for example, merely getting a User Model’s data migration script to run), do not wait—immediately execute a Commit to “seal” the current absolutely clean, safe system state.

Before the third step, “complete rebuild,” determine whether the faulty commits have been shared and whether uncommitted work needs preserving. Git’s recovery tools act on different things and are not interchangeable.

Safety boundary: git reset --hard is restricted to personal, unshared branches. Never use it to rewrite history on collaborative or shared branches; use git revert. First verify the repository path, current branch, working tree and index contents, and the target commit’s full hash and diff. Confirm that the target is the accepted milestone you intend to restore. Having no upstream does not prove a branch is unshared; if you cannot establish whether others use it, treat it as shared.

--hard discards uncommitted changes to tracked files; untracked files or directories obstructing target files may also be deleted. Preserve needed work first and verify that backups are readable. Git and reflog cannot guarantee recovery of uncommitted content or untracked files. Frequent commits provide recovery points, not permission to delete other work.

Situation	Recovery path	Preconditions and limits
Faulty commits are on a collaborative or shared branch	git revert <full-faulty-commit-hash> creates a new undo commit	Verify each commit, resolve conflicts, and repeat acceptance; merge commits require a separate mainline decision, so do not blindly apply this example
Uncommitted work must be saved before changing approach	git stash push -u -m "before-rebuild"	-u includes untracked files, but not ignored files; inspect saved contents and back up ignored files separately. Restore with git stash apply, verify, then decide what to do with the stash entry
A personal, unshared branch must return to an accepted commit	git reset --hard <verified-full-commit-hash>	Preserve uncommitted work and verify the target and discarded differences before executing

git stash saves working state; it does not undo historical commits. Bare git reset --hard defaults to the current HEAD; it does not find “the last clean milestone.” Start with these read-only checks. Replace placeholders with a verified full hash before considering a recovery operation from the table:

Example type: reference. Reference fragment; it is not guaranteed to run alone. Adapt it to the lesson context, project versions and real interfaces, then validate with observed output.

git rev-parse --show-toplevel
git branch --show-current
git status --short --untracked-files=all
git diff
git diff --cached
git log --oneline --decorate -10
git show --stat <full-target-commit-hash>
git diff <full-target-commit-hash> HEAD

After recovery, inspect the diff and run milestone acceptance before issuing new instructions. Restoring source code does not automatically undo database, external-service, or deployment state; those changes need their own recovery plans. See Git’s official reset, revert, and stash documentation for command semantics.

[Hands-On] A Deliberate Architectural Drift and Rebuild Drill

Purpose: Let trainees personally experience the complete process of “architectural drift → escalate instruction → complete rebuild,” turning “rolling back is not shameful” into muscle memory.

Preparation:

1. Prepare a simple project that already has two milestones (such as a note-taking app with “list + detail”), both already committed;
2. Use an isolated, personal, unshared practice branch; inspect the working tree, index, and untracked files, preserve and verify needed work, and record the accepted milestone’s full commit hash.

Steps:

Step one (create the drift): Issue a deliberately vague instruction to AI: “Add rate limiting.”—do not provide any technical constraints. Observe that AI will most likely directly hardcode a piece of in-memory rate-limiting logic inside the existing authentication middleware file, coupling authentication and rate limiting together (corresponding to the “illegal implementation” scenario in blueprint planning).

Step two (identify signals): Inspect the code and point out architectural drift signals—tampering with the foundation (modifying an already-solidified middleware file) or size out of control (file bloat).

Step three (escalate instruction): Correct in the architect’s language: “The rate-limiting logic should not be coupled in the authentication middleware; please extract it into an independent rate-limiting middleware.” Observe AI’s reaction—it may fall into a self-consistency trap, introducing a bulky and incompatible third-party traffic-control framework for the sake of decoupling, even breaking the original route binding mechanism so the gateway cannot start.

• Decide from inspection evidence. Stop and diagnose repeated failures; preserve work and confirm targets and authorization before recovery. Retry counts do not automatically trigger a rebuild.

Step five (update blueprint then restart): Rewrite the Prompt, refine the blueprint instructions for the rate-limiting mechanism, explicitly requiring “use Redis-driven, maintain middleware isolation”; use Chapter 14’s safety precondition before clearing the polluted dialogue, then feed the new blueprint to a fresh AI instance. Observe that the new round of code generation not only precisely implements the feature but also perfectly preserves the elegance of the architecture.

Retrospective questions:

1. Why does the first “vague instruction” almost inevitably lead to architectural drift? (Lack of constraints)
2. Why is “escalating instruction” more effective than a “micro-management instruction”? (It targets the structural problem, not syntax details)

• Decide from inspection evidence. Stop and diagnose repeated failures; preserve work and confirm targets and authorization before recovery. Retry counts do not automatically trigger a rebuild.

4. When is git reset --hard permitted? (Personal, unshared branch; preserved work; verified target and diff. Use revert for shared commits; stash only saves working state.)
5. Why “open a new dialogue + update the blueprint” after a rebuild? (To cut off AI’s negative memory and restart with a clean context)

Acceptance points:

• Can trainees independently identify the three major architectural drift signals?
• Can trainees issue correction instructions in “architect language” (escalation) rather than “bricklayer language” (micro-management)?
• Decide from inspection evidence. Stop and diagnose repeated failures; preserve work and confirm targets and authorization before recovery. Retry counts do not automatically trigger a rebuild.
• Do trainees understand that “rolling back is not failure, but the most rational economic decision”?

---

Part Three complete. You have now mastered the foundation of AI-assisted programming: the six-step working method (decomposition → issue instructions → coding → acceptance → branch decision → update blueprint), the three disciplines and one supplementary principle (no work without a blueprint, no lock-in without acceptance, rebuild on any chaos, no discussion without terminology), acceptance-driven development (three lines of defense and the acceptance decision tree), and structural milestones and complete rebuilds (the compute-and-labor economic account, the three-step correction method, the Git time machine).

Now, let us enter Part Four: Blueprint and Architecture—Using Documents and Boundaries to Frame AI. There, you will learn how to turn “no work without a blueprint” from a slogan into a CONTEXT.md that can actually constrain AI.

Independent exercise

Use fictional or authorized deidentified material. Answer independently before revealing the reference. Save chapter-10.md with versions, decisions, evidence and gaps.

Draw validation → classification → API → UI dependencies. Compare a local contract repair with milestone recovery and list read-only checks and backups.

Required chapter artifact: structural-milestone dependency map

The submission for this independent exercise must contain the evidence below. The existing prompts supply content but do not replace these acceptance items.

• O1: The structural-milestone dependency map orders data foundation, service boundary and interface integration by dependency
• O2: Every layer in the structural-milestone dependency map states its input, completion rule and reviewable evidence
• O3: The artifact lists dependencies, version points and exits for data, service and interface milestones

Reveal reference feedback (answer first)

Reference feedback

Verify repository, branch, status, full target hash and diff; preserve tracked, untracked and needed ignored files. Shared changes need a reviewable reverse commit. Personal branches do not justify discarding work without confirmation. Git recovery does not restore databases or deployments; rerun inspection.

Self-review and next steps

Check whether your decision is explicit, evidence reproducible and unknowns honestly recorded. The reference illustrates one defensible approach, not a unique answer. Seek peer review for alternatives with equivalent evidence. Mark unsupported parts unfinished and revisit the corresponding step.