If you use an AI assistant daily, you’ve probably felt this frustration:
- You told it the constraints yesterday.
- You shared the repo structure.
- You explained the goal.
…and today it confidently suggests something that ignores all of it.
This usually isn’t “the model being dumb.” It’s a workflow issue: you don’t have a clear picture of what’s actually in the context window right now.
So here’s a simple technique I keep coming back to:
The Context Window Map
A Context Window Map is a 1-page inventory of everything you’re feeding the assistant in this run.
Think of it as a lightweight bill of materials for the conversation:
- What facts are in scope?
- What files/snippets did we include?
- What decisions did we already make?
- What constraints must not be violated?
- What is explicitly out of scope?
When you have this map, you stop relying on vibes (“I’m sure I mentioned that…”) and start working with something you can verify.
Why it works
Most failures in AI-assisted work come from one of three problems:
- Missing context — the assistant never saw the key detail.
- Buried context — the detail exists, but it’s lost in a long thread.
- Stale context — the detail changed, but the assistant is still acting on the old version.
A Context Window Map reduces all three because it makes context explicit, reviewable, and updateable.
The template (copy/paste)
Use this at the top of a new chat, inside your project notes, or as a pinned comment in your issue tracker.
# Context Window Map
## Goal (1–2 sentences)
-
## Definition of done
-
## Hard constraints (must not break)
-
## Inputs included in this run
- Repo/files:
-
- Specs/links:
-
- Data samples:
-
## Key decisions already made
-
## Assumptions (explicit, to confirm)
-
## Out of scope / not doing
-
## Open questions
-
You can keep it short. The power is not the length — it’s the habit of writing it down.
Example: shipping a small CLI tool
Let’s say you’re building a CLI that renames a batch of files based on a pattern.
Here’s a filled-in Context Window Map:
# Context Window Map
## Goal
- Build a CLI that renames files using a pattern and a preview step.
## Definition of done
- Dry-run mode shows exact rename operations
- Real run performs renames safely
- Works on macOS + Linux
## Hard constraints
- Never overwrite an existing file
- Must be fast on 10k files
- No external dependencies (single binary preferred)
## Inputs included in this run
- Repo/files:
- src/main.rs
- README.md
- Data samples:
- 15 filenames from a real directory (see snippet below)
## Key decisions already made
- Language: Rust
- CLI parser: clap
- Pattern syntax: {n} for sequence number, {stem} for original name
## Assumptions
- Users want a preview by default (confirm)
- Unicode filenames should be supported (confirm)
## Out of scope
- Recursive directory walking (v1)
- Interactive TUI
## Open questions
- Should default be dry-run or real run?
- How do we format preview output?
Now the assistant has a stable “ground truth” it can keep referencing.
How to use the map during the session
The trick is to treat the map as a living artifact, not a one-time prompt.
1) Start each run by pasting the map
Even if you’re continuing a previous conversation, paste the current map again. Long threads are unreliable. Make the context fresh.
2) When output is wrong, ask: “Which map item did we violate?”
This is a debugging move.
Instead of:
“No, that’s not what I meant.”
Try:
“You violated the constraint ‘Never overwrite an existing file’. Update your plan.”
You’ll get fewer emotional back-and-forths and more concrete corrections.
3) Promote new facts into the map
As soon as something becomes important, add it.
Examples:
- “We decided to support Windows too.” → add under constraints/decisions.
- “The directory is on NFS; renames can fail intermittently.” → add under assumptions.
- “We discovered files may already include the target pattern.” → add under edge cases/constraints.
4) Use it as a handoff document
If you jump between tools (chat → editor → terminal → another chat), the map is your handoff.
It’s also the easiest way to ask for help from a teammate without sending them 200 messages:
- paste the map
- paste the current failure
- ask for a specific next step
A concrete prompt pattern: “Map-first answers”
To make the assistant reliably use the map, I add one instruction:
“Before answering, restate the relevant items from the Context Window Map and explain how your plan satisfies each constraint.”
This forces alignment.
Here’s a reusable snippet:
Use the Context Window Map above as the source of truth.
Before you propose a solution, list the relevant constraints/decisions and show how your approach satisfies them.
If anything is missing or ambiguous, ask 1–3 clarifying questions first.
Common pitfalls (and how to avoid them)
Pitfall: turning the map into a novel
If it becomes a multi-page doc, you’ll stop maintaining it.
Keep it to:
- 1–2 sentences for the goal
- 3–7 bullets for constraints
- 3–10 bullets for inputs/decisions
Pitfall: mixing “facts” and “wishes”
“I want it to be fast” is vague.
Rewrite it as:
- “Must handle 10k files in under 2 seconds on my machine.”
Pitfall: forgetting what’s not in the context
The map helps here: if it’s not listed under “inputs included,” assume the assistant hasn’t seen it.
That one rule prevents a surprising amount of confusion.
The payoff
A Context Window Map is boring in the best way.
It turns AI assistance from a fuzzy conversation into a repeatable workflow:
- clearer constraints
- fewer hallucinated assumptions
- faster debugging when things go off the rails
- easier handoffs between sessions
If you try it, start small: use the template once for your next task, then iterate.
You don’t need perfect prompts. You need visible context.
Top comments (0)