Home/ Part IV — AI Studio Deep Dive: Every Knob Matters Eventually/11. Context Management Like a Pro/11.4 Handling multi-file projects without losing coherence

11.4 Handling multi-file projects without losing coherence

Overview and links for this section of the guide.

On this page

The multi-file problem

Multi-file projects break models in predictable ways:

  • imports don’t match,
  • function signatures drift,
  • the model forgets where code lives,
  • it rewrites files to “make it consistent,”
  • it loses coherence across modules.

You solve this by giving the model a map and only changing one seam at a time.

Use a file map (index)

A file map is a compact description of modules and responsibilities. Example:

File map:
- src/cli.py: parse args, call core, print result
- src/core.py: business logic (pure functions)
- src/io.py: external boundaries (files/network)
- tests/: unit + integration tests

Paste the file map at the top of relevant prompts. It gives orientation without flooding context.

File map is “context glue”

It helps the model connect the slices you paste across iterations.

A practical multi-file workflow

  1. Map: maintain a file map and stable spec block.
  2. Choose a seam: one module boundary to change.
  3. Update contracts: function signatures/schemas first.
  4. Implement one step: diff-only changes to a small set of files.
  5. Verify: unit tests for module + one integration test across seam.
  6. Repeat: next seam, next step.

This is the “small modules, stitched later” pattern applied as a context technique.

Stitching changes safely

When you connect modules, failures are common. Make them easy to diagnose:

  • keep seams explicit (interfaces, contracts),
  • avoid changing two seams at once,
  • write one integration test per seam,
  • use diff-only and small scope.
Don’t let “consistency” trigger rewrites

Models love “make everything consistent.” That’s how you get a repo-wide rewrite. Be explicit: “only change files X and Y.”

Copy-paste prompt templates

Template: ask for a file map

Given this file tree, produce a file map:
- 1–2 sentences per important module
- note entrypoints and dependencies
- list likely test locations

Stop after the file map.

Template: implement one seam change

We are changing one seam only.

File map:
(paste)

Task:
[describe seam change]

Constraints:
- Only touch: [...]
- Diff-only changes
- Add/adjust tests for this seam

Output:
1) Plan (3–5 steps), stop.
2) Then implement step 1 only.

Where to go next