AI can write quickly. It cannot automatically know your customers, your standards, the decisions you already made, or the constraints you discovered after three weeks of research. When that information is missing, the model fills gaps with reasonable-sounding guesses. That is not a model failure. It is a context failure.

Context is the material someone would need before they could make a good decision about the project. It can include customer research, market observations, brand rules, technical constraints, existing architecture, source material, and decisions that are already settled.

The vague request problem

Imagine telling Codex:

It has to guess who the directory is for, how entries are chosen, what pages exist, whether users can save tools, whether there are accounts, and what not to build. You will get *a* directory. You may not get yours.

Now give it CONTEXT.md first:

# Product Context

## User
Independent founders who need practical AI tools for a real job today.

## What we learned
- Generic directories overwhelm people with too many weak listings.
- Users want to understand the use case and price quickly.
- A smaller curated collection is more useful than a giant catalogue.

## Product decisions
- Organize by job to be done.
- Start with curated entries.
- Let users save tools.

## Out of scope for version one
- User reviews
- Payments
- A native mobile app

The code may still need improvement. But the AI is now making decisions inside the world you actually want to create.

Context is not a dump

Giving an AI more text is not automatically better. A 200-page pile of notes can bury the important decisions. Good context is selected, organized, dated where necessary, and honest about uncertainty.

Use headings so the agent can find what matters. Put a date on time-sensitive research. Label an assumption as an assumption. If the answer is unknown, say it is unknown.

A practical context workflow

Chats, calls, sources, notesSelect what mattersCONTEXT.mdSPEC.md or prompt fileAI taskUpdate context when a decision changes

CONTEXT.md is not necessarily the only file. A mature project may keep separate customer research, brand guidance, architecture, and research-method files. The important habit is to put stable, reusable knowledge somewhere the next person—or agent—can find it.

Save the work before the conversation gets too full

We will introduce Command Line Interfaces (CLIs) and how to use them with AI in a later lesson. It matters here because a CLI agent session is one of the clearest reasons project context belongs in files, not only inside a chat.

A long AI working session can accumulate exploration, failed approaches, pasted logs, old instructions, and temporary decisions. Eventually the useful signal gets buried under the history.

That has two costs. It can make the agent slower or less focused because it has to keep sorting through old material, and it can burn through more tokens than the next task deserves. A giant conversation window is not a project memory system. It is a working surface.

When a task reaches a useful stopping point, save the durable state to a Markdown handoff file, then start a clean session for the next task. You carry forward the decisions and evidence—not every dead end. Later, when you are working with an AI in a CLI, this becomes an essential habit.

Long AI working sessionStop at a clear checkpointWrite a handoff Markdown fileOpen a clean CLI sessionRead the handoff and relevant contextContinue the next focused task

Put handoffs in one predictable place, such as docs/handoffs/, notes/handoffs/, or project-memory/. The folder matters less than the habit. A new agent should be able to find it without asking where the last session left off.

Here is a useful handoff structure:

# Handoff: company-comparison page

## Goal
Build the first version of the company-comparison page.

## Completed
- Added the page layout and comparison data structure.
- Local build passes.

## Decisions made
- Compare three companies at a time.
- Keep source links visible beside each claim.

## Current state
- Work is on branch `feature/company-comparison`.
- The browser version still needs mobile review.

## Next task
Test the mobile layout, fix any overflow, and report changed files.

## Do not do
- Do not change the database schema.
- Do not deploy to production.

The new session can begin with: “Read CONTEXT.md and docs/handoffs/company-comparison.md. Confirm the current state, then complete only the next task. Do not deploy.” This is cleaner than asking a new chat to reconstruct hours of work from memory.

You will learn the CLI workflow, branches, parallel agents, and safe cloud actions in the later Computers, CLI & Development Environments lessons. For now, keep the principle: save durable knowledge in files; use the chat window for the work happening right now.

Sonariq as a supporting example

In Sonariq, an agent researching a company should not begin with a blank page. It needs the shared research standards, the sector framework, the expected handoff format, and the specific job it is assigned. Those documents are context. They reduce the chance that ten agents produce ten incompatible versions of “research.”

Your project may be much smaller. The principle stays the same: give the AI the relevant operating reality before asking it to act.

Build your first context file

Create CONTEXT.md for your own project. Keep it to one or two pages at first.

# Context

## Problem
[What is happening now that should be better?]

## User
[Who has this problem?]

## Evidence
- [Useful observation or source]
- [Useful observation or source]

## Decisions already made
- [Decision and why]

## Constraints
- [Budget, timeline, technology, brand, privacy, or quality constraint]

## Open questions
- [What still needs a real answer?]

Ask an AI: “Read CONTEXT.md. List the facts, assumptions, decisions, and open questions separately. Do not invent answers to the open questions.” That is a useful test. If the AI cannot separate them, your context is not clear enough yet.

Check your understanding

1. What is the difference between context and a prompt? 2. Why can too much unstructured context be harmful? 3. What should happen when a material project decision changes? 4. What would an AI need to know before it could make a good decision about your project? 5. When should you write a handoff file and start a clean CLI session?