مقتطف من الدرس

AGENTS.md Best Practices: Why a Giant Instructions File Fails and How to Build a Router

Why agents ignore a giant AGENTS.md or CLAUDE.md: four causes of instruction decay, the instruction SNR metric, a three-tier router → docs → executable checks architecture, and the rule passport.

router architecture instruction SNR three-tier architecture rule passport

ما ستتعلمه في هذا الدرس

You will break down your instructions file into a router and topic-specific documents.
You will calculate the SNR of your instructions and identify what ought to be removed.
You will learn to use the rule passport to decide what deserves a place in the instructions and what belongs in a test.

بداية الدرس

Three months of edits, and the agent got worse

Every agent bug → a new rule in AGENTS.md
The file grew to 600 lines — and the agent started making more mistakes
A critical safety rule is ignored despite being right there in the file

It all started sensibly enough: the agent made a mistake, so you added a rule. It slipped up again, so you added another. Three months later, AGENTS.md runs to 600 lines, and you're rather proud of it: now everything's covered. But on a simple bug fix, the agent somehow reads the deployment instructions, which have nothing whatsoever to do with the task. And the safety rule at line 300 — the very reason this whole exercise began — gets ignored as if it weren't there at all. On top of that, three contradictory style rules produce random behaviour from one run to the next.

This is a systemic failure, not a one-off agent bug

A simple bug fix → the agent reads irrelevant deployment instructions
The critical safety rule at line 300 might as well be invisible
Three contradictory style rules → random behaviour

This isn't a one-off agent bug — it's a systemic symptom. When an instructions file grows unchecked, the same thing happens every time: relevant content drowns in the irrelevant, important rules become visually indistinguishable from trivial ones, and contradictions pile up because deleting anything feels too risky. Later in this lecture we'll cover four independent causes behind all this, a metric that will show you the scale of the problem in your own file, and an architecture that fixes it systematically — rather than piling yet another rule on top of the old ones.

Myth: the more rules in AGENTS.md, the safer the agent

🤔 Myth / Common misconception:
Every new rule makes the agent more reliable
A 600-line file = maximum control
✅ In reality:
Agent performance dropped as soon as the line count grew too high
The critical rule got lost among the minor ones
📌 Remember: signal beats volume — count SNR, not lines

It seems logical: the more rules you write down, the safer the agent. In practice, quite the opposite. In our example, the file grew to 600 lines — and that was precisely when the critical safety rule stopped being followed. It's not about the number of rules; it's that the agent physically cannot give each of 600 lines equal attention. Volume of instructions does not equal effectiveness. Next, we'll work through four independent reasons why a growing instructions file reduces, rather than improves, agent reliability.

الدرس الكامل متاح بالاشتراك

و22 شريحة أخرى في النسخة الكاملة.

تُفتح الفيديو وجميع الشرائح والملاحظات والاختبارات والمرشد الذكي والمقابلة بعد تسجيل الدخول والاشتراك.

تسجيل الدخول أو إنشاء حساب الاشتراك الآن

محتوى الدرس

Three months of edits, and the agent got worse
This is a systemic failure, not a one-off agent bug
Myth: the more rules in AGENTS.md, the safer the agent
Four independent causes — and they act simultaneously
600 lines in a file is already 10% of your context budget
The rule at line 300 — right where the model goes blind
All the rules look the same — the agent has no signal to go on
Why nobody dares to delete a line from AGENTS.md
Why fixing a single cause changes nothing
❓ Passwords in the logs twice in one month — and the rule is right there on line 210
💡 It is not the wording of the rule — it is its position in the file
SNR: the number that honestly shows how much noise is in your file
How to calculate your file's SNR
Three levels instead of one giant file
The router has exactly five duties — and not one more
Documents the agent opens only when relevant, not every time
The instruction you don't have to write — it's already in the code
A proper link to level 2: with a condition, not just a path
🛠 War story: a rule with no passport that nearly got forgotten
A rule's passport: three attributes, or it lives forever
Placement matters: where a rule goes, and where a bug story goes
In practice: scheduled reviews and three questions
Why lines almost never get removed from AGENTS.md
Practice: split your instructions file into a router and documents — today
The router beats the encyclopaedia