Skip to content

Commit 86c9ce9

Browse files
ofriwofriw
committed
audio: add dialogue scripts and regenerated audio for the new chapters
1 parent 20f36d3 commit 86c9ce9

16 files changed

Lines changed: 3208 additions & 462 deletions

‎website/audio/dialogue/context-files.json‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
{
2+
"chapterId": "context-files",
3+
"sourceHash": "c26ae747cd49d4e657b294769770e5de252f363cb3deb6bca64c474195bdaf51",
4+
"turns": [
5+
{
6+
"id": "t1",
7+
"speaker": "alex",
8+
"anchor": { "kind": "heading", "id": "context-files" },
9+
"text": "Context files are markdown documents injected between the system prompt and your input. They give an agent project memory without the same explanation every session: architecture, conventions, build commands, constraints."
10+
},
11+
{
12+
"id": "t2",
13+
"speaker": "sam",
14+
"anchor": { "kind": "heading", "id": "context-files" },
15+
"text": "So it's memory that shows up before I say a word. What's the catch?"
16+
},
17+
{
18+
"id": "t3",
19+
"speaker": "alex",
20+
"anchor": { "kind": "heading", "id": "context-files" },
21+
"text": "The catch is mechanical. On every call, the loop rebuilds the window and re-injects the file ahead of your prompt. That's the promise: it sits in the fixed prefix, always in front of the model, so nothing has to be re-explained or fetched on demand."
22+
},
23+
{
24+
"id": "t4",
25+
"speaker": "sam",
26+
"anchor": { "kind": "heading", "id": "context-files" },
27+
"text": "And the price is that same fact seen from the other side."
28+
},
29+
{
30+
"id": "t5",
31+
"speaker": "alex",
32+
"anchor": { "kind": "heading", "id": "context-files" },
33+
"text": "Exactly. Because it sits before your prompt, its size sets how far the task drifts once the loop starts appending turns behind it. Keep it small and the prompt stays close to the front of the window, where attention is strongest. Let it grow and you shove that same prompt into the dead center."
34+
},
35+
{
36+
"id": "t6",
37+
"speaker": "sam",
38+
"anchor": { "kind": "heading", "id": "context-files" },
39+
"text": "So the file always arrives. The tradeoff is where it leaves my task."
40+
},
41+
{
42+
"id": "t7",
43+
"speaker": "alex",
44+
"anchor": { "kind": "figure", "index": 0 },
45+
"text": "Here's the trap, and this time it's about your own file."
46+
},
47+
{
48+
"id": "t8",
49+
"speaker": "alex",
50+
"anchor": { "kind": "figure", "index": 0 },
51+
"text": "Same task, same loop, same steps — the only difference is how big the context file is when the session starts. A lean one keeps your task in the strong band from beginning to end."
52+
},
53+
{
54+
"id": "t9",
55+
"speaker": "alex",
56+
"anchor": { "kind": "figure", "index": 0 },
57+
"text": "A bloated one eats most of the window before the work even starts. Then the loop piles its own output on top, and your task sinks into the middle — buried under everything the agent did after you asked."
58+
},
59+
{
60+
"id": "t10",
61+
"speaker": "sam",
62+
"anchor": { "kind": "figure", "index": 0 },
63+
"text": "But buried isn't gone. It's still in the window; I just can't count on the agent to hold it accurately anymore. It can echo the gist, not the details — and since every step is a guess, the longer that goes on, the more the work drifts from what I asked."
64+
},
65+
{
66+
"id": "t11",
67+
"speaker": "alex",
68+
"anchor": { "kind": "heading", "id": "agentsmd-is-the-standard" },
69+
"text": "So which file are we actually talking about? In practice, it's AGENTS.md. It's the industry standard: plain Markdown, used by over 60,000 open-source projects, and governed by the Linux Foundation's Agentic AI Foundation. Every major coding agent reads it natively."
70+
},
71+
{
72+
"id": "t12",
73+
"speaker": "sam",
74+
"anchor": { "kind": "heading", "id": "agentsmd-is-the-standard" },
75+
"text": "Which makes it powerful — and, I'd guess, dangerous for exactly the same reason."
76+
},
77+
{
78+
"id": "t13",
79+
"speaker": "alex",
80+
"anchor": { "kind": "heading", "id": "agentsmd-is-the-standard" },
81+
"text": "Yes. An AGENTS.md isn't scoped to one session, one task, or one tool. It enters the fixed prefix of every call, for every agent that touches the repository, on every task, and for everyone who clones it later. Change one line and you've changed how all of them behave, immediately, with nothing in the test suite to catch it."
82+
},
83+
{
84+
"id": "t14",
85+
"speaker": "sam",
86+
"anchor": { "kind": "heading", "id": "agentsmd-is-the-standard" },
87+
"text": "No source file has that kind of reach."
88+
},
89+
{
90+
"id": "t15",
91+
"speaker": "alex",
92+
"anchor": { "kind": "heading", "id": "agentsmd-is-the-standard" },
93+
"text": "And because it sits in that prefix, ahead of every prompt, its size is a shared cost rather than a private one. A single conversation drifts on its own; a shared AGENTS.md does that to every conversation at once. Every added token pushes every contributor's prompt further from the primacy edge and deeper toward the dead center."
94+
},
95+
{
96+
"id": "t16",
97+
"speaker": "sam",
98+
"anchor": { "kind": "heading", "id": "agentsmd-is-the-standard" },
99+
"text": "So a bloated file doesn't slow one agent down. It degrades all of them, on every task, for as long as it stays bloated."
100+
},
101+
{
102+
"id": "t17",
103+
"speaker": "alex",
104+
"anchor": { "kind": "heading", "id": "agentsmd-is-the-standard" },
105+
"text": "Which is why AGENTS.md is the most important file in the repo to audit, review, and keep minimal — more than any code file. It's always on, it silently steers every agent, and one vague or stale line degrades everything downstream."
106+
},
107+
{
108+
"id": "t18",
109+
"speaker": "sam",
110+
"anchor": { "kind": "heading", "id": "agentsmd-is-the-standard" },
111+
"text": "And when the file and the code disagree?"
112+
},
113+
{
114+
"id": "t19",
115+
"speaker": "alex",
116+
"anchor": { "kind": "heading", "id": "agentsmd-is-the-standard" },
117+
"text": "The agent follows the file, even when the file is wrong. So treat it as a public interface: human-reviewed, held under version control, and pruned the moment it goes stale."
118+
},
119+
{
120+
"id": "t20",
121+
"speaker": "alex",
122+
"anchor": { "kind": "heading", "id": "writing-an-agentsmd" },
123+
"text": "Which brings us to writing one. The best way to start is not to write one at all. Work on the project with your agent first and let the file earn its lines. You can't know in advance what an agent will get wrong in your repository, and a rule written on speculation is a guess that bloats the prefix without changing behavior."
124+
},
125+
{
126+
"id": "t21",
127+
"speaker": "sam",
128+
"anchor": { "kind": "heading", "id": "writing-an-agentsmd" },
129+
"text": "So don't speculate. Wait for evidence."
130+
},
131+
{
132+
"id": "t22",
133+
"speaker": "alex",
134+
"anchor": { "kind": "heading", "id": "writing-an-agentsmd" },
135+
"text": "Add a line only when a mistake repeats. One wrong turn is noise; the same wrong turn across tasks is a signal. When it recurs, write the smallest instruction that names the offender and the fix — the exact command, the forbidden path, the convention the code doesn't express — and nothing more."
136+
},
137+
{
138+
"id": "t23",
139+
"speaker": "sam",
140+
"anchor": { "kind": "heading", "id": "writing-an-agentsmd" },
141+
"text": "Because only rules earned from real failures actually change behavior."
142+
},
143+
{
144+
"id": "t24",
145+
"speaker": "alex",
146+
"anchor": { "kind": "heading", "id": "writing-an-agentsmd" },
147+
"text": "Then prune. Models improve, and a rule that corrected last year's model may be redundant today — internalized, or guarding code that no longer exists. So re-read the file periodically and delete whatever no longer earns its place. An AGENTS.md that only ever grows is exactly the bloat that buries the original ask under everything that follows."
148+
},
149+
{
150+
"id": "t25",
151+
"speaker": "sam",
152+
"anchor": { "kind": "heading", "id": "writing-an-agentsmd" },
153+
"text": "And if I'm tempted to patch a recurring mistake with yet another rule?"
154+
},
155+
{
156+
"id": "t26",
157+
"speaker": "alex",
158+
"anchor": { "kind": "heading", "id": "writing-an-agentsmd" },
159+
"text": "Reach for it last. AGENTS.md is a last resort, not a first fix. A recurring mistake usually points at the code: an invariant the types don't capture, a function that's hard to find, a name that misleads. Clean, well-documented code is easier for any agent to get right, and tool-driven retrieval lets it fetch the answer on demand at codebase scale instead of hauling it through every prompt."
160+
},
161+
{
162+
"id": "t27",
163+
"speaker": "sam",
164+
"anchor": { "kind": "heading", "id": "writing-an-agentsmd" },
165+
"text": "Both fix the root cause and keep context efficient. The knowledge gets paid for only when it's needed, not by every agent on every call."
166+
},
167+
{
168+
"id": "t28",
169+
"speaker": "alex",
170+
"anchor": { "kind": "heading", "id": "writing-an-agentsmd" },
171+
"text": "So add a line only for what the code and the tools still can't resolve. Now, one warning before you trust any of this. Context files are injected straight into the system prompt, which makes them an attack surface — so keep them minimal, version-controlled, and code-reviewed like any other code. Rules File Backdoor attacks hide instructions in Unicode or evasion tricks a reviewer skims past."
172+
},
173+
{
174+
"id": "t29",
175+
"speaker": "sam",
176+
"anchor": { "kind": "heading", "id": "writing-an-agentsmd" },
177+
"text": "And the tools don't always gate them."
178+
},
179+
{
180+
"id": "t30",
181+
"speaker": "alex",
182+
"anchor": { "kind": "heading", "id": "writing-an-agentsmd" },
183+
"text": "Right. A context file can be read before any trust decision, so a freshly cloned repository's AGENTS.md may reach the prompt before you've approved the project. pi, for example, loads context files regardless of project trust — the pi security docs spell that out. Treat an unfamiliar AGENTS.md as executable content, not documentation."
184+
},
185+
{
186+
"id": "t31",
187+
"speaker": "sam",
188+
"anchor": { "kind": "heading", "id": null },
189+
"text": "Let me put the whole thing back together. A context file is prepaid memory that loads with every call, so its bulk decides how long your actual task stays in view. A small startup file kept it in view; a bulky one let it slip toward the center. AGENTS.md is everywhere, which is also why a careless line there reaches everyone. So you earn rules from repeated failures, cut the ones that stopped paying rent, prefer fixing the code, and treat the file as untrusted input until you've read it."
190+
}
191+
]
192+
}

0 commit comments

Comments
 (0)