A practical guide for engineering teams and business leaders on working with AI on existing codebases — from a single service to one million lines.
The most common failure mode: treating the model as a search engine. A better frame: an exceptionally talented engineer who arrived this morning with no prior knowledge of your company, codebase, or product.
“The quality of AI output is determined by the quality of context you provide. Prompting is onboarding.”
You would not hand a new hire a ticket and say “go fix this bug.” You would invest time in orientation — business context, system architecture, team conventions, past decisions and their reasons. The quality of their work would be directly proportional to the quality of that onboarding.
The AI has no memory between sessions. Every session is Day One for a new hire. This means context investment must be reusable, structured, and maintained like code — not rebuilt from scratch each time.
This also means Opus specifically rewards the approach more than lighter models. Its capability ceiling is genuinely high. The bottleneck is almost always context quality, not model quality. Giving Opus a thin prompt is like hiring a consultant and refusing to brief them.
Note for business leaders: Layer 1 is your layer. Documenting business intent in plain language — in a shared location — multiplies developer and AI productivity. This is not documentation overhead. It is leverage.
These phases apply whether the codebase has 10,000 lines or 10 million. They are not sequential checkboxes — they are orientations your thinking moves through. Experienced practitioners do all four instinctively. This framework makes that instinct teachable.
Map the territory before you move
Build shared mental models of intent
Execute with maintained context
Keep business stakeholders in the loop
A living reference file checked into the repository. Loaded at the start of every AI session. Updated when the system changes. Without it, every session is starting cold.
Most teams already have several context documents — none of them labeled as such. A README, architecture decision records, inline comments on non-obvious logic, API documentation. The problem is they're scattered, partially stale, and written for different audiences.
The practice is simply making this intentional: one file — a CONTEXT.md at the repository root — that you know is the thing you load at the start of every AI session.
What to include: What this system does and who uses it. The tech stack. Key architectural patterns and why. What the team treats as sacred (never break these things). Pointers to where the interesting complexity lives.
Target length: 200–400 lines of plain prose and bullet points. An afternoon to write the first version. 10 minutes to update when something significant changes.
For large or multi-service systems, you'll eventually have one system-level document and one per major domain. But that's a maturity step, not a starting point. Start with one.
This takes 2–3 minutes and dramatically improves output quality for the entire session.
The four-phase framework holds for codebases of 1 million lines or more. What changes is the investment required and the strategies needed to manage scope — not the underlying principles.
Never treat a large codebase as a single unit. Decompose into bounded domains — areas of responsibility that can be oriented and understood independently. Each domain gets its own Context Document section. AI sessions are scoped to one domain at a time wherever possible.
In tightly coupled systems, it's harder to know what a change affects. Before any significant change, explicitly ask: “Identify every component, interface, or data contract this modification might affect — in order of likelihood and severity.” This surfaces risks before they become failures.
For large legacy systems: build new capabilities alongside the old system, gradually replacing legacy behavior. No risky big-bang rewrites. AI assists this pattern exceptionally well — interfaces, adapters, consistency across boundaries — but the pattern must be established by human architects first.
For large systems, context operates at three levels. You never start from scratch; you narrow progressively.
| Level | Scope | Contains | Updated When |
|---|---|---|---|
| System-level | The entire codebase | Architecture, business rules, global conventions, tech stack | Major architectural changes |
| Domain-level | One module or service | Module purpose, local patterns, key interfaces, known risks | Domain is meaningfully changed |
| Session-level | This specific task | Specific goal, relevant files, current constraints, definition of done | Every AI session |
Recognising failure modes is as important as knowing best practices. These patterns are common, plausible-looking, and consistently produce bad outcomes.
A summary of all four phases — developer focus, stakeholder signal, and the key question each phase answers.
| Phase | Developer Focus | Business Signal | Key Question |
|---|---|---|---|
| 01 · Orient | Map structure, identify weight-bearing components, surface unknowns. Build the initial map before any changes. | "We understand the system. Here is what we found, and here is what requires care." | What is this system and how does it work? |
| 02 · Understand | Decode intent, document business rules, build the Context Document. Move from structure to meaning. | "Here is what this code is actually doing, in plain language — and here is what we must preserve." | Why does this code exist and what does it protect? |
| 03 · Contribute | Structured prompts with full context, iterative deepening, review as diff. Make changes with precision. | "Here is what changed, why it was the right approach, and what we verified before merging." | How do we change things without breaking what matters? |
| 04 · Communicate | Translate technical decisions into business language, surface risks early, maintain the decision log. | "Here is our progress, here is what we decided and why, and here is what you need to act on." | How do we keep everyone aligned as things move fast? |
© 2026 Tetrifox. All rights reserved.
Portfolio Advisory Programme · AI-Assisted Development FrameworkConfidential