What kinds of information belong in a project instruction file, and what should stay out?

beginner

Re-explain

Put in stable facts that affect many tasks:

Add a short definition of done, such as running focused tests and reporting any failures.

Leave out secrets, credentials and customer data.
Leave out temporary task details and long tutorials too. Point to a trusted document instead of copying it.
Skip vague advice such as "write good code", because it gives the model nothing to act on.
Drop rules that tools or linters already enforce, unless the assistant needs them to choose an approach.

A useful file is a small map and policy guide, not a complete project handbook.

Rewriting in plainer words…

This answer doesn't lend itself to a diagram - it reads best . No credits were charged.

Why there's no diagram: “”

The interactive diagram is below the answer - jump to diagram ↓ · Below it, the related concept . Jump to it ↓

The diagram below the answer is the concept . Jump to it ↓

Tailored explanation · switch back to · ·

What should the new diagram focus on?

How well did you know this?

AI:

Saved in this browser - sign in to keep your review list.

How should your speech become text?

Listening… your words appear above as you speak - tap Stop when you're done.

Recording · cr - tap Stop & transcribe when you're done.

Transcribing with AI…

Voice:

Keep going - a few more words and AI can grade it.

Interview lens How interviewers actually use this question

Why keep the file short if the model can read a long one? The file loads into every session, so each line costs context every time, and a long list makes the model more likely to miss the rules that matter.
How do you stop the file from going stale as the code changes? Treat it like code. Review changes in PRs, give it an owner, and fix or delete a rule as soon as it sends the agent the wrong way.
How do you decide between the rules file, a linked doc, and the task prompt? Go by how often and how widely it applies. Every-task facts go in the file, deep detail in docs it points to, one-off details in the prompt.
Where would you put a rule that applies to only one package in a monorepo? Put it in a directory-level file next to that package, which tools read when work happens there. The root file stays about the whole repo.
How would you tell whether a rule in the file changes what the agent does? Run the same tasks with and without the rule and compare the diffs or transcripts. If a rule changes nothing, it is a candidate to delete.

An instruction file should hold stable facts that affect many tasks. It works as a short map and policy guide, not a full project handbook.
That means the important directories, the standard commands, architectural boundaries, naming rules, approved libraries, and any dangerous action that needs approval first.
I'd also add a short definition of done, like running the focused tests and reporting any failures.
Secrets, credentials and customer data stay out, and so do temporary task details and long tutorials. If a trusted doc already exists, I point to it instead of copying it in.
I skip vague advice like 'write good code', because the model can't act on it. I also drop rules a linter already enforces, unless the agent needs them to pick an approach.
The cost is that the tool loads every line into every session, so I keep the file small and cut any rule that doesn't change what the agent does.

Dumps the whole handbook into the file A long file uses up context in every session and buries the rules that matter. Say you keep a short map and point to trusted docs instead of copying them.
Never mentions secrets or customer data Leaving out the hard exclusion is a red flag. Say plainly that keys, credentials and customer data never go in, because the file is shared and sent to the model.
Offers vague values like 'write clean code' The model has nothing to act on. Give concrete rules it can follow, such as the exact test command, the approved library, or which actions need approval.
Only covers what goes in The question has two halves. Naming what stays out, like temporary task details and rules the linter already enforces, shows you know every line has a cost.

Interview lens

Likely follow-ups, what you can say, and the weak answers to avoid.

Want a quick review of the fundamentals? See the Context Engineering cheatsheet.

Pro · $10/mo

Full answers, code samples, and AI explanations that go simpler or deeper. Cancel anytime.