<?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 Niteshkrjhag on Medium]]></title>
        <description><![CDATA[Stories by Niteshkrjhag on Medium]]></description>
        <link>https://medium.com/@niteshkrjhag?source=rss-9dbcdadc41e4------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*p-UP0eDzOfO2F0hK</url>
            <title>Stories by Niteshkrjhag on Medium</title>
            <link>https://medium.com/@niteshkrjhag?source=rss-9dbcdadc41e4------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Fri, 20 Nov 2026 13:44:54 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@niteshkrjhag/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[AI Coding Dictionary in Detail: DX vs AX]]></title>
            <link>https://medium.com/@niteshkrjhag/ai-coding-dictionary-in-detail-dx-vs-ax-3adc36cde0f9?source=rss-9dbcdadc41e4------2</link>
            <guid isPermaLink="false">https://medium.com/p/3adc36cde0f9</guid>
            <category><![CDATA[machine-learning]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[agent-experience]]></category>
            <category><![CDATA[digital-experience-design]]></category>
            <dc:creator><![CDATA[Niteshkrjhag]]></dc:creator>
            <pubDate>Mon, 14 Sep 2026 14:40:27 GMT</pubDate>
            <atom:updated>2026-09-14T14:40:27.541Z</atom:updated>
            <content:encoded><![CDATA[<p>Imagine two developers join the same project.</p><p>The first is human.</p><p>The second is an AI coding agent.</p><p>Both need to:</p><pre>understand the repository<br>      ↓<br>find relevant code<br>      ↓<br>make a change<br>      ↓<br>run tests<br>      ↓<br>understand failures<br>      ↓<br>correct the implementation</pre><p>Many things that make this easy for the human also help the agent.</p><p>But not everything does.</p><p>That difference gives us two terms:</p><p><strong>DX → Developer Experience</strong><br><strong>AX → Agent Experience</strong></p><p>The simplest distinction is:</p><blockquote><strong><em>DX asks: “How easy is this environment for a human developer to work in?”</em></strong></blockquote><blockquote><strong><em>AX asks: “How easy is this environment for an AI agent to work in reliably?”</em></strong></blockquote><h3>1. DX — Developer Experience</h3><h3>What is DX?</h3><p><strong>Developer Experience is the quality of a developer’s interaction with a codebase, tools, documentation, APIs, and development workflow.</strong></p><p>Good DX means a developer can move from:</p><pre>&quot;I need to change this&quot;</pre><p>to:</p><pre>&quot;I changed it correctly&quot;</pre><p>without unnecessary friction.</p><p>For example:</p><pre>clone repository<br>      ↓<br>one setup command<br>      ↓<br>clear error if something is missing<br>      ↓<br>fast local tests<br>      ↓<br>easy-to-understand project structure</pre><p>That is good DX.</p><h3>What does bad DX feel like?</h3><p>Imagine joining a backend project.</p><p>The README says:</p><pre>npm install</pre><p>but the team actually uses:</p><pre>pnpm install</pre><p>The tests require an environment variable nobody documented.</p><p>The command fails with:</p><pre>Something went wrong.</pre><p>And when you ask where billing logic lives, someone tells you:</p><blockquote><em>“Ask Sarah. She knows that module.”</em></blockquote><p>A human developer can eventually survive this.</p><p>They learn:</p><pre>Use pnpm<br>The secret env file is in this folder<br>Billing logic lives here<br>That error actually means Redis is down</pre><p>After a few weeks, those facts live in the developer’s head.</p><p>The codebase may still have poor DX.</p><p>The developer has simply learned how to work around it.</p><h3>Humans accumulate knowledge</h3><p>This is where humans and agents begin to diverge.</p><p>A human developer might learn on Monday:</p><blockquote><em>“Never run the full integration suite locally. Use </em><em>pytest tests/auth first.”</em></blockquote><p>On Tuesday, they still remember it.</p><p>On Friday, they still remember it.</p><p>They build a mental map:</p><pre>auth → src/auth/<br>payments → services/billing/<br>generated files → don&#39;t touch<br>deployment → ask DevOps</pre><p>That accumulated knowledge can hide weaknesses in the development environment.</p><p>The team starts saying:</p><blockquote><em>“The repo is actually easy once you know it.”</em></blockquote><p>The important phrase is:</p><blockquote><strong><em>once you know it.</em></strong></blockquote><h3>2. AX — Agent Experience</h3><p>Now give the same repository to a coding agent.</p><p>The agent may have an excellent model.</p><p>It may have excellent tools.</p><p>But if the environment says:</p><pre>Tests take 45 minutes</pre><pre>Errors say:<br>&quot;Build failed&quot;</pre><pre>Important rules live in Slack</pre><pre>Directory names are inconsistent</pre><pre>Generated files look editable</pre><pre>Documentation is stale</pre><pre>No automated type checks exist</pre><p>the agent has very little reliable feedback.</p><p>The model is not necessarily the problem.</p><p>The <strong>environment is difficult for an agent to operate in</strong>.</p><p>That is the problem AX tries to describe.</p><h3>What is AX?</h3><p>In this series:</p><blockquote><strong><em>Agent Experience is how well a repository, toolchain, and surrounding environment enable an AI coding agent to understand the project, take useful actions, receive clear feedback, and recover from mistakes.</em></strong></blockquote><p>AX is an emerging term rather than a decades-old standardized discipline. Broader AX work describes it as designing systems so agents can access, understand, and operate them effectively. For coding specifically, the same idea applies to repositories, SDKs, CLIs, tests, documentation, and tools.</p><h3>A simple example</h3><p>Imagine two repositories.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XYAtW8IoMP6_EvEZt9mb4g.png" /></figure><h3>What makes good coding AX?</h3><p>Three areas matter especially.</p><h3>1. Good automated feedback</h3><p>The agent needs machines to tell it when it is wrong.</p><pre>Tests<br>Type checks<br>Lint<br>Build<br>Schema validation</pre><p>Better still, failures should be useful:</p><pre>BAD</pre><pre>Build failed.</pre><p>versus:</p><pre>GOOD</pre><pre>src/orders/service.py:81</pre><pre>Argument `customer_id`<br>expected UUID<br>received string</pre><p>The second result gives the agent something concrete to correct.</p><h3>2. Navigable architecture</h3><p>An agent should not need to read 500 files to discover where authentication lives.</p><p>Compare:</p><pre>src/auth/<br>src/payments/<br>src/users/</pre><p>with:</p><pre>utils/<br>helpers/<br>shared/<br>common/<br>misc/</pre><p>Predictable names and small interfaces help both humans and agents.</p><p>But they matter especially for agents because every unnecessary search or file read consumes:</p><pre>tool calls<br>+<br>tokens<br>+<br>context</pre><h3>3. Efficient context</h3><p>An agent also has a constraint humans do not experience in the same way:</p><p><strong>the context window.</strong></p><p>Suppose every session automatically loads:</p><pre>8K style guide<br>6K deployment guide<br>5K database handbook<br>4K historical notes<br>3K unused tool definitions</pre><p>before the task starts.</p><p>The agent has already spent a large amount of its working context on information that may be irrelevant.</p><p>Better AX uses concepts we already covered:</p><pre>small AGENTS.md<br>      +<br>context pointers<br>      +<br>skills<br>      +<br>progressive disclosure</pre><p>so detailed information appears only when needed.</p><h3>DX and AX overlap</h3><p>A large amount of good engineering improves both.</p><pre>Fast tests<br>        ↓<br>Human gets feedback faster<br>Agent gets feedback faster</pre><pre>Clear architecture<br>        ↓<br>Human navigates faster<br>Agent searches fewer files</pre><pre>Useful errors<br>        ↓<br>Human debugs faster<br>Agent self-corrects better</pre><p>So:</p><pre>GOOD ENGINEERING<br>      ↓<br>often improves<br>   DX + AX</pre><h3>But DX and AX can diverge</h3><p>Imagine your company has excellent onboarding.</p><p>A senior developer spends two days with every new engineer explaining:</p><pre>where important modules live<br>which documentation is outdated<br>which commands actually work<br>who owns each service</pre><p>Humans may report:</p><blockquote><em>“Our developer experience is great.”</em></blockquote><p>Now start a fresh coding agent.</p><p>It does not automatically get those two days of mentoring.</p><p>Unless that knowledge has been turned into something it can access:</p><pre>AGENTS.md<br>docs<br>skills<br>tests<br>tool descriptions<br>structured errors</pre><p>it may not exist from the agent’s perspective.</p><p>That is an AX gap.</p><h3>Another important difference: interfaces</h3><p>Humans sometimes benefit from:</p><pre>beautiful dashboards<br>IDE hover information<br>visual diagrams<br>tribal knowledge<br>informal conversations</pre><p>Agents often benefit more from machine-accessible equivalents:</p><pre>structured CLI output<br>clear APIs<br>text-based errors<br>discoverable documentation<br>stable schemas<br>tool-accessible data</pre><p>This does not mean agents cannot use graphical interfaces.</p><p>It means:</p><blockquote><strong><em>Designing something beautifully for humans does not automatically make it easy for agents to operate.</em></strong></blockquote><p>That broader idea is also appearing outside coding: current AX work focuses on making products, services, APIs, and digital environments easier for agents to discover and use reliably.</p><h3>A Useful Diagnostic</h3><p>Suppose your agent performs badly.</p><p>The instinct is:</p><pre>Bad result<br>   ↓<br>Use a bigger model</pre><p>Sometimes that is correct.</p><p>But ask these questions first:</p><pre>Could it find the right file?</pre><pre>Did it know the project rules?</pre><pre>Could it run the relevant tests?</pre><pre>Were failures understandable?</pre><pre>Was authoritative documentation reachable?</pre><pre>Was unnecessary context loaded?</pre><pre>Could it verify its own work?</pre><p>If several answers are <strong>no</strong>, changing the model may not solve the underlying problem.</p><p>You may have an AX issue.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MZQk8_CHrjpnBvxYmYaH4w.png" /></figure><p>The relationship is:</p><pre>                 CODEBASE<br>                    │<br>          ┌─────────┴─────────┐<br>          ▼                   ▼<br>         DX                  AX<br>          │                   │<br>&quot;Can a human work      &quot;Can an agent work<br> here effectively?&quot;    here effectively?&quot;</pre><p>They overlap heavily.</p><p>But they are not identical.</p><h3>The Two Definitions Worth Remembering</h3><h3>DX — Developer Experience</h3><p><strong>How easy a codebase, tools, documentation, and development workflow make it for human developers to do good work.</strong></p><h3>AX — Agent Experience</h3><p><strong>How well an environment enables AI agents to understand what matters, use the available capabilities, receive useful feedback, and complete work reliably.</strong></p><p>For coding AX, think especially about:</p><pre>checks<br>architecture<br>documentation<br>tools<br>context efficiency</pre><h3>The Practical Lesson</h3><p>When the same coding agent performs brilliantly in one repository and struggles in another, do not automatically conclude:</p><blockquote><em>“The model is inconsistent.”</em></blockquote><p>Look at the environment.</p><p>A strong repository gives an agent:</p><pre>clear instructions<br>      +<br>easy navigation<br>      +<br>fast verification<br>      +<br>useful errors<br>      +<br>relevant context</pre><p>The simplest way to remember the difference is:</p><blockquote><strong><em>DX makes the codebase easier for developers to work with. AX makes the codebase easier for agents to work with. Great engineering increasingly needs both.</em></strong></blockquote><p>If this article helped clarify the difference between <strong>Developer Experience and Agent Experience</strong>, react to it and share your thoughts in the comments.</p><p><strong>Follow me here on LinkedIn</strong> for the next article in the <em>AI Coding Dictionary in Detail</em> series.</p><p>You can also connect with me here:</p><p><a href="https://www.linkedin.com/in/nitesh-kr-jha-/">linkedin.com/in/nitesh-kr-jha-/</a></p><p>Thanks for reading. 🚀</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3adc36cde0f9" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI Coding Dictionary in Detail: Design Concept, Grilling & Prototyping]]></title>
            <link>https://medium.com/@niteshkrjhag/ai-coding-dictionary-in-detail-design-concept-grilling-prototyping-d81966722596?source=rss-9dbcdadc41e4------2</link>
            <guid isPermaLink="false">https://medium.com/p/d81966722596</guid>
            <category><![CDATA[prototyping]]></category>
            <category><![CDATA[aritificial-intelligence]]></category>
            <category><![CDATA[design-thinking]]></category>
            <category><![CDATA[design]]></category>
            <category><![CDATA[ai-agent]]></category>
            <dc:creator><![CDATA[Niteshkrjhag]]></dc:creator>
            <pubDate>Mon, 14 Sep 2026 14:37:50 GMT</pubDate>
            <atom:updated>2026-09-14T14:37:50.848Z</atom:updated>
            <content:encoded><![CDATA[<p>You tell an AI coding agent:</p><blockquote><em>“Build a cancellation feature for orders.”</em></blockquote><p>It asks a few questions, writes a clean spec, implements everything correctly according to that spec — and when you finally use it, you realize:</p><blockquote><em>“This is not what I wanted.”</em></blockquote><p>The agent followed the instructions.</p><p>The code works.</p><p>The tests pass.</p><p>So what went wrong?</p><p>Sometimes the problem starts <strong>before coding and even before the spec</strong>.</p><p>You and the agent never developed the same understanding of what the product was supposed to be.</p><p>That connects three concepts:</p><p><strong>Design Concept → Grilling → Prototyping</strong></p><p>The relationship is:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*cTuUQnNW7iLH6f6Yjw5tSQ.png" /></figure><h3>1. Design Concept</h3><h3>What is a design concept?</h3><p>For this series:</p><blockquote><strong><em>A design concept is the shared mental understanding of what we are trying to build, how it should behave, and why those choices make sense.</em></strong></blockquote><p>It is not the code.</p><p>It is not the spec.</p><p>It is not the Figma file.</p><p>Those are <strong>artifacts that attempt to express the design concept</strong>.</p><p>This distinction is inspired by Fred Brooks’ writing on design and conceptual integrity: good systems need a coherent underlying idea rather than merely a collection of individually reasonable decisions.</p><p>Think:</p><pre>       DESIGN CONCEPT<br>    what we actually mean</pre><pre>        ↓ expressed through</pre><pre>    Conversation<br>    Spec<br>    Prototype<br>    Code<br>    Tests</pre><p>The artifacts can be wrong even when they are beautifully written.</p><h3>A relatable example</h3><p>Suppose you say:</p><blockquote><em>“Users should be able to cancel an order.”</em></blockquote><p>Sounds clear.</p><p>But several decisions are hidden inside that sentence.</p><p>What if:</p><pre>Payment already succeeded?</pre><pre>Only one item should be cancelled?</pre><pre>The warehouse already packed the order?</pre><pre>Part of the order already shipped?</pre><pre>A discount depended on order value?</pre><pre>Refund takes three days?</pre><pre>Seller rejects the cancellation?</pre><p>If you have not decided these things, the agent has only two options:</p><pre>Ask</pre><p>or:</p><pre>Guess</pre><p>And agents are very capable of producing reasonable-looking guesses.</p><p>That is the dangerous part.</p><h3>When correct implementation is still wrong</h3><p>Imagine your prompt says:</p><blockquote><em>“Allow users to cancel an order before shipping.”</em></blockquote><p>The agent decides:</p><pre>Cancel order<br>      ↓<br>set status = cancelled<br>      ↓<br>refund full payment</pre><p>Everything works.</p><p>But your actual business model requires:</p><pre>Cancel whole order?<br>or one item?</pre><pre>Was coupon applied?</pre><pre>Has seller accepted?</pre><pre>Was inventory reserved?</pre><pre>Should shipping charge be refunded?</pre><p>The agent did not necessarily fail.</p><p>Your <strong>design concept was incomplete</strong>.</p><p>The prompt contained the decisions you had already made.</p><p>The agent filled in the rest.</p><h3>How do you know the design concept is becoming shared?</h3><p>A useful signal is when the agent starts predicting your decisions correctly.</p><p>Early:</p><pre>AGENT:<br>&quot;What happens if one item has shipped?&quot;</pre><pre>YOU:<br>&quot;Oh, I hadn&#39;t thought about that.&quot;</pre><p>Later:</p><pre>AGENT:<br>&quot;If one item has shipped, I&#39;m assuming we allow<br>cancellation only for the remaining unshipped items,<br>and calculate refund per item. Correct?&quot;</pre><pre>YOU:<br>&quot;Exactly.&quot;</pre><p>That is much closer to shared understanding.</p><p>The goal is not for the agent to read your mind.</p><p>The goal is that enough decisions have been made explicitly that both sides are operating from the same model of the product.</p><h3>Why writing the spec too early can be dangerous</h3><p>A spec feels authoritative.</p><p>That is precisely why it can be dangerous when created too early.</p><p>You begin with:</p><pre>&quot;Build order cancellation.&quot;</pre><p>The agent silently fills ten gaps and generates:</p><pre>CANCELLATION_SPEC.md</pre><p>Now assumptions that existed for thirty seconds suddenly look like established requirements.</p><p>The problem has moved from:</p><pre>unresolved question</pre><p>to:</p><pre>professional-looking document</pre><p>without actually being resolved.</p><p>So before durable artifacts, we often need conversation.</p><p>That is where <strong>grilling</strong> comes in.</p><h3>2. Grilling</h3><h3>What is grilling?</h3><p>For this series:</p><blockquote><strong><em>Grilling is a deliberate interview where the agent exposes unresolved decisions instead of silently choosing defaults for them.</em></strong></blockquote><p>The name sounds aggressive, but the technique is simple.</p><p>Instead of:</p><blockquote><em>“Write me a spec for cancellation.”</em></blockquote><p>you ask the agent:</p><blockquote><em>“Interview me first. Find the decisions that are still unresolved. Ask one important question at a time and recommend an option where useful.”</em></blockquote><p>Now the workflow changes.</p><h3>Without grilling</h3><pre>USER<br>&quot;Build cancellation.&quot;<br>      ↓<br>AGENT<br>fills gaps<br>      ↓<br>SPEC<br>      ↓<br>IMPLEMENTATION<br>      ↓<br>&quot;Wait, that&#39;s not what I meant.&quot;</pre><h3>With grilling</h3><pre>USER<br>&quot;Build cancellation.&quot;<br>      ↓<br>AGENT<br>&quot;What happens after shipment?&quot;<br>      ↓<br>USER ANSWERS<br>      ↓<br>AGENT<br>&quot;Can users partially cancel?&quot;<br>      ↓<br>USER ANSWERS<br>      ↓<br>AGENT<br>&quot;How should coupon refunds work?&quot;<br>      ↓<br>USER ANSWERS<br>      ↓<br>DESIGN CONCEPT becomes clearer<br>      ↓<br>SPEC</pre><p>The agent is doing something very valuable:</p><blockquote><strong><em>Turning invisible assumptions into visible decisions.</em></strong></blockquote><h3>Why one question at a time?</h3><p>Imagine receiving twenty questions like:</p><pre>Cancellation timing?<br>Refund timing?<br>Partial order?<br>Shipping?<br>Coupons?<br>Inventory?<br>Seller approval?<br>Notifications?<br>Analytics?<br>Fraud?</pre><p>You will probably answer the first few carefully and rush through the rest.</p><p>Instead:</p><pre>Question<br>   ↓<br>Decision<br>   ↓<br>Next question based on that decision</pre><p>creates a better conversation.</p><p>For example:</p><blockquote><em>“Should cancellation be allowed after fulfillment starts? My recommendation is no, because after warehouse processing begins we should move into a return flow instead.”</em></blockquote><p>Now you are not answering an abstract question.</p><p>You are making one concrete design decision.</p><h3>Grilling works when words are enough</h3><p>Suppose the question is:</p><blockquote><em>“Should an expired token return 401 or 403?”</em></blockquote><p>You can discuss that.</p><p>Suppose the question is:</p><blockquote><em>“Should this checkout experience be one long page or a three-step flow?”</em></blockquote><p>You may respond:</p><blockquote><em>“I don’t know. I need to see both.”</em></blockquote><p>More conversation may not help.</p><p>You have reached the limit of grilling.</p><p>That is where <strong>prototyping</strong> begins.</p><h3>3. Prototyping</h3><h3>What is prototyping?</h3><p><strong>Prototyping means building a fast, incomplete version of something so you can learn from interacting with the artifact instead of continuing to reason only in words.</strong></p><p>The prototype is not primarily there to ship.</p><p>It is there to answer a question.</p><p>For example:</p><pre>QUESTION</pre><pre>Should onboarding be:<br>A. one page<br>B. three steps?</pre><p>Instead of another 30-minute discussion:</p><pre>Agent builds A<br>+<br>Agent builds B<br>      ↓<br>You try both<br>      ↓<br>&quot;Three steps feels much clearer.&quot;</pre><p>One design decision just became obvious.</p><h3>Prototyping is not only for UI</h3><p>UI is the easiest example because you can see it.</p><p>But developers prototype technical interfaces too.</p><p>Suppose you are designing an SDK.</p><p>Option A:</p><pre>client.users.create(...)</pre><p>Option B:</p><pre>with client.user() as user:<br>    user.create(...)</pre><p>You can debate which API is cleaner.</p><p>Or you can write ten lines of realistic calling code for both.</p><p>Suddenly:</p><pre>Which one is easier to use?<br>Which one makes errors obvious?<br>Which one scales to future methods?</pre><p>becomes much easier to judge.</p><p>That is a prototype too.</p><h3>Why AI changes the economics of prototyping</h3><p>Historically, teams sometimes avoided prototypes because even a disposable version could take hours or days.</p><p>AI agents can make rough implementations much cheaper.</p><p>Current tools such as Figma’s AI prototyping workflows explicitly support turning natural-language ideas into interactive flows that can then be refined through feedback.</p><p>That changes the calculation.</p><p>Instead of:</p><blockquote><em>“We should discuss this for another hour.”</em></blockquote><p>you can often say:</p><blockquote><em>“Build both versions. I’ll react to them.”</em></blockquote><p>The prototype becomes part of the conversation.</p><h3>Grilling vs Prototyping</h3><p>The distinction is simple:</p><h3>Grilling</h3><p>Use when:</p><blockquote><strong><em>I can answer the question if you ask me clearly.</em></strong></blockquote><p>Example:</p><pre>Should cancellation be allowed after shipment?</pre><h3>Prototyping</h3><p>Use when:</p><blockquote><strong><em>I cannot answer confidently until I see or use something.</em></strong></blockquote><p>Example:</p><pre>Should the dashboard use tabs or a single scrolling page?</pre><p>So:</p><pre>CAN RESOLVE WITH WORDS?<br>        │<br>       YES<br>        ↓<br>     GRILLING<br><br>        │ NO<br>        ▼<br>   <br>   PROTOTYPING</pre><p>Both are human-in-the-loop techniques.</p><p>The human provides judgment.</p><p>The agent helps expose the decision.</p><h3>The Full Workflow</h3><p>The strongest sequence is often:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*bzqZoU5YD40DBeE77KIQyw.png" /></figure><p>Notice the order.</p><p>The spec comes <strong>after enough understanding exists to make the document trustworthy</strong>.</p><p>Not before.</p><h3>The Three Definitions Worth Remembering</h3><h3>Design Concept</h3><p><strong>The shared mental understanding of what is being built, how it should behave, and why.</strong></p><p>Specs, prototypes, conversations, and code express that understanding, but none is automatically identical to it.</p><h3>Grilling</h3><p><strong>A structured human-in-the-loop interview used to expose unresolved decisions before the agent silently turns assumptions into requirements.</strong></p><p>Use it when questions can be resolved through conversation.</p><h3>Prototyping</h3><p><strong>Building a quick artifact to resolve decisions that are difficult to make through words alone.</strong></p><p>Use it when your honest answer is:</p><blockquote><em>“I need to see it.”</em></blockquote><h3>The Practical Lesson</h3><p>When the agent repeatedly produces something that is technically correct but still feels wrong, do not immediately improve the prompt or rewrite the code.</p><p>Ask a more fundamental question:</p><blockquote><strong><em>Do we actually agree on what we are building yet?</em></strong></blockquote><p>If not:</p><pre>ASK<br>when conversation can resolve it</pre><pre>BUILD<br>when experience is needed to resolve it</pre><pre>WRITE THE SPEC<br>once the decisions are stable enough to preserve</pre><p>The cheapest place to discover a bad product decision is usually <strong>before it becomes production code</strong>.</p><p>If this article helped clarify why good AI coding often starts before the coding itself, <strong>react to it and share your thoughts in the comments</strong>.</p><p><strong>Follow me here on LinkedIn</strong> for the next article in the <em>AI Coding Dictionary in Detail</em> series.</p><p>You can also connect with me here:</p><p><a href="https://www.linkedin.com/in/nitesh-kr-jha-/">linkedin.com/in/nitesh-kr-jha-/</a></p><p>Thanks for reading. 🚀</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d81966722596" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI Coding Dictionary in Detail: Automated Checks, Automated Review, Human Review & Vibe Coding]]></title>
            <link>https://medium.com/@niteshkrjhag/ai-coding-dictionary-in-detail-automated-checks-automated-review-human-review-vibe-coding-bb8c5e875519?source=rss-9dbcdadc41e4------2</link>
            <guid isPermaLink="false">https://medium.com/p/bb8c5e875519</guid>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[automated-checks]]></category>
            <category><![CDATA[ai-engineer]]></category>
            <category><![CDATA[machine-learning]]></category>
            <dc:creator><![CDATA[Niteshkrjhag]]></dc:creator>
            <pubDate>Sun, 13 Sep 2026 14:33:48 GMT</pubDate>
            <atom:updated>2026-09-13T14:33:48.796Z</atom:updated>
            <content:encoded><![CDATA[<p>An AI coding agent finishes a task and tells you:</p><blockquote><em>“Done. Everything looks good.”</em></blockquote><p>Should you trust that?</p><p>Not yet.</p><p>There are several different ways we can verify agent-generated code:</p><p><strong>Automated Check → Automated Review → Human Review</strong></p><p>And there is another workflow where we deliberately remove one of those layers:</p><p><strong>Vibe Coding</strong></p><p>The easiest mental model is:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lmxL-wlPeuJJoPSkvdyfJw.png" /></figure><p>Each layer catches a different kind of mistake.</p><h3>1. Automated Check</h3><h3>What is an automated check?</h3><p>An <strong>automated check is a rule-based verification that can run without someone forming a judgment each time.</strong></p><p>Common examples are:</p><pre>Unit tests<br>Integration tests<br>Type checking<br>Linting<br>Build<br>Formatting checks<br>Pre-commit validation<br>Schema validation</pre><p>Suppose an agent changes:</p><pre>def calculate_total(price: int) -&gt; int:<br>    return str(price)</pre><p>A type checker may return:</p><pre>error:<br>Expected int, got str</pre><p>The agent now has useful feedback without asking you anything.</p><h3>Why are checks so useful for agents?</h3><p>Because they create a self-correction loop:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Eo5h-kKneorcgFvx9jWAOQ.png" /></figure><p>No human needed.</p><p>This becomes particularly valuable during AFK work.</p><p>If the agent is running unattended, good checks can catch obvious mistakes before you ever see the finished diff.</p><h3>Why do we call them deterministic?</h3><p>Because the <strong>verification rule itself should ideally give the same verdict for the same relevant state</strong>.</p><p>For example:</p><pre>Does this code type-check?<br>Does this assertion pass?<br>Does this file satisfy the linter?</pre><p>But real-world checks can still be flaky.</p><p>A test depending on:</p><pre>network timing<br>current time<br>randomness<br>shared database state<br>race conditions<br>external APIs</pre><p>might pass once and fail later without the code changing.</p><p>That does not turn it into an automated review.</p><p>It means you have a <strong>bad or unstable automated check</strong>.</p><h3>Green does not mean correct</h3><p>This is the limitation to remember.</p><p>Suppose your tests verify:</p><pre>✓ User can log in<br>✓ Wrong password is rejected</pre><p>But they never verify:</p><pre>Refresh token is not written to logs</pre><p>The whole suite can be green while your application leaks credentials.</p><p>So:</p><pre>CHECK PASSED</pre><p>means:</p><blockquote><strong><em>The properties that were actually checked passed.</em></strong></blockquote><p>It does not mean:</p><blockquote><strong><em>The entire implementation is correct.</em></strong></blockquote><p>That gap leads us to review.</p><h3>2. Automated Review</h3><p>Suppose all tests pass, but the agent changed this:</p><pre>def get_user():<br>    ...</pre><p>to:</p><pre>def get_stuff():<br>    ...</pre><p>The code works.</p><p>Tests pass.</p><p>Types pass.</p><p>But get_stuff() is a terrible name.</p><p>Or imagine the implementation duplicates authentication logic in two services.</p><p>Nothing necessarily fails mechanically.</p><p>Someone — or something — has to <strong>judge the design</strong>.</p><h3>What is automated review?</h3><p><strong>Automated review is when another model or agent examines work and forms a judgment about potential problems.</strong></p><p>For example:</p><pre>WORKING AGENT<br>creates diff<br>      ↓<br>REVIEW AGENT<br>reads diff + relevant code<br>      ↓<br>&quot;Possible issue:<br>this change bypasses the existing retry policy.&quot;</pre><p>Unlike:</p><pre>pytest</pre><p>there may not be one mathematically fixed correct output.</p><p>Another run might notice a different issue.</p><p>That is why automated review is different from an automated check.</p><p>OpenAI has documented real deployments where AI reviewers examine PRs for broader problems such as cross-module interactions, missing coverage, and API-contract risks that ordinary rule-based checks may not catch.</p><h3>Check vs review</h3><p>The simplest distinction is:</p><pre>AUTOMATED CHECK</pre><pre>&quot;Does this violate a rule<br>I already know how to test?&quot;</pre><p>versus:</p><pre>AUTOMATED REVIEW</pre><pre>&quot;Looking at this change,<br>what might be wrong?&quot;</pre><p>Examples:</p><pre>Type error<br>→ automated check</pre><pre>Unit-test failure<br>→ automated check</pre><pre>Misleading abstraction<br>→ review</pre><pre>Suspicious security decision<br>→ review</pre><pre>Unexpected API compatibility risk<br>→ review</pre><h3>Why use a separate reviewer?</h3><p>Suppose the working agent spent an hour deciding:</p><blockquote><em>“Approach A is correct.”</em></blockquote><p>Its session now contains all of the reasoning supporting Approach A.</p><p>Then you ask the same agent:</p><blockquote><em>“Review your implementation.”</em></blockquote><p>It may simply reinforce its previous reasoning.</p><p>A cleaner setup is:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*wDiXzcosRAM6blW2MuLZgw.png" /></figure><pre>AGENT A<br>writes implementation<br>      ↓<br>fresh context<br>      ↓<br>AGENT B<br>reviews implementation</pre><p>The reviewer does not need to be a different model, but separation can help.</p><p>You can also give the reviewer a narrow role:</p><pre>Review only for:<br>- security<br>- API compatibility<br>- concurrency</pre><p>That tends to be more useful than:</p><blockquote><em>“Tell me if this code is good.”</em></blockquote><h3>Automated review is still not ground truth</h3><p>An LLM reviewer can:</p><pre>miss real bugs<br>flag harmless code<br>misunderstand intent<br>invent a concern</pre><p>So automated review should usually be treated as another layer of evidence.</p><p>Not:</p><pre>AI REVIEW SAID APPROVED<br>        ↓<br>AUTO-MERGE EVERYTHING</pre><p>For high-stakes software, machine review works best as a filter that raises the quality floor before human judgment. OpenAI’s engineering guidance similarly describes AI review as complementary while engineers retain responsibility for what ultimately ships.</p><h3>3. Human Review</h3><p>Now the pull request reaches you.</p><p>The agent provides this summary:</p><blockquote><em>“Fixed authentication, removed dead code, and added tests.”</em></blockquote><p>Have you reviewed the change?</p><p>No.</p><p>You have reviewed <strong>the agent’s description of the change</strong>.</p><h3>What is human review?</h3><p><strong>Human review means a person examines the actual artifact and forms a judgment about whether the change should be accepted.</strong></p><p>For code, that usually means looking at:</p><pre>git diff<br>changed files<br>tests<br>important runtime behavior<br>architecture implications</pre><p>The agent’s summary is useful for orientation.</p><p>But remember our earlier terminology:</p><pre>AGENT SUMMARY<br>= secondary source</pre><pre>ACTUAL DIFF<br>= primary evidence for what changed</pre><p>If the summary says:</p><blockquote><em>“Removed unused function.”</em></blockquote><p>but the diff shows:</p><pre>- def refresh_legacy_token(...):<br>-     ...</pre><p>you may recognize:</p><blockquote><em>“That isn’t unused. Our generated client still calls it.”</em></blockquote><p>You only catch that by looking at the artifact.</p><h3>What is the human actually adding?</h3><p>Checks are good at rules.</p><p>Automated reviewers are good at scalable judgment.</p><p>Humans are especially valuable for questions such as:</p><blockquote><em>“Is this the change we actually wanted?”</em></blockquote><p>For example:</p><pre>Should this feature exist?</pre><pre>Does this architecture match our direction?</pre><pre>Is this migration risk acceptable?</pre><pre>Will another team depend on this behavior?</pre><pre>Is this implementation understandable six months from now?</pre><p>Those decisions depend on organizational and product context that may not be completely represented in the repository.</p><p>As agent-generated code volume grows, this human judgment can become the bottleneck — which is precisely why the earlier verification layers matter.</p><p>The ideal is not:</p><pre>Human manually catches everything.</pre><p>It is:</p><pre>Checks catch mechanical failures<br>        ↓<br>Automated review catches another class of risk<br>        ↓<br>Human spends attention on high-value judgment</pre><h3>4. Vibe Coding</h3><p>Now imagine removing the last step.</p><p>The agent generates a large diff.</p><p>You do not read it.</p><p>You run the application.</p><p>It appears to work.</p><p>You say:</p><blockquote><em>“Great. Ship it.”</em></blockquote><p>That gets us to <strong>vibe coding</strong>.</p><h3>What is vibe coding?</h3><p>The term was coined by Andrej Karpathy in February 2025 for a workflow where you increasingly interact with software through natural-language instructions and observed behaviour while largely giving up on understanding the generated code itself. Contemporary descriptions of the original usage emphasize not reading the generated diffs and judging the system mainly by whether it appears to work.</p><p>For this series, the useful definition is:</p><blockquote><strong><em>Vibe coding is a working style where AI-generated code is treated largely as an opaque implementation and the user relies primarily on observed behavior rather than understanding and reviewing the code itself.</em></strong></blockquote><h3>Vibe coding is not the same as AI-assisted coding</h3><p>This distinction matters.</p><p>Suppose an agent writes 95% of your code, but you:</p><pre>read the diff<br>understand the architecture<br>run tests<br>review security implications<br>verify important behavior</pre><p>That is heavily AI-assisted engineering.</p><p>But it is not what the original phrase <strong>vibe coding</strong> was trying to describe.</p><p>The important variable is not:</p><pre>Who typed the code?</pre><p>It is:</p><pre>Did anyone understand and review<br>what was generated?</pre><h3>Can vibe coding still have automated checks?</h3><p>Yes.</p><p>You could do:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hDZ3L7b6tGYcz6TL17edGg.png" /></figure><p>That can still fit the vibe-coding idea.</p><p>Automated verification and human understanding are different things.</p><h3>When can that trade-off make sense?</h3><p>Imagine building:</p><pre>throwaway weekend prototype<br>one-off data conversion script<br>temporary internal demo<br>personal experiment</pre><p>If failure costs almost nothing, spending an hour reviewing every generated line may be unnecessary.</p><p>Now consider:</p><pre>authentication<br>payments<br>production migrations<br>healthcare records<br>customer permissions<br>security-sensitive infrastructure</pre><p>The trade changes dramatically.</p><p>The question becomes:</p><blockquote><strong><em>What happens if behavior looks correct while the implementation contains something I cannot see from the UI?</em></strong></blockquote><p>Examples include:</p><pre>secret logged silently<br>incorrect error handling<br>missing authorization edge case<br>data corruption on rare input<br>dependency with unexpected behavior</pre><p>Karpathy’s original framing itself described vibe coding as something suited to casual or throwaway work rather than a general replacement for careful engineering.</p><h3>Putting All Four Together</h3><p>The hierarchy is:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*OMD5ScsHputJycjvu8JDyA.png" /></figure><p>So the four concepts solve different problems:</p><pre>AUTOMATED CHECK<br>= mechanical verification</pre><pre>AUTOMATED REVIEW<br>= machine judgment</pre><pre>HUMAN REVIEW<br>= human judgment</pre><pre>VIBE CODING<br>= intentionally reducing or skipping<br>deep human inspection of the generated code</pre><h3>The Four Definitions Worth Remembering</h3><h3>Automated Check</h3><p><strong>A repeatable rule-based verification such as tests, type checks, linting, or builds that produces actionable pass/fail feedback.</strong></p><h3>Automated Review</h3><p><strong>A machine-generated judgment about code quality, risk, architecture, correctness, or other concerns that cannot be completely expressed as deterministic rules.</strong></p><h3>Human Review</h3><p><strong>A person examining the actual change and deciding whether it is correct, appropriate, and safe to accept.</strong></p><p>Reading only the agent’s summary is not equivalent to reviewing the implementation.</p><h3>Vibe Coding</h3><p><strong>A workflow where generated code is largely treated as opaque and success is judged mainly through observed behavior instead of understanding and reviewing the implementation.</strong></p><p>It describes a <strong>review/understanding stance</strong>, not simply “AI wrote the code.”</p><h3>The Practical Lesson</h3><p>The stronger your verification stack becomes:</p><pre>AGENT<br>  ↓<br>CHECK<br>  ↓<br>MACHINE REVIEW<br>  ↓<br>HUMAN REVIEW</pre><p>the more code agents can produce without making the human responsible for catching every mechanical mistake manually.</p><p>But the layers are not interchangeable.</p><blockquote><strong><em>Tests can prove only what they test. Automated reviewers can make mistakes. Humans have limited attention.</em></strong></blockquote><p>The engineering skill is deciding which layers a particular change deserves.</p><p>And if you deliberately remove human understanding from the loop, give that choice its proper name:</p><p><strong>vibe coding.</strong></p><p>If this article helped clarify the difference between <strong>checking</strong>, <strong>reviewing</strong>, and simply trusting generated code because it works, <strong>react to it and share your thoughts in the comments</strong>.</p><p><strong>Follow me here on LinkedIn</strong> for the next article in the <em>AI Coding Dictionary in Detail</em> series.</p><p>You can also connect with me here:</p><p><a href="https://www.linkedin.com/in/nitesh-kr-jha-/">linkedin.com/in/nitesh-kr-jha-/</a></p><p>Thanks for reading. 🚀</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=bb8c5e875519" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI Coding Dictionary in Detail: Human-in-the-Loop & AFK(Away from Keyboard)]]></title>
            <link>https://medium.com/@niteshkrjhag/ai-coding-dictionary-in-detail-human-in-the-loop-afk-away-from-keyboard-018f1802a0d0?source=rss-9dbcdadc41e4------2</link>
            <guid isPermaLink="false">https://medium.com/p/018f1802a0d0</guid>
            <category><![CDATA[away-from-keyword]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[human-in-the-loop]]></category>
            <category><![CDATA[machine-learning]]></category>
            <dc:creator><![CDATA[Niteshkrjhag]]></dc:creator>
            <pubDate>Sun, 13 Sep 2026 14:33:04 GMT</pubDate>
            <atom:updated>2026-09-13T14:33:04.147Z</atom:updated>
            <content:encoded><![CDATA[<p>You give an AI coding agent this task:</p><blockquote><em>“Refactor the authentication module.”</em></blockquote><p>There are two very different ways you can work with it.</p><h3>Option A</h3><p>You stay.</p><p>You watch what it reads, question its assumptions, redirect it when necessary, and review important decisions as they happen.</p><h3>Option B</h3><p>You give it the task, walk away, and inspect the finished result later.</p><p>These two patterns are:</p><p><strong>Human-in-the-Loop → AFK</strong></p><p>Neither is automatically better.</p><p>The right choice depends on one question:</p><blockquote><strong><em>How expensive would a wrong decision be before I notice it?</em></strong></blockquote><h3>1. Human-in-the-Loop</h3><h3>What does human-in-the-loop mean?</h3><p><strong>Human-in-the-loop means a human actively participates while the agent is working — reviewing, correcting, answering questions, or steering decisions before the task is finished.</strong></p><p>For example:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gGecTfso_aAH9iHIlExDww.png" /></figure><p>That one correction may save 30 minutes of work built on the wrong assumption.</p><h3>This is broader than permission approval</h3><p>Human-in-the-loop does <strong>not</strong> simply mean:</p><pre>Agent asks:<br>&quot;Can I run this command?&quot;</pre><pre>You click:<br>Approve</pre><p>That is a <strong>permission request</strong>.</p><p>Human-in-the-loop is the broader working pattern.</p><p>You may intervene because:</p><ul><li>the requirement was misunderstood,</li><li>the wrong architecture is being chosen,</li><li>an assumption needs clarification,</li><li>you dislike the direction of a prototype,</li><li>the consequences are difficult to reverse.</li></ul><p>Think of it as <strong>pair programming with an agent</strong>.</p><h3>When should you stay in the loop?</h3><p>Suppose the task is:</p><blockquote><em>“Rename this variable across five files.”</em></blockquote><p>The risk is low.</p><p>But consider:</p><blockquote><em>“Design the new database schema and migrate production data.”</em></blockquote><p>Now an early mistake could affect everything that follows.</p><p>Human-in-the-loop makes more sense when work is:</p><pre>Ambiguous<br>High-risk<br>Hard to reverse<br>Architectural<br>Difficult to verify afterwards</pre><p>The principle is:</p><blockquote><strong><em>The more expensive a wrong turn is, the more valuable early human steering becomes.</em></strong></blockquote><h3>2. AFK</h3><p><strong>AFK means Away From Keyboard.</strong></p><p>In AI coding, it describes a working pattern where:</p><blockquote><strong><em>You give the agent a task and allow it to continue without actively supervising every step.</em></strong></blockquote><p>For example:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*u_e5wFi9Llt0WZ1R75RsLQ.png" /></figure><p>The advantage is obvious:</p><p><strong>your attention is no longer required during execution.</strong></p><p>You can do something else — or run several independent tasks at once.</p><h3>The danger of AFK work</h3><p>Suppose the instruction is:</p><blockquote><em>“Migrate all legacy customer IDs.”</em></blockquote><p>Ten minutes into the unattended run, the agent incorrectly assumes:</p><pre>legacy_customer_id<br>can be deleted immediately</pre><p>Then it spends the next hour consistently implementing that assumption.</p><p>You return to a large, polished change.</p><p>The work may be internally coherent.</p><p>It is just coherent around the <strong>wrong decision</strong>.</p><p>That is the characteristic AFK risk:</p><pre>Small wrong assumption<br>        ↓<br>no human correction<br>        ↓<br>many dependent decisions<br>        ↓<br>large wrong result</pre><h3>What makes a task suitable for AFK?</h3><p>Good AFK work tends to be:</p><pre>Well specified<br>Low risk<br>Reversible<br>Easy to test automatically<br>Easy to review afterwards</pre><p>Examples:</p><ul><li>mechanical refactors,</li><li>updating repetitive tests,</li><li>formatting or lint fixes,</li><li>implementing a clearly specified ticket inside a sandbox.</li></ul><p>Before leaving, reduce ambiguity:</p><pre>SPEC / TICKET<br>      ↓<br>clear acceptance criteria<br>      ↓<br>safe environment<br>      ↓<br>automated tests<br>      ↓<br>AFK RUN<br>      ↓<br>human review</pre><p>AFK does <strong>not</strong> mean removing humans entirely.</p><p>It means moving human attention from:</p><blockquote><strong><em>continuous supervision</em></strong></blockquote><p>to:</p><blockquote><strong><em>good instructions before + review after.</em></strong></blockquote><h3>Human-in-the-Loop vs AFK</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*3y50tTBctmmtwRNuJekDAw.png" /></figure><p>The relationship is simple:</p><pre>HIGH UNCERTAINTY / HIGH RISK<br>            ↓<br>    HUMAN-IN-THE-LOOP</pre><pre>LOW UNCERTAINTY / EASY VERIFICATION<br>            ↓<br>           AFK</pre><h3>The Two Definitions Worth Remembering</h3><h3>Human-in-the-Loop</h3><p><strong>A working pattern where a human actively collaborates with and steers the agent while the task is still in progress.</strong></p><h3>AFK</h3><p><strong>An unattended working pattern where the agent executes a sufficiently well-defined task while the human steps away and reviews the result later.</strong></p><p>The practical rule is:</p><blockquote><strong><em>Stay in the loop when a wrong decision needs to be caught early. Go AFK when the task is clear enough that tests, constraints, and final review can safely catch mistakes later.</em></strong></blockquote><p>If this article helped clarify when to supervise an AI coding agent and when to let it work independently, <strong>react to it and share your thoughts in the comments</strong>.</p><p><strong>Follow me here on LinkedIn</strong> for the next article in the <em>AI Coding Dictionary in Detail</em> series.</p><p>You can also connect with me here:</p><p><a href="https://www.linkedin.com/in/nitesh-kr-jha-/">linkedin.com/in/nitesh-kr-jha-/</a></p><p>Thanks for reading. 🚀</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=018f1802a0d0" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI Coding Dictionary in Detail: Context Pointers, Skills & Subagents]]></title>
            <link>https://medium.com/@niteshkrjhag/ai-coding-dictionary-in-detail-context-pointers-skills-subagents-46381ce2382f?source=rss-9dbcdadc41e4------2</link>
            <guid isPermaLink="false">https://medium.com/p/46381ce2382f</guid>
            <category><![CDATA[begineers]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[machine-learning]]></category>
            <dc:creator><![CDATA[Niteshkrjhag]]></dc:creator>
            <pubDate>Sat, 12 Sep 2026 06:35:41 GMT</pubDate>
            <atom:updated>2026-09-12T06:35:41.700Z</atom:updated>
            <content:encoded><![CDATA[<p>Suppose your coding agent has access to:</p><ul><li>a 5,000-line deployment guide,</li><li>a database migration handbook,</li><li>frontend conventions,</li><li>security rules,</li><li>testing instructions,</li><li>and dozens of reusable workflows.</li></ul><p>Should all of that be loaded into the context window before you even ask:</p><blockquote><em>“Fix this failing unit test”?</em></blockquote><p>Probably not.</p><p>A better system gives the agent <strong>small clues about what information exists</strong>, then lets it load the detailed material only when the task requires it.</p><p>That connects three concepts:</p><p><strong>Context Pointer → Skill → Subagent</strong></p><p>They solve different problems:</p><pre>CONTEXT POINTER<br>= where can I find more information?</pre><pre>SKILL<br>= how should I perform this kind of task?</pre><pre>SUBAGENT<br>= can another isolated agent handle this subtask?</pre><h3>1. Context Pointer</h3><h3>What is a context pointer?</h3><p>For this series, a <strong>context pointer is a small piece of information that tells the agent where more detailed context can be found if it becomes relevant.</strong></p><p>Imagine AGENTS.md contains:</p><pre>For deployment or rollback work:<br>read docs/deployment/runbook.md</pre><p>That one line is small.</p><p>The actual file might contain:</p><pre>4,000 tokens</pre><p>of deployment instructions.</p><p>A normal bug-fixing session does not need those 4,000 tokens.</p><p>But a deployment task does.</p><p>So instead of:</p><pre>EVERY SESSION</pre><pre>AGENTS.md<br>+<br>4K deployment guide<br>+<br>6K database guide<br>+<br>5K frontend guide<br>+<br>...</pre><p>we keep:</p><pre>AGENTS.md</pre><pre>Deployment → docs/deployment/runbook.md<br>Database migrations → docs/database/migrations.md<br>Frontend → docs/frontend/style.md</pre><p>Then:</p><pre>Task:<br>&quot;Deploy version 3.2&quot;<br>      ↓<br>Agent notices deployment pointer<br>      ↓<br>read docs/deployment/runbook.md<br>      ↓<br>Detailed instructions enter context</pre><p>That is <strong>progressive disclosure</strong> built from pointers.</p><h3>A good pointer needs more than a filename</h3><p>This:</p><pre>docs/deployment/runbook.md</pre><p>is technically a path.</p><p>But why should the agent read it?</p><p>A better pointer says:</p><pre>For releases, deployments, or rollbacks,<br>read docs/deployment/runbook.md before acting.</pre><p>Now it contains two things:</p><pre>WHEN TO FOLLOW IT<br>        +<br>WHERE IT LEADS</pre><p>That makes it much more useful.</p><h3>Pointers also connect summaries back to evidence</h3><p>Remember our previous distinction:</p><pre>PRIMARY SOURCE<br>= original evidence</pre><pre>SECONDARY SOURCE<br>= summary or interpretation</pre><p>Imagine a handoff says:</p><pre>Auth migration is complete.</pre><pre>Evidence:<br>tests/auth/test_refresh.py<br>src/auth/token_service.py</pre><p>The handoff is a secondary source.</p><p>Those file paths act as pointers back to stronger evidence.</p><p>So if the next agent doubts the summary:</p><pre>HANDOFF<br>   ↓<br>pointer<br>   ↓<br>actual test / source file<br>   ↓<br>verify</pre><p>This makes summaries much safer.</p><h3>2. Skill</h3><p>A context pointer tells the agent:</p><blockquote><em>“There is useful information over there.”</em></blockquote><p>A <strong>skill</strong> goes further.</p><p>It packages a repeatable way of doing a particular kind of work.</p><h3>What is a skill?</h3><p>An <strong>Agent Skill is a reusable package of instructions and supporting resources that teaches a compatible agent how to perform a specific workflow.</strong></p><p>The Agent Skills specification defines a skill as a directory containing at least:</p><pre>my-skill/<br>│<br>└── SKILL.md</pre><p>and optionally:</p><pre>scripts/<br>references/<br>assets/</pre><p>SKILL.md contains required metadata such as a name and description, followed by the actual workflow instructions.</p><p>For example:</p><pre>database-migration/<br>│<br>├── SKILL.md<br>├── scripts/<br>│   └── validate_migration.py<br>├── references/<br>│   └── migration-rules.md<br>└── assets/<br>    └── migration-template.sql</pre><h3>What could SKILL.md contain?</h3><p>A simplified example:</p><pre>---<br>name: database-migration<br>description: Use when creating or reviewing database migrations.<br>---</pre><pre>1. Read the current schema.<br>2. Never modify an applied migration.<br>3. Create a new migration file.<br>4. Run migration validation.<br>5. Run database tests.<br>6. Report backward-compatibility risks.</pre><p>Now every agent does not have to rediscover your migration process from scratch.</p><p>The workflow is written down once.</p><h3>Why is a skill different from AGENTS.md?</h3><p>AGENTS.md might say:</p><pre>For database migrations, use the database-migration skill.</pre><p>That small instruction can be available broadly.</p><p>But the detailed workflow stays outside the active context until it becomes relevant.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TkfGHX37vRBXqR6I5IQ9UA.png" /></figure><p>Conceptually:</p><pre>AGENTS.md<br>   ↓<br>small pointer<br>   ↓<br>database-migration skill<br>   ↓<br>full migration workflow</pre><p>This is much better than putting the entire migration handbook into every session.</p><h3>Skills use progressive disclosure</h3><p>This is one of the strongest connections with our previous article.</p><p>The Agent Skills specification describes three levels:</p><pre>1. DISCOVERY<br>Name + description</pre><pre>     ↓ when relevant</pre><pre>2. ACTIVATION<br>Full SKILL.md instructions</pre><pre>     ↓ when required</pre><pre>3. RESOURCES<br>Scripts / references / assets</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ZAvANu_kvtEACOnp8PaKRQ.png" /></figure><p>So a compatible agent can know:</p><blockquote><em>“A database migration skill exists.”</em></blockquote><p>without loading every line of that skill immediately.</p><p>Example:</p><pre>SESSION START</pre><pre>database-migration<br>&quot;Use for database migration work.&quot;</pre><pre>pdf-processing<br>&quot;Use for PDF tasks.&quot;</pre><pre>frontend-review<br>&quot;Use for UI review.&quot;</pre><p>Then you ask:</p><blockquote><em>“Add an index to </em><em>company_id.”</em></blockquote><p>The agent activates:</p><pre>database-migration</pre><p>and ignores:</p><pre>pdf-processing<br>frontend-review</pre><p>That is progressive disclosure in practice.</p><h3>Are Skills a portable standard?</h3><p>Yes — but say this carefully.</p><p>Agent Skills is an open format originally developed by Anthropic, and compatible clients can implement the same SKILL.md structure. The official Agent Skills documentation lists Claude Code, OpenAI Codex, and compatible environments as examples; OpenAI also states that its Skills follow the Agent Skills open standard.</p><p>But this does <strong>not</strong> mean:</p><blockquote><em>“Every AI harness automatically supports every skill identically.”</em></blockquote><p>Tool access, filesystem layout, permissions, and optional fields can still vary between implementations.</p><p>Think:</p><blockquote><strong><em>portable format, product-specific runtime.</em></strong></blockquote><h3>Skill vs Tool</h3><p>This distinction is important.</p><p>A <strong>tool</strong> gives the agent an ability:</p><pre>run_shell()<br>read_file()<br>query_database()</pre><p>A <strong>skill</strong> teaches the agent how to use capabilities to complete a workflow:</p><pre>How to perform our database migration safely</pre><p>So:</p><pre>TOOL<br>= capability the agent CALLS</pre><pre>SKILL<br>= instructions the agent READS and follows</pre><p>A skill may tell the agent to use several tools.</p><h3>3. Subagent</h3><p>Now imagine the problem is not detailed instructions.</p><p>The problem is <strong>too much noisy work</strong>.</p><p>Suppose your main agent needs to find every place authentication is implemented across a large repository.</p><p>It could perform:</p><pre>grep<br>read file<br>read file<br>search<br>read another file<br>inspect tests<br>read logs<br>...</pre><p>inside the main session.</p><p>But then all that exploration can pollute the main context.</p><p>Instead, the main agent can delegate the research.</p><h3>What is a subagent?</h3><p>A <strong>subagent is a separate agent instance delegated a specific subtask, usually with its own context, instructions, and tool access, whose result is returned to the parent workflow.</strong></p><p>Conceptually:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5uY5D1OjVZKVNPD78cpPrA.png" /></figure><p>The parent does not necessarily need all 15 file contents.</p><p>Maybe it only needs:</p><pre>Authentication is implemented in:</pre><pre>1. src/auth/service.py<br>2. src/auth/tokens.py<br>3. middleware/auth.py</pre><pre>Main issue:<br>token validation is duplicated in #1 and #3.</pre><p>Claude Code, for example, explicitly describes subagents as delegated workers that operate in their own context and return a summary to the main conversation.</p><h3>Why are subagents useful for context?</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fLCkLmN1Pvjz-TAaJ7yFUg.png" /></figure><p>The noisy exploration happens in a disposable context.</p><p>The useful conclusion returns.</p><p>Claude Code’s documentation explicitly recommends subagents for high-volume searches, test output, documentation fetching, and similar work because only the relevant summary needs to return to the main conversation.</p><h3>But the report is a secondary source</h3><p>There is a trade-off.</p><p>Suppose the subagent reads 20 files and reports:</p><blockquote><em>“The retry logic is exponential.”</em></blockquote><p>The parent agent did not necessarily inspect the implementation itself.</p><p>It received the <strong>subagent’s interpretation</strong>.</p><p>So:</p><pre>SUBAGENT RAW WORK<br>       ↓<br>SUMMARY<br>       ↓<br>PARENT AGENT</pre><p>The summary is a secondary source.</p><p>If the exact behavior matters, the parent should follow a pointer back to:</p><pre>src/retry.py</pre><p>and inspect the primary source.</p><h3>Subagent vs Handoff</h3><p>These can look similar because both move work between agents or sessions.</p><p>But the relationship is different.</p><h3>Handoff</h3><pre>Agent A<br>   ↓<br>passes work onward<br>   ↓<br>Agent B continues</pre><p>There may be no expectation that Agent B reports back to Agent A.</p><h3>Subagent</h3><pre>Parent Agent<br>    ↓<br>delegates subtask<br>    ↓<br>Subagent<br>    ↓<br>returns result<br>    ↓<br>Parent Agent continues</pre><p>So:</p><pre>HANDOFF<br>= transfer</pre><pre>SUBAGENT<br>= delegation + return path</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*582VT2wWaCqnMDfUtzTLrg.png" /></figure><h3>Can subagents spawn more subagents?</h3><p>Do not make this a universal rule.</p><p>Some harnesses prohibit nested subagents.</p><p>Claude Code currently does: its documentation explicitly says Claude Code subagents cannot spawn other subagents, partly to prevent recursive nesting.</p><p>But that is a <strong>Claude Code runtime rule</strong>, not the definition of a subagent across all agent architectures.</p><p>Other systems may support deeper delegation graphs.</p><p>So the durable definition should not include:</p><blockquote><em>“A subagent can never spawn another subagent.”</em></blockquote><p>Instead:</p><blockquote><strong><em>Delegation depth is controlled by the harness.</em></strong></blockquote><h3>How the Three Concepts Connect</h3><p>The hierarchy is:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*lMmcpXC36iXlebAxMLZM8A.png" /></figure><p>They all help control context, but in different ways:</p><pre>CONTEXT POINTER<br>= don&#39;t load the detail yet</pre><pre>SKILL<br>= don&#39;t load the workflow until needed</pre><pre>SUBAGENT<br>= don&#39;t put the noisy subtask in the parent context</pre><h3>The Three Definitions Worth Remembering</h3><h3>Context Pointer</h3><p><strong>A small reference that tells an agent where relevant information can be retrieved when the task requires it.</strong></p><p>A strong pointer says both <strong>where to look</strong> and <strong>when to look there</strong>.</p><h3>Skill</h3><p><strong>A reusable package of instructions and optional resources that teaches a compatible agent how to perform a specific workflow.</strong></p><p>Skills are instructions, not tools.</p><h3>Subagent</h3><p><strong>A delegated agent worker that handles a bounded subtask in separate context and returns useful results to the parent workflow.</strong></p><p>Its purpose can include specialization, parallelism, and context isolation.</p><h3>The Practical Lesson</h3><p>When an AI coding system becomes overloaded with information, you have more options than simply increasing the context window.</p><p>Use:</p><pre>POINTERS<br>to keep detailed information outside context</pre><pre>SKILLS<br>to keep reusable workflows outside context</pre><pre>SUBAGENTS<br>to keep noisy execution outside the parent context</pre><p>The common principle is:</p><blockquote><strong><em>Do not make the main agent carry information it does not need right now.</em></strong></blockquote><p>That is progressive disclosure applied not just to documentation, but to the architecture of the agent itself.</p><p>If this article helped clarify how modern coding agents keep large amounts of knowledge and work outside the main context, <strong>react to it and share your thoughts in the comments</strong>.</p><p><strong>Follow me here on LinkedIn</strong> for the next article in the <em>AI Coding Dictionary in Detail</em> series.</p><p>You can also connect with me here:</p><p><a href="https://www.linkedin.com/in/nitesh-kr-jha-/">linkedin.com/in/nitesh-kr-jha-/</a></p><p>Thanks for reading. 🚀</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=46381ce2382f" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI Coding Dictionary in Detail: Memory Systems, AGENTS.md & Progressive Disclosure]]></title>
            <link>https://medium.com/@niteshkrjhag/ai-coding-dictionary-in-detail-memory-systems-agents-md-progressive-disclosure-68e18af5852b?source=rss-9dbcdadc41e4------2</link>
            <guid isPermaLink="false">https://medium.com/p/68e18af5852b</guid>
            <category><![CDATA[agents]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[ai-coding]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <category><![CDATA[ai-engineer]]></category>
            <dc:creator><![CDATA[Niteshkrjhag]]></dc:creator>
            <pubDate>Sat, 12 Sep 2026 06:34:42 GMT</pubDate>
            <atom:updated>2026-09-12T06:34:42.264Z</atom:updated>
            <content:encoded><![CDATA[<p>You start a new AI coding session and say:</p><blockquote><em>“Remember, this project uses PostgreSQL, not MySQL.”</em></blockquote><p>The agent follows that perfectly.</p><p>Tomorrow you start another session.</p><p>Do you need to explain it again?</p><p>If the answer is <strong>no</strong>, something outside the model preserved that information.</p><p>That gives us three connected concepts:</p><p><strong>Memory System → AGENTS.md → Progressive Disclosure</strong></p><p>The clean hierarchy is:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*TR53mNQP1JKPU0UGg3Gbzw.png" /></figure><h3>1. Memory System</h3><h3>What is a memory system?</h3><p>A <strong>memory system is an external mechanism that stores useful information beyond the current session and makes relevant parts available again later.</strong></p><p>Remember:</p><pre>SESSION 1<br>&quot;Use PostgreSQL, not MySQL.&quot;<br>        ↓<br>session ends</pre><p>The model’s parameters did not change.</p><p>Without anything outside the model:</p><pre>SESSION 2<br>        ↓<br>      MODEL<br>        ↓<br>does not automatically know<br>the previous project correction</pre><p>A memory system creates continuity around that stateless model.</p><h3>How does memory actually work?</h3><p>A useful memory system has two broad paths:</p><pre>WRITE PATH<br>What should survive?</pre><pre>READ PATH<br>What should come back?</pre><p>Suppose during Session 1 you say:</p><blockquote><em>“We use pnpm in this repository. Never run npm install.”</em></blockquote><h3>Write path</h3><p>Something outside the model records:</p><pre>Project package manager: pnpm<br>Do not use npm install.</pre><p>That information might live in:</p><ul><li>a Markdown file,</li><li>a database,</li><li>a key-value store,</li><li>a searchable memory index,</li><li>or provider-managed storage.</li></ul><p>Now Session 1 can disappear.</p><p>The information survives elsewhere.</p><h3>Read path</h3><p>During Session 2:</p><pre>New task<br>    ↓<br>Harness / application<br>    ↓<br>retrieve relevant memory<br>    ↓<br>&quot;Project uses pnpm&quot;<br>    ↓<br>put into current context<br>    ↓<br>MODEL</pre><p>That is what creates the appearance:</p><blockquote><em>“The agent remembered.”</em></blockquote><p>More precisely:</p><blockquote><strong><em>The system stored something earlier and supplied it to the model again.</em></strong></blockquote><h3>Memory does not mean changing parameters</h3><p>This distinction should stay consistent with everything we have learned.</p><pre>TRAINING<br>   ↓<br>changes<br>   ↓<br>PARAMETERS</pre><p>but:</p><pre>MEMORY SYSTEM<br>   ↓<br>stores information externally<br>   ↓<br>retrieves it later<br>   ↓<br>places it into context</pre><p>So:</p><pre>MODEL MEMORY?<br>No permanent parameter update.</pre><pre>APPLICATION MEMORY?<br>Yes — external persistence + retrieval.</pre><p>That is why memory can change immediately without retraining the model.</p><h3>Should every memory load at session start?</h3><p>No.</p><p>Imagine you have accumulated 2,000 memories:</p><pre>Frontend conventions<br>Database conventions<br>Deployment process<br>Customer terminology<br>Testing commands<br>Python style<br>Kubernetes notes<br>Old architecture decisions<br>...</pre><p>Loading all of them into every session would defeat the purpose of good context management.</p><p>A better system may do:</p><pre>New task:<br>&quot;Fix the PostgreSQL migration.&quot;<br>        ↓<br>retrieve only:<br>- database conventions<br>- migration rules<br>- relevant project decisions</pre><p>while ignoring:</p><pre>frontend style guide<br>mobile release process<br>CSS conventions</pre><p>So memory systems often benefit from <strong>retrieval</strong>, not simply “load everything.”</p><h3>Memory can become wrong</h3><p>Suppose a memory saved in March says:</p><pre>Database:<br>MySQL</pre><p>In June the project migrates to:</p><pre>PostgreSQL</pre><p>If nobody updates the memory, every future session may receive stale information.</p><p>That makes memory another <strong>secondary source</strong>.</p><p>It can be:</p><ul><li>outdated,</li><li>incomplete,</li><li>incorrectly summarized,</li><li>irrelevant to the current task.</li></ul><p>So good memory systems need some form of:</p><pre>Review<br>Update<br>Replace<br>Delete</pre><p>Persistent does not mean permanently correct.</p><h3>2. AGENTS.md</h3><p>Now suppose some information should apply to almost every coding session:</p><pre>Use pnpm.</pre><pre>Run pytest before completing backend changes.</pre><pre>Never manually edit generated clients.</pre><pre>API responses use snake_case.</pre><p>You could put those instructions somewhere the coding harness knows to read.</p><p>One increasingly common convention is:</p><p><strong>AGENTS.md</strong></p><h3>What is AGENTS.md?</h3><p><strong>AGENTS.md is a repository instruction file used by supported coding agents to understand how they should work inside a project.</strong></p><p>For Codex, OpenAI explicitly supports repository AGENTS.md files for instructions such as:</p><ul><li>repository navigation,</li><li>testing commands,</li><li>coding conventions,</li><li>project-specific practices.</li></ul><p>A simple file might contain:</p><pre>file_name = AGENTS.md</pre><pre>## Package manager<br>Use pnpm. Never run npm install.</pre><pre>## Backend tests<br>Run:<br>pytest tests/backend</pre><pre>## Generated files<br>Do not manually edit:<br>src/generated/</pre><pre>## API convention<br>Use snake_case response fields.</pre><p>A fresh coding session can receive those instructions without you typing them again.</p><h3>Is AGENTS.md a memory system?</h3><p>Not exactly.</p><p>This distinction matters.</p><pre>MEMORY SYSTEM<br>= mechanism for storing + retrieving information</pre><p>while:</p><pre>AGENTS.md<br>= persistent instruction artifact</pre><p>An AGENTS.md file can <strong>participate in cross-session continuity</strong>, but it does not by itself perform intelligent memory retrieval.</p><p>Think:</p><pre>MEMORY SYSTEM<br>may decide:<br>&quot;What should I remember from yesterday?&quot;</pre><pre>AGENTS.md<br>says:<br>&quot;These standing project rules already exist.<br>Read and follow them.&quot;</pre><p>So AGENTS.md is closer to a durable <strong>project brief</strong>.</p><h3>Is AGENTS.md universal?</h3><p>No.</p><p>Different coding harnesses use different conventions.</p><p>For example:</p><pre>Codex<br>→ AGENTS.md</pre><p>while Claude Code uses files such as:</p><pre>CLAUDE.md</pre><p>for persistent project and user instructions. Anthropic documents project and user memory locations and automatically loads applicable CLAUDE.md instructions, with nested instructions discovered according to directory context.</p><p>So don’t memorize:</p><blockquote><em>“Every AI agent reads AGENTS.md.”</em></blockquote><p>Instead remember:</p><blockquote><strong><em>Coding harnesses often support durable project-instruction files; the filename and loading rules are product-specific.</em></strong></blockquote><h3>What belongs in AGENTS.md?</h3><p>Use it for instructions that are broadly useful:</p><pre>✓ build commands<br>✓ test commands<br>✓ package manager<br>✓ important architectural rules<br>✓ directories that should not be edited<br>✓ unusual project conventions</pre><p>Avoid turning it into:</p><pre>entire architecture guide<br>+<br>database handbook<br>+<br>deployment manual<br>+<br>frontend style guide<br>+<br>every historical decision</pre><p>Why?</p><p>Because always-available instructions still compete for model context and attention.</p><p>OpenAI’s current model guidance explicitly recommends lean prompts: remove repeated instructions, keep tool descriptions concise, and expose only what is relevant to the task.</p><p>That leads directly to our final concept.</p><h3>3. Progressive Disclosure</h3><p>Suppose your project has a 70-page frontend style guide.</p><p>Should you paste all 70 pages into AGENTS.md?</p><p>Probably not.</p><p>Most backend sessions will never need it.</p><p>Instead:</p><pre>AGENTS.md</pre><pre>Frontend work:<br>Follow docs/frontend-style-guide.md<br>when modifying UI components.</pre><p>Now the full document stays outside the immediate context until it is needed.</p><p>That is <strong>progressive disclosure</strong>.</p><h3>What is progressive disclosure?</h3><p>In this series:</p><blockquote><strong><em>Progressive disclosure means keeping the always-available context small and loading deeper information only when the current task requires it.</em></strong></blockquote><p>Instead of:</p><pre>SESSION START</pre><pre>AGENTS.md<br>+ entire backend guide<br>+ entire frontend guide<br>+ deployment runbook<br>+ database handbook<br>+ security manual<br>        ↓<br>MODEL</pre><p>use:</p><pre>SESSION START</pre><pre>Small project brief<br>        ↓<br>      MODEL<br>        ↓<br>task requires deployment<br>        ↓<br>follow pointer<br>        ↓<br>load deployment runbook</pre><p>That is much cleaner.</p><h3>Think of AGENTS.md as a map</h3><p>This is probably the easiest mental model.</p><p>Bad design:</p><pre>AGENTS.md<br>= entire encyclopedia</pre><p>Better:</p><pre>AGENTS.md<br>= map + universal rules</pre><p>For example:</p><pre># Project Rules</pre><pre>Use pnpm.</pre><pre>Backend tests:<br>pytest tests/backend</pre><pre>For database migrations:<br>read docs/database/migrations.md</pre><pre>For frontend work:<br>read docs/frontend/style-guide.md</pre><pre>For deployments:<br>read docs/deployment/runbook.md</pre><p>Now:</p><pre>Always-loaded layer<br>        ↓<br>      small</pre><pre>Detailed knowledge<br>        ↓<br>loaded when relevant</pre><p>OpenAI has described a similar repository strategy internally: keeping AGENTS.md short and using it as a map into a larger structured documentation tree rather than treating it as an encyclopedia.</p><h3>A Real Coding Example</h3><p>You ask:</p><blockquote><em>“Add an index to the </em><em>company_id column.”</em></blockquote><p>The session starts with:</p><pre>AGENTS.md</pre><pre>Database work:<br>Read docs/database/migrations.md<br>before changing schema.</pre><p>The agent follows the pointer:</p><pre>AGENTS.md<br>    ↓<br>docs/database/migrations.md<br>    ↓<br>&quot;Never modify old migrations.<br>Create a new migration.<br>Run migration tests.&quot;<br>    ↓<br>CONTEXT<br>    ↓<br>MODEL</pre><p>The frontend guide never gets loaded.</p><p>The deployment manual never gets loaded.</p><p>The agent receives <strong>just enough additional context for this task</strong>.</p><p>That is progressive disclosure in practice.</p><h3>How the Three Concepts Connect</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*emApOUoyR2pnMHbE9nPJPQ.png" /></figure><p>The three terms solve different problems:</p><pre>MEMORY SYSTEM<br>= What should survive across sessions?</pre><pre>AGENTS.md<br>= What standing project instructions<br>should fresh coding sessions know?</pre><pre>PROGRESSIVE DISCLOSURE<br>= How do we avoid loading every detail<br>before we know it is needed?</pre><h3>The Three Definitions Worth Remembering</h3><h3>Memory System</h3><p><strong>An external persistence-and-retrieval mechanism that gives an otherwise stateless model useful continuity across sessions.</strong></p><p>The stored information can live in files, databases, indexes, or other systems.</p><h3>AGENTS.md</h3><p><strong>A persistent repository instruction file understood by supported coding harnesses such as Codex.</strong></p><p>Use it for concise, broadly applicable project rules — not your entire documentation library.</p><h3>Progressive Disclosure</h3><p><strong>A context-management strategy where small instructions or pointers are available first, and detailed information is loaded only when the current task requires it.</strong></p><h3>The Practical Lesson</h3><p>Do not solve cross-session continuity by loading everything forever.</p><p>Use layers:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_NdJYQfV-_lvveIIABIH-Q.png" /></figure><p>The goal is not:</p><blockquote><strong><em>Give the agent everything you know.</em></strong></blockquote><p>It is:</p><blockquote><strong><em>Make the right information easy to retrieve at the moment the agent needs it.</em></strong></blockquote><p>That gives you continuity without turning every fresh session into a giant pile of instructions.</p><p>If this article helped clarify how AI coding agents can “remember” across sessions without the model itself learning, <strong>react to it and share your thoughts in the comments</strong>.</p><p><strong>Follow me here on LinkedIn</strong> for the next article in the <em>AI Coding Dictionary in Detail</em> series.</p><p>You can also connect with me here:</p><p><a href="https://www.linkedin.com/in/nitesh-kr-jha-/">linkedin.com/in/nitesh-kr-jha-/</a></p><p>Thanks for reading. 🚀</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=68e18af5852b" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI Coding Dictionary in Detail: Spec, Ticket, Compaction & Autocompact]]></title>
            <link>https://medium.com/@niteshkrjhag/ai-coding-dictionary-in-detail-spec-ticket-compaction-autocompact-812eedef5341?source=rss-9dbcdadc41e4------2</link>
            <guid isPermaLink="false">https://medium.com/p/812eedef5341</guid>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[compaction]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[agentic-ai]]></category>
            <dc:creator><![CDATA[Niteshkrjhag]]></dc:creator>
            <pubDate>Thu, 10 Sep 2026 03:48:43 GMT</pubDate>
            <atom:updated>2026-09-10T03:48:43.979Z</atom:updated>
            <content:encoded><![CDATA[<p>Some coding tasks fit comfortably inside one AI session:</p><blockquote><em>“Fix this validation bug.”</em></blockquote><p>Others do not:</p><blockquote><em>“Replace our authentication system, migrate existing users, update the API, add monitoring, and remove the old implementation.”</em></blockquote><p>Trying to push the second task through one enormous session creates two problems:</p><ol><li><strong>The work itself is too large to manage as one unit.</strong></li><li><strong>The session history keeps growing while the work continues.</strong></li></ol><p>These are different problems, and they need different solutions.</p><p>That is where four concepts connect:</p><p><strong>Spec → Ticket → Compaction → Autocompact</strong></p><p>A simple mental model is:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YTi9dxEKaiomFx383P7YuQ.png" /></figure><p>And if the harness performs that compression automatically:</p><pre>AUTOCOMPACT</pre><h3>1. Spec</h3><h3>What is a spec?</h3><p>For this series, a <strong>spec is a durable description of a piece of work that is larger than one session</strong>.</p><p>It answers questions such as:</p><pre>What are we building?</pre><pre>Why are we building it?</pre><pre>What constraints matter?</pre><pre>What decisions have already been made?</pre><pre>How will we know it is finished?</pre><pre>What pieces of work remain?</pre><p>The important word is <strong>durable</strong>.</p><p>A session is temporary.</p><p>The project is not.</p><h3>Why does an AI agent need a spec?</h3><p>Imagine you are migrating an API from v2 to v3.</p><p>The work may take several sessions:</p><pre>Session 1<br>Understand current API</pre><pre>Session 2<br>Change database schema</pre><pre>Session 3<br>Update backend</pre><pre>Session 4<br>Backfill data</pre><pre>Session 5<br>Remove old code</pre><pre>Session 6<br>Run migration tests</pre><p>If the entire plan exists only in Session 1’s conversation history, Session 4 has a problem.</p><p>It may not know:</p><ul><li>why a previous decision was made,</li><li>which constraints still apply,</li><li>which work is complete,</li><li>which work remains.</li></ul><p>Instead, put the project state somewhere persistent:</p><pre>migration-spec.md</pre><p>For example:</p><pre>Goal<br>Move company endpoints from API v2 to v3.</pre><pre>Constraints<br>- No downtime.<br>- Existing clients must remain compatible during migration.<br>- Database backfill must finish before old fields are removed.</pre><pre>Decisions<br>- Run old and new fields in parallel temporarily.<br>- Switch reads before removing writes.</pre><pre>Work<br>[✓] Add new columns<br>[✓] Dual-write old and new fields<br>[ ] Backfill existing rows<br>[ ] Switch reads<br>[ ] Remove old fields</pre><p>Now every fresh session has somewhere to start.</p><h3>Spec is a role, not one file format</h3><p>The word <strong>spec</strong> does not require a specific template.</p><p>Depending on the team, the durable source of intent might be:</p><pre>PRD<br>RFC<br>design document<br>GitHub issue<br>Linear project<br>plan.md<br>migration-spec.md</pre><p>The format is secondary.</p><p>The important role is:</p><blockquote><strong><em>The spec is the durable source of project intent and current plan across multiple sessions.</em></strong></blockquote><h3>Should a spec change?</h3><p>Usually, yes.</p><p>Suppose the original plan says:</p><pre>Use Redis for idempotency.</pre><p>During implementation, you discover the database already has the correct uniqueness guarantees.</p><p>The team decides:</p><pre>Use a database unique constraint instead.</pre><p>If the spec still says Redis, future sessions inherit an outdated plan.</p><p>So the spec should reflect <strong>current agreed intent</strong>, not preserve every old idea forever.</p><p>Git history, decision records, or comments can preserve how it evolved if that history matters.</p><h3>2. Ticket</h3><p>A spec can still be too large for one agent to execute directly.</p><p>So we break it down.</p><h3>What is a ticket?</h3><p>For this series, a <strong>ticket is a bounded unit of work small enough for one focused session or agent run</strong>.</p><p>Suppose the spec is:</p><blockquote><em>“Migrate authentication to the new token system.”</em></blockquote><p>That may become:</p><pre>Ticket 1<br>Add new token schema.</pre><pre>Ticket 2<br>Implement new token generation.</pre><pre>Ticket 3<br>Implement new token validation.</pre><pre>Ticket 4<br>Backfill existing sessions.</pre><pre>Ticket 5<br>Switch authentication endpoint.</pre><pre>Ticket 6<br>Delete old implementation.</pre><p>Instead of telling one agent:</p><blockquote><em>“Do the entire migration.”</em></blockquote><p>you tell one session:</p><blockquote><em>“Implement Ticket 2.”</em></blockquote><h3>What makes a good ticket?</h3><p>A fresh session should be able to understand it without having to rediscover the whole project.</p><p>A useful ticket might contain:</p><pre>Goal<br>Implement refresh-token validation.</pre><pre>Relevant files<br>src/auth/token_service.py<br>tests/test_refresh_token.py</pre><pre>Constraints<br>Use the new token schema from migration-spec.md.</pre><pre>Acceptance criteria<br>- valid token succeeds<br>- expired token fails<br>- revoked token fails<br>- existing auth tests remain green</pre><pre>Depends on<br>Ticket 1 — new token schema</pre><p>That gives the agent:</p><pre>scope<br>+<br>context pointers<br>+<br>constraints<br>+<br>definition of done</pre><h3>How big should a ticket be?</h3><p>There is no universal token number.</p><p>The practical test is simpler:</p><blockquote><strong><em>Can one focused session complete and verify it without becoming confused by its own accumulated history?</em></strong></blockquote><p>If every ticket turns into:</p><pre>3 hours<br>60 tool calls<br>multiple architecture decisions<br>three unrelated subproblems</pre><p>the ticket may be too large.</p><p>If every session spends 15 minutes understanding the project to make a one-line edit, your tickets may be too small.</p><p>The goal is not maximum fragmentation.</p><p>It is a <strong>coherent unit of work</strong>.</p><h3>Tickets also enable parallel work</h3><p>Suppose your dependency structure is:</p><pre>            Schema<br>              │<br>        ┌─────┴─────┐<br>        ▼           ▼<br>   Backend API    Admin UI<br>        │           │<br>        └─────┬─────┘<br>              ▼<br>        Integration Test</pre><p>Once the schema work is complete:</p><pre>Backend API</pre><p>and:</p><pre>Admin UI</pre><p>can potentially run in parallel.</p><p>That could mean two developers.</p><p>Or two separate agent sessions.</p><p>So tickets do more than reduce context size.</p><p>They expose the <strong>dependency graph</strong> of the work.</p><h3>3. Compaction</h3><p>Even a well-scoped ticket can sometimes create a long session.</p><p>Imagine debugging a complex failure:</p><pre>Read 8 files<br>Run 12 tests<br>Try approach A<br>Revert<br>Inspect database<br>Try approach B<br>Read more logs<br>Discover root cause</pre><p>Your working history becomes large.</p><p>You still need continuity, but you do not necessarily need every previous token.</p><p>That is where <strong>compaction</strong> comes in.</p><h3>What is compaction?</h3><p><strong>Compaction is the process of replacing a large amount of conversation or agent state with a smaller representation that preserves the information needed to continue.</strong></p><p>Conceptually:</p><pre>LARGE WORKING HISTORY</pre><pre>User messages<br>Model responses<br>10 file reads<br>8 test logs<br>Failed attempt<br>Corrected attempt<br>Architecture discussion<br>Tool results<br>        ↓<br>     COMPACT<br>        ↓<br>SMALLER CONTINUATION STATE</pre><pre>Goal<br>Current approach<br>Important decisions<br>Relevant files<br>Known failures<br>Next step</pre><p>The purpose is:</p><pre>preserve useful state<br>        +<br>recover context headroom</pre><h3>Compaction is a form of compression</h3><p>Remember our earlier distinction:</p><pre>PRIMARY SOURCE<br>= original information</pre><pre>SECONDARY SOURCE<br>= compressed account</pre><p>Traditional summary-style compaction creates something like a secondary source.</p><p>That means it is <strong>lossy</strong>.</p><p>Suppose the full history contained:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Sdgg-BpCJ1o4d45F7CefBA.png" /></figure><pre>User:<br>Enterprise accounts must never use fallback authentication.</pre><p>But the compacted summary says only:</p><pre>Authentication migration is in progress.</pre><p>The important constraint disappeared.</p><p>The agent may continue confidently without knowing anything was lost.</p><p>That is the risk.</p><h3>But not every implementation is a readable summary</h3><p>This is an important modern nuance.</p><p>Some harnesses may create a human-readable summary.</p><p>Others can use provider-specific compacted representations.</p><p>OpenAI’s current Responses API, for example, exposes a /responses/compact operation that reduces conversation state for continuation. Current OpenAI documentation describes compacted items as an opaque representation intended to preserve task-relevant state while reducing token footprint.</p><p>So the durable concept is:</p><blockquote><strong><em>Compaction reduces the working representation while attempting to preserve what matters.</em></strong></blockquote><p>Do not define it as:</p><blockquote><em>“The model always writes a Markdown summary and starts a visibly new chat.”</em></blockquote><p>That is only one possible implementation.</p><h3>When should you compact?</h3><p>A natural moment is a <strong>phase boundary</strong>.</p><p>For example:</p><pre>Investigation complete<br>        ↓<br>Root cause confirmed<br>        ↓<br>     COMPACT<br>        ↓<br>Implementation begins</pre><p>That is much cleaner than compacting halfway through:</p><pre>editing function<br>↓<br>half-finished reasoning<br>↓<br>COMPACT<br>↓<br>continue somehow</pre><p>OpenAI’s current guidance similarly recommends planning compaction around major milestones in long, tool-heavy workflows rather than mechanically compacting every turn.</p><h3>Is the trigger always 80%?</h3><p>No.</p><p>Do not memorize:</p><pre>Autocompact = 80%</pre><p>That is not a universal rule.</p><p>Threshold behavior depends on:</p><ul><li>provider,</li><li>model,</li><li>harness,</li><li>configuration,</li><li>product version.</li></ul><p>The concept is simply:</p><blockquote><strong><em>The system decides when to compact rather than waiting for the user to initiate it manually.</em></strong></blockquote><h3>Why can autocompact be risky?</h3><p>Because the trigger may happen at an inconvenient point.</p><p>Imagine this sequence:</p><pre>Agent discovers:<br>&quot;Never delete legacy_customer_id until backfill is verified.&quot;</pre><pre>      ↓</pre><pre>More debugging</pre><pre>      ↓</pre><pre>Autocompact triggers</pre><pre>      ↓</pre><pre>Compacted state preserves:<br>&quot;Migration in progress.&quot;</pre><pre>but loses:<br>&quot;Never delete legacy_customer_id...&quot;</pre><p>The agent continues.</p><p>Nothing visibly crashes.</p><p>But an important constraint may now be missing.</p><p>This is why durable decisions should not live <strong>only</strong> in transient conversation history.</p><p>Put important project state into:</p><pre>spec<br>ticket<br>decision record<br>handoff artifact<br>tests<br>code comments where appropriate</pre><p>Then compaction does not become the only thing preserving them.</p><h3>Putting All Four Together</h3><pre>BIG PROJECT<br>    ↓<br>SPEC<br>    ↓<br>split into<br>    ↓<br>TICKETS<br>    ↓<br>focused sessions<br>    ↓<br>COMPACTION when context grows too large</pre><p>These solve two different scaling problems:</p><pre>SPEC + TICKETS<br>= scale the WORK<br>= break one large project into smaller, manageable units</pre><pre>COMPACTION<br>= scale the CONTEXT<br>= shrink an overloaded session history so the agent can continue with more context space</pre><p>In short:</p><blockquote><strong><em>Specs and tickets organize how much work the agent does at once. Compaction organizes how much history the model carries while doing it.</em></strong></blockquote><h3>The Four Definitions Worth Remembering</h3><h3>Spec</h3><p><strong>A durable source of intent for work that spans multiple sessions.</strong></p><p>It records goals, constraints, decisions, status, and the pieces of work still required.</p><h3>Ticket</h3><p><strong>A bounded unit of work intended to be completed and verified within a focused session or agent run.</strong></p><p>It should include enough context and acceptance criteria to stand mostly on its own.</p><h3>Compaction</h3><p><strong>Reducing a large working history into a smaller continuation representation while attempting to preserve task-relevant information.</strong></p><p>It creates context headroom but may lose detail.</p><h3>Autocompact</h3><p><strong>Compaction initiated automatically by the harness or API according to its context-management policy.</strong></p><p>Its trigger is implementation-specific, not a universal percentage.</p><h3>The Practical Lesson</h3><p>For large AI coding projects, don’t try to solve both project scale and context scale with one endless conversation.</p><p>Use:</p><pre>SPEC<br>for the whole project</pre><pre>TICKETS<br>for focused pieces of work</pre><pre>COMPACTION<br>when one session becomes too heavy</pre><pre>DURABLE ARTIFACTS<br>for decisions that must survive any compaction</pre><p>The result is a much cleaner workflow:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JOX6q7rROUqtsRMGhAOq3g.png" /></figure><p>The project survives even though individual sessions remain disposable.</p><p>If this article helped make large AI coding workflows easier to structure, <strong>react to it and share your thoughts in the comments</strong>.</p><p><strong>Follow me here on LinkedIn</strong> for the next article in the <em>AI Coding Dictionary in Detail</em> series.</p><p>You can also connect with me here:</p><p><a href="https://www.linkedin.com/in/nitesh-kr-jha-/">linkedin.com/in/nitesh-kr-jha-/</a></p><p>Thanks for reading. 🚀</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=812eedef5341" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI Coding Dictionary in Detail: Clearing, Handoff, Primary Sources, Secondary Sources & Handoff…]]></title>
            <link>https://medium.com/@niteshkrjhag/ai-coding-dictionary-in-detail-clearing-handoff-primary-sources-secondary-sources-handoff-ebea8fcea5eb?source=rss-9dbcdadc41e4------2</link>
            <guid isPermaLink="false">https://medium.com/p/ebea8fcea5eb</guid>
            <category><![CDATA[handoff]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[ai-engineering]]></category>
            <category><![CDATA[sessions]]></category>
            <dc:creator><![CDATA[Niteshkrjhag]]></dc:creator>
            <pubDate>Thu, 10 Sep 2026 03:47:58 GMT</pubDate>
            <atom:updated>2026-09-10T03:47:58.181Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*v_Ee2R8Xv7gqm__I6dJx8Q.png" /></figure><h3>AI Coding Dictionary in Detail: Clearing, Handoff, Primary Sources, Secondary Sources &amp; Handoff Artifacts</h3><p>Imagine you have been working with an AI coding agent for two hours.</p><p>The session now contains:</p><ul><li>the original task,</li><li>three failed approaches,</li><li>dozens of file reads,</li><li>long test logs,</li><li>an abandoned architecture idea,</li><li>a corrected database assumption,</li><li>and finally, a working plan.</li></ul><p>The agent is starting to drift.</p><p>You could keep pushing.</p><p>Or you could start fresh.</p><p>But there is a problem:</p><blockquote><strong><em>How do you remove the noisy history without losing the useful decisions?</em></strong></blockquote><p>That question connects five terms:</p><p><strong>Clearing → Handoff → Primary Source → Secondary Source → Handoff Artifact</strong></p><p>The whole workflow is:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HDsCOWudcF0hEop3RKEA4g.png" /></figure><h3>1. Clearing</h3><h3>What is clearing?</h3><p><strong>Clearing means ending the current working session and beginning a fresh one without carrying the old conversation history forward as working context.</strong></p><p>Suppose your current session contains:</p><pre>Correct architecture decision<br>+<br>Old architecture decision<br>+<br>Failed implementation<br>+<br>Old test failures<br>+<br>Current implementation<br>+<br>60 tool results</pre><p>The model now has to work through all of that.</p><p>Clearing gives you something closer to:</p><pre>Fresh session<br>+<br>current task<br>+<br>only the information we deliberately reload</pre><p>The goal is not simply to save tokens.</p><p>It is to remove <strong>context residue</strong>.</p><h3>A relatable coding example</h3><p>Suppose your agent has spent an hour debugging authentication.</p><p>Initially, both of you believed:</p><pre>The refresh token is stored in Redis.</pre><p>Twenty turns later, you discover:</p><pre>Actually, the current implementation stores it in PostgreSQL.</pre><p>The old Redis discussion is still sitting in the session.</p><p>Later, the agent proposes a fix involving Redis again.</p><p>You correct it.</p><p>It apologizes.</p><p>Ten minutes later, Redis appears again.</p><p>At some point, continuing to fight the accumulated history becomes less useful than creating:</p><pre>Fresh session</pre><pre>Known facts:<br>- PostgreSQL stores refresh tokens<br>- auth/service.py is authoritative<br>- failing test is tests/test_refresh.py</pre><p>That is where clearing helps.</p><h3>Does clearing mean the next model request contains literally nothing?</h3><p>No.</p><p>A new session can still receive:</p><ul><li>system instructions,</li><li>project instructions,</li><li>AGENTS.md,</li><li>saved memory,</li><li>repository information,</li><li>whatever you deliberately provide.</li></ul><p>So:</p><pre>CLEARING<br>≠<br>empty model with zero instructions</pre><p>It means:</p><blockquote><strong><em>The previous session’s accumulated working history is no longer automatically part of the new session.</em></strong></blockquote><p>That is the useful distinction.</p><h3>2. Handoff</h3><p>Now clearing creates another problem.</p><p>Your old session may know something valuable:</p><pre>Root cause identified<br>Architecture decision made<br>Files already changed<br>Tests still failing<br>Next step known</pre><p>If you simply clear, all that working history may disappear from the new session.</p><p>So before clearing, you may perform a <strong>handoff</strong>.</p><h3>What is a handoff?</h3><p><strong>A handoff is the deliberate transfer of useful working information from one session, agent, or phase of work to another.</strong></p><p>Think of shift changes in a hospital.</p><p>A doctor finishing their shift does not tell the next doctor:</p><blockquote><em>“Good luck. Start investigating the patient from zero.”</em></blockquote><p>They communicate:</p><pre>What happened<br>What was tested<br>What was ruled out<br>What was decided<br>What still needs attention</pre><p>AI coding handoffs solve the same problem.</p><h3>A coding example</h3><p>Session 1 is responsible for investigation.</p><p>It discovers:</p><pre>Problem:<br>duplicate orders occur during concurrent checkout.<br><br>Root cause:<br>check-then-insert is not atomic.<br><br>Relevant files:<br>src/checkout/service.py<br>src/orders/repository.py<br><br>Decision:<br>use database-level uniqueness +<br>idempotency key.</pre><pre>Not done:<br>implementation and concurrency test.</pre><p>Session 2 should not need to rediscover all of that.</p><p>Instead:</p><pre>SESSION 1<br>investigation<br>     ↓<br>HANDOFF<br>     ↓<br>SESSION 2<br>implementation</pre><p>This lets each session remain focused.</p><h3>Handoff is broader than a document</h3><p>A handoff is the <strong>act of transferring working context</strong>.</p><p>The transfer mechanism could be:</p><pre>Written document<br>Summary<br>Ticket<br>Plan<br>Memory entry<br>Compaction result</pre><p>One particularly useful mechanism is the <strong>handoff artifact</strong>, which we will define shortly.</p><p>So:</p><pre>HANDOFF<br>= process</pre><pre>HANDOFF ARTIFACT<br>= one possible object used to perform it</pre><h3>3. Primary Source</h3><p>Once a new session receives a handoff, another problem appears.</p><p>Suppose the handoff says:</p><blockquote><em>“Authentication tests are passing.”</em></blockquote><p>Should the new session simply trust that?</p><p>Not necessarily.</p><p>To understand why, we need <strong>primary sources</strong>.</p><h3>What is a primary source?</h3><p>For software work, a <strong>primary source is the original artifact or observation you need to inspect to establish a claim directly.</strong></p><p>Examples:</p><pre>Claim:<br>&quot;The function accepts three arguments.&quot;</pre><pre>Primary source:<br>the actual function definition</pre><pre>Claim:<br>&quot;The test fails with a timeout.&quot;</pre><pre>Primary source:<br>the actual test output</pre><pre>Claim:<br>&quot;The API returned status 429.&quot;</pre><pre>Primary source:<br>the actual API response / captured log</pre><pre>Claim:<br>&quot;We agreed to use PostgreSQL.&quot;</pre><pre>Primary source for that decision:<br>the original recorded conversation or decision record</pre><p>The exact primary source depends on <strong>what claim you are trying to verify</strong>.</p><h3>Code is not always the primary source for everything</h3><p>This nuance is important.</p><p>Suppose someone asks:</p><blockquote><em>“What behaviour did the team intend?”</em></blockquote><p>The current code may not answer that.</p><p>A design decision record or original discussion may be the relevant primary source.</p><p>But if the question is:</p><blockquote><em>“What does production code currently do?”</em></blockquote><p>then:</p><pre>Actual code<br>Actual configuration<br>Actual runtime behavior</pre><p>are much stronger sources than an old architecture document.</p><p>So primary source really means:</p><blockquote><strong><em>the closest original evidence for the specific claim being investigated.</em></strong></blockquote><h3>Why AI coding needs primary sources</h3><p>Imagine a handoff says:</p><blockquote><em>“</em><em>create_order() already checks idempotency.”</em></blockquote><p>The new agent trusts the document and builds on it.</p><p>But the actual code says:</p><pre>def create_order(data):<br>    return db.insert(data)</pre><p>No idempotency check exists.</p><p>The handoff was wrong.</p><p>The primary source corrects it.</p><p>That gives us a powerful working pattern:</p><pre>Summary says X<br>      ↓<br>Does X materially affect the task?<br>      ↓<br>     YES<br>      ↓<br>Verify against primary source</pre><h3>4. Secondary Source</h3><p>Most handoffs are not primary sources.</p><p>They are <strong>secondary sources</strong>.</p><h3>What is a secondary source?</h3><p><strong>A secondary source is an interpretation, summary, or description of a primary source.</strong></p><p>Examples include:</p><pre>README describing code<br><br>Architecture diagram describing a system<br><br>Summary describing a long conversation<br><br>Bug report describing production logs<br><br>Handoff document describing work completed</pre><p>Secondary sources are useful because they compress information.</p><h3>Why do we need them?</h3><p>Suppose Session 1 consumed:</p><pre>120K tokens</pre><p>of:</p><ul><li>code,</li><li>logs,</li><li>discussions,</li><li>searches,</li><li>tests.</li></ul><p>Session 2 does not necessarily need all 120K.</p><p>Maybe it needs:</p><pre>2K-token summary</pre><p>containing:</p><pre>What matters<br>What was decided<br>What is unfinished<br>Where to look next</pre><p>That is the value of a secondary source.</p><p>It trades:</p><pre>COMPLETENESS<br>      ↓<br>for<br>      ↓<br>COMPRESSION</pre><p>Or more precisely:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*YY6nDTrMtbxN8Zpoc0H19A.png" /></figure><h3>Secondary sources fail in two important ways</h3><h3>1. Loss</h3><p>The summary leaves something important out.</p><p>For example:</p><blockquote><em>“Migration strategy approved.”</em></blockquote><p>But it forgets:</p><blockquote><em>“Except for enterprise customers, who require a different path.”</em></blockquote><p>The next session never sees the exception.</p><h3>2. Drift</h3><p>The source changes, but the document does not.</p><p>For example:</p><pre>January README:<br>Authentication uses JWT v1.</pre><pre>August code:<br>Authentication uses JWT v2.</pre><p>The README may still sound confident.</p><p>It is simply outdated.</p><h3>So should agents always use primary sources?</h3><p>No.</p><p>That would create the opposite problem.</p><p>Imagine loading:</p><pre>entire Git history<br>full CI logs<br>every conversation<br>all source files</pre><p>for every question.</p><p>You would destroy context efficiency.</p><p>The better pattern is:</p><blockquote><strong><em>Use secondary sources for orientation. Use primary sources when precision matters.</em></strong></blockquote><p>For example:</p><pre>HANDOFF: &quot;Bug is in auth/service.py line around refresh-token validation.&quot;<br>        ↓</pre><pre>NEW AGENT: uses handoff to know where to look</pre><pre>        ↓</pre><pre>reads auth/service.py</pre><pre>        ↓</pre><pre>runs actual failing test</pre><pre>        ↓</pre><pre>works from primary evidence</pre><p>That is far more efficient.</p><h3>5. Handoff Artifact</h3><p>Now all the pieces connect.</p><h3>What is a handoff artifact?</h3><p><strong>A handoff artifact is a persistent document created specifically to transfer useful working state to another session or agent.</strong></p><p>Examples include:</p><pre>HANDOFF.md<br>PLAN.md<br>implementation-plan.md<br>migration-spec.md<br>ticket<br>decision record</pre><p>It usually lives in the environment so another session can read it later.</p><h3>Why not just tell the next agent to read the old conversation?</h3><p>Because the old conversation may contain:</p><pre>Correct ideas<br>Wrong ideas<br>Experiments<br>Dead ends<br>Repetitions<br>Old logs<br>Contradictions</pre><p>A good handoff artifact deliberately compresses that into:</p><pre>CURRENT TRUTH<br>DECISIONS<br>EVIDENCE<br>FILES<br>PROGRESS<br>NEXT STEPS</pre><p>That makes it a <strong>secondary source optimized for continuation</strong>.</p><h3>What should a good handoff artifact contain?</h3><p>Imagine the next agent knows absolutely nothing about the current session.</p><p>It should still be able to answer:</p><h3>What are we doing?</h3><pre>Goal:<br>Prevent duplicate checkout orders.</pre><h3>What did we learn?</h3><pre>Root cause:<br>check-then-insert race condition.</pre><h3>What was decided?</h3><pre>Use:<br>idempotency key + database unique constraint.</pre><h3>Why?</h3><pre>Application-only checks still race under concurrency.</pre><h3>What files matter?</h3><pre>src/checkout/service.py<br>src/orders/repository.py<br>tests/test_checkout_concurrency.py</pre><h3>What has already been done?</h3><pre>Unique constraint added.<br>Repository code updated.</pre><h3>What remains?</h3><pre>Add concurrency regression test.<br>Run full checkout suite.</pre><h3>What should be verified?</h3><pre>Do not trust this document for test status.<br>Run the tests again.</pre><p>That last line is especially useful.</p><p>It reminds the next agent:</p><blockquote><strong><em>This document is a secondary source. Verify important state against reality.</em></strong></blockquote><h3>A Strong Handoff Workflow</h3><p>Putting everything together:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FvzT32HGHpyqf9quF6VZZw.png" /></figure><p>A handoff gives you the middle ground:</p><blockquote><strong><em>Fresh context without losing useful progress.</em></strong></blockquote><h3>The Five Definitions Worth Remembering</h3><h3>Clearing</h3><p><strong>Ending the current working session and starting a fresh one without carrying forward its accumulated conversational history.</strong></p><p>Use it when old context is becoming more harmful than useful.</p><h3>Handoff</h3><p><strong>The process of transferring the important state of one piece of work to another session, agent, or phase.</strong></p><h3>Primary Source</h3><p><strong>The closest original evidence for the claim you are trying to verify.</strong></p><p>Code, actual test output, raw API responses, or original decision records can all be primary sources depending on the question.</p><h3>Secondary Source</h3><p><strong>A summary, interpretation, or description of primary evidence.</strong></p><p>Smaller and easier to consume, but potentially incomplete or stale.</p><h3>Handoff Artifact</h3><p><strong>A persistent secondary-source document designed specifically to brief another session or agent.</strong></p><p>It should tell a fresh session what matters and point back to primary evidence where verification is important.</p><h3>The Practical Lesson</h3><p>The goal is not to keep every token forever.</p><p>And it is not to throw everything away.</p><p>The better pattern is:</p><pre>KEEP<br>important decisions</pre><pre>DROP<br>failed attempts and noise</pre><pre>WRITE<br>a clear handoff</pre><pre>CLEAR<br>the polluted session</pre><pre>RELOAD<br>only what matters</pre><pre>VERIFY<br>important claims against primary sources</pre><p>That is how you turn a long AI coding workflow into a sequence of clean, focused sessions without repeatedly starting the project from zero.</p><p>If this article helped make session handoffs and source quality clearer, <strong>react to it and share your thoughts in the comments</strong>.</p><p><strong>Follow me here on LinkedIn</strong> for the next article in the <em>AI Coding Dictionary in Detail</em> series.</p><p>You can also connect with me here:</p><p><a href="https://www.linkedin.com/in/nitesh-kr-jha-/">linkedin.com/in/nitesh-kr-jha-/</a></p><p>Thanks for reading. 🚀</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=ebea8fcea5eb" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI Coding Dictionary in Detail: Attention Relationships, Attention Budget, Attention Degradation &…]]></title>
            <link>https://medium.com/@niteshkrjhag/ai-coding-dictionary-in-detail-attention-relationships-attention-budget-attention-degradation-01303b9357fb?source=rss-9dbcdadc41e4------2</link>
            <guid isPermaLink="false">https://medium.com/p/01303b9357fb</guid>
            <category><![CDATA[attention]]></category>
            <category><![CDATA[ai-engineering]]></category>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[ai-agent]]></category>
            <category><![CDATA[ml-engineering]]></category>
            <dc:creator><![CDATA[Niteshkrjhag]]></dc:creator>
            <pubDate>Mon, 07 Sep 2026 17:04:59 GMT</pubDate>
            <atom:updated>2026-09-07T17:04:59.132Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*XLEr2wWDxYRhd6V7wSGlJg.png" /></figure><h3>AI Coding Dictionary in Detail: Attention Relationships, Attention Budget, Attention Degradation &amp; Smart Zone</h3><p>You start an AI coding session.</p><p>For the first hour, the agent feels sharp.</p><p>It remembers your constraints, connects a function call to the correct definition, follows the schema you gave it, and catches subtle bugs.</p><p>Later, after dozens of file reads, test logs, edits, and conversations, something changes.</p><p>The same agent starts to:</p><ul><li>ignore an instruction from earlier,</li><li>confuse two similar functions,</li><li>use an outdated version of a type,</li><li>or contradict information that is technically still somewhere in the conversation.</li></ul><p>The model did not suddenly lose parameters.</p><p>So what changed?</p><p>The amount — and arrangement — of information it has to work through changed.</p><p>To understand that, we need four connected ideas:</p><p><strong>Attention Relationship → Attention Budget → Attention Degradation → Smart Zone</strong></p><p>One warning before we begin:</p><blockquote><strong><em>“Attention relationship,” “attention budget,” and “smart/dumb zone” are useful teaching terms, but they are not all formal names from transformer architecture.</em></strong></blockquote><p>We will use them as mental models while keeping the actual mechanism accurate.</p><h3>1. Attention Relationship</h3><p>Before defining an <strong>attention relationship</strong>, we first need to understand <strong>attention</strong>.</p><h3>What is attention?</h3><p>In a transformer model, attention is a mechanism that helps each token representation decide:</p><blockquote><strong><em>Which earlier information is relevant to what I am processing right now?</em></strong></blockquote><p>Suppose the model sees:</p><pre>Riya opened the pull request because she wanted a review.</pre><p>When processing she, the model should connect it strongly with:</p><pre>Riya</pre><p>rather than with:</p><pre>pull request</pre><p>Something similar happens in code.</p><p>Imagine the model has already read:</p><pre>def get_user(user_id: int, include_deleted: bool = False):<br>    ...</pre><p>and much later sees:</p><pre>user = get_user(id, True)</pre><p>To understand that True means:</p><pre>include_deleted = True</pre><p>the model needs information from the earlier function definition to influence how it interprets the later call.</p><p>That connection is what we will informally call an <strong>attention relationship</strong>.</p><h3>What actually happens inside attention?</h3><p>At a simplified level, each token representation produces three vectors commonly called:</p><pre>Query<br>Key<br>Value</pre><p>You can think of them like this:</p><h3>Query</h3><blockquote><em>“What information am I looking for?”</em></blockquote><h3>Key</h3><blockquote><em>“What kind of information do I contain?”</em></blockquote><h3>Value</h3><blockquote><em>“What information should I contribute if I am relevant?”</em></blockquote><p>The model compares a query against keys from other available token positions.</p><p>Conceptually:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4Cztj-AUM9vArQwUH2z0Ew.png" /></figure><p>For causal language models, a token can normally attend to itself and <strong>earlier</strong> token positions, not future tokens that have not been generated yet.</p><p>The softmax step turns the scores into normalized weights for that attention head, meaning the weights for that query sum to roughly 1.</p><h3>A coding example</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*N6oZKqhervN5Qkq6ZEkAuA.png" /></figure><p>Suppose your context contains two functions:</p><pre>def get_user(user_id):<br>    ...</pre><p>and much later:</p><pre>def get_user_permissions(user_id):<br>    ...</pre><p>Then the agent sees:</p><pre>user = get_user(current_user_id)</pre><p>The model needs the relevant earlier get_user definition to influence this call more than the unrelated get_user_permissions definition.</p><p>Conceptually:</p><pre>get_user(...) call<br>       │<br>       ├──────── strong useful relationship ───────→ get_user definition<br>       │<br>       └──────── weaker relationship ──────────────→ get_user_permissions</pre><p>That does <strong>not</strong> mean there is one permanent line inside the model connecting those two pieces of code.</p><p>Those attention patterns are computed as the model processes the current input.</p><h3>What about N² attention?</h3><p>You may have heard:</p><blockquote><em>“Attention is quadratic.”</em></blockquote><p>For <strong>standard full self-attention</strong>, that is approximately correct.</p><p>If there are N token positions, comparing queries with keys produces an attention matrix whose size grows on the order of:</p><pre>N × N</pre><p>So roughly:</p><p>TokensPossible attention-score positions1,000~1 million10,000~100 million100,000~10 billion</p><p>For a causal decoder, future positions are masked, so not every matrix entry is usable, but the standard computation still scales quadratically in sequence length.</p><p>There is one important caveat:</p><blockquote><strong><em>Not every modern long-context model uses plain full attention everywhere.</em></strong></blockquote><p>Architectures can use local attention, sparse attention, grouped-query attention, and other optimizations.</p><p>So N² is a useful explanation of <strong>standard full self-attention</strong>, not a claim about every frontier model’s exact internal implementation.</p><p>And we should not guess how many attention heads an unpublished frontier model has.</p><h3>2. Attention Budget</h3><p>Now imagine one model query needs information from 100 possible earlier places.</p><p>For one attention head, the normalized attention weights might conceptually look like:</p><pre>Relevant function definition     0.42<br>Current instruction              0.24<br>Related type definition          0.18<br>Recent test output               0.08<br>Other tokens combined            0.08</pre><p>The exact numbers are only illustrative.</p><p>But notice:</p><blockquote><em>For that query and attention head, stronger weighting somewhere means less normalized weight available elsewhere.</em></blockquote><p>This gives us a useful teaching idea:</p><p><strong>attention budget</strong>.</p><h3>What is an attention budget?</h3><p>For this series:</p><blockquote><strong><em>Attention budget is a practical metaphor for the limited ability of the model to strongly prioritize every piece of a large context at the same time.</em></strong></blockquote><p>Do not interpret it as:</p><pre>The transformer has one literal global<br>&quot;attention budget = 100 points&quot;</pre><p>It doesn’t.</p><p>Attention happens:</p><ul><li>across many heads,</li><li>across many layers,</li><li>for many token positions,</li><li>with different patterns at each stage.</li></ul><p>But the metaphor is still useful.</p><h3>Think signal vs noise</h3><p>Suppose your important instruction is:</p><blockquote><em>“Never write directly to </em><em>raw_company_details; use the repository layer.”</em></blockquote><p>At the start of a session, the context contains:</p><pre>Important instruction<br>Relevant source file<br>User request</pre><p>Very little distraction.</p><p>Later, the session contains:</p><pre>Important instruction<br>+<br>30 file reads<br>+<br>15 search outputs<br>+<br>8 long test logs<br>+<br>old architectural discussion<br>+<br>failed implementation attempt<br>+<br>new implementation attempt<br>+<br>unrelated debugging</pre><p>The instruction is technically still present.</p><p>But the model now has far more competing information to interpret.</p><p>A useful analogy is a meeting.</p><h3>Small meeting</h3><p>You tell four people:</p><blockquote><em>“Deployment must happen after database migration.”</em></blockquote><p>Everyone hears it clearly.</p><h3>Huge noisy meeting</h3><p>You say the same sentence while 150 people are discussing:</p><ul><li>testing,</li><li>monitoring,</li><li>database errors,</li><li>frontend bugs,</li><li>deadlines.</li></ul><p>Your sentence did not physically become quieter.</p><p>But <strong>finding and prioritizing the relevant signal became harder</strong>.</p><p>That is what the attention-budget metaphor is trying to capture.</p><h3>Important correction: more tokens do not automatically divide attention equally</h3><p>We should not say:</p><blockquote><em>“At 100K tokens, the important relationship gets only one ten-billionth of the attention.”</em></blockquote><p>That sounds mathematical but is misleading.</p><p>Attention is <strong>learned and selective</strong>.</p><p>A highly relevant token can receive far more weight than thousands of irrelevant ones.</p><p>The real problem is not:</p><pre>More tokens<br>↓<br>attention divided equally</pre><p>It is closer to:</p><pre>More potentially competing information<br>+<br>position effects<br>+<br>similar-looking information<br>+<br>irrelevant material<br>        ↓<br>harder retrieval and prioritization</pre><p>That brings us to the practical failure mode.</p><h3>3. Attention Degradation</h3><h3>What is attention degradation?</h3><p>For this series, <strong>attention degradation</strong> means:</p><blockquote><strong><em>The practical decline in a model’s ability to reliably retrieve and use the right information as the context becomes longer, noisier, or harder to navigate.</em></strong></blockquote><p>This can look like:</p><pre>Earlier:<br>✓ follows schema<br>✓ remembers constraint<br>✓ uses correct definition</pre><pre>Later:<br>✕ invents field<br>✕ ignores constraint<br>✕ confuses two implementations</pre><p>But be careful with the cause.</p><p>It is too simplistic to say:</p><blockquote><em>“The model gets worse only because every token has less attention available.”</em></blockquote><p>Research on long-context models shows a more complicated picture.</p><h3>The “lost in the middle” problem</h3><p>One famous result comes from the paper <strong>Lost in the Middle</strong>.</p><p>Researchers placed relevant information in different positions inside long contexts.</p><p>They found that models often performed better when the useful information appeared near the <strong>beginning or end</strong>, and worse when it appeared in the <strong>middle</strong>.</p><p>Conceptually:</p><pre>LONG CONTEXT</pre><pre>[important fact]<br>████████████████████████<br>                         → often easier</pre><pre>██████████<br>[important fact]<br>██████████<br>                         → can be harder</pre><pre>████████████████████████<br>[important fact]<br>                         → often easier</pre><p>Later research connected this phenomenon with positional biases in model attention, while newer models have become more robust but have not eliminated long-context biases entirely.</p><p>So long-context failure can involve several things:</p><ul><li>position,</li><li>distraction,</li><li>competing evidence,</li><li>similar symbols,</li><li>retrieval difficulty,</li><li>accumulated stale information.</li></ul><p>Not simply “too many tokens.”</p><h3>A real coding example</h3><p>Suppose early in the session the agent reads:</p><pre>class Company:<br>    industry: str | None</pre><p>Thirty turns later it reads another old file containing:</p><pre>industry: dict</pre><p>Then it sees:</p><pre>company.industry</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MY08CgBTfefFq9w-9Aps5w.png" /></figure><p>Now the context contains two conflicting representations.</p><p>The agent may choose the wrong one.</p><p>The fix is not necessarily:</p><blockquote><em>“Paste both files again.”</em></blockquote><p>A better approach may be:</p><pre>Find authoritative definition<br>      ↓<br>remove / ignore stale representation<br>      ↓<br>load exact current type<br>      ↓<br>continue</pre><p>This is why context engineering often involves <strong>removing information</strong>, not merely adding it.</p><h3>How do you recover?</h3><p>When an agent starts drifting, consider:</p><pre>1. Is the correct information actually present?<br><br>2. Is there conflicting or stale information?<br><br>3. Can I reload the authoritative source?<br><br>4. Can old tool output be summarized or removed?<br><br>5. Should I compact or start a fresh session?</pre><p>Sometimes adding context is correct.</p><p>For example:</p><pre>Missing schema<br>↓<br>load schema</pre><p>But if the schema is already buried inside a huge noisy history:</p><pre>More documentation</pre><p>may only add more material to navigate.</p><p>The right move may instead be:</p><pre>Fresh context<br>+<br>exact schema<br>+<br>current task</pre><h3>4. Smart Zone</h3><p>This leads to a term that is useful operationally but should <strong>not</strong> be mistaken for a scientific transformer concept:</p><p><strong>smart zone</strong>.</p><h3>What is the smart zone?</h3><p>For this series:</p><blockquote><strong><em>The smart zone is the practical part of a session where the agent still has focused, relevant context and is performing reliably on the current task.</em></strong></blockquote><p>As the session accumulates unrelated or stale information, you may feel it drift into what people informally call the:</p><blockquote><strong><em>dumb zone</em></strong></blockquote><p>But there is no switch inside the transformer saying:</p><pre>Token 124,999 → SMART</pre><pre>Token 125,000 → DUMB</pre><p>No such universal boundary exists.</p><h3>There is no universal 125K threshold</h3><p>The original definition suggested that frontier models often enter the dumb zone around:</p><pre>125K–150K tokens</pre><p>I would not publish that as a general rule.</p><p>Long-context performance depends on:</p><ul><li>model,</li><li>task,</li><li>location of relevant information,</li><li>amount of distractor content,</li><li>harness,</li><li>retrieval strategy,</li><li>prompt structure,</li><li>type of reasoning required.</li></ul><p>Research has also shown that newer models are becoming more robust to some positional problems, although long-context biases remain measurable.</p><p>So:</p><pre>Context window = 200K</pre><p>does not mean:</p><pre>Always excellent until 199K</pre><p>and it also does not mean:</p><pre>Always bad after 125K</pre><p>The quality boundary is task-dependent.</p><h3>Think usable budget, not maximum capacity</h3><p>Imagine your car has a maximum capacity of:</p><pre>5 passengers</pre><p>That tells you what physically fits.</p><p>It does not tell you:</p><blockquote><em>“Five passengers, five suitcases, mountain roads, and 45°C weather will produce the same performance as one passenger on an empty highway.”</em></blockquote><p>Similarly:</p><pre>CONTEXT WINDOW<br>= what can technically fit</pre><p>while:</p><pre>SMART ZONE<br>= what remains practically useful<br>for this task</pre><p>The second is not a fixed model specification.</p><p>It is an operating judgment.</p><h3>Signs you may be leaving the smart zone</h3><p>Watch for patterns such as:</p><pre>Repeatedly forgetting constraints<br><br>Confusing old and new versions of code<br><br>Re-asking already answered questions<br><br>Ignoring authoritative files<br><br>Contradicting earlier verified result<br><br>Following stale tool outputs<br><br>Growing difficulty steering the task</pre><p>One mistake alone does not prove attention degradation.</p><p>But repeated drift during an increasingly bloated session is a useful signal.</p><h3>A better workflow</h3><p>Suppose a project has four large phases:</p><pre>1. Understand architecture<br>2. Design migration<br>3. Implement migration<br>4. Verify and clean up</pre><p>Instead of forcing all four through one enormous session:</p><pre>SESSION</pre><pre>Architecture<br>+<br>Planning<br>+<br>Implementation<br>+<br>Debugging<br>+<br>Verification<br>+<br>all accumulated history</pre><p>you might use:</p><pre>SESSION 1<br>Understand + produce plan<br>        ↓<br>HANDOFF<br>--------------------------<br><br>SESSION 2<br>Implement from plan<br>        ↓<br>HANDOFF<br>----------------------------<br><br>SESSION 3<br>Verify + review</pre><p>Each session begins with cleaner, task-specific context.</p><p>That is often more valuable than maximizing how many tokens you can technically keep alive.</p><h3>Putting All Four Together</h3><p>The hierarchy now looks like this:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HDsCOWudcF0hEop3RKEA4g.png" /></figure><h3>The Four Definitions Worth Remembering</h3><h3>Attention Relationship</h3><p><strong>An informal way to describe how strongly information at one token position influences the processing of another through attention.</strong></p><p>In real transformer attention, queries are compared with keys and used to weight values.</p><h3>Attention Budget</h3><p><strong>A practical metaphor for the model’s limited ability to make every part of a large context strongly relevant at once.</strong></p><p>It should not be interpreted as one literal global numerical budget.</p><h3>Attention Degradation</h3><p><strong>A practical decline in reliable use of context as the input becomes longer, noisier, conflicting, or positionally difficult.</strong></p><p>Long-context research shows real retrieval and positional weaknesses, but the mechanism is more complex than simple equal dilution.</p><h3>Smart Zone</h3><p><strong>An informal operational label for the part of a session where context remains focused enough for the agent to work reliably.</strong></p><p>There is no universal token number where the smart zone ends.</p><h3>The Practical Lesson</h3><p>A large context window answers:</p><blockquote><strong><em>“How much can the model technically receive?”</em></strong></blockquote><p>It does not answer:</p><blockquote><strong><em>“How much can the model use equally well?”</em></strong></blockquote><p>For AI coding, the better strategy is usually:</p><pre>RIGHT INFORMATION<br>      +<br>RIGHT TIME<br>      +<br>LOW DISTRACTION<br>      +<br>AUTHORITATIVE SOURCES<br>      ↓<br>BETTER CONTEXT</pre><p>not:</p><pre>EVERY FILE<br>+<br>EVERY LOG<br>+<br>EVERY PREVIOUS DISCUSSION<br>      ↓<br>HOPE THE MODEL FINDS THE RIGHT PART</pre><p>A bigger context window is useful.</p><p>But <strong>context quality still matters more than context volume</strong>.</p><p>If this article helped make attention and long-context behavior clearer, <strong>react to it and share your thoughts in the comments</strong>.</p><p><strong>Follow me here on LinkedIn</strong> for the next article in the <em>AI Coding Dictionary in Detail</em> series.</p><p>You can also connect with me here:</p><p><a href="https://www.linkedin.com/in/nitesh-kr-jha-/">linkedin.com/in/nitesh-kr-jha-/</a></p><p>Thanks for reading. 🚀</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=01303b9357fb" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[AI Coding Dictionary in Detail: Parametric Knowledge, Knowledge Cutoff & Contextual Knowledge]]></title>
            <link>https://medium.com/@niteshkrjhag/ai-coding-dictionary-in-detail-parametric-knowledge-knowledge-cutoff-contextual-knowledge-f10916ab04f0?source=rss-9dbcdadc41e4------2</link>
            <guid isPermaLink="false">https://medium.com/p/f10916ab04f0</guid>
            <category><![CDATA[ml-engineering]]></category>
            <category><![CDATA[ai-engineering]]></category>
            <category><![CDATA[knowledge-engineering]]></category>
            <category><![CDATA[context-engineering]]></category>
            <category><![CDATA[ai-agent]]></category>
            <dc:creator><![CDATA[Niteshkrjhag]]></dc:creator>
            <pubDate>Mon, 07 Sep 2026 17:03:41 GMT</pubDate>
            <atom:updated>2026-09-07T17:03:41.298Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LjoTQMPGwDDwim16UILXDg.png" /></figure><p>You ask an AI coding agent:</p><blockquote><em>“How do I create a React component?”</em></blockquote><p>It answers easily.</p><p>Then you ask:</p><blockquote><em>“How do I call our company’s internal </em><em>sdk.create_company() method?”</em></blockquote><p>Suddenly it invents:</p><pre>sdk.company.create(...)</pre><p>The syntax looks believable.</p><p>But that method does not exist.</p><p>Why can the same model know React extremely well and still invent your internal API?</p><p>The answer comes down to three connected concepts:</p><p><strong>Parametric Knowledge → Knowledge Cutoff → Contextual Knowledge</strong></p><p>The easiest mental model is:</p><pre>           PARAMETRIC KNOWLEDGE<br>-&gt; what the model learned during training<br><br>                    vs<br><br>           CONTEXTUAL KNOWLEDGE<br>-&gt; what the model can read right now</pre><p>And sitting between them is another important boundary:</p><p><strong>Knowledge Cutoff</strong></p><h3>1. Parametric Knowledge</h3><h3>What is parametric knowledge?</h3><p><strong>Parametric knowledge is information and patterns a model can produce because they were learned into its parameters during training.</strong></p><p>Remember:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*5_oNK_GUmhjBm1Z3-Dkflg.png" /></figure><p>After training, those learned parameters allow the model to generate useful responses about many topics.</p><p>For example, a model may already know common patterns for:</p><pre>Python<br>JavaScript<br>React<br>SQL<br>HTTP<br>Git<br>Docker</pre><p>because its training exposed it to large amounts of related material.</p><p>You do not need to paste:</p><blockquote><em>“A Python function starts with </em><em>def.”</em></blockquote><p>into every conversation.</p><p>That information can already be available through the model’s learned parameters.</p><p>That is <strong>parametric knowledge</strong>.</p><h3>But is there a database of facts inside the model?</h3><p>No.</p><p>Do not imagine:</p><pre>MODEL DATABASE</pre><pre>React → JavaScript library<br>HTTP 404 → Not Found<br>Python → uses def</pre><p>A language model does not normally retrieve those facts from rows in an internal database.</p><p>Training adjusts enormous collections of numerical parameters so that the model becomes better at producing appropriate outputs.</p><p>Conceptually:</p><pre>Training examples<br>      ↓<br>Prediction errors<br>      ↓<br>Parameter adjustments<br>      ↓<br>Patterns encoded across the network</pre><p>So:</p><blockquote><em>“React knowledge is stored in the parameters”</em></blockquote><p>does <strong>not</strong> mean there is one parameter containing:</p><pre>React = component library</pre><p>Knowledge is distributed across the network.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*AWmXoE52azc36xDr-L19TQ.png" /></figure><h3>Why does common knowledge often work better?</h3><p>Imagine two technologies.</p><h3>Technology A — React</h3><p>The training data may contain enormous amounts of:</p><pre>documentation<br>Stack Overflow discussions<br>GitHub repositories<br>tutorials<br>blog posts<br>code examples</pre><h3>Technology B — Your private company SDK</h3><p>Maybe the public internet contains:</p><pre>zero documentation<br>zero examples<br>zero GitHub repositories</pre><p>Now ask the model:</p><blockquote><em>“How do I create a React component?”</em></blockquote><p>It has strong learned patterns.</p><p>Ask:</p><blockquote><em>“How does </em><em>sdk fetch company details?”</em></blockquote><p>It may have almost nothing reliable to work from.</p><p>So it does what language models are very good at:</p><p><strong>produce something that looks plausible.</strong></p><p>For example:</p><pre>sdk.companies.fetch(company_id)</pre><p>That looks like a perfectly reasonable API.</p><p>It may also be completely imaginary.</p><h3>Parametric knowledge is not equally reliable</h3><p>This is important.</p><p>Do not think:</p><pre>Inside parameters = known perfectly<br>Outside parameters = unknown</pre><p>Reality is fuzzier.</p><p>The model may have:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*fzubm7JVYJNlu7f23zqT6Q.png" /></figure><p>So parametric knowledge has different levels of reliability.</p><p>And the model does not provide a perfect meter saying:</p><pre>I am 99% recalling this.</pre><pre>I am 40% reconstructing this.</pre><pre>I am basically guessing now.</pre><p>That is why a fabricated API method can arrive in exactly the same fluent tone as a real one.</p><h3>2. Knowledge Cutoff</h3><p>Now imagine a different problem.</p><p>The library is not private.</p><p>It is simply <strong>new</strong>.</p><p>Your project uses version 5.</p><p>But the model keeps writing version 3 syntax.</p><p>Why?</p><p>Because the newer version may not have been part of the model’s training knowledge.</p><p>This brings us to the <strong>knowledge cutoff</strong>.</p><h3>What is a knowledge cutoff?</h3><p>A <strong>knowledge cutoff is the approximate boundary beyond which a model’s built-in parametric knowledge should not be assumed to include newer information.</strong></p><p>Suppose, conceptually:</p><pre>Training knowledge<br>─────────────────────────────●──────────────→ time<br>                             ↑<br>                      approximate cutoff</pre><p>A library version released substantially after that point may not exist reliably in the model’s learned parameters.</p><p>So the model might know:</p><pre>SDK v1<br>SDK v2<br>SDK v3</pre><p>but your project now uses:</p><pre>SDK v5</pre><p>When you ask:</p><blockquote><em>“How do I authenticate with this SDK?”</em></blockquote><p>the model may generate the old pattern it knows best.</p><h3>Is the cutoff a perfect hard wall?</h3><p>Not necessarily.</p><p>This is where simplified explanations can become misleading.</p><p>A knowledge cutoff should not be imagined as:</p><pre>Before June 1 → model knows everything</pre><pre>After June 1 → model knows absolutely nothing</pre><p>Training pipelines can include:</p><ul><li>different datasets collected at different times,</li><li>post-training data,</li><li>specialized updates,</li><li>curated information.</li></ul><p>And the <strong>AI product</strong> may have web search or retrieval even when the underlying model’s parameters are older.</p><p>So always separate:</p><pre>MODEL&#39;S BUILT-IN KNOWLEDGE</pre><p>from:</p><pre>PRODUCT&#39;S ACCESS TO CURRENT INFORMATION</pre><p>A model may have an older knowledge boundary while an agent using that model can still search today’s documentation.</p><h3>A practical coding example</h3><p>Suppose a framework changes from:</p><pre>client.old_method()</pre><p>to:</p><pre>client.responses.create()</pre><p>after the model’s training boundary.</p><p>Without current documentation, the model may confidently generate:</p><pre>client.old_method()</pre><p>because that pattern is strong in its parameters.</p><p>Or worse, it may combine old and new patterns:</p><pre>client.responses.old_method()</pre><p>which never existed.</p><p>This is why new SDK versions are especially dangerous for AI coding.</p><p>The generated code often looks reasonable enough that you may not notice the error until:</p><pre>ImportError<br>AttributeError<br>Type checker failure<br>Runtime error</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zxL1z4brLpxP-yI5DCS2dQ.png" /></figure><h3>The solution is not “make the model remember harder”</h3><p>If information is too new for reliable parametric knowledge, increasing confidence or repeatedly asking:</p><blockquote><em>“Are you sure?”</em></blockquote><p>does not solve the problem.</p><p>You need current evidence.</p><p>That brings us to <strong>contextual knowledge</strong>.</p><h3>3. Contextual Knowledge</h3><h3>What is contextual knowledge?</h3><p><strong>Contextual knowledge is information the model can use because it has been supplied or retrieved into the current working context.</strong></p><p>Examples include:</p><pre>Your prompt<br>Source files<br>API documentation<br>Tool results<br>Database schema<br>AGENTS.md<br>Error logs<br>Type definitions<br>Search results</pre><p>Suppose your internal SDK documentation says:</p><pre>Fetch company details with:</pre><pre>client.company.fetch_by_linkedin_https://medium.com/url(url)</pre><p>The model did not know this from training.</p><p>But now the harness reads the documentation and puts that information into context.</p><p>Conceptually:</p><pre>Private SDK docs<br>      ↓<br>Read/Search Tool<br>      ↓<br>Tool Result<br>      ↓<br>CONTEXT<br>      ↓<br>MODEL<br>      ↓<br>correct API usage</pre><p>The knowledge came from the current context rather than the frozen parameters.</p><h3>Parametric vs contextual knowledge</h3><p>This is the distinction worth keeping:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*6lUzgcHB9y4PijPKWWQmwQ.png" /></figure><p>For AI coding, this difference is extremely practical.</p><h3>A familiar working-professional example</h3><p>Imagine hiring a senior backend engineer.</p><p>They already know:</p><pre>Python<br>REST APIs<br>SQL<br>database transactions<br>testing</pre><p>That is similar to <strong>parametric knowledge</strong>.</p><p>Now you give them:</p><pre>your architecture diagram<br>your API docs<br>your database schema<br>today&#39;s error logs<br>your project conventions</pre><p>That is similar to <strong>contextual knowledge</strong>.</p><p>You would not expect the engineer to have magically learned your private database schema before joining the company.</p><p>You put the information in front of them.</p><p>AI agents work the same way.</p><h3>What happens when parametric and contextual knowledge conflict?</h3><p>Suppose the model learned an older API during training:</p><pre>client.chat.completions.create(...)</pre><p>but the documentation currently in context says your project should use:</p><pre>client.responses.create(...)</pre><p>Ideally:</p><pre>Old parametric pattern<br>        ↓<br>Current documentation in context<br>        ↓<br>Model follows current documentation</pre><p>Strong, relevant context can steer the model toward the newer information.</p><p>But do not interpret this as:</p><blockquote><em>“Context permanently overwrote the old knowledge.”</em></blockquote><p>It did not.</p><p>Start another session without those docs and the older parametric pattern may appear again.</p><h3>Why contextual knowledge is the lever you control</h3><p>You normally cannot modify a frontier model’s trained parameters during everyday coding.</p><p>But you can control:</p><pre>Which file gets read<br><br>Which documentation gets retrieved<br><br>Which schema gets loaded<br><br>Which error output reaches the model<br><br>Which project rules are included</pre><p>That makes contextual knowledge one of the strongest practical tools in AI coding.</p><p>When the model lacks knowledge, the engineering question becomes:</p><blockquote><strong><em>How do I bring the correct information into context at the moment it is needed?</em></strong></blockquote><p>That may mean:</p><pre>Search the repository<br>Read the type definition<br>Fetch current documentation<br>Query the database schema<br>Read the actual API response</pre><p>This is often much more useful than repeatedly rewriting the prompt.</p><h3>But more contextual knowledge is not automatically better</h3><p>Remember our earlier context rule:</p><blockquote><strong><em>Relevant information beats maximum information.</em></strong></blockquote><p>Suppose the model needs one current function definition.</p><p>You could load:</p><pre>5K tokens of exact SDK documentation</pre><p>or:</p><pre>200K tokens of the entire documentation website</pre><p>The second option contains more knowledge.</p><p>But it may make the task harder.</p><p>So:</p><pre>GOOD CONTEXTUAL KNOWLEDGE = CURRENT + CORRECT + RELEVANT + ENOUGH</pre><p>not:</p><pre>EVERYTHING WE CAN FIND</pre><h3>The Three Concepts Together</h3><p>Now the hierarchy is simple:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*NO1hrSjNlaXlM_YvPjcVig.png" /></figure><p>When the model struggles with an API, ask:</p><pre>Does the model know this reliably<br>from its parameters?</pre><p>If not:</p><p>Is it too new?<br>Is it too obscure?<br>Is it private?</p><p>Then:</p><pre>bring the authoritative source into context</pre><h3>The Three Definitions Worth Remembering</h3><h3>Parametric Knowledge</h3><p><strong>Knowledge and patterns the model can produce because they were learned into its parameters during training.</strong></p><p>It can be strong for common topics and unreliable for obscure, private, or changing information.</p><h3>Knowledge Cutoff</h3><p><strong>The approximate freshness boundary of a model’s built-in parametric knowledge.</strong></p><p>Information newer than that should not be assumed to exist reliably in the parameters.</p><h3>Contextual Knowledge</h3><p><strong>Information available to the model because it has been supplied or retrieved into the current context.</strong></p><p>For AI coding, this is the knowledge source you can most directly control.</p><h3>The Practical Lesson</h3><p>When an AI coding agent invents an API, do not immediately conclude:</p><blockquote><em>“The model is bad at coding.”</em></blockquote><p>Ask:</p><blockquote><strong><em>Where was it supposed to get the correct information from?</em></strong></blockquote><p>If the answer is:</p><blockquote><em>“Its training.”</em></blockquote><p>you are relying on parametric knowledge.</p><p>If the technology is:</p><ul><li>new,</li><li>obscure,</li><li>internal,</li><li>rapidly changing,</li></ul><p>that may be unreliable.</p><p>Instead:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FxVN6TvRfvDjHM-FT6nqmg.png" /></figure><p>That is one of the most reliable patterns in AI coding:</p><blockquote><strong><em>Use parametric knowledge for broad capability. Use contextual knowledge for specific truth.</em></strong></blockquote><p>If this article helped clarify where a model’s “knowledge” actually comes from, <strong>react to it and share your thoughts in the comments</strong>.</p><p><strong>Follow me here on LinkedIn</strong> for the next article in the <em>AI Coding Dictionary in Detail</em> series.</p><p>You can also connect with me here:</p><p><a href="https://www.linkedin.com/in/nitesh-kr-jha-/">linkedin.com/in/nitesh-kr-jha-/</a></p><p>Thanks for reading. 🚀</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=f10916ab04f0" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>