{
  "version": "https://jsonfeed.org/version/1.1",
  "title": "Sohab Sk: blog",
  "home_page_url": "https://sohab.dev/blog",
  "feed_url": "https://sohab.dev/feed.json",
  "description": "Senior Software Engineer building reliable AI agents, multi-agent workflows, and scalable software systems.",
  "language": "en",
  "authors": [
    {
      "name": "Sohab Sk",
      "url": "https://sohab.dev"
    }
  ],
  "items": [
    {
      "id": "https://sohab.dev/blog/package-by-feature",
      "url": "https://sohab.dev/blog/package-by-feature",
      "title": "Package by feature, when an agent writes the code",
      "summary": "Why I put features at the top of the folder tree now that agents change my code more than I do, and the rules that keep it from rotting.",
      "content_html": "<p>For years I organised code by layer: controllers here, services there, repositories somewhere else. It suited me. I wrote most of the code, so I knew where everything lived.</p>\n<p>Now an agent touches my code more than I do, and it knows where nothing lives. It searches, then it works. That changes what a folder tree is for. It isn't only a map for me anymore. It's the first thing the agent reads.</p>\n<h2 id=\"same-change-two-layouts\">Same change, two layouts<a class=\"heading-anchor\" aria-label=\"Link to this section\" href=\"#same-change-two-layouts\">#</a></h2>\n<p>Ask an agent to add discount codes to checkout.</p>\n<p><em>Figure: The same change in both layouts: five files either way, in five folders or in one.</em> <a href=\"https://sohab.dev/blog/package-by-feature#figure-layout-change\">Open the interactive figure</a></p>\n<p>It's the same five files either way. In a layered tree they sit in five folders, and in each one the agent has to pick checkout's file out from every other feature's. In a feature tree they sit in one folder. Less searching, and less chance of editing a neighbour's file by mistake.</p>\n<p>Nobody has measured this, as far as I can find. There are write-ups from practitioners and papers on <a href=\"https://arxiv.org/abs/2606.11976\">how agents explore repositories</a>, but no study of folder layouts. So this is reasoning plus what I see at work, where I've moved to package by feature: the agent searches for the feature name, lands in one folder, and stays there.</p>\n<p>None of it is new. Package by feature is old Java advice, and Jimmy Bogard's <a href=\"https://jimmybogard.com/vertical-slice-architecture/\">vertical slice architecture</a> says the same from .NET. Jeremy Miller, who wrote Wolverine, argues that a codebase's structure <a href=\"https://letsdatascience.com/news/wolverine-enables-ai-friendly-vertical-slice-development-a7759c4d\">becomes part of the prompt</a>. Agents just raise the price of ignoring it.</p>\n<h2 id=\"features-on-top-light-layers-inside\">Features on top, light layers inside<a class=\"heading-anchor\" aria-label=\"Link to this section\" href=\"#features-on-top-light-layers-inside\">#</a></h2>\n<p>Top level by feature. Inside, I name files by role: <code>checkout.service.ts</code>, <code>checkout.repository.ts</code>, <code>checkout.test.ts</code>. A dot-suffix tells an agent what a file is without opening it, and you can match it with a glob, which matters in a moment. I keep nesting shallow and start flat. When a word in the glossary needs its own boundary, the folder becomes a domain. That's as much strategic DDD as I use.</p>\n<p>Two small files help. A short <code>AGENTS.md</code> per feature says what it's for, what it exposes and what it must not import. A root <code>GLOSSARY.md</code> keeps the code and the agent on the same words. Claude Code <a href=\"https://code.claude.com/docs/en/memory\">loads subdirectory instruction files on demand</a>, so a feature's rules show up when the agent starts working in it.</p>\n<h2 id=\"draw-the-lines-then-fence-them\">Draw the lines, then fence them<a class=\"heading-anchor\" aria-label=\"Link to this section\" href=\"#draw-the-lines-then-fence-them\">#</a></h2>\n<p>A human draws the boundaries. They're costly to move and invisible in a single diff, so I don't leave them to the agent. My test is whether two different people would own the two sides.</p>\n<p>Folders won't hold the line alone. An agent takes the shortest import path, and the tests still pass. So other features import only through a feature's <code>index.ts</code>, and CI checks it with <a href=\"https://github.com/sverweij/dependency-cruiser\">dependency-cruiser</a>:</p>\n<pre class=\"shiki github-dark-default\" style=\"background-color:#0d1117;color:#e6edf3\" tabindex=\"0\"><code><span class=\"line\"><span style=\"color:#8B949E\">// .dependency-cruiser.cjs</span></span>\n<span class=\"line\"><span style=\"color:#79C0FF\">module</span><span style=\"color:#E6EDF3\">.</span><span style=\"color:#79C0FF\">exports</span><span style=\"color:#FF7B72\"> =</span><span style=\"color:#E6EDF3\"> {</span></span>\n<span class=\"line\"><span style=\"color:#E6EDF3\">  forbidden: [</span></span>\n<span class=\"line\"><span style=\"color:#E6EDF3\">    {</span></span>\n<span class=\"line\"><span style=\"color:#E6EDF3\">      name: </span><span style=\"color:#A5D6FF\">\"no-deep-feature-imports\"</span><span style=\"color:#E6EDF3\">,</span></span>\n<span class=\"line\"><span style=\"color:#E6EDF3\">      comment: </span><span style=\"color:#A5D6FF\">\"Import another feature through its index.ts only.\"</span><span style=\"color:#E6EDF3\">,</span></span>\n<span class=\"line\"><span style=\"color:#E6EDF3\">      severity: </span><span style=\"color:#A5D6FF\">\"error\"</span><span style=\"color:#E6EDF3\">,</span></span>\n<span class=\"line\"><span style=\"color:#E6EDF3\">      from: { path: </span><span style=\"color:#A5D6FF\">\"^src/features/([^/]+)/\"</span><span style=\"color:#E6EDF3\"> },</span></span>\n<span class=\"line\"><span style=\"color:#E6EDF3\">      to: {</span></span>\n<span class=\"line\"><span style=\"color:#E6EDF3\">        path: </span><span style=\"color:#A5D6FF\">\"^src/features/[^/]+/\"</span><span style=\"color:#E6EDF3\">,</span></span>\n<span class=\"line\"><span style=\"color:#E6EDF3\">        pathNot: [</span><span style=\"color:#A5D6FF\">\"^src/features/$1/\"</span><span style=\"color:#E6EDF3\">, </span><span style=\"color:#A5D6FF\">\"^src/features/[^/]+/index</span><span style=\"color:#FF7B72\">\\.</span><span style=\"color:#A5D6FF\">ts$\"</span><span style=\"color:#E6EDF3\">],</span></span>\n<span class=\"line\"><span style=\"color:#E6EDF3\">      },</span></span>\n<span class=\"line\"><span style=\"color:#E6EDF3\">    },</span></span>\n<span class=\"line\"><span style=\"color:#E6EDF3\">  ],</span></span>\n<span class=\"line\"><span style=\"color:#E6EDF3\">};</span></span></code></pre>\n<p>The <code>comment</code> is the message the agent sees when it fails, so write it as an instruction. That's the same idea as the lint message in my <a href=\"https://sohab.dev/blog/harness-engineering\">harness post</a>.</p>\n<p>The other thing that rots is <code>shared/</code>, because agents love to dedupe. My rule: duplicate until the third use, and shared code holds no business logic. If it does, a feature boundary is leaking.</p>\n<h2 id=\"in-my-own-repos\">In my own repos<a class=\"heading-anchor\" aria-label=\"Link to this section\" href=\"#in-my-own-repos\">#</a></h2>\n<p><a href=\"https://plico.sohab.dev\">Plico</a>'s packages are layers by design (contracts, sdk, core, runtime, server, cli), because they're published separately. Inside them it's features: each CLI command is a module in <code>commands/</code>, each server route one in <code>routes/</code>, registered instead of piled into a dispatcher. Its <code>AGENTS.md</code> says to add them \"as new modules and register them\", keeps files around 250 lines, and points at a root <code>GLOSSARY.md</code>.</p>\n<h2 id=\"when-layers-are-fine\">When layers are fine<a class=\"heading-anchor\" aria-label=\"Link to this section\" href=\"#when-layers-are-fine\">#</a></h2>\n<p>A small repo (one source puts the line at about 10K lines), a throwaway script, a pure library: layers are fine, and agents know MVC well. This is for repos that keep growing. Cross-cutting concerns like auth and logging also belong to no feature, and I don't have a tidy answer for them yet. A small shared template is the usual advice.</p>\n<h2 id=\"try-it-tomorrow\">Try it tomorrow<a class=\"heading-anchor\" aria-label=\"Link to this section\" href=\"#try-it-tomorrow\">#</a></h2>\n<ul>\n<li>Pick the feature you change most and list the folders a typical change touches.</li>\n<li>Move its files together, keep the role suffixes, and add its <code>AGENTS.md</code>.</li>\n<li>Add the import rule and let CI fail on the first deep import.</li>\n</ul>\n<div class=\"prompt-box\"><div class=\"prompt-head\"><p class=\"prompt-title\">Audit your repo's boundaries</p></div><pre class=\"prompt-text\"><code>Map the features in this repository: for each one, list its files and where they live. Then find imports that reach into another feature's internals instead of its public entry, and anything in shared/ that contains business logic. Suggest where a boundary rule or a feature AGENTS.md would help most, but don't change any code yet.</code></pre></div>\n<h2 id=\"sources\">Sources<a class=\"heading-anchor\" aria-label=\"Link to this section\" href=\"#sources\">#</a></h2>\n<ul>\n<li>Jimmy Bogard, <a href=\"https://jimmybogard.com/vertical-slice-architecture/\">Vertical Slice Architecture</a></li>\n<li>Jeremy Miller on Wolverine and AI-friendly vertical slices, <a href=\"https://letsdatascience.com/news/wolverine-enables-ai-friendly-vertical-slice-development-a7759c4d\">summary</a></li>\n<li>Very Good Ventures, <a href=\"https://verygood.ventures/blog/feature-first-clean-architecture/\">Feature-First Clean Architecture</a></li>\n<li>InfoQ, <a href=\"https://www.infoq.com/articles/skeleton-architecture\">Skeleton architecture</a></li>\n<li>Anthropic, <a href=\"https://code.claude.com/docs/en/memory\">Claude Code memory</a></li>\n<li><a href=\"https://arxiv.org/abs/2606.11976\">Exploration Structure in LLM Agents for Multi-File Change Localization</a> (June 2026)</li>\n</ul>",
      "date_published": "2026-11-10T00:00:00.000Z",
      "tags": [
        "ai-agents",
        "architecture"
      ],
      "image": "https://sohab.dev/blog/package-by-feature/og.png"
    },
    {
      "id": "https://sohab.dev/blog/harness-engineering",
      "url": "https://sohab.dev/blog/harness-engineering",
      "title": "Harness engineering: the part of an agent that isn't the model",
      "summary": "What an agent harness is, why it matters as much as the model, and the small habit that keeps improving it.",
      "content_html": "<p>When a coding agent does something dumb, my first reflex is to blame the model. Usually the model is fine. It ran the wrong test command because nothing told it the right one. It said \"done\" because nothing checked. That isn't a model problem. It's a harness problem.</p>\n<h2 id=\"agent--model--harness\">Agent = Model + Harness<a class=\"heading-anchor\" aria-label=\"Link to this section\" href=\"#agent--model--harness\">#</a></h2>\n<p>That's Vivek Trivedy's definition at LangChain, and it's the shortest one I know. The harness is \"every piece of code, configuration, and execution logic that isn't the model itself.\" If it isn't the model, it's the harness.</p>\n<p>Here's what's in one:</p>\n<p><em>Figure: The six parts of a harness, after LangChain and Addy Osmani.</em> <a href=\"https://sohab.dev/blog/harness-engineering#figure-harness-anatomy\">Open the interactive figure</a></p>\n<p>Does it matter more than the model? Addy Osmani thinks so: \"A decent model with a great harness beats a great model with a bad harness.\" LangChain says it moved its coding agent from Top 30 to Top 5 on Terminal Bench 2.0 by changing only the harness. Neither publishes scores, so read that as experience rather than measurement. It matches mine, though.</p>\n<h2 id=\"guides-and-sensors\">Guides and sensors<a class=\"heading-anchor\" aria-label=\"Link to this section\" href=\"#guides-and-sensors\">#</a></h2>\n<p>Birgitta Böckeler has the most useful way to sort the parts. A <strong>guide</strong> steers the agent before it acts, like an <code>AGENTS.md</code> line or a skill. A <strong>sensor</strong> catches it afterwards, like a test, a linter or an AI reviewer.</p>\n<p>You want both. With only sensors, the agent \"keeps repeating the same mistakes.\" With only guides, it \"encodes rules but never finds out whether they worked.\"</p>\n<p>My favourite detail from her article: a lint message written for the agent, with the fix in it, is \"a positive kind of prompt injection.\"</p>\n<h2 id=\"the-ratchet\">The ratchet<a class=\"heading-anchor\" aria-label=\"Link to this section\" href=\"#the-ratchet\">#</a></h2>\n<p>Mitchell Hashimoto turned this into a habit, and that habit is where the name comes from: \"anytime you find an agent makes a mistake, you take the time to engineer a solution such that the agent never makes that mistake again.\"</p>\n<p>The fix is either a line in <code>AGENTS.md</code>, for simple things like wrong commands, or a real tool, like a script that runs filtered tests. Each one tightens the harness a notch, and it doesn't slip back.</p>\n<p><em>Figure: The ratchet: every repeated mistake ends as a file, and the file runs every time.</em> <a href=\"https://sohab.dev/blog/harness-engineering#figure-ratchet-loop\">Open the interactive figure</a></p>\n<p>Osmani's rule of thumb follows from it: every line in a good <code>AGENTS.md</code> should trace back to something that went wrong. If you can't name the mistake a rule prevents, it probably doesn't belong.</p>\n<h2 id=\"in-my-own-repos\">In my own repos<a class=\"heading-anchor\" aria-label=\"Link to this section\" href=\"#in-my-own-repos\">#</a></h2>\n<p><a href=\"https://plico.sohab.dev\">Plico</a>, the agent app kit I'm building, has an <code>AGENTS.md</code> that tells the agent to build before typechecking, because the packages resolve each other through <code>dist</code>. That's the guide. <code>pnpm check</code> runs lint, build, typecheck and tests, so the agent finds out it was wrong before I read the diff. That's the sensor.</p>\n<p>My <code>pr</code> skill in <a href=\"https://sohab.dev/projects/dev-skills\">dev-skills</a> grew the same way. Real pull requests showed gaps, so it gained a <code>Closes #&#x3C;issue></code> line and a fallback for changes with nothing to demo. Small and boring, which is the point: a harness is mostly small files that exist because something once went wrong.</p>\n<h2 id=\"try-it-tomorrow\">Try it tomorrow<a class=\"heading-anchor\" aria-label=\"Link to this section\" href=\"#try-it-tomorrow\">#</a></h2>\n<ul>\n<li>Write down every mistake you see twice. Fix it in a file, not in the chat.</li>\n<li>Ask whether the agent didn't know (add a guide) or nothing told it it was wrong (add a sensor).</li>\n<li>Prefer a check you can run. A failing test beats a sentence in a prompt.</li>\n<li>Make failures say what to do next.</li>\n</ul>\n<div class=\"prompt-box\"><div class=\"prompt-head\"><p class=\"prompt-title\">Audit your AGENTS.md</p></div><pre class=\"prompt-text\"><code>Read the AGENTS.md (or CLAUDE.md) in this repository. For each rule, tell me which repeated mistake it prevents, and whether a test, lint rule or script could enforce it instead. Flag rules with no clear mistake behind them. Suggest the three most useful changes, but don't edit anything yet.</code></pre></div>\n<p>Some of this isn't solved yet. Böckeler points out that a harness has nothing like code coverage, and that when sensors never fire, you can't tell good code from weak detection. Someone still has to notice the mistake. For now, that's you.</p>\n<h2 id=\"sources\">Sources<a class=\"heading-anchor\" aria-label=\"Link to this section\" href=\"#sources\">#</a></h2>\n<ul>\n<li>Mitchell Hashimoto, <a href=\"https://mitchellh.com/writing/my-ai-adoption-journey\">My AI Adoption Journey</a> (February 2026)</li>\n<li>Vivek Trivedy, <a href=\"https://www.langchain.com/blog/the-anatomy-of-an-agent-harness\">The Anatomy of an Agent Harness</a>, LangChain (March 2026)</li>\n<li>Birgitta Böckeler, <a href=\"https://martinfowler.com/articles/harness-engineering.html\">Harness engineering for coding agent users</a>, martinfowler.com (April 2026)</li>\n<li>Addy Osmani, <a href=\"https://addyosmani.com/blog/agent-harness-engineering/\">Agent Harness Engineering</a> (April 2026)</li>\n</ul>",
      "date_published": "2026-11-10T00:00:00.000Z",
      "tags": [
        "ai-agents",
        "harness-engineering"
      ],
      "image": "https://sohab.dev/blog/harness-engineering/og.png"
    }
  ]
}