Email: Your AGENTS.md might be a big problem

Subject:
Your AGENTS.md might be a big problem
Received:
1/29/2026, 7:23:45 PM
From:
"Matt Pocock (AI Hero)" <matt@aihero.dev>
To:
porch.hat.81@rss.andrealin.it
&lt;!DOCTYPE html&gt;
&lt;html&gt;
&lt;head&gt;
&lt;style&gt;.ck-link { text-decoration: underline; }&lt;/style&gt;
&lt;style&gt;.ck-link { text-decoration: underline; }&lt;/style&gt;
&lt;style&gt;@media only screen { .email * { word-break: break-word; } }
@media screen and (max-width: 384px) { .mail-message-content { width: 414px !important; } }
@media only screen { .email * { word-break: break-word; } }
@media screen and (max-width: 384px) { .mail-message-content { width: 414px !important; } }
@media only screen and (max-width:600px) { .ck-mobile-font-size { font-size:50px !important; }  }
@media only screen and (max-width:600px) { .ck-mobile-font-size { font-size:50px !important; }  }&lt;/style&gt;
&lt;meta http-equiv="Content-Type" content="text/html; charset=UTF-8"&gt;
&lt;/head&gt;
&lt;body style="margin:0;padding:0;-webkit-font-smoothing:antialiased;-ms-text-size-adjust:100%;-webkit-text-size-adjust:100%"&gt;
&lt;div class="email" style="margin-left:18px;margin-right:18px"&gt;
&lt;table cellpadding="0" cellspacing="0" style="border-collapse:separate;mso-table-lspace:0pt;mso-table-rspace:0pt;width:100%;margin:0 auto"&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td style="vertical-align:top"&gt;
&lt;p class="" style="margin:1em 0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen-Sans,Ubuntu,Cantarell,'Helvetica Neue',sans-serif;color:#2d2d2f;font-size:16px;line-height:1.5"&gt;Hey Andrea,&lt;/p&gt;
&lt;p class="" style="margin:1em 0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen-Sans,Ubuntu,Cantarell,'Helvetica Neue',sans-serif;color:#2d2d2f;font-size:16px;line-height:1.5"&gt;Bad &lt;code&gt;AGENTS.md&lt;/code&gt; files can make your coding agent worse and cost you tokens.&lt;/p&gt;
&lt;p class="" style="margin:1em 0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen-Sans,Ubuntu,Cantarell,'Helvetica Neue',sans-serif;color:#2d2d2f;font-size:16px;line-height:1.5"&gt;Most developers don't realize their &lt;code&gt;AGENTS.md&lt;/code&gt; is the problem. They add rules every time the agent messes up. A few months later, they've got this sprawling document that's actually &lt;em&gt;hurting&lt;/em&gt; performance instead of helping it.&lt;/p&gt;
&lt;p class="" style="margin:1em 0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen-Sans,Ubuntu,Cantarell,'Helvetica Neue',sans-serif;color:#2d2d2f;font-size:16px;line-height:1.5"&gt;Here's why: you've got a limited "instruction budget". Frontier LLMs can really focus on about 150-200 instructions before things get fuzzy. Every rule in your &lt;code&gt;AGENTS.md&lt;/code&gt; burns through that budget on &lt;em&gt;every single request&lt;/em&gt;, whether it's relevant or not.&lt;/p&gt;
&lt;p class="" style="margin:1em 0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen-Sans,Ubuntu,Cantarell,'Helvetica Neue',sans-serif;color:#2d2d2f;font-size:16px;line-height:1.5"&gt;The solution? Progressive disclosure. Keep your root &lt;code&gt;AGENTS.md&lt;/code&gt; ruthlessly small (3-5 things, max), then nest everything else into separate files that agents pull in when they need them. Smaller token overhead. Better agent focus. Problem solved.&lt;/p&gt;
&lt;p class="" style="margin:1em 0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen-Sans,Ubuntu,Cantarell,'Helvetica Neue',sans-serif;color:#2d2d2f;font-size:16px;line-height:1.5"&gt;In this article, you'll discover:&lt;/p&gt;
&lt;ul class="unordered_list" style="margin:1em 0;margin-left:1em;padding:0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen-Sans,Ubuntu,Cantarell,'Helvetica Neue',sans-serif;color:#2d2d2f;font-size:16px;line-height:1.5;list-style-position:outside !important"&gt;
&lt;li class="list_item" style="padding:0 0 0 1em;margin:0;margin-left:1em"&gt;&lt;span&gt;The exact minimum your &lt;code&gt;AGENTS.md&lt;/code&gt; should contain&lt;/span&gt;&lt;/li&gt;
&lt;li class="list_item" style="padding:0 0 0 1em;margin:0;margin-left:1em"&gt;&lt;span&gt;Why stale documentation actively &lt;em&gt;poisons&lt;/em&gt; your agent's context&lt;/span&gt;&lt;/li&gt;
&lt;li class="list_item" style="padding:0 0 0 1em;margin:0;margin-left:1em"&gt;&lt;span&gt;How to use progressive disclosure to keep your instruction budget tight&lt;/span&gt;&lt;/li&gt;
&lt;li class="list_item" style="padding:0 0 0 1em;margin:0;margin-left:1em"&gt;&lt;span&gt;A copy-paste prompt to refactor a bloated &lt;code&gt;AGENTS.md&lt;/code&gt; automatically&lt;/span&gt;&lt;/li&gt;
&lt;li class="list_item" style="padding:0 0 0 1em;margin:0;margin-left:1em"&gt;&lt;span&gt;How monorepos can use nested &lt;code&gt;AGENTS.md&lt;/code&gt; files without chaos&lt;/span&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p class="" style="margin:1em 0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen-Sans,Ubuntu,Cantarell,'Helvetica Neue',sans-serif;color:#2d2d2f;font-size:16px;line-height:1.5"&gt;&lt;a href="https://7751c435.click.convertkit-mail2.com/qdu2e69300t8u72r68malh82pvrkki4hllmmq/48hvh7umwvv8p5ux/aHR0cHM6Ly93d3cuYWloZXJvLmRldi9zL1M4SXFkRw==" target="_blank" class="ck-link" rel="noopener noreferrer" style="color:#0875c1" url-id="1828288561"&gt;Read the full article →&lt;/a&gt;&lt;/p&gt;
&lt;p class="" style="margin:1em 0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen-Sans,Ubuntu,Cantarell,'Helvetica Neue',sans-serif;color:#2d2d2f;font-size:16px;line-height:1.5"&gt;Matt&lt;/p&gt;
&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;div class="email-footer"&gt;&lt;table cellpadding="0" cellspacing="0" style="border-collapse:separate;mso-table-lspace:0pt;mso-table-rspace:0pt;width:100%;margin:0 auto"&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td style="vertical-align:top"&gt;
&lt;div&gt;&lt;div class="email-footer" style="color:#4b4b4b"&gt;
  &lt;p style="margin:1em 0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen-Sans,Ubuntu,Cantarell,'Helvetica Neue',sans-serif;color:#2d2d2f;font-size:16px;line-height:1.5;color:#4b4b4b; margin:1em 0;font-family:Arial,-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen-Sans,Ubuntu,Cantarell,'Helvetica Neue',sans-serif;;font-size:12px;line-height:1.5;display:block;margin:13px 0;"&gt;&lt;a href="https://7751c435.click.convertkit-mail2.com/qdu2e69300t8u72r68malh82pvrkki4hllmmq/qvhmk2kqf8udezzp4vcl/aHR0cHM6Ly93d3cudG90YWx0eXBlc2NyaXB0LmNvbS91bnN1YnNjcmliZWQ_c2VxdWVuY2U9YWlfaGVybw==" trigger-id="5153768" style="color:#0875c1" url-id="1828288563"&gt;Unsubscribe from AI Hero Emails&lt;/a&gt;. You can also &lt;a href="https://7751c435.unsubscribe.convertkit-mail2.com/qdu2e69300t8u72r68malh82pvrkki4hllmmq" style="color:#0875c1"&gt;&lt;span style="font-size:12px"&gt;unsubscribe&lt;/span&gt;&lt;/a&gt;&lt;span style="font-size:12px"&gt; from all emails at any time.&lt;/span&gt;&lt;/p&gt;
  &lt;p style="margin:1em 0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen-Sans,Ubuntu,Cantarell,'Helvetica Neue',sans-serif;color:#2d2d2f;font-size:16px;line-height:1.5;color:#4b4b4b; margin:1em 0;font-family:Arial,-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen-Sans,Ubuntu,Cantarell,'Helvetica Neue',sans-serif;;line-height:1.5;display:block;margin:13px 0;"&gt;&lt;span style="font-size:10px"&gt;12333 Sowden Rd, Ste. B, PMB #97429, Houston, TX 77080&lt;/span&gt;&lt;/p&gt;
&lt;/div&gt;&lt;/div&gt;
&lt;p class="" style="margin:1em 0;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,Oxygen-Sans,Ubuntu,Cantarell,'Helvetica Neue',sans-serif;color:#2d2d2f;font-size:16px;line-height:1.5"&gt;&lt;/p&gt;
&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;&lt;/div&gt;
&lt;/div&gt;
&lt;!-- --&gt;
&lt;img src="https://7751c435.open.convertkit-mail2.com/qdu2e69300t8u72r68malh82pvrkki4hllmmq" alt="" style="border:0 none;display:block;height:auto;line-height:100%;outline:none;-webkit-text-decoration:none;text-decoration:none;max-width:100%"&gt;
&lt;/body&gt;
&lt;/html&gt;
Email Content
