<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Massimiliano Trezzi on Medium]]></title>
        <description><![CDATA[Stories by Massimiliano Trezzi on Medium]]></description>
        <link>https://medium.com/@maxy.trezzi?source=rss-5588ae67ca8f------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*_we-1LYv45yRkei9_xidUQ.jpeg</url>
            <title>Stories by Massimiliano Trezzi on Medium</title>
            <link>https://medium.com/@maxy.trezzi?source=rss-5588ae67ca8f------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Mon, 16 Nov 2026 09:07:30 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@maxy.trezzi/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Show the genie only what matters]]></title>
            <link>https://medium.com/@maxy.trezzi/show-the-genie-only-what-matters-a4830b09d9f3?source=rss-5588ae67ca8f------2</link>
            <guid isPermaLink="false">https://medium.com/p/a4830b09d9f3</guid>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <dc:creator><![CDATA[Massimiliano Trezzi]]></dc:creator>
            <pubDate>Mon, 02 Nov 2026 21:26:52 GMT</pubDate>
            <atom:updated>2026-11-02T22:23:41.353Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*IxhEaYvJut4eUJTNlgZebQ.png" /></figure><p><em>How this article was written: Claude wrote the text, and I guided it, as I do with code. More on this at the end.</em></p><p>Context is the real problem with coding agents, and most of us know it. And yet we work on large projects, and we keep adding information in a messy way: one more instruction file, one more decision record, one more spec. I meet people who really think that adding more is enough to get better results.</p><p>It does not work like that. I borrow the word “genie” from <a href="https://newsletter.kentbeck.com/p/augmented-coding-beyond-the-vibes">Kent Beck</a>: a genie grants your wishes, but not always the ones you meant. Our genie does not see all of that information at once. It sees a window, and everything we add competes for a place in it. Telling it more does not help much. The question I keep asking is: <strong>how do we make it see only what is useful?</strong></p><p>I have been writing all of my code through agents for some months now, at work on business software and on my own side projects. Working on very different projects, I have felt how much this question matters, and how much harder it gets as a project grows. More powerful models help, but they don’t remove the problem.</p><p>One comparison made this clear to me. A really hard task in a small, tidy codebase took far fewer tokens and far less time than a much simpler task in a very complex one. In the second case I had long waits, huge token use, and extra checks I could not skip. The difficulty of the task mattered less than the shape of the code around it.</p><p>There is also the cost. Today tokens look cheap, but I do not think this will stay true: the big AI labs still lose money, and today’s prices are widely seen as a subsidy that cannot last forever (<a href="https://www.axios.com/2026/03/12/ai-models-costs-ipo-pricing">Axios</a>; the same article still expects costs to keep going down). Cheap models are not a full answer either. Some open-weight models get their results by thinking much longer: in one benchmark, on the same math, coding and science problems and with the same accuracy (about 82%), DeepSeek-V4-Flash used 83.6k tokens on average, where GPT-5.4 used 3.2k (<a href="https://arxiv.org/pdf/2511.05722">OckBench, arXiv 2511.05722</a>, paper). Those are tokens the model writes, not tokens it reads, but the lesson is the same: a low price per token can still mean a high price per task, and making the agent read less of what it does not need will always be worth something.</p><p>Here are my six answers, followed by what recent studies and practitioner reports say about each.</p><h3>Six ways to show only what matters</h3><h4>1. Compress meaning into concepts</h4><p>The most compact information you can give an agent is a good concept. When the analysis gets the domain concepts right, with clear names and relationships, each one carries its own rules, and the agent can infer many of them on its own. Very detailed specs do the opposite: they fill the window by repeating what a concept would have implied.</p><p>A small example. No spec paragraph is needed to say that a refund needs a payment date, or that a pending payment has no amount yet: the type already says it.</p><pre>enum Payment:<br>  case Pending(dueDate: LocalDate)<br>  case Paid(paidOn: LocalDate, amount: Money)<br>  case Refunded(paidOn: LocalDate, refundedOn: LocalDate, amount: Money)</pre><p>The same idea works for state. Here is an example of my own. Before, the state of an order is spread over flags:</p><pre>// The ifs are easy to read, but the data allows &quot;shipped and not paid&quot;,<br>// and every function that uses Order has to rebuild the state on its own.<br>case class Order(paid: Boolean, shipped: Boolean, deliveredOn: Option[LocalDate])<br><br>def cancel(order: Order, today: LocalDate): Either[String, Refund] =<br>  if !order.paid then Right(Refund.none)<br>  else if !order.shipped then Right(Refund.full(order))<br>  else order.deliveredOn match<br>    case None      =&gt; Left(&quot;Already shipped: wait for delivery&quot;)<br>    case Some(day) =&gt;<br>      if today.isAfter(day.plusDays(14)) then Left(&quot;Return window closed&quot;)<br>      else Right(Refund.full(order))</pre><p>After, the state is a concept, and invalid combinations cannot exist:</p><pre>enum OrderStatus:<br>  case Open, Paid, Shipped<br>  case Delivered(on: LocalDate)<br><br>case class Order(status: OrderStatus)<br><br>def cancel(order: Order, today: LocalDate): Either[String, Refund] =<br>  order.status match<br>    case OrderStatus.Open          =&gt; Right(Refund.none)<br>    case OrderStatus.Paid          =&gt; Right(Refund.full(order))<br>    case OrderStatus.Shipped       =&gt; Left(&quot;Already shipped: wait for delivery&quot;)<br>    case OrderStatus.Delivered(on) =&gt;<br>      if today.isAfter(on.plusDays(14)) then Left(&quot;Return window closed&quot;)<br>      else Right(Refund.full(order))</pre><p>The “before” version is not bad code, and the two functions have about the same length. The difference is in the data: the “after” version cannot represent an order that is shipped but not paid, so neither this function nor any other has to think about it, and the compiler warns if a new state is not handled.</p><h4>2. Make the code say what it means</h4><p>The same is true one level down. Good types, interfaces and names let the agent understand a piece of code without reading everything around it. I have seen agents make the same mistakes again and again with magic numbers used instead of an enumeration, and with identifiers and string keys that have unclear names. When the meaning is not in the code, the agent guesses, and not always in the same way.</p><pre>// Before: what are 3 and &quot;B2B&quot;? The agent has to search, or guess.<br>if order.status == 3 &amp;&amp; order.kind == &quot;B2B&quot; then applyDiscount(order)<br><br>// After: the meaning is in the code, and the compiler checks it.<br>enum OrderStatus:<br>  case Open, Paid, Shipped<br>  case Delivered(on: LocalDate)<br>enum Channel:<br>  case Retail, Business<br><br>if order.status == OrderStatus.Shipped &amp;&amp; order.channel == Channel.Business then<br>  applyDiscount(order)</pre><h4>3. Draw boundaries the agent can stop at</h4><p>Well-managed modules, with no circular dependencies, let the agent work on one part of the system and see only the interfaces it depends on. A cycle can drag everything it touches into the context. An acyclic structure gives the agent a place to stop.</p><h4>4. Write only what can’t be discovered</h4><p>Agents make documents cheap, and they write them in a long-winded way. Every document in the repository can end up in the window. The ones that repeat what the code already says are just noise, and noise has a cost.</p><h4>5. Keep the thinking somewhere else</h4><p>I keep brainstorming, exploration and drafts in a companion repository. Only the final artifacts, the decisions that are settled and the final specs, go into the main one. The agent that works on the product reads only what has really been decided.</p><h4>6. Steer the decisions, not the code</h4><p>This last one is about where human attention should go. In my experience, agents are not good at design decisions, especially in code that is specific to a domain. For me, the design choices are what need real attention, much more than a line-by-line review of the code. So I guide the agent through them in a step-by-step conversation, making the technical choices together and pushing it in the right direction, because on its own it has no taste for application design.</p><p>This depends a lot on the kind of code. When the task is very standard, like an integration or a well-known pattern, the agent usually chooses well: its training is full of best practices, and it picks the right one. The problem is complex logic that is specific to your domain. There, training does not help much, and the signal in your repository is weaker than the habits the model learned in training. Non-determinism also affects what the agent decides to read for the current task, so the same question can rest on different evidence each time. In domain-specific logic, your concepts and your code are the only signal against the model’s habits, so that signal must be as clear as possible. Newer models are already better at choosing what to read, but a clean codebase helps every model, because there is less to throw away.</p><h3>What the evidence says</h3><p>The sources are not all equally strong: some are arXiv papers, some are studies reported by technical blogs, and some are just opinion. I say which is which as I go. A few numbers come from second-hand summaries, so the exact figures should be treated with care.</p><h4>1. Concepts beat volume</h4><p>Anthropic’s engineering team calls model attention a scarce resource: every extra token competes with the others, because the number of token relationships grows with the square of the context length (<a href="https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents">Anthropic</a>). Dense meaning works better than a large amount of instructions.</p><p>There is also a name for what happens when we try to fix this with longer specs: over-specification. A 2026 practitioner’s guide on arXiv warns that very detailed specs turn into pseudo-code, which defeats the whole purpose of keeping the “what” apart from the “how” (<a href="https://arxiv.org/html/2602.00180v1">arXiv 2602.00180</a>, guide, not an empirical study). An O’Reilly piece adds that small, well-bounded tasks need only structured intent: a goal, a few examples, non-goals and acceptance criteria. It also notes that the easier an API (application programming interface) is to inspect, the more the code itself becomes the spec (<a href="https://stackoverflow.blog/2026/08/21/dispatches-from-o-reilly-the-right-amount-of-spec-for-agentic-development/">Stack Overflow / O’Reilly</a>, expert opinion).</p><p>Critics of spec-driven development are more direct: Brandon Kindred calls it mostly waterfall with a new name, and Thoughtworks says that the running code stays the source of truth (<a href="https://dev.to/krlz/spec-driven-development-in-2026-what-it-is-the-tooling-and-how-teams-actually-use-it-2fk2">overview on DEV</a>). Even its advocates recommend specs in domain language rather than implementation detail (<a href="https://addyosmani.com/blog/good-spec/">Addy Osmani</a>, expert opinion).</p><p>The order example in point 1 follows two well-known Scala voices. Martin Odersky presents pattern matching as the safe alternative to chains of type tests and casts, and he is clear that it fits best when the set of cases is closed, which is usually true for the states of a business process (<a href="https://www.artima.com/scalazine/articles/pattern_matching.html">Odersky, Artima interview</a>). Li Haoyi makes a related point about data types: make invalid data impossible by how the type is defined, instead of checking it at runtime (<a href="http://www.lihaoyi.com/post/StrategicScalaStyleDesigningDatatypes.html">Li Haoyi, Designing Datatypes</a>).</p><h4>2. Code structure is measurable</h4><p>The best study I found comes from CodeScene and Lund University (January 2026), and it was peer-reviewed for FORGE 2026, a conference on AI foundation models and software engineering held together with ICSE, the International Conference on Software Engineering. Six large language models (LLMs) refactored 5,000 short Python files (60 to 120 lines, taken from programming contests), split into “healthy” and “unhealthy” by the CodeHealth metric (<a href="https://arxiv.org/pdf/2601.02200">Borg et al., arXiv 2601.02200</a>, paper; summary by <a href="https://www.ian-thomas.net/ai-friendly-code/">Ian Thomas</a>). With the five mid-size models, refactorings of healthy code had 15% to 30% lower odds of breaking the tests. With the strongest model, Sonnet 4.5, and with Claude Code working as an agent, the difference was small and not statistically significant, but these two were tested on only about 1,000 files, so the study cannot really say whether they are sensitive to code quality. And all the files were small: the study does not test large codebases, where in my experience cleanliness dramatically changes cost, time and results.</p><p>Share of refactorings with all tests still passing:</p><ul><li>Sonnet 4.5: 86.8% on healthy code, 84.0% on unhealthy code (difference not significant)</li><li>Qwen (best mid-size model): 80.7% on healthy code, 72.2% on unhealthy code</li><li>Granite (weakest mid-size model): 46.5% on healthy code, 37.2% on unhealthy code</li></ul><p>The most common code smell in the dataset, counted 4,901 times, was “Bumpy Road Ahead”: several blocks of nested logic inside one function. The point where code becomes risky for AI is about the same point where it becomes hard for people to read, and agents sometimes made the structure worse while the tests still passed. Thoughtworks had already pointed to “AI-friendly code design” back in April 2025 (<a href="https://www.thoughtworks.com/content/dam/thoughtworks/documents/radar/2025/04/tr_technology_radar_vol_32_en.pdf">Technology Radar vol. 32</a>).</p><p>A second, pre-registered study from the same research group (October 2026) is closer to real projects: 465 pull requests written by agents, from 246 open-source repositories, reviewed and fixed by a pipeline of agents with three different models (<a href="https://arxiv.org/pdf/2610.21914">Gullstrand Heander, Borg, Söderberg, Rydenfält, arXiv 2610.21914</a>, paper). Healthier code was cheaper: each CodeHealth point meant 3.5% to 6.1% fewer tokens, and a typical healthy pull request cost about 22% to 35% less than a typical unhealthy one of the same size. The extra cost came from reading, not from writing: on unhealthy code the agents took more turns and read more, but they did not find more problems. This time the effect was also there for the strongest model tested, Sonnet 5, although none of the three models was a flagship. There is one limit: when the authors took the size of the files into account, the effect disappeared. In their sample, unhealthy code lived in very large files (a median of 2,146 lines, against 128 for healthy code), so the authors read the result as a reason to split code into smaller, cohesive units, not just to raise the score.</p><p>The same study also tested single code smells. Two of them predicted how many tokens the fixing agent spent, with all three models: complex methods and complex conditions. The effect is real but modest, and it is hard to separate from file size, because complex code tends to live in long files. The authors’ explanation makes sense to me: tangled control flow forces the agent to follow more execution paths before it can safely change anything. This is one more reason to move complexity out of the control flow and into the types, as in the order example of point 1.</p><p>An October 2026 paper from Microsoft Research looks at where the difficulty for agents really comes from (<a href="https://arxiv.org/pdf/2610.10610">arXiv 2610.10610</a>, paper). With tools like grep, agents stay near-perfect on large but simple tasks; they start to fail when the code is hard to understand. On SWE-bench Verified, a benchmark of real GitHub issues, the number of tool calls an agent spends reading and analysing code predicts failure better than the number of lines it edits (all the correlations are weak, but this one is the strongest). In a task built to need a lot of understanding, renaming variables hurt the agents more than anything else, which suggests they lean on names to understand code. This is point 2 again: for the agent, names carry meaning. And Codebase-Memory, a tool that gives the agent a compact graph of the code, answers at 83% quality against 92% for an agent that explores files, using about a tenth of the tokens (<a href="https://arxiv.org/html/2603.27277v1">arXiv 2603.27277</a>, paper; a tool paper by its own authors, with answers graded by the first author). A compact view of the code saves a lot of tokens, but it also loses some quality. Showing less has a cost too, so the real work is choosing well what to show.</p><h4>3. Boundaries are context engineering</h4><p>Graftcode argues that the architecture itself is context engineering: agents fail when they run out of context before they reach the part that matters (<a href="https://graftcode.com/blog/context-engineering">Graftcode</a>, opinion).</p><p>A May 2026 article says that small units with clear interfaces lower the load on the model (<a href="https://dasroot.net/posts/2026/05/code-for-ai-reader-redesigning-architecture-llm-era/">Code for the AI Reader</a>, opinion). Others suggest filtering what enters the prompt upstream, rather than chasing bigger context windows (<a href="https://towardsdatascience.com/coding-agents-dont-need-bigger-context-windows-they-need-a-context-compiler/">Towards Data Science</a>), and performance degradation as context fills up is a recurring observation (<a href="https://dev.to/somedood/coding-agents-as-a-first-class-consideration-in-project-structures-2a6b">DEV</a>). A concrete technique is the compressed repository map, as in Aider: signatures first, full files only on request (<a href="https://blog.jenuel.dev/blog/build-ai-agent-project-brain-without-overloading-context">Jenuel</a>).</p><p>None of the sources I found measures circular dependencies on their own; that part comes from my own experience. In a business application, I would make each bounded context (sales, purchasing, accounting) a module whose dependencies form an acyclic graph, checked by the build. In sbt this comes for free, because the build refuses cyclic dependencies between projects:</p><pre>// build.sbt<br>lazy val shared     = project<br>lazy val sales      = project.dependsOn(shared)<br>lazy val purchasing = project.dependsOn(shared)<br>lazy val accounting = project.dependsOn(sales, purchasing)<br>// If sales tried to depend on accounting, sbt would stop with a cyclic reference error.</pre><p>Inside one module, packages can still form cycles; a tool like ArchUnit can check that in a test. The same boundaries also let you give different parts different levels of human review, as <a href="https://www.ian-thomas.net/ai-friendly-code/">Ian Thomas</a> suggests.</p><h4>4. Generated documentation can make agents worse</h4><p>This is the finding that best answers the people I talked about earlier. In February 2026, an ETH Zurich team built AGENTbench, 138 tasks taken from 5,694 real pull requests, and measured how context files like AGENTS.md affect four coding agents (<a href="https://arxiv.org/abs/2602.11988">Gloaguen et al., arXiv 2602.11988</a>, paper; summary by <a href="https://umesh-malik.com/blog/agents-md-ai-coding-agents-study">Umesh Malik</a>).</p><p>Compared with no context file at all:</p><ul><li>Files written by developers: about +4% task success, up to +19% inference cost</li><li>Files generated by an LLM: −2% to −3% task success, over +20% inference cost</li></ul><p>With LLM-generated files, agents spent 10% to 22% more reasoning tokens. Repository overviews did not help them find the right files, and files written by an LLM mostly repeated documentation that was already there. Files written by developers did help, but only a little, and at a clear extra cost. The authors’ advice: skip generated context files for now, and keep handwritten ones to minimal requirements, such as the specific tooling a repository uses. One more detail supports this advice: when the authors removed the normal documentation from the repositories, the LLM-generated context files became more helpful. So these files mostly make up for missing documentation; in a well-documented repository they add little.</p><p>Practitioners agree. A September 2026 article gives each type of document a role: common rules in the agent file, procedures as skills loaded only when needed, an architecture map, ADRs (Architecture Decision Records) for the why, and logs kept searchable but out of the default context (<a href="https://medium.com/@ashwindevelops/your-ai-agent-does-not-need-more-markdown-it-needs-the-right-markdown-b86d705cb21b">Ashwin, Medium</a>). One developer reports that a small ADR index with bodies loaded on demand improved compliance and cut context bloat (<a href="https://dev.to/yureki_lab/how-i-taught-my-ai-coding-agent-to-stop-undoing-my-design-decisions-2o38">yureki_lab, DEV</a>).</p><p>Decision records written by AI tend to add invented details and nice-to-have features nobody asked for. The suggested fix is to review docs in the same pull request as the code and to keep decisions approved by a person (<a href="https://www.explainx.ai/blog/agents-dont-need-memory-they-need-documentation-operator-memory-2026">explainx</a>). And an ADR loaded into context still has to be enforced (<a href="https://mnemehq.com/insights/how-ai-coding-agents-use-adrs/">Mneme</a>).</p><h4>5. The companion repo has close relatives</h4><p>“Companion repo” is not a standard term, as far as I can tell, but several similar patterns are written up. The most solid one is the “Codified Context” paper (February 2026): a three-level context setup built during the development of a 108,000-line C# distributed system, with a top “constitution” always loaded and lower levels loaded only when needed (<a href="https://arxiv.org/html/2602.20478v1">Vasilopoulos, arXiv 2602.20478</a>, paper; commentary in <a href="https://devnewsletter.com/p/meta-repo-pattern/">Dev Newsletter</a>).</p><p>In practice there are two main versions. The “repo-of-repos” is an outer repository whose manifest clones the real projects inside it (<a href="https://raffertyuy.com/raztype/repo-of-repos-pattern/">Rafferty Uy</a>). The “private workspace with submodules” keeps private knowledge, like debugging notes and local config, apart from what each project publishes (<a href="https://medium.com/@sunghyunroh/multi-repo-workspace-strategy-the-structure-where-ai-coding-agents-actually-shine-4ed6b87fb11d">Sunghyun Roh, Medium</a>).</p><p>My version is simpler, and shaped by how I have really used it. My companion repo holds the work around the project: a review of similar libraries, the technologies to use, the design, the release planning, and things I want to keep private and strategic. It is where brainstorming, exploration, drafts and discarded options live. Only the definitive artifacts reach the main repository, which keeps just a short agent file following the <a href="https://agents.md/">AGENTS.md</a> convention. The agent that works on the product reads only what has been decided, and the private material never reaches the public repo. The risk is drift between the two, so any decision that constrains the code should stay checkable by the product’s build.</p><pre>my-library-companion/        (private)<br>  research/similar-libraries.md<br>  design/brainstorming/<br>  design/discarded-options/<br>  spikes/                    throwaway code<br>  release-planning.md<br>my-library/                  (main, public)<br>  AGENTS.md                  short<br>  docs/adr/                  settled decisions only<br>  modules/...</pre><p>The pattern is most useful when there is a lot of material. For a single implementation I often collect a large amount of documentation first: earlier implementations to align with, references, background. All of it leads to the code, but very little of it belongs next to the code. The same is true for the throwaway work that comes before the real implementation: MVPs (minimum viable products), spikes and studies, the things you build to learn and then put aside. Inside the main project they are a real nuisance, filling a repo that should only hold what ships. I keep all of that mass in the companion repo and promote to the main project only what actually needs to live there, so the main repo’s volume doesn’t carry the weight of everything that was considered.</p><p>There is another use I have not tried myself but that seems sound: keeping all the agent material, the instructions, skills and configuration, out of the main project too, so the product repo stays only about the product. Some people already do a version of this, for example keeping agent config in a private repo linked by symlinks (<a href="https://irina.codes/keep-your-claude-code-agents-out-of-the-teams-repo/">irina.codes</a>).</p><h4>6. Judgment stays with the human</h4><p>This is the belief I hold most strongly, and also the hardest to measure: design judgment is the part I trust agents with least, especially in domain-specific code. They produce plausible solutions, but they have no taste for which trade-offs make sense. Ask the same agent to build the same feature five times and you will probably get five different choices for the architecture, the naming and the error handling. Each of these choices needs a person with judgment on the output side. One author calls this “architectural governance at a higher level” (<a href="https://wrcd.ai/en/insights/ai-made-bad-design-expensive/">WRCD</a>, opinion).</p><p>“Taste is the new bottleneck” argues that judgment can no longer stay unspoken in the age of agents (<a href="https://www.designative.info/2026/02/01/taste-is-the-new-bottleneck-design-strategy-and-judgment-in-the-age-of-agents-and-vibe-coding/">Designative</a>, opinion). Others describe the change as less inspection and more steering: with agents writing the code, review becomes the moment where people add taste and correct the architecture (<a href="https://alexlooney.substack.com/p/code-review-as-we-know-it-must-die">Alex Looney</a>, opinion; <a href="https://codagent.beehiiv.com/p/the-middle-agentic-path">The Middle Agentic Path</a>, opinion). Even a position paper that argues agents should replace human code review keeps human oversight for architecture decisions with long-lived consequences, and says that a coherent architecture is best kept through design documents, ADRs and dedicated architecture reviews (<a href="https://arxiv.org/html/2606.13175v1">arXiv 2606.13175</a>, position paper by Martin Monperrus). A small DESIGN.md that records the why is one lightweight way to hold the line (<a href="https://rowanblackwoon.medium.com/design-md-the-small-file-that-keeps-coding-agents-from-guessing-your-architecture-09cbbb8026d2">Rowan Blackwoon</a>, opinion).</p><p>Research on so-called knowledge conflicts supports the difference between standard and domain-specific code. When the context says something different from what a model learned in training, the model cannot fully set its internal knowledge aside, even when told to, and it performs better when the two agree (<a href="https://arxiv.org/abs/2506.06485v1">arXiv 2506.06485</a>, paper). On code, a 2026 study found that LLMs struggle to use the APIs of private libraries even when they are given the knowledge they need (<a href="https://arxiv.org/html/2603.15159v4">arXiv 2603.15159</a>, paper). The first study adds a useful detail: explaining the reason behind a conflict makes the model rely more on the context. This is one more argument for writing down the why, as ADRs and DESIGN.md do.</p><p>In practice, for me, this is a step-by-step conversation: make the technical choices together, steer the agent where it matters, and let it write the code once the decision is sound.</p><h3>The human window</h3><p>There is one more thing I have learned, about the human side: the human has a window too, and it is smaller than the agent’s. Agentic development pushes you to multitask. While one agent works, waiting feels like a waste, so you open another session. This is a real opportunity, but it comes with two risks: you get scattered, and you get very tired.</p><p>I am not the only one who sees this. A long-term study of developer logs found that AI users switch context slightly more over time, while non-users switch slightly less (<a href="https://arxiv.org/pdf/2601.10258">arXiv 2601.10258</a>, paper). Simon Willison says he can run four agents in parallel on four different problems, but by 11 a.m. he is worn out, because there is a limit to how much a person can hold in their head at one time (<a href="https://simonwillison.net/2026/Apr/2/lennys-podcast/">his notes on the podcast interview</a>). Addy Osmani explains part of the reason: parallel agents free up time, but they also create a steady stream of moments that need your judgment, and you can supervise more agents than you can really understand (<a href="https://addyosmani.com/blog/cognitive-parallel-agents/">Addy Osmani</a>, opinion). Not everyone calls it multitasking: Constantin Gonzalez compares it to a head chef running a kitchen of line cooks (<a href="https://constantin.glez.de/posts/2026-07-16-why-working-with-ai-agents-is-so-tiring-and-what-to-do-about-it/">Constantin Gonzalez</a>, opinion). But even in a kitchen, the chef’s attention is the limit.</p><p>Fatigue is one risk. The bigger one, for me, is that when my attention is split, some decisions slip past me: choices the LLM made on its own, based on its own guesses. This is the problem of the sixth point, made worse. So I try to set limits, even if I am still working out how. Usually I run two complex flows at the same time, or one complex flow plus a few small filler tasks. It is not a perfect rule, and there are many traps, but it helps keep the important decisions with someone who is actually paying attention.</p><h3>Back to the genie</h3><p>The genie sees only a small window of the room, and what it looks at can change from run to run. Five of the six answers make that window hold only what matters. The sixth keeps the decisions in human hands, because a bigger window will never fix that.</p><p>One last confession. I did not write a single word of this article. Claude wrote all of it, and working on it felt exactly like working on code with an agent. I chose what to say and what to leave out. I decided which sources to keep and which to drop, I rejected an example that was misleading and asked for one I could defend, and I made sure the key numbers were checked in the original papers. Most of the work was managing the context: what Claude should see, and what it should ignore. The result feels completely mine, in the same way my code does, and I can see my hand in every section.</p><p>There is a lot of talk today about programmers not mattering anymore. My experience says the opposite. If human guidance matters this much for an article, it matters even more for software, where design decisions last for years and a wrong one costs much more. The agent writes the words or the code, but someone has to know what the work is for, which trade-offs to accept, and when a plausible answer is wrong.</p><p>Looking ahead, good libraries, clear abstractions and well-designed languages will still matter. They make intent explicit and leave less room for the agent to guess. As agents take over more routine implementation, I expect domain logic and design decisions to matter even more. Someone still has to make those decisions.</p><p>So the next time someone suggests adding one more file to help the agent, I would ask one simple question: even if the information is true, does the agent need to see it now?</p><h3>Sources</h3><h4><strong>Papers and preprints</strong></h4><ul><li>Borg, Hagatulah, Tornhill, Söderberg — <a href="https://arxiv.org/pdf/2601.02200">Code health and LLM refactoring, CodeScene / Lund University (arXiv 2601.02200)</a></li><li>Gullstrand Heander, Borg, Söderberg, Rydenfält — <a href="https://arxiv.org/pdf/2610.21914">CodeHealth Predicts the Token Cost of Agentic Code Review (arXiv 2610.21914)</a></li><li>Gloaguen, Mündler, Müller, Raychev, Vechev — <a href="https://arxiv.org/abs/2602.11988">Evaluating AGENTS.md, ETH Zurich (arXiv 2602.11988)</a></li><li>Balepur, Tomlinson, Schnabel — <a href="https://arxiv.org/pdf/2610.10610">Code Understanding is a Bottleneck for Coding Agents, Microsoft Research (arXiv 2610.10610)</a></li><li>Monperrus — <a href="https://arxiv.org/html/2606.13175v1">The End of Code Review: Coding Agents Supersede Human Inspection, position paper (arXiv 2606.13175)</a></li><li>Vogel et al. — <a href="https://arxiv.org/html/2603.27277v1">Codebase-Memory: Tree-Sitter-Based Knowledge Graphs (arXiv 2603.27277)</a></li><li><a href="https://arxiv.org/html/2602.00180v1">Spec-Driven Development: From Code to Contract (arXiv 2602.00180)</a></li><li>Vasilopoulos — <a href="https://arxiv.org/html/2602.20478v1">Codified Context (arXiv 2602.20478)</a></li><li><a href="https://arxiv.org/pdf/2601.10258">Evolving with AI: A Longitudinal Analysis of Developer Logs (arXiv 2601.10258)</a></li><li>Sun et al. — <a href="https://arxiv.org/abs/2506.06485v1">What Is Seen Cannot Be Unseen: The Disruptive Effect of Knowledge Conflict on Large Language Models (arXiv 2506.06485)</a></li><li><a href="https://arxiv.org/html/2603.15159v4">To See is Not to Master: Teaching LLMs to Use Private Libraries for Code Generation (arXiv 2603.15159)</a></li><li><a href="https://arxiv.org/pdf/2511.05722">OckBench: Measuring the Efficiency of LLM Reasoning (arXiv 2511.05722)</a></li></ul><h4><strong>Technical articles and reports</strong></h4><ul><li><a href="https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents">Anthropic — Effective context engineering for AI agents</a></li><li><a href="https://stackoverflow.blog/2026/08/21/dispatches-from-o-reilly-the-right-amount-of-spec-for-agentic-development/">Stack Overflow / O’Reilly — The right amount of spec for agentic development</a></li><li><a href="https://www.thoughtworks.com/content/dam/thoughtworks/documents/radar/2025/04/tr_technology_radar_vol_32_en.pdf">Thoughtworks Technology Radar vol. 32</a></li><li><a href="https://www.ian-thomas.net/ai-friendly-code/">Ian Thomas — Your AI Agent Has a Code Quality Problem</a></li><li><a href="https://umesh-malik.com/blog/agents-md-ai-coding-agents-study">Umesh Malik — AGENTS.md Files Don’t Work the Way You Think</a></li><li><a href="https://graftcode.com/blog/context-engineering">Graftcode — Software Architecture Is Context Engineering</a></li><li><a href="https://towardsdatascience.com/coding-agents-dont-need-bigger-context-windows-they-need-a-context-compiler/">Towards Data Science — Coding Agents Need a Context Compiler</a></li><li><a href="https://addyosmani.com/blog/good-spec/">Addy Osmani — How to write a good spec for AI agents</a></li><li><a href="https://devnewsletter.com/p/meta-repo-pattern/">Dev Newsletter — The Meta-Repo Pattern</a></li><li><a href="https://agents.md/">AGENTS.md</a></li><li><a href="https://simonwillison.net/2026/Apr/2/lennys-podcast/">Simon Willison — Highlights from my conversation about agentic engineering on Lenny’s Podcast</a></li><li><a href="https://newsletter.kentbeck.com/p/augmented-coding-beyond-the-vibes">Kent Beck — Augmented Coding: Beyond the Vibes</a></li><li><a href="https://www.artima.com/scalazine/articles/pattern_matching.html">Martin Odersky — The Point of Pattern Matching in Scala (Artima interview)</a></li><li><a href="http://www.lihaoyi.com/post/StrategicScalaStyleDesigningDatatypes.html">Li Haoyi — Strategic Scala Style: Designing Datatypes</a></li><li><a href="https://www.axios.com/2026/03/12/ai-models-costs-ipo-pricing">Axios — Don’t get used to cheap AI</a></li></ul><h4><strong>Opinion and practitioner reports</strong></h4><ul><li><a href="https://dasroot.net/posts/2026/05/code-for-ai-reader-redesigning-architecture-llm-era/">Code for the AI Reader</a></li><li><a href="https://dev.to/krlz/spec-driven-development-in-2026-what-it-is-the-tooling-and-how-teams-actually-use-it-2fk2">DEV — Spec-Driven Development in 2026</a></li><li><a href="https://dev.to/somedood/coding-agents-as-a-first-class-consideration-in-project-structures-2a6b">DEV — Coding Agents as a First-Class Consideration in Project Structures</a></li><li><a href="https://blog.jenuel.dev/blog/build-ai-agent-project-brain-without-overloading-context">Jenuel — Build an AI Agent Project Brain</a></li><li><a href="https://medium.com/@ashwindevelops/your-ai-agent-does-not-need-more-markdown-it-needs-the-right-markdown-b86d705cb21b">Ashwin — Your AI Agent Does Not Need More Markdown</a></li><li><a href="https://dev.to/yureki_lab/how-i-taught-my-ai-coding-agent-to-stop-undoing-my-design-decisions-2o38">yureki_lab — Stop Undoing My Design Decisions</a></li><li><a href="https://www.explainx.ai/blog/agents-dont-need-memory-they-need-documentation-operator-memory-2026">explainx — Agents Don’t Need Memory, They Need Documentation</a></li><li><a href="https://mnemehq.com/insights/how-ai-coding-agents-use-adrs/">Mneme — How AI Coding Agents Use ADRs</a></li><li><a href="https://raffertyuy.com/raztype/repo-of-repos-pattern/">Rafferty Uy — Repo-of-Repos</a></li><li><a href="https://medium.com/@sunghyunroh/multi-repo-workspace-strategy-the-structure-where-ai-coding-agents-actually-shine-4ed6b87fb11d">Sunghyun Roh — Multi-Repo Workspace Strategy</a></li><li><a href="https://wrcd.ai/en/insights/ai-made-bad-design-expensive/">WRCD — AI Made Bad Design Expensive</a></li><li><a href="https://www.designative.info/2026/02/01/taste-is-the-new-bottleneck-design-strategy-and-judgment-in-the-age-of-agents-and-vibe-coding/">Designative — Taste Is the New Bottleneck</a></li><li><a href="https://alexlooney.substack.com/p/code-review-as-we-know-it-must-die">Alex Looney — Code Review (As We Know It) Must Die</a></li><li><a href="https://codagent.beehiiv.com/p/the-middle-agentic-path">The Middle Agentic Path</a></li><li><a href="https://rowanblackwoon.medium.com/design-md-the-small-file-that-keeps-coding-agents-from-guessing-your-architecture-09cbbb8026d2">Rowan Blackwoon — DESIGN.md</a></li><li><a href="https://irina.codes/keep-your-claude-code-agents-out-of-the-teams-repo/">irina.codes — Keep Your Claude Code Agents Out of the Team’s Repo</a></li><li><a href="https://addyosmani.com/blog/cognitive-parallel-agents/">Addy Osmani — Your parallel Agent limit</a></li><li><a href="https://constantin.glez.de/posts/2026-07-16-why-working-with-ai-agents-is-so-tiring-and-what-to-do-about-it/">Constantin Gonzalez — Why working with AI agents is so tiring</a></li></ul><p><em>I am Massimiliano, a software engineer from Italy. I work on business software, and in my free time I build open-source projects. You can find them on </em><a href="https://github.com/maxtrezzi"><em>GitHub</em></a><em>.</em></p><p><em>If you work with coding agents too, I would love to hear how you handle context and design decisions. Leave a comment, or find me on </em><a href="http://linkedin.com/in/massimilianotrezzi"><em>LinkedIn</em></a><em>.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a4830b09d9f3" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>