An agent’s entire world is what it has read. Not your project — the parts of your project it opened, plus what you told it, plus what it remembers from training.
Everything else is a guess.
Once you accept that, most mysterious behaviour becomes obvious, and most fixes become “show it the thing”.
The three things worth giving it
1. The files.
Do not make it hunt. If you know where the relevant code is, say so:
The save logic is at the bottom of readlist.html, in the function
called addLink. Change that one.
Agents can search, and they are decent at it. But searching burns context and sometimes lands on the wrong match. When you know, tell it. It is one extra line and it removes an entire category of failure.
The catch: you can only name the file if you have looked. Come back to your own project after two weeks and you are in the same position as the agent — you know roughly what is in there, and roughly is not a file path.
The terminal on this page has one of those projects in it: a link saver, built a while ago, not opened since. Before you could ask for one small change to it, you would need three answers — what is in the folder, what rules the project already has, and where the saving actually happens.
Get them the way you would in a real project:
- What is in here? —
ls - What has this project already decided? — it keeps a
NOTES.md; read it - Where does the saving happen? —
grepthe page for the wordfunctionand every function in it lists itself
Half a minute of looking. Now “the save logic is in readlist.html, in the function called addLink” is a sentence you know to be true instead of one you hope is true — and that is the whole difference between handing over context and guessing at it.
2. The goal, not just the change.
Compare:
Add a check that the URL starts with http.
against:
People paste things that are not links and the list fills with junk.
I want only real links to be saved.
The first gets you exactly that check — including on httpfoo, which passes. The second gets you a solution to your actual problem, and possibly a question about what should happen to a rejected paste.
State the why. It is the difference between an instruction-follower and a collaborator.
3. The constraints that must not come back.
Every session accumulates decisions: one file, no dependencies, do not touch the styling. These fade as the conversation grows.
Quick check
Which request is most likely to produce something you actually want?
The project notes file
You read one of these in the terminal a minute ago. NOTES.md told you what the project is, the one-file rule, and the folder not to touch — in a project you had never opened before. An agent gets exactly that same head start from it, every session.
Most agents look for a plain-text notes file in your project folder and read it at the start of every session. The name varies by tool. The idea does not: it is a place for the rules that must survive every conversation.
A useful one is short:
# Readlist — project notes
What this is: a single-page link saver, stored in browser local storage.
Rules:
- Everything stays in one file: readlist.html
- No frameworks, no build step, no dependencies
- No server, no accounts, no analytics
- Keep the JavaScript readable over clever — a beginner maintains this
How to run: open readlist.html in a browser. There is nothing to build.
That file does more for output quality than any amount of tuning, because it turns “I said it once, ten messages ago” into “it reads this every single time”.
Tip
Write the notes file after your first working version, not before. By then you know which decisions were real. Guessing them upfront produces a file full of rules nobody follows.
Quick check
What is the right length for a project notes file?
Why long sessions decay
Context is a fixed budget. Every file read, every message, every command output takes a slice of it.
As it fills, the beginning of the conversation competes with the end. Your careful setup from an hour ago is still technically there, and it is one detail among thousands. The instruction you gave two minutes ago is louder.
Practical consequences:
- Start a fresh session for a new task. Do not add “and now build the export feature” onto a two-hour debugging session.
- Restate the important constraint when you change topic. One line.
- Move anything permanent into the notes file so it does not depend on remembering.
Note
A session going sideways is often just full. Starting fresh with the notes file plus a two-line summary of where you are is faster than trying to steer a saturated one.
What not to put in context
Two things never go into a prompt, a chat, or a file you might publish:
- Secrets — API keys, passwords, , connection strings.
- Other people’s personal data — real customer records, real emails.
Both because you have no control over where the text ends up, and because a key pasted into a conversation has a habit of ending up in a source file, and a source file has a habit of ending up in a public repository.
If the agent needs to know a key exists, tell it the name, never the value:
The API key is in an environment variable called READLIST_API_KEY.
Read it from there; never write the value into a file.
Quick check
Your project needs an API key. How do you tell the agent about it?
The one-line summary
Before any non-trivial request, ask: does it know where to look, why I want this, and what it must not break?
Three seconds. It is the highest-leverage habit in this course.