18. Vibe Coding for Existing Codebases

What this section is for

Existing codebases are where AI-assisted development creates the most value—and the most risk. Value comes from speed: you can understand and change large systems faster. Risk comes from hidden contracts and regressions.

This section teaches workflows that keep changes:

• small and reviewable,
• grounded in tests and evidence,
• bounded to specific files and scopes,
• safe in legacy code where behavior is fragile.

Why existing codebases are different

Greenfield code can be “plausible.” Existing code must be compatible. Existing codebases have:

• implicit behavior relied on by other systems,
• quirky edge cases baked into production,
• tests that encode real contracts (when you’re lucky),
• constraints around dependencies, performance, and deployment.

If you ask the model to “improve the code,” it may break those contracts. This section teaches the guardrails that prevent that.

A safe workflow for existing repos

1. Repo tour: orient quickly with file tree + entrypoints.
2. System map: document modules, dependencies, and data flow.
3. Plan first: propose small steps with verification after each step.
4. Diff-only changes: avoid rewrites.
5. Tests as truth: add regression tests before risky changes.
6. Extract seams: in legacy code, create safe boundaries before changing behavior.

Principles that prevent disasters

• Small diffs: if you can’t review it, don’t accept it.
• File scope: “only touch these files” is a core control.
• Behavior preservation: refactors are behavior-preserving; feature changes have explicit acceptance criteria.
• Evidence: errors, tests, and logs are the input to the next prompt.
• Ship points: commit after stable checkpoints.

Section 18 map (18.1–18.5)

• 18.1 “Repo tour” prompts that work
• 18.2 Creating a system-level map (modules, dependencies, entrypoints)
• 18.3 Safe refactoring prompts (small steps, diffs, tests)
• 18.4 Legacy code: extract seams before changing behavior
• 18.5 Migrating frameworks or libraries with AI help

Where to go next

• Start with 18.1
• Then go to 19 (debugging & incident response)