feat(route): add /humanlayer/blog route#21565
Open
zj1123581321 wants to merge 3 commits intoDIYgod:masterfrom
Open
feat(route): add /humanlayer/blog route#21565zj1123581321 wants to merge 3 commits intoDIYgod:masterfrom
zj1123581321 wants to merge 3 commits intoDIYgod:masterfrom
Conversation
Add RSS feed for HumanLayer blog (www.humanlayer.dev/blog), scraping blog listing and full article content with cheerio. via [HAPI](https://hapi.run) Co-Authored-By: HAPI <noreply@hapi.run> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
Successfully generated as following: http://localhost:1200/humanlayer/blog - Success ✔️<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:atom="http://www.w3.org/2005/Atom" version="2.0">
<channel>
<title>HumanLayer Blog</title>
<link>https://www.humanlayer.dev/blog</link>
<atom:link href="http://localhost:1200/humanlayer/blog" rel="self" type="application/rss+xml"></atom:link>
<description>HumanLayer Blog - Powered by RSSHub</description>
<generator>RSSHub</generator>
<webMaster>contact@rsshub.app (RSSHub)</webMaster>
<language>en</language>
<lastBuildDate>Tue, 31 Mar 2026 06:51:52 GMT</lastBuildDate>
<ttl>5</ttl>
<item>
<title>Long-Context Isn't the Answer</title>
<description><p style="display:block;color:var(--text-secondary)" class="mb-4">Anthropic just switched the default model in Claude Code to Opus 4.6 with a 1M context window. We tried it when it launched. But now we're switching back to Opus 4.5</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->How about some context?</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Unlike previous Claude Opus models which have a ~ 200k context window, Opus 4.6 has as 1M context window. This was very exciting for us!</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We spend a lot of time working on hard problems in large enterprise codebases, and if the model can reliably hold more of the codebase in its head at a time, so to speak, then that creates new possibilities for the scale of problem that can be solved in a single context window.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It would mean less compaction (whether <a href="https://www.humanlayer.dev/blog/advanced-context-engineering" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">frequent intentional compaction</a> or auto-compact), and less "context pressure" to solve the problem before your context window fills up.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">As Calvin French-Owen, who helped launch Codex last year, <a href="https://youtu.be/qwmmWzPnhog?si=ReRWTavUKTItIGGr&amp;t=918" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">puts it in an episode of YC's Lightcone podcast</a>:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">...imagine you're a college student. You're taking an exam. In the first five minutes of that exam, you're like, "Oh, I have all the time in the world. I'll do a great job. I'll think through each of these problems."</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Let's say you have like five minutes left and you still have half the exam left. You're like, "Oh man, I just got to do whatever I can." Like, that's the LLM with a context window</p>
</blockquote>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->More context, less instruction adherence</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">While the context window is dramatically larger, we noticed over the course of a couple of weeks that instruction adherence was dramatically degraded, and not just at longer context lengths.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Even well-within what we would consider the <a href="https://youtu.be/rmvDxxNubIg?si=O17nmS3SScaAkpp-&amp;t=355" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">smart zone</a> of a 200k-context frontier model, the model was less precise. It would ignore design documents and other inputs when writing a plan file. It would make trivial mistakes, or misunderstand simple instructions - or worse, directly disobey them.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">At longer context lengths, the degradation was even steeper - like the user instructions were getting drowned out by the intermediate tool results and mass of accumulated context.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->What determines instruction adherence?</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We've written about the concept of <a href="https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the instruction budget</a> before - a measurable property of LLMs which describes how many instructions they can follow reasonably well before instruction adherence drops off.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It's different for each model, but it's a function primarily of the quality of the model's instruction tuning, and more importantly for our purposes, it is <strong style="color:var(--text-primary)">strongly correlated with the size of the model</strong>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/writing-a-good-claude-md/instructionfollowing.png" alt="Instruction following" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">You can clearly see that the larger models from the <a href="https://arxiv.org/pdf/2507.11538" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">study</a> can follow dramatically more instructions before adherence drops off.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Instruction adherence at long context lengths</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Why does this matter?</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">When a lab offers an extended-context version of a model, you're usually not getting a bigger model with more parameters and therefore a larger "instruction budget" to go with the larger context window - you're likely getting the same model with some clever math (e.g. <a href="https://arxiv.org/pdf/2309.00071" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">YaRN</a>) to extend the sequence length the model can attend to, and probably some more post-training to stabilize the model at the longer sequence lengths.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">This means that while the context window size increases, the instruction budget remains the same. You can fit more context and more instructions in the context window, but the model isn't actually better at attending to those instructions over the context length.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Instruction-following as needle in a haystack</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">You can think of your context window as a haystack where all of your tool calls and documents and files are hay - every line in your CLAUDE.md file, every instruction in your tool descriptions, every tool result, every instruction in your system prompt, and every user message.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The quality &amp; correctness of the agent's next step depends on the LLM's ability to find a needle in there: namely, the instruction(s) in the context window that are most-relevant to the current state of the context window, which give it the information it needs to make the correct decision about its next action.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Now imagine we increase the size of the haystack by 500% - but the size of the needle remains the same. Unless our ability to find the needle also increases by 500%, we will have a dramatically harder time finding it. The extra context isn't really helping us - it's just digging us deeper into the dumb zone.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/long-context.jpg" alt="long context" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->What Works Instead</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Instead of trying to stuff as much information in a context window as possible and having the LLM reason over it, we found that the context management techniques we had been using had to be used even <em style="color:var(--text-secondary)">more</em> aggressively to keep Opus 4.6 1M on track.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">In my post on <a href="https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">harness engineering</a>, I wrote about this as the limit case for using sub-agents:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/limit-case.png" alt="limit case" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The day after I published it, I decided maybe it wasn't such a bad idea, and sat down and wrote this skill:</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">---
</span>name: subagent-orchestrator
<!-- -->description: orchestrate sub-agents to accomplish complex long-horizon tasks without losing coherency by delegating to sub-agents
<!-- -->---
<!-- -->
<!-- -->This skill provides you with **CRITICAL** instructions that will help you to maintain coherency in long-horizon context-heavy tasks.
<!-- -->
<!-- -->You have a large number of tools available to you. The most important one is the one that allows you to dispatch sub-agents: either `Agent` or `Task`.
<!-- -->
<!-- -->All non-trivial operations should be delegated to sub-agents. You should delegate research and codebase understanding tasks to codebase-analyzer, codebase-locator and pattern-locator sub-agents.
<!-- -->
<!-- -->You should delegate running bash commands (particularly ones that are likely to produce lots of output) such as investigating with the `aws` CLI, using the `gh` CLI, digging through logs to `Bash` sub-agents.
<!-- -->
<!-- -->You should use separate sub-agents for separate tasks, and you may launch them in parallel - but do not delegate multiple tasks that are likely to have significant overlap to separate sub-agents.
<!-- -->
<!-- -->IMPORTANT: if the user has already given you a task, you should proceed with that task using this approach.
<!-- -->
<!-- -->If you have not already been explicitly given a taks, you should ask the user what task they would like for you to work on - do not assume or begin working on a ticket automatically.</code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">I found that using this skill in combination with our existing workflow skills helped me keep Opus coherent at longer context lengths. Why?
As I wrote about in that post, sub-agents encapsulate context and ensure that only highly-relevant context (the prompt, and the focused sub-agent result) end up in the context window, avoiding <a href="https://research.trychroma.com/context-rot" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">context rot</a>:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/context-firewall.png" alt="context firewall" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->How we're incorporating this at HumanLayer</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We have had a feature in the tool for a while that warns the user when they're context is getting high. We used to set this at around %40 of sonnets 168k token window (200k - 32k reserved for output). This came out to about 100k tokens.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">To help users maximize instruction adherence and intelligence on hard codebase problems, we've updated our context warnings for long-context models to trigger at the 100k token mark instead of 40% of the usable context. For opus 1m this is only 10% of the context window.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->TL;DR</h2>
<div class="pl-8 mb-6"><ol class="list-decimal space-y-4" style="color:var(--text-secondary)">
<li>Long-context models degrade at all context lengths, not just long ones.</li>
<li>More context isn't more capability - the instruction budget doesn't scale with the context window.</li>
<li>Context isolation beats context expansion. Sub-agents, progressive disclosure, and <a href="https://www.humanlayer.dev/blog/context-efficient-backpressure" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">context-efficient backpressure</a> keep each context window small, focused, and in the smart zone.</li>
</ol></div></description>
<link>https://www.humanlayer.dev/blog/long-context-isnt-the-answer</link>
<guid isPermaLink="false">https://www.humanlayer.dev/blog/long-context-isnt-the-answer</guid>
<pubDate>Sun, 22 Mar 2026 16:00:00 GMT</pubDate>
<author>Kyle</author>
</item>
<item>
<title>Getting Claude to Actually Read Your CLAUDE.md</title>
<description><p style="display:block;color:var(--text-secondary)" class="mb-4">Claude Code wraps your CLAUDE.md in a <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;system_reminder&gt;</code> that explicitly tells the model the contents "may or may not be relevant." The longer your file gets, the more Claude seems to treat individual sections as optional.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">wrote before</a> about keeping these files concise and avoiding stuff that belongs in a linter. But even after trimming things down, I kept running into cases where Claude would ignore testing instructions while writing tests, or skip our API conventions when building endpoints.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Conditional <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;important if&gt;</code> blocks</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">What's been working for me: wrapping sections in <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;important if="condition"&gt;</code> tags.</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">&lt;important if="you are writing or modifying tests"&gt;
</span>- Use `createTestApp()` helper for integration tests
<!-- -->- Mock database with `dbMock` from `packages/db/test`
<!-- -->- Test fixtures live in `__fixtures__/` directories
<!-- -->&lt;/important&gt;</code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We don't have a rigorous explanation for why this helps. My guess is that the explicit condition gives Claude a clearer signal about when to apply the instructions, rather than leaving it to decide relevance on its own. Whatever the mechanism, we've seen noticeably better adherence on tasks where only some sections of my CLAUDE.md should apply.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">A few things I've learned:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">Don't wrap everything.</strong> Project identity, directory structure, and tech stack are relevant to basically every task. The conditional blocks are for testing setup or deployment procedures that only matter sometimes.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">Make conditions specific.</strong> <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;important if="you are writing code"&gt;</code> matches almost everything and defeats the purpose. I try to make each condition narrow enough that it only fires when I actually want those rules applied.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->A skill to automate this</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">I did a lot of restructuring CLAUDE.md files by hand, so I made a Claude Code skill that does the rewrite. It pulls out the foundational stuff, wraps domain-specific sections in conditional blocks, and cleans up some common problems (stale code snippets, style rules that should be in a linter, vague instructions that don't actually help).</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It's not perfect—you'll probably want to review what it produces—but it's a decent starting point.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Try it</h2>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">npx skills add humanlayer/skills --skill improve-claude-md</span></code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Then in your project:</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">/improve-claude-md</span></code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It reads your existing CLAUDE.md and outputs a rewritten version. Source is at <a href="https://github.com/humanlayer/skills/tree/main/plugins/improve-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">github.com/humanlayer/skills</a>.</p></description>
<link>https://www.humanlayer.dev/blog/stop-claude-from-ignoring-your-claude-md</link>
<guid isPermaLink="false">https://www.humanlayer.dev/blog/stop-claude-from-ignoring-your-claude-md</guid>
<pubDate>Mon, 16 Mar 2026 16:00:00 GMT</pubDate>
<author>Dex</author>
</item>
<item>
<title>Skill Issue: Harness Engineering for Coding Agents</title>
<description><p style="display:block;color:var(--text-secondary)" class="mb-4">We've spent the past year watching coding agents fail in every conceivable way: ignoring instructions, executing dangerous commands un-prompted, and going in circles on the simplest of tasks.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We've seen teams ship immense amounts of slop. We've even <a href="https://www.youtube.com/live/99Kxkemj1g8?si=tVsK88M3XPyo0urD&amp;t=20967" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">shipped a little bit of slop ourselves</a>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Every time, the instinct was the same:</p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li>"We just need better models, GPT-6 will fix it"</li>
<li>"We just need better instruction-following"</li>
<li>"It'll work once [niche library I'm using] is in the training data"</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">But over the course of dozens of projects and hundreds of agent sessions, we kept arriving at the same conclusion: it's not a model problem. It's a <strong style="color:var(--text-primary)">configuration problem</strong>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Yes, models will get smarter, and some existing failure modes will disappear. And then because they are smarter, we will give them new problems which are bigger and harder, and they will <strong style="color:var(--text-primary)">continue to fail in unexpected ways</strong>. Unexpected failures modes are a fundamental problem for non-deterministic systems.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/gpt-6.png" alt="gpt-6" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">So instead of praying for <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">gpt-6.4-codex-ultrahigh_extended</code> to save us all, we try to focus on answering the question of <em style="color:var(--text-secondary)">"how do we get the most out of <strong style="color:var(--text-primary)">today's</strong> models?"</em></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">There are lots of ways to get better performance out of your coding agent. If you use coding agents for moderately hard tasks, you've probably configured your coding agent a bit. Have you used skills? MCP servers? Sub-agents? Memory? AGENTS.md files?</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">coding agent = AI model(s) + harness</span></code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">These are all technically separate concepts, but they are all part of the coding agent's configuration surface. We call this the <strong style="color:var(--text-primary)">coding agent's harness</strong>, and we think of it as <a href="https://www.vtrivedy.com/posts/claude-code-sdk-haas-harness-as-a-service" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the agent’s runtime</a>, or as its peripherals: what does the model use to interact with its environment?</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Harness Engineering</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">Harness engineering</strong>, coined by <a href="https://x.com/Vtrivedy10" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Viv</a>, describes the practice of leveraging these configuration points to customize and improve your coding agent's output quality and reliability.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/harness-components.png" alt="harness components" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer">
<em style="color:var(--text-secondary)">Image from <a href="https://blog.langchain.com/the-anatomy-of-an-agent-harness/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Viv's post</a></em></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">As <a href="https://mitchellh.com/writing/my-ai-adoption-journey#step-5-engineer-the-harness" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Mitchell Hashimoto put it</a>, harness engineering</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">[...] is the idea that 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>
</blockquote>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->... as a Subset of Context Engineering</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We view harness engineering as a subset of <a href="https://www.humanlayer.dev/blog/advanced-context-engineering" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">context engineering</a>. Coined by my cofounder <a href="https://x.com/dexhorthy" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Dex</a> in <a href="https://github.com/humanlayer/12-factor-agents" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">12-factor agents</a>, context engineering is a superset of “prompt engineering” and a variety of other techniques for systematically improving AI agents’ reliability.&nbsp;You can find the original talk on <a href="https://www.youtube.com/watch?v=IS_y40zY-hc" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">here</a>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Harness engineering then is the subset of context engineering which primarily involves leveraging harness configuration points to carefully manage the context windows of coding agents.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/harness-engineering.png" alt="harness engineering as context engineering" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It answers:</p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li>How do we give our coding agent new capabilities?</li>
<li>How do we teach it things about our codebase that aren’t in the training data?</li>
<li>How do we add determinism beyond <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">CRITICAL: always do XYZ</code> in the system message?</li>
<li>How do we adapt the agent’s behavior for our specific codebase?</li>
<li>How do we increase task success rates beyond “magic prompts”?</li>
<li>How do we prevent our context window from inflating too rapidly, or with too much bad context?</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Skills, MCP servers, sub-agents, hooks, and back-pressure mechanisms are all tactical solutions we’ve arrived at.</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->Views on Harness Engineering</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Viv’s posts on harness engineering are worth reading alongside this one — <a href="https://www.vtrivedy.com/posts/claude-code-sdk-haas-harness-as-a-service" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the first</a> frames the four customization levers (system prompt, tools/MCPs, context, sub-agents), and <a href="https://blog.langchain.com/the-anatomy-of-an-agent-harness/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the second</a> works backwards from what models <em style="color:var(--text-secondary)">can’t</em> do natively to derive why each harness component exists.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/backwards.png" alt="working backwards from what models can't do natively" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer">
<em style="color:var(--text-secondary)">Image from <a href="https://blog.langchain.com/the-anatomy-of-an-agent-harness/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Viv's post</a></em></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We’d add two levers he doesn’t emphasize:</p>
<div class="pl-8 mb-6"><ol class="list-decimal space-y-4" style="color:var(--text-secondary)">
<li><strong style="color:var(--text-primary)">hooks</strong> for automated integration and deterministic control flow</li>
<li><strong style="color:var(--text-primary)">skills</strong> for progressive disclosure of knowledge. (Dex likes to refer to them as "Instruction Modules" - more on this in another post.)</li>
</ol></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">After months of solving hard problems in complex brownfield enterprise-scale codebases, we have found that sub-agents are a particularly powerful lever. When working on hard problems that require many, many context windows to solve, <strong style="color:var(--text-primary)">sub-agents are the key to maintaining coherency across many sessions</strong>. Sub-agents <strong style="color:var(--text-primary)">function as a "context firewall"</strong> that ensures discrete tasks can run in isolated context windows so none of the intermediate noise accumulates in your parent thread which is responsible for orchestration, and you can maintain coherency for much, much longer.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/context-firewall.png" alt="context firewall" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">OpenAI recently wrote a <a href="https://openai.com/index/harness-engineering/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">blog post</a> on the topic as well. There's some great content in there, and it seems to indicate that they view harness engineering as configuring everything <em style="color:var(--text-secondary)">outside</em> of the agent's runtime. It's more focused on back-pressure and verification mechanisms. (Although this may be a mis-reading; the post is somewhat unclear: the word "harness" only appears once in the text of the post, and in reference to evals rather than harness engineering itself.)</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->But What About Post-Training?</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Given that frontier coding models are post-trained on their harnesses (e.g. Claude in Claude Code, GPT-5 Codex in Codex), some will argue that the best harness and/or configuration is the one that the model was trained on.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">For example, the Codex models are so tightly coupled with the Codex harness's <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">apply_patch</code> tool that <a href="https://opencode.ai/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">OpenCode</a> — built as an open-source alternative to Claude Code — had to <a href="https://github.com/anomalyco/opencode/pull/9127" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">add an <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">apply_patch</code> tool</a> specifically for GPT/Codex models to mimic the Codex harness to improve the Codex models' performance in the OpenCode harness - while Claude and other models still use normal <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">edit</code> and <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">write</code> tools.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">This <em style="color:var(--text-secondary)">can</em> mean that a model will perform better when coupled with the harness it was post-trained on, and some might infer that this means you shouldn't customize the harness at all.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">But it cuts both ways: <strong style="color:var(--text-primary)">models can be over-fitted to their harness</strong>. Viv cites <a href="https://terminalbench.com/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Terminal Bench 2.0</a> where Opus 4.6 in Claude Code comes in position #33, but when placed in a different harness that wasn't seen during post-training, it comes in at #5 (+/- about 4 positions in either direction).</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/terminal-bench.png" alt="terminal bench" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Engineering Your Harness</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">With that in mind, let's walk through the configuration surfaces we've found most impactful.</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->CLAUDE.md &amp; AGENTS.md</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Before touching any other harness configuration points, it's usually worth customizing your CLAUDE.md / AGENTS.md files. These are markdown files at the top-level of your repository that get deterministically injected into the agent's system prompt by the harness.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We have already shared <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">some opinions about what makes a good CLAUDE.md</a> file and how to use it correctly, so give that a read if you're not familiar with it. Matt Pocock also wrote a <a href="https://www.aihero.dev/a-complete-guide-to-agents-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">great follow-up</a> that more generally applies to AGENTS.md.</p>
<h4 class="text-xl mb-1 mt-8 font-bold" style="color:var(--text-primary)">#### <!-- -->The ETH Zurich Study</h4>
<p style="display:block;color:var(--text-secondary)" class="mb-4">After ETH Zurich published their <a href="https://arxiv.org/abs/2602.11988" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">study testing 138 agentfiles across various repos</a> which indicated that most agentfiles were useless-or-worse, we got a lot of feedback on our <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">CLAUDE.md post</a>:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">See, CLAUDE.md files don't even help — they're a waste of time.</p>
</blockquote>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Indeed: the study tested many agentfiles across a wide variety of repos, and found:</p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li>that LLM-generated ones actually <em style="color:var(--text-secondary)">hurt</em> performance while costing 20%+ more</li>
<li>human-written ones only helped about 4%.</li>
<li>Agents spent 14-22% more reasoning tokens processing context file instructions, took more steps to complete tasks, and ran more tools — all without improving resolution rates.</li>
<li>Codebase overviews and directory listings didn't help at all; agents discover repository structure on their own just fine.</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">A careful reading of the study <strong style="color:var(--text-primary)">indicates that what we said in our post was correct:</strong></p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">Agent-generated files were worse. Yes, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">avoid auto-generating it. You should carefully craft its contents for best results.</p>
</blockquote>
</li>
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">Lots of files too-heavily-steered the model to use specific tools, causing worse outcomes. Yep, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">Less (instructions) is more. While you shouldn't omit necessary instructions, you should include as few instructions as reasonably possible in the file.</p>
</blockquote>
</li>
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">Files contained irrelevant context. Yep, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">Use Progressive Disclosure</p>
</blockquote>
</li>
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">The human-written ones barely helped because of too many conditional rules. Yep, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">Keep the contents of your CLAUDE.md concise and universally applicable.</p>
</blockquote>
</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Our CLAUDE.md is under 60 lines.</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->MCP Servers Are for Tools</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">MCP servers are&nbsp;primarily for plugging tools into your coding agent to extend its capabilities beyond file I/O and bash commands. The MCP specification includes additional features like resources, prompts, and elicitations, but <strong style="color:var(--text-primary)">these are generally not well-supported by MCP clients and coding agent harnesses</strong>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The MCP spec supports servers that run on your (or the agent's) local machine which allow the agent to interact with its local environment, but it also supports HTTP-based MCP servers that can connect your agent with remote tools and services like Linear, Sentry, and more.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">When you plug an MCP server into your coding agent, the list of available tools, their descriptions, and the arguments needed to invoke them <strong style="color:var(--text-primary)">are injected into your coding agent's system prompt</strong>. As a result, the MCP server can use the tool descriptions to customize your agent’s behavior by providing your agent with instructions about when to use them.&nbsp;</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">WARNING</strong>: because MCP servers’ tool descriptions are added to your coding agent’s system prompt, never connect to one you don’t trust. This can be a dangerous vector for prompt injection! STDIO servers and other servers that run client-side with npx or uvx can also execute code on your host in the absence of prompt injection.</p>
<h4 class="text-xl mb-1 mt-8 font-bold" style="color:var(--text-primary)">#### <!-- -->Too Many Tools Is Bad</h4>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We’ve seen this firsthand: plug too many MCP tools into your agent, and the context window fills up with tool descriptions, pushing you into <a href="https://youtu.be/rmvDxxNubIg?si=O17nmS3SScaAkpp-&amp;t=355" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the dumb zone</a> much faster:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/too-many-tools.png" alt="too many tools" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The <a href="https://www.aihero.dev/a-complete-guide-to-agents-md#the-instruction-budget" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">instruction budget</a> matters too — every irrelevant tool description is an instruction the agent has to process without any benefit.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">In fact, these failure modes are so common that Anthropic released <a href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">experimental support for MCP tool search</a> to progressively disclose tools to Claude when the user has too many MCP tools connected. TL;DR: if you’re not actively using a server which provides a large number of tools, turn it off.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We also found that if an MCP server duplicates functionality that’s already available as a CLI well-represented in training data, it works better to just prompt the agent to use the CLI. For things like GitHub, Docker, or most databases, your coding agent can just use the right CLIs and shell commands. The model has seen these tools enough during training that it already knows how to use them, and you gain the added benefit of composability with tools like <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">grep</code> and <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">jq</code> to enable additional context-efficiency.</p>
<h4 class="text-xl mb-1 mt-8 font-bold" style="color:var(--text-primary)">#### <!-- -->Always Be Context-Engineering</h4>
<p style="display:block;color:var(--text-secondary)" class="mb-4">At HumanLayer, we used the Linear MCP server for a while before realizing that we really only used a small subset of the tools it provides - so we wrote a small CLI that wraps the Linear API and provides very context-efficient responses, and we included 6 example usages in our <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">CLAUDE.md</a> file:</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group- |
Contributor
Auto ReviewNo clear rule violations found in the current diff. |
Contributor
|
Successfully generated as following: http://localhost:1200/humanlayer/blog - Success ✔️<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:atom="http://www.w3.org/2005/Atom" version="2.0">
<channel>
<title>HumanLayer Blog</title>
<link>https://www.humanlayer.dev/blog</link>
<atom:link href="http://localhost:1200/humanlayer/blog" rel="self" type="application/rss+xml"></atom:link>
<description>HumanLayer Blog - Powered by RSSHub</description>
<generator>RSSHub</generator>
<webMaster>contact@rsshub.app (RSSHub)</webMaster>
<language>en</language>
<lastBuildDate>Tue, 31 Mar 2026 06:52:36 GMT</lastBuildDate>
<ttl>5</ttl>
<item>
<title>Long-Context Isn't the Answer</title>
<description><p style="display:block;color:var(--text-secondary)" class="mb-4">Anthropic just switched the default model in Claude Code to Opus 4.6 with a 1M context window. We tried it when it launched. But now we're switching back to Opus 4.5</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->How about some context?</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Unlike previous Claude Opus models which have a ~ 200k context window, Opus 4.6 has as 1M context window. This was very exciting for us!</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We spend a lot of time working on hard problems in large enterprise codebases, and if the model can reliably hold more of the codebase in its head at a time, so to speak, then that creates new possibilities for the scale of problem that can be solved in a single context window.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It would mean less compaction (whether <a href="https://www.humanlayer.dev/blog/advanced-context-engineering" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">frequent intentional compaction</a> or auto-compact), and less "context pressure" to solve the problem before your context window fills up.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">As Calvin French-Owen, who helped launch Codex last year, <a href="https://youtu.be/qwmmWzPnhog?si=ReRWTavUKTItIGGr&amp;t=918" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">puts it in an episode of YC's Lightcone podcast</a>:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">...imagine you're a college student. You're taking an exam. In the first five minutes of that exam, you're like, "Oh, I have all the time in the world. I'll do a great job. I'll think through each of these problems."</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Let's say you have like five minutes left and you still have half the exam left. You're like, "Oh man, I just got to do whatever I can." Like, that's the LLM with a context window</p>
</blockquote>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->More context, less instruction adherence</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">While the context window is dramatically larger, we noticed over the course of a couple of weeks that instruction adherence was dramatically degraded, and not just at longer context lengths.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Even well-within what we would consider the <a href="https://youtu.be/rmvDxxNubIg?si=O17nmS3SScaAkpp-&amp;t=355" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">smart zone</a> of a 200k-context frontier model, the model was less precise. It would ignore design documents and other inputs when writing a plan file. It would make trivial mistakes, or misunderstand simple instructions - or worse, directly disobey them.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">At longer context lengths, the degradation was even steeper - like the user instructions were getting drowned out by the intermediate tool results and mass of accumulated context.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->What determines instruction adherence?</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We've written about the concept of <a href="https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the instruction budget</a> before - a measurable property of LLMs which describes how many instructions they can follow reasonably well before instruction adherence drops off.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It's different for each model, but it's a function primarily of the quality of the model's instruction tuning, and more importantly for our purposes, it is <strong style="color:var(--text-primary)">strongly correlated with the size of the model</strong>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/writing-a-good-claude-md/instructionfollowing.png" alt="Instruction following" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">You can clearly see that the larger models from the <a href="https://arxiv.org/pdf/2507.11538" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">study</a> can follow dramatically more instructions before adherence drops off.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Instruction adherence at long context lengths</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Why does this matter?</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">When a lab offers an extended-context version of a model, you're usually not getting a bigger model with more parameters and therefore a larger "instruction budget" to go with the larger context window - you're likely getting the same model with some clever math (e.g. <a href="https://arxiv.org/pdf/2309.00071" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">YaRN</a>) to extend the sequence length the model can attend to, and probably some more post-training to stabilize the model at the longer sequence lengths.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">This means that while the context window size increases, the instruction budget remains the same. You can fit more context and more instructions in the context window, but the model isn't actually better at attending to those instructions over the context length.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Instruction-following as needle in a haystack</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">You can think of your context window as a haystack where all of your tool calls and documents and files are hay - every line in your CLAUDE.md file, every instruction in your tool descriptions, every tool result, every instruction in your system prompt, and every user message.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The quality &amp; correctness of the agent's next step depends on the LLM's ability to find a needle in there: namely, the instruction(s) in the context window that are most-relevant to the current state of the context window, which give it the information it needs to make the correct decision about its next action.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Now imagine we increase the size of the haystack by 500% - but the size of the needle remains the same. Unless our ability to find the needle also increases by 500%, we will have a dramatically harder time finding it. The extra context isn't really helping us - it's just digging us deeper into the dumb zone.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/long-context.jpg" alt="long context" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->What Works Instead</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Instead of trying to stuff as much information in a context window as possible and having the LLM reason over it, we found that the context management techniques we had been using had to be used even <em style="color:var(--text-secondary)">more</em> aggressively to keep Opus 4.6 1M on track.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">In my post on <a href="https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">harness engineering</a>, I wrote about this as the limit case for using sub-agents:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/limit-case.png" alt="limit case" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The day after I published it, I decided maybe it wasn't such a bad idea, and sat down and wrote this skill:</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">---
</span>name: subagent-orchestrator
<!-- -->description: orchestrate sub-agents to accomplish complex long-horizon tasks without losing coherency by delegating to sub-agents
<!-- -->---
<!-- -->
<!-- -->This skill provides you with **CRITICAL** instructions that will help you to maintain coherency in long-horizon context-heavy tasks.
<!-- -->
<!-- -->You have a large number of tools available to you. The most important one is the one that allows you to dispatch sub-agents: either `Agent` or `Task`.
<!-- -->
<!-- -->All non-trivial operations should be delegated to sub-agents. You should delegate research and codebase understanding tasks to codebase-analyzer, codebase-locator and pattern-locator sub-agents.
<!-- -->
<!-- -->You should delegate running bash commands (particularly ones that are likely to produce lots of output) such as investigating with the `aws` CLI, using the `gh` CLI, digging through logs to `Bash` sub-agents.
<!-- -->
<!-- -->You should use separate sub-agents for separate tasks, and you may launch them in parallel - but do not delegate multiple tasks that are likely to have significant overlap to separate sub-agents.
<!-- -->
<!-- -->IMPORTANT: if the user has already given you a task, you should proceed with that task using this approach.
<!-- -->
<!-- -->If you have not already been explicitly given a taks, you should ask the user what task they would like for you to work on - do not assume or begin working on a ticket automatically.</code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">I found that using this skill in combination with our existing workflow skills helped me keep Opus coherent at longer context lengths. Why?
As I wrote about in that post, sub-agents encapsulate context and ensure that only highly-relevant context (the prompt, and the focused sub-agent result) end up in the context window, avoiding <a href="https://research.trychroma.com/context-rot" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">context rot</a>:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/context-firewall.png" alt="context firewall" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->How we're incorporating this at HumanLayer</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We have had a feature in the tool for a while that warns the user when they're context is getting high. We used to set this at around %40 of sonnets 168k token window (200k - 32k reserved for output). This came out to about 100k tokens.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">To help users maximize instruction adherence and intelligence on hard codebase problems, we've updated our context warnings for long-context models to trigger at the 100k token mark instead of 40% of the usable context. For opus 1m this is only 10% of the context window.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->TL;DR</h2>
<div class="pl-8 mb-6"><ol class="list-decimal space-y-4" style="color:var(--text-secondary)">
<li>Long-context models degrade at all context lengths, not just long ones.</li>
<li>More context isn't more capability - the instruction budget doesn't scale with the context window.</li>
<li>Context isolation beats context expansion. Sub-agents, progressive disclosure, and <a href="https://www.humanlayer.dev/blog/context-efficient-backpressure" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">context-efficient backpressure</a> keep each context window small, focused, and in the smart zone.</li>
</ol></div></description>
<link>https://www.humanlayer.dev/blog/long-context-isnt-the-answer</link>
<guid isPermaLink="false">https://www.humanlayer.dev/blog/long-context-isnt-the-answer</guid>
<pubDate>Sun, 22 Mar 2026 16:00:00 GMT</pubDate>
<author>Kyle</author>
</item>
<item>
<title>Getting Claude to Actually Read Your CLAUDE.md</title>
<description><p style="display:block;color:var(--text-secondary)" class="mb-4">Claude Code wraps your CLAUDE.md in a <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;system_reminder&gt;</code> that explicitly tells the model the contents "may or may not be relevant." The longer your file gets, the more Claude seems to treat individual sections as optional.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">wrote before</a> about keeping these files concise and avoiding stuff that belongs in a linter. But even after trimming things down, I kept running into cases where Claude would ignore testing instructions while writing tests, or skip our API conventions when building endpoints.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Conditional <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;important if&gt;</code> blocks</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">What's been working for me: wrapping sections in <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;important if="condition"&gt;</code> tags.</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">&lt;important if="you are writing or modifying tests"&gt;
</span>- Use `createTestApp()` helper for integration tests
<!-- -->- Mock database with `dbMock` from `packages/db/test`
<!-- -->- Test fixtures live in `__fixtures__/` directories
<!-- -->&lt;/important&gt;</code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We don't have a rigorous explanation for why this helps. My guess is that the explicit condition gives Claude a clearer signal about when to apply the instructions, rather than leaving it to decide relevance on its own. Whatever the mechanism, we've seen noticeably better adherence on tasks where only some sections of my CLAUDE.md should apply.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">A few things I've learned:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">Don't wrap everything.</strong> Project identity, directory structure, and tech stack are relevant to basically every task. The conditional blocks are for testing setup or deployment procedures that only matter sometimes.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">Make conditions specific.</strong> <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;important if="you are writing code"&gt;</code> matches almost everything and defeats the purpose. I try to make each condition narrow enough that it only fires when I actually want those rules applied.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->A skill to automate this</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">I did a lot of restructuring CLAUDE.md files by hand, so I made a Claude Code skill that does the rewrite. It pulls out the foundational stuff, wraps domain-specific sections in conditional blocks, and cleans up some common problems (stale code snippets, style rules that should be in a linter, vague instructions that don't actually help).</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It's not perfect—you'll probably want to review what it produces—but it's a decent starting point.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Try it</h2>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">npx skills add humanlayer/skills --skill improve-claude-md</span></code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Then in your project:</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">/improve-claude-md</span></code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It reads your existing CLAUDE.md and outputs a rewritten version. Source is at <a href="https://github.com/humanlayer/skills/tree/main/plugins/improve-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">github.com/humanlayer/skills</a>.</p></description>
<link>https://www.humanlayer.dev/blog/stop-claude-from-ignoring-your-claude-md</link>
<guid isPermaLink="false">https://www.humanlayer.dev/blog/stop-claude-from-ignoring-your-claude-md</guid>
<pubDate>Mon, 16 Mar 2026 16:00:00 GMT</pubDate>
<author>Dex</author>
</item>
<item>
<title>Skill Issue: Harness Engineering for Coding Agents</title>
<description><p style="display:block;color:var(--text-secondary)" class="mb-4">We've spent the past year watching coding agents fail in every conceivable way: ignoring instructions, executing dangerous commands un-prompted, and going in circles on the simplest of tasks.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We've seen teams ship immense amounts of slop. We've even <a href="https://www.youtube.com/live/99Kxkemj1g8?si=tVsK88M3XPyo0urD&amp;t=20967" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">shipped a little bit of slop ourselves</a>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Every time, the instinct was the same:</p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li>"We just need better models, GPT-6 will fix it"</li>
<li>"We just need better instruction-following"</li>
<li>"It'll work once [niche library I'm using] is in the training data"</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">But over the course of dozens of projects and hundreds of agent sessions, we kept arriving at the same conclusion: it's not a model problem. It's a <strong style="color:var(--text-primary)">configuration problem</strong>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Yes, models will get smarter, and some existing failure modes will disappear. And then because they are smarter, we will give them new problems which are bigger and harder, and they will <strong style="color:var(--text-primary)">continue to fail in unexpected ways</strong>. Unexpected failures modes are a fundamental problem for non-deterministic systems.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/gpt-6.png" alt="gpt-6" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">So instead of praying for <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">gpt-6.4-codex-ultrahigh_extended</code> to save us all, we try to focus on answering the question of <em style="color:var(--text-secondary)">"how do we get the most out of <strong style="color:var(--text-primary)">today's</strong> models?"</em></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">There are lots of ways to get better performance out of your coding agent. If you use coding agents for moderately hard tasks, you've probably configured your coding agent a bit. Have you used skills? MCP servers? Sub-agents? Memory? AGENTS.md files?</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">coding agent = AI model(s) + harness</span></code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">These are all technically separate concepts, but they are all part of the coding agent's configuration surface. We call this the <strong style="color:var(--text-primary)">coding agent's harness</strong>, and we think of it as <a href="https://www.vtrivedy.com/posts/claude-code-sdk-haas-harness-as-a-service" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the agent’s runtime</a>, or as its peripherals: what does the model use to interact with its environment?</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Harness Engineering</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">Harness engineering</strong>, coined by <a href="https://x.com/Vtrivedy10" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Viv</a>, describes the practice of leveraging these configuration points to customize and improve your coding agent's output quality and reliability.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/harness-components.png" alt="harness components" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer">
<em style="color:var(--text-secondary)">Image from <a href="https://blog.langchain.com/the-anatomy-of-an-agent-harness/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Viv's post</a></em></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">As <a href="https://mitchellh.com/writing/my-ai-adoption-journey#step-5-engineer-the-harness" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Mitchell Hashimoto put it</a>, harness engineering</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">[...] is the idea that 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>
</blockquote>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->... as a Subset of Context Engineering</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We view harness engineering as a subset of <a href="https://www.humanlayer.dev/blog/advanced-context-engineering" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">context engineering</a>. Coined by my cofounder <a href="https://x.com/dexhorthy" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Dex</a> in <a href="https://github.com/humanlayer/12-factor-agents" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">12-factor agents</a>, context engineering is a superset of “prompt engineering” and a variety of other techniques for systematically improving AI agents’ reliability.&nbsp;You can find the original talk on <a href="https://www.youtube.com/watch?v=IS_y40zY-hc" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">here</a>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Harness engineering then is the subset of context engineering which primarily involves leveraging harness configuration points to carefully manage the context windows of coding agents.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/harness-engineering.png" alt="harness engineering as context engineering" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It answers:</p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li>How do we give our coding agent new capabilities?</li>
<li>How do we teach it things about our codebase that aren’t in the training data?</li>
<li>How do we add determinism beyond <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">CRITICAL: always do XYZ</code> in the system message?</li>
<li>How do we adapt the agent’s behavior for our specific codebase?</li>
<li>How do we increase task success rates beyond “magic prompts”?</li>
<li>How do we prevent our context window from inflating too rapidly, or with too much bad context?</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Skills, MCP servers, sub-agents, hooks, and back-pressure mechanisms are all tactical solutions we’ve arrived at.</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->Views on Harness Engineering</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Viv’s posts on harness engineering are worth reading alongside this one — <a href="https://www.vtrivedy.com/posts/claude-code-sdk-haas-harness-as-a-service" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the first</a> frames the four customization levers (system prompt, tools/MCPs, context, sub-agents), and <a href="https://blog.langchain.com/the-anatomy-of-an-agent-harness/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the second</a> works backwards from what models <em style="color:var(--text-secondary)">can’t</em> do natively to derive why each harness component exists.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/backwards.png" alt="working backwards from what models can't do natively" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer">
<em style="color:var(--text-secondary)">Image from <a href="https://blog.langchain.com/the-anatomy-of-an-agent-harness/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Viv's post</a></em></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We’d add two levers he doesn’t emphasize:</p>
<div class="pl-8 mb-6"><ol class="list-decimal space-y-4" style="color:var(--text-secondary)">
<li><strong style="color:var(--text-primary)">hooks</strong> for automated integration and deterministic control flow</li>
<li><strong style="color:var(--text-primary)">skills</strong> for progressive disclosure of knowledge. (Dex likes to refer to them as "Instruction Modules" - more on this in another post.)</li>
</ol></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">After months of solving hard problems in complex brownfield enterprise-scale codebases, we have found that sub-agents are a particularly powerful lever. When working on hard problems that require many, many context windows to solve, <strong style="color:var(--text-primary)">sub-agents are the key to maintaining coherency across many sessions</strong>. Sub-agents <strong style="color:var(--text-primary)">function as a "context firewall"</strong> that ensures discrete tasks can run in isolated context windows so none of the intermediate noise accumulates in your parent thread which is responsible for orchestration, and you can maintain coherency for much, much longer.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/context-firewall.png" alt="context firewall" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">OpenAI recently wrote a <a href="https://openai.com/index/harness-engineering/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">blog post</a> on the topic as well. There's some great content in there, and it seems to indicate that they view harness engineering as configuring everything <em style="color:var(--text-secondary)">outside</em> of the agent's runtime. It's more focused on back-pressure and verification mechanisms. (Although this may be a mis-reading; the post is somewhat unclear: the word "harness" only appears once in the text of the post, and in reference to evals rather than harness engineering itself.)</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->But What About Post-Training?</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Given that frontier coding models are post-trained on their harnesses (e.g. Claude in Claude Code, GPT-5 Codex in Codex), some will argue that the best harness and/or configuration is the one that the model was trained on.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">For example, the Codex models are so tightly coupled with the Codex harness's <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">apply_patch</code> tool that <a href="https://opencode.ai/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">OpenCode</a> — built as an open-source alternative to Claude Code — had to <a href="https://github.com/anomalyco/opencode/pull/9127" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">add an <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">apply_patch</code> tool</a> specifically for GPT/Codex models to mimic the Codex harness to improve the Codex models' performance in the OpenCode harness - while Claude and other models still use normal <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">edit</code> and <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">write</code> tools.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">This <em style="color:var(--text-secondary)">can</em> mean that a model will perform better when coupled with the harness it was post-trained on, and some might infer that this means you shouldn't customize the harness at all.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">But it cuts both ways: <strong style="color:var(--text-primary)">models can be over-fitted to their harness</strong>. Viv cites <a href="https://terminalbench.com/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Terminal Bench 2.0</a> where Opus 4.6 in Claude Code comes in position #33, but when placed in a different harness that wasn't seen during post-training, it comes in at #5 (+/- about 4 positions in either direction).</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/terminal-bench.png" alt="terminal bench" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Engineering Your Harness</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">With that in mind, let's walk through the configuration surfaces we've found most impactful.</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->CLAUDE.md &amp; AGENTS.md</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Before touching any other harness configuration points, it's usually worth customizing your CLAUDE.md / AGENTS.md files. These are markdown files at the top-level of your repository that get deterministically injected into the agent's system prompt by the harness.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We have already shared <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">some opinions about what makes a good CLAUDE.md</a> file and how to use it correctly, so give that a read if you're not familiar with it. Matt Pocock also wrote a <a href="https://www.aihero.dev/a-complete-guide-to-agents-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">great follow-up</a> that more generally applies to AGENTS.md.</p>
<h4 class="text-xl mb-1 mt-8 font-bold" style="color:var(--text-primary)">#### <!-- -->The ETH Zurich Study</h4>
<p style="display:block;color:var(--text-secondary)" class="mb-4">After ETH Zurich published their <a href="https://arxiv.org/abs/2602.11988" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">study testing 138 agentfiles across various repos</a> which indicated that most agentfiles were useless-or-worse, we got a lot of feedback on our <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">CLAUDE.md post</a>:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">See, CLAUDE.md files don't even help — they're a waste of time.</p>
</blockquote>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Indeed: the study tested many agentfiles across a wide variety of repos, and found:</p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li>that LLM-generated ones actually <em style="color:var(--text-secondary)">hurt</em> performance while costing 20%+ more</li>
<li>human-written ones only helped about 4%.</li>
<li>Agents spent 14-22% more reasoning tokens processing context file instructions, took more steps to complete tasks, and ran more tools — all without improving resolution rates.</li>
<li>Codebase overviews and directory listings didn't help at all; agents discover repository structure on their own just fine.</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">A careful reading of the study <strong style="color:var(--text-primary)">indicates that what we said in our post was correct:</strong></p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">Agent-generated files were worse. Yes, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">avoid auto-generating it. You should carefully craft its contents for best results.</p>
</blockquote>
</li>
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">Lots of files too-heavily-steered the model to use specific tools, causing worse outcomes. Yep, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">Less (instructions) is more. While you shouldn't omit necessary instructions, you should include as few instructions as reasonably possible in the file.</p>
</blockquote>
</li>
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">Files contained irrelevant context. Yep, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">Use Progressive Disclosure</p>
</blockquote>
</li>
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">The human-written ones barely helped because of too many conditional rules. Yep, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">Keep the contents of your CLAUDE.md concise and universally applicable.</p>
</blockquote>
</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Our CLAUDE.md is under 60 lines.</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->MCP Servers Are for Tools</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">MCP servers are&nbsp;primarily for plugging tools into your coding agent to extend its capabilities beyond file I/O and bash commands. The MCP specification includes additional features like resources, prompts, and elicitations, but <strong style="color:var(--text-primary)">these are generally not well-supported by MCP clients and coding agent harnesses</strong>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The MCP spec supports servers that run on your (or the agent's) local machine which allow the agent to interact with its local environment, but it also supports HTTP-based MCP servers that can connect your agent with remote tools and services like Linear, Sentry, and more.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">When you plug an MCP server into your coding agent, the list of available tools, their descriptions, and the arguments needed to invoke them <strong style="color:var(--text-primary)">are injected into your coding agent's system prompt</strong>. As a result, the MCP server can use the tool descriptions to customize your agent’s behavior by providing your agent with instructions about when to use them.&nbsp;</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">WARNING</strong>: because MCP servers’ tool descriptions are added to your coding agent’s system prompt, never connect to one you don’t trust. This can be a dangerous vector for prompt injection! STDIO servers and other servers that run client-side with npx or uvx can also execute code on your host in the absence of prompt injection.</p>
<h4 class="text-xl mb-1 mt-8 font-bold" style="color:var(--text-primary)">#### <!-- -->Too Many Tools Is Bad</h4>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We’ve seen this firsthand: plug too many MCP tools into your agent, and the context window fills up with tool descriptions, pushing you into <a href="https://youtu.be/rmvDxxNubIg?si=O17nmS3SScaAkpp-&amp;t=355" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the dumb zone</a> much faster:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/too-many-tools.png" alt="too many tools" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The <a href="https://www.aihero.dev/a-complete-guide-to-agents-md#the-instruction-budget" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">instruction budget</a> matters too — every irrelevant tool description is an instruction the agent has to process without any benefit.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">In fact, these failure modes are so common that Anthropic released <a href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">experimental support for MCP tool search</a> to progressively disclose tools to Claude when the user has too many MCP tools connected. TL;DR: if you’re not actively using a server which provides a large number of tools, turn it off.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We also found that if an MCP server duplicates functionality that’s already available as a CLI well-represented in training data, it works better to just prompt the agent to use the CLI. For things like GitHub, Docker, or most databases, your coding agent can just use the right CLIs and shell commands. The model has seen these tools enough during training that it already knows how to use them, and you gain the added benefit of composability with tools like <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">grep</code> and <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">jq</code> to enable additional context-efficiency.</p>
<h4 class="text-xl mb-1 mt-8 font-bold" style="color:var(--text-primary)">#### <!-- -->Always Be Context-Engineering</h4>
<p style="display:block;color:var(--text-secondary)" class="mb-4">At HumanLayer, we used the Linear MCP server for a while before realizing that we really only used a small subset of the tools it provides - so we wrote a small CLI that wraps the Linear API and provides very context-efficient responses, and we included 6 example usages in our <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">CLAUDE.md</a> file:</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group- |
Contributor
Auto ReviewNo clear rule violations found in the current diff. |
TonyRL
reviewed
Mar 31, 2026
lib/routes/humanlayer/blog.ts
Outdated
Comment on lines
+43
to
+46
| .filter((el) => { | ||
| const href = $(el).attr('href')!; | ||
| return !href.startsWith('/blog/tags/'); | ||
| }) |
Collaborator
There was a problem hiding this comment.
Useless filtering since
RSSHub/lib/routes/humanlayer/blog.ts
Line 41 in f8d9c61
/blog/tags/
…anlayer blog Address PR review feedback: move /blog/tags/ exclusion into the CSS selector instead of using a separate .filter() call. via [HAPI](https://hapi.run) Co-Authored-By: HAPI <noreply@hapi.run> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
Successfully generated as following: http://localhost:1200/humanlayer/blog - Success ✔️<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:atom="http://www.w3.org/2005/Atom" version="2.0">
<channel>
<title>HumanLayer Blog</title>
<link>https://www.humanlayer.dev/blog</link>
<atom:link href="http://localhost:1200/humanlayer/blog" rel="self" type="application/rss+xml"></atom:link>
<description>HumanLayer Blog - Powered by RSSHub</description>
<generator>RSSHub</generator>
<webMaster>contact@rsshub.app (RSSHub)</webMaster>
<language>en</language>
<lastBuildDate>Wed, 01 Apr 2026 09:14:14 GMT</lastBuildDate>
<ttl>5</ttl>
<item>
<title>Long-Context Isn't the Answer</title>
<description><p style="display:block;color:var(--text-secondary)" class="mb-4">Anthropic just switched the default model in Claude Code to Opus 4.6 with a 1M context window. We tried it when it launched. But now we're switching back to Opus 4.5</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->How about some context?</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Unlike previous Claude Opus models which have a ~ 200k context window, Opus 4.6 has as 1M context window. This was very exciting for us!</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We spend a lot of time working on hard problems in large enterprise codebases, and if the model can reliably hold more of the codebase in its head at a time, so to speak, then that creates new possibilities for the scale of problem that can be solved in a single context window.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It would mean less compaction (whether <a href="https://www.humanlayer.dev/blog/advanced-context-engineering" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">frequent intentional compaction</a> or auto-compact), and less "context pressure" to solve the problem before your context window fills up.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">As Calvin French-Owen, who helped launch Codex last year, <a href="https://youtu.be/qwmmWzPnhog?si=ReRWTavUKTItIGGr&amp;t=918" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">puts it in an episode of YC's Lightcone podcast</a>:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">...imagine you're a college student. You're taking an exam. In the first five minutes of that exam, you're like, "Oh, I have all the time in the world. I'll do a great job. I'll think through each of these problems."</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Let's say you have like five minutes left and you still have half the exam left. You're like, "Oh man, I just got to do whatever I can." Like, that's the LLM with a context window</p>
</blockquote>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->More context, less instruction adherence</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">While the context window is dramatically larger, we noticed over the course of a couple of weeks that instruction adherence was dramatically degraded, and not just at longer context lengths.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Even well-within what we would consider the <a href="https://youtu.be/rmvDxxNubIg?si=O17nmS3SScaAkpp-&amp;t=355" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">smart zone</a> of a 200k-context frontier model, the model was less precise. It would ignore design documents and other inputs when writing a plan file. It would make trivial mistakes, or misunderstand simple instructions - or worse, directly disobey them.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">At longer context lengths, the degradation was even steeper - like the user instructions were getting drowned out by the intermediate tool results and mass of accumulated context.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->What determines instruction adherence?</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We've written about the concept of <a href="https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the instruction budget</a> before - a measurable property of LLMs which describes how many instructions they can follow reasonably well before instruction adherence drops off.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It's different for each model, but it's a function primarily of the quality of the model's instruction tuning, and more importantly for our purposes, it is <strong style="color:var(--text-primary)">strongly correlated with the size of the model</strong>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/writing-a-good-claude-md/instructionfollowing.png" alt="Instruction following" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">You can clearly see that the larger models from the <a href="https://arxiv.org/pdf/2507.11538" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">study</a> can follow dramatically more instructions before adherence drops off.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Instruction adherence at long context lengths</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Why does this matter?</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">When a lab offers an extended-context version of a model, you're usually not getting a bigger model with more parameters and therefore a larger "instruction budget" to go with the larger context window - you're likely getting the same model with some clever math (e.g. <a href="https://arxiv.org/pdf/2309.00071" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">YaRN</a>) to extend the sequence length the model can attend to, and probably some more post-training to stabilize the model at the longer sequence lengths.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">This means that while the context window size increases, the instruction budget remains the same. You can fit more context and more instructions in the context window, but the model isn't actually better at attending to those instructions over the context length.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Instruction-following as needle in a haystack</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">You can think of your context window as a haystack where all of your tool calls and documents and files are hay - every line in your CLAUDE.md file, every instruction in your tool descriptions, every tool result, every instruction in your system prompt, and every user message.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The quality &amp; correctness of the agent's next step depends on the LLM's ability to find a needle in there: namely, the instruction(s) in the context window that are most-relevant to the current state of the context window, which give it the information it needs to make the correct decision about its next action.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Now imagine we increase the size of the haystack by 500% - but the size of the needle remains the same. Unless our ability to find the needle also increases by 500%, we will have a dramatically harder time finding it. The extra context isn't really helping us - it's just digging us deeper into the dumb zone.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/long-context.jpg" alt="long context" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->What Works Instead</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Instead of trying to stuff as much information in a context window as possible and having the LLM reason over it, we found that the context management techniques we had been using had to be used even <em style="color:var(--text-secondary)">more</em> aggressively to keep Opus 4.6 1M on track.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">In my post on <a href="https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">harness engineering</a>, I wrote about this as the limit case for using sub-agents:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/limit-case.png" alt="limit case" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The day after I published it, I decided maybe it wasn't such a bad idea, and sat down and wrote this skill:</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">---
</span>name: subagent-orchestrator
<!-- -->description: orchestrate sub-agents to accomplish complex long-horizon tasks without losing coherency by delegating to sub-agents
<!-- -->---
<!-- -->
<!-- -->This skill provides you with **CRITICAL** instructions that will help you to maintain coherency in long-horizon context-heavy tasks.
<!-- -->
<!-- -->You have a large number of tools available to you. The most important one is the one that allows you to dispatch sub-agents: either `Agent` or `Task`.
<!-- -->
<!-- -->All non-trivial operations should be delegated to sub-agents. You should delegate research and codebase understanding tasks to codebase-analyzer, codebase-locator and pattern-locator sub-agents.
<!-- -->
<!-- -->You should delegate running bash commands (particularly ones that are likely to produce lots of output) such as investigating with the `aws` CLI, using the `gh` CLI, digging through logs to `Bash` sub-agents.
<!-- -->
<!-- -->You should use separate sub-agents for separate tasks, and you may launch them in parallel - but do not delegate multiple tasks that are likely to have significant overlap to separate sub-agents.
<!-- -->
<!-- -->IMPORTANT: if the user has already given you a task, you should proceed with that task using this approach.
<!-- -->
<!-- -->If you have not already been explicitly given a taks, you should ask the user what task they would like for you to work on - do not assume or begin working on a ticket automatically.</code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">I found that using this skill in combination with our existing workflow skills helped me keep Opus coherent at longer context lengths. Why?
As I wrote about in that post, sub-agents encapsulate context and ensure that only highly-relevant context (the prompt, and the focused sub-agent result) end up in the context window, avoiding <a href="https://research.trychroma.com/context-rot" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">context rot</a>:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/context-firewall.png" alt="context firewall" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->How we're incorporating this at HumanLayer</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We have had a feature in the tool for a while that warns the user when they're context is getting high. We used to set this at around %40 of sonnets 168k token window (200k - 32k reserved for output). This came out to about 100k tokens.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">To help users maximize instruction adherence and intelligence on hard codebase problems, we've updated our context warnings for long-context models to trigger at the 100k token mark instead of 40% of the usable context. For opus 1m this is only 10% of the context window.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->TL;DR</h2>
<div class="pl-8 mb-6"><ol class="list-decimal space-y-4" style="color:var(--text-secondary)">
<li>Long-context models degrade at all context lengths, not just long ones.</li>
<li>More context isn't more capability - the instruction budget doesn't scale with the context window.</li>
<li>Context isolation beats context expansion. Sub-agents, progressive disclosure, and <a href="https://www.humanlayer.dev/blog/context-efficient-backpressure" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">context-efficient backpressure</a> keep each context window small, focused, and in the smart zone.</li>
</ol></div></description>
<link>https://www.humanlayer.dev/blog/long-context-isnt-the-answer</link>
<guid isPermaLink="false">https://www.humanlayer.dev/blog/long-context-isnt-the-answer</guid>
<pubDate>Sun, 22 Mar 2026 16:00:00 GMT</pubDate>
<author>Kyle</author>
</item>
<item>
<title>Getting Claude to Actually Read Your CLAUDE.md</title>
<description><p style="display:block;color:var(--text-secondary)" class="mb-4">Claude Code wraps your CLAUDE.md in a <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;system_reminder&gt;</code> that explicitly tells the model the contents "may or may not be relevant." The longer your file gets, the more Claude seems to treat individual sections as optional.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">wrote before</a> about keeping these files concise and avoiding stuff that belongs in a linter. But even after trimming things down, I kept running into cases where Claude would ignore testing instructions while writing tests, or skip our API conventions when building endpoints.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Conditional <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;important if&gt;</code> blocks</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">What's been working for me: wrapping sections in <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;important if="condition"&gt;</code> tags.</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">&lt;important if="you are writing or modifying tests"&gt;
</span>- Use `createTestApp()` helper for integration tests
<!-- -->- Mock database with `dbMock` from `packages/db/test`
<!-- -->- Test fixtures live in `__fixtures__/` directories
<!-- -->&lt;/important&gt;</code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We don't have a rigorous explanation for why this helps. My guess is that the explicit condition gives Claude a clearer signal about when to apply the instructions, rather than leaving it to decide relevance on its own. Whatever the mechanism, we've seen noticeably better adherence on tasks where only some sections of my CLAUDE.md should apply.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">A few things I've learned:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">Don't wrap everything.</strong> Project identity, directory structure, and tech stack are relevant to basically every task. The conditional blocks are for testing setup or deployment procedures that only matter sometimes.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">Make conditions specific.</strong> <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;important if="you are writing code"&gt;</code> matches almost everything and defeats the purpose. I try to make each condition narrow enough that it only fires when I actually want those rules applied.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->A skill to automate this</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">I did a lot of restructuring CLAUDE.md files by hand, so I made a Claude Code skill that does the rewrite. It pulls out the foundational stuff, wraps domain-specific sections in conditional blocks, and cleans up some common problems (stale code snippets, style rules that should be in a linter, vague instructions that don't actually help).</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It's not perfect—you'll probably want to review what it produces—but it's a decent starting point.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Try it</h2>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">npx skills add humanlayer/skills --skill improve-claude-md</span></code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Then in your project:</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">/improve-claude-md</span></code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It reads your existing CLAUDE.md and outputs a rewritten version. Source is at <a href="https://github.com/humanlayer/skills/tree/main/plugins/improve-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">github.com/humanlayer/skills</a>.</p></description>
<link>https://www.humanlayer.dev/blog/stop-claude-from-ignoring-your-claude-md</link>
<guid isPermaLink="false">https://www.humanlayer.dev/blog/stop-claude-from-ignoring-your-claude-md</guid>
<pubDate>Mon, 16 Mar 2026 16:00:00 GMT</pubDate>
<author>Dex</author>
</item>
<item>
<title>Skill Issue: Harness Engineering for Coding Agents</title>
<description><p style="display:block;color:var(--text-secondary)" class="mb-4">We've spent the past year watching coding agents fail in every conceivable way: ignoring instructions, executing dangerous commands un-prompted, and going in circles on the simplest of tasks.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We've seen teams ship immense amounts of slop. We've even <a href="https://www.youtube.com/live/99Kxkemj1g8?si=tVsK88M3XPyo0urD&amp;t=20967" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">shipped a little bit of slop ourselves</a>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Every time, the instinct was the same:</p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li>"We just need better models, GPT-6 will fix it"</li>
<li>"We just need better instruction-following"</li>
<li>"It'll work once [niche library I'm using] is in the training data"</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">But over the course of dozens of projects and hundreds of agent sessions, we kept arriving at the same conclusion: it's not a model problem. It's a <strong style="color:var(--text-primary)">configuration problem</strong>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Yes, models will get smarter, and some existing failure modes will disappear. And then because they are smarter, we will give them new problems which are bigger and harder, and they will <strong style="color:var(--text-primary)">continue to fail in unexpected ways</strong>. Unexpected failures modes are a fundamental problem for non-deterministic systems.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/gpt-6.png" alt="gpt-6" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">So instead of praying for <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">gpt-6.4-codex-ultrahigh_extended</code> to save us all, we try to focus on answering the question of <em style="color:var(--text-secondary)">"how do we get the most out of <strong style="color:var(--text-primary)">today's</strong> models?"</em></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">There are lots of ways to get better performance out of your coding agent. If you use coding agents for moderately hard tasks, you've probably configured your coding agent a bit. Have you used skills? MCP servers? Sub-agents? Memory? AGENTS.md files?</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">coding agent = AI model(s) + harness</span></code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">These are all technically separate concepts, but they are all part of the coding agent's configuration surface. We call this the <strong style="color:var(--text-primary)">coding agent's harness</strong>, and we think of it as <a href="https://www.vtrivedy.com/posts/claude-code-sdk-haas-harness-as-a-service" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the agent’s runtime</a>, or as its peripherals: what does the model use to interact with its environment?</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Harness Engineering</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">Harness engineering</strong>, coined by <a href="https://x.com/Vtrivedy10" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Viv</a>, describes the practice of leveraging these configuration points to customize and improve your coding agent's output quality and reliability.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/harness-components.png" alt="harness components" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer">
<em style="color:var(--text-secondary)">Image from <a href="https://blog.langchain.com/the-anatomy-of-an-agent-harness/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Viv's post</a></em></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">As <a href="https://mitchellh.com/writing/my-ai-adoption-journey#step-5-engineer-the-harness" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Mitchell Hashimoto put it</a>, harness engineering</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">[...] is the idea that 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>
</blockquote>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->... as a Subset of Context Engineering</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We view harness engineering as a subset of <a href="https://www.humanlayer.dev/blog/advanced-context-engineering" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">context engineering</a>. Coined by my cofounder <a href="https://x.com/dexhorthy" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Dex</a> in <a href="https://github.com/humanlayer/12-factor-agents" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">12-factor agents</a>, context engineering is a superset of “prompt engineering” and a variety of other techniques for systematically improving AI agents’ reliability.&nbsp;You can find the original talk on <a href="https://www.youtube.com/watch?v=IS_y40zY-hc" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">here</a>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Harness engineering then is the subset of context engineering which primarily involves leveraging harness configuration points to carefully manage the context windows of coding agents.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/harness-engineering.png" alt="harness engineering as context engineering" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It answers:</p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li>How do we give our coding agent new capabilities?</li>
<li>How do we teach it things about our codebase that aren’t in the training data?</li>
<li>How do we add determinism beyond <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">CRITICAL: always do XYZ</code> in the system message?</li>
<li>How do we adapt the agent’s behavior for our specific codebase?</li>
<li>How do we increase task success rates beyond “magic prompts”?</li>
<li>How do we prevent our context window from inflating too rapidly, or with too much bad context?</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Skills, MCP servers, sub-agents, hooks, and back-pressure mechanisms are all tactical solutions we’ve arrived at.</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->Views on Harness Engineering</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Viv’s posts on harness engineering are worth reading alongside this one — <a href="https://www.vtrivedy.com/posts/claude-code-sdk-haas-harness-as-a-service" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the first</a> frames the four customization levers (system prompt, tools/MCPs, context, sub-agents), and <a href="https://blog.langchain.com/the-anatomy-of-an-agent-harness/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the second</a> works backwards from what models <em style="color:var(--text-secondary)">can’t</em> do natively to derive why each harness component exists.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/backwards.png" alt="working backwards from what models can't do natively" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer">
<em style="color:var(--text-secondary)">Image from <a href="https://blog.langchain.com/the-anatomy-of-an-agent-harness/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Viv's post</a></em></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We’d add two levers he doesn’t emphasize:</p>
<div class="pl-8 mb-6"><ol class="list-decimal space-y-4" style="color:var(--text-secondary)">
<li><strong style="color:var(--text-primary)">hooks</strong> for automated integration and deterministic control flow</li>
<li><strong style="color:var(--text-primary)">skills</strong> for progressive disclosure of knowledge. (Dex likes to refer to them as "Instruction Modules" - more on this in another post.)</li>
</ol></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">After months of solving hard problems in complex brownfield enterprise-scale codebases, we have found that sub-agents are a particularly powerful lever. When working on hard problems that require many, many context windows to solve, <strong style="color:var(--text-primary)">sub-agents are the key to maintaining coherency across many sessions</strong>. Sub-agents <strong style="color:var(--text-primary)">function as a "context firewall"</strong> that ensures discrete tasks can run in isolated context windows so none of the intermediate noise accumulates in your parent thread which is responsible for orchestration, and you can maintain coherency for much, much longer.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/context-firewall.png" alt="context firewall" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">OpenAI recently wrote a <a href="https://openai.com/index/harness-engineering/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">blog post</a> on the topic as well. There's some great content in there, and it seems to indicate that they view harness engineering as configuring everything <em style="color:var(--text-secondary)">outside</em> of the agent's runtime. It's more focused on back-pressure and verification mechanisms. (Although this may be a mis-reading; the post is somewhat unclear: the word "harness" only appears once in the text of the post, and in reference to evals rather than harness engineering itself.)</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->But What About Post-Training?</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Given that frontier coding models are post-trained on their harnesses (e.g. Claude in Claude Code, GPT-5 Codex in Codex), some will argue that the best harness and/or configuration is the one that the model was trained on.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">For example, the Codex models are so tightly coupled with the Codex harness's <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">apply_patch</code> tool that <a href="https://opencode.ai/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">OpenCode</a> — built as an open-source alternative to Claude Code — had to <a href="https://github.com/anomalyco/opencode/pull/9127" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">add an <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">apply_patch</code> tool</a> specifically for GPT/Codex models to mimic the Codex harness to improve the Codex models' performance in the OpenCode harness - while Claude and other models still use normal <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">edit</code> and <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">write</code> tools.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">This <em style="color:var(--text-secondary)">can</em> mean that a model will perform better when coupled with the harness it was post-trained on, and some might infer that this means you shouldn't customize the harness at all.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">But it cuts both ways: <strong style="color:var(--text-primary)">models can be over-fitted to their harness</strong>. Viv cites <a href="https://terminalbench.com/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Terminal Bench 2.0</a> where Opus 4.6 in Claude Code comes in position #33, but when placed in a different harness that wasn't seen during post-training, it comes in at #5 (+/- about 4 positions in either direction).</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/terminal-bench.png" alt="terminal bench" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Engineering Your Harness</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">With that in mind, let's walk through the configuration surfaces we've found most impactful.</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->CLAUDE.md &amp; AGENTS.md</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Before touching any other harness configuration points, it's usually worth customizing your CLAUDE.md / AGENTS.md files. These are markdown files at the top-level of your repository that get deterministically injected into the agent's system prompt by the harness.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We have already shared <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">some opinions about what makes a good CLAUDE.md</a> file and how to use it correctly, so give that a read if you're not familiar with it. Matt Pocock also wrote a <a href="https://www.aihero.dev/a-complete-guide-to-agents-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">great follow-up</a> that more generally applies to AGENTS.md.</p>
<h4 class="text-xl mb-1 mt-8 font-bold" style="color:var(--text-primary)">#### <!-- -->The ETH Zurich Study</h4>
<p style="display:block;color:var(--text-secondary)" class="mb-4">After ETH Zurich published their <a href="https://arxiv.org/abs/2602.11988" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">study testing 138 agentfiles across various repos</a> which indicated that most agentfiles were useless-or-worse, we got a lot of feedback on our <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">CLAUDE.md post</a>:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">See, CLAUDE.md files don't even help — they're a waste of time.</p>
</blockquote>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Indeed: the study tested many agentfiles across a wide variety of repos, and found:</p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li>that LLM-generated ones actually <em style="color:var(--text-secondary)">hurt</em> performance while costing 20%+ more</li>
<li>human-written ones only helped about 4%.</li>
<li>Agents spent 14-22% more reasoning tokens processing context file instructions, took more steps to complete tasks, and ran more tools — all without improving resolution rates.</li>
<li>Codebase overviews and directory listings didn't help at all; agents discover repository structure on their own just fine.</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">A careful reading of the study <strong style="color:var(--text-primary)">indicates that what we said in our post was correct:</strong></p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">Agent-generated files were worse. Yes, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">avoid auto-generating it. You should carefully craft its contents for best results.</p>
</blockquote>
</li>
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">Lots of files too-heavily-steered the model to use specific tools, causing worse outcomes. Yep, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">Less (instructions) is more. While you shouldn't omit necessary instructions, you should include as few instructions as reasonably possible in the file.</p>
</blockquote>
</li>
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">Files contained irrelevant context. Yep, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">Use Progressive Disclosure</p>
</blockquote>
</li>
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">The human-written ones barely helped because of too many conditional rules. Yep, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">Keep the contents of your CLAUDE.md concise and universally applicable.</p>
</blockquote>
</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Our CLAUDE.md is under 60 lines.</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->MCP Servers Are for Tools</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">MCP servers are&nbsp;primarily for plugging tools into your coding agent to extend its capabilities beyond file I/O and bash commands. The MCP specification includes additional features like resources, prompts, and elicitations, but <strong style="color:var(--text-primary)">these are generally not well-supported by MCP clients and coding agent harnesses</strong>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The MCP spec supports servers that run on your (or the agent's) local machine which allow the agent to interact with its local environment, but it also supports HTTP-based MCP servers that can connect your agent with remote tools and services like Linear, Sentry, and more.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">When you plug an MCP server into your coding agent, the list of available tools, their descriptions, and the arguments needed to invoke them <strong style="color:var(--text-primary)">are injected into your coding agent's system prompt</strong>. As a result, the MCP server can use the tool descriptions to customize your agent’s behavior by providing your agent with instructions about when to use them.&nbsp;</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">WARNING</strong>: because MCP servers’ tool descriptions are added to your coding agent’s system prompt, never connect to one you don’t trust. This can be a dangerous vector for prompt injection! STDIO servers and other servers that run client-side with npx or uvx can also execute code on your host in the absence of prompt injection.</p>
<h4 class="text-xl mb-1 mt-8 font-bold" style="color:var(--text-primary)">#### <!-- -->Too Many Tools Is Bad</h4>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We’ve seen this firsthand: plug too many MCP tools into your agent, and the context window fills up with tool descriptions, pushing you into <a href="https://youtu.be/rmvDxxNubIg?si=O17nmS3SScaAkpp-&amp;t=355" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the dumb zone</a> much faster:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/too-many-tools.png" alt="too many tools" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The <a href="https://www.aihero.dev/a-complete-guide-to-agents-md#the-instruction-budget" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">instruction budget</a> matters too — every irrelevant tool description is an instruction the agent has to process without any benefit.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">In fact, these failure modes are so common that Anthropic released <a href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">experimental support for MCP tool search</a> to progressively disclose tools to Claude when the user has too many MCP tools connected. TL;DR: if you’re not actively using a server which provides a large number of tools, turn it off.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We also found that if an MCP server duplicates functionality that’s already available as a CLI well-represented in training data, it works better to just prompt the agent to use the CLI. For things like GitHub, Docker, or most databases, your coding agent can just use the right CLIs and shell commands. The model has seen these tools enough during training that it already knows how to use them, and you gain the added benefit of composability with tools like <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">grep</code> and <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">jq</code> to enable additional context-efficiency.</p>
<h4 class="text-xl mb-1 mt-8 font-bold" style="color:var(--text-primary)">#### <!-- -->Always Be Context-Engineering</h4>
<p style="display:block;color:var(--text-secondary)" class="mb-4">At HumanLayer, we used the Linear MCP server for a while before realizing that we really only used a small subset of the tools it provides - so we wrote a small CLI that wraps the Linear API and provides very context-efficient responses, and we included 6 example usages in our <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">CLAUDE.md</a> file:</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group- |
Contributor
Auto ReviewNo clear rule violations found in the current diff. |
Parse #-prefixed tags from the meta line and populate the category field. via [HAPI](https://hapi.run) Co-Authored-By: HAPI <noreply@hapi.run> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
Successfully generated as following: http://localhost:1200/humanlayer/blog - Success ✔️<?xml version="1.0" encoding="UTF-8"?>
<rss xmlns:atom="http://www.w3.org/2005/Atom" version="2.0">
<channel>
<title>HumanLayer Blog</title>
<link>https://www.humanlayer.dev/blog</link>
<atom:link href="http://localhost:1200/humanlayer/blog" rel="self" type="application/rss+xml"></atom:link>
<description>HumanLayer Blog - Powered by RSSHub</description>
<generator>RSSHub</generator>
<webMaster>contact@rsshub.app (RSSHub)</webMaster>
<language>en</language>
<lastBuildDate>Wed, 01 Apr 2026 09:42:06 GMT</lastBuildDate>
<ttl>5</ttl>
<item>
<title>Long-Context Isn't the Answer</title>
<description><p style="display:block;color:var(--text-secondary)" class="mb-4">Anthropic just switched the default model in Claude Code to Opus 4.6 with a 1M context window. We tried it when it launched. But now we're switching back to Opus 4.5</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->How about some context?</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Unlike previous Claude Opus models which have a ~ 200k context window, Opus 4.6 has as 1M context window. This was very exciting for us!</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We spend a lot of time working on hard problems in large enterprise codebases, and if the model can reliably hold more of the codebase in its head at a time, so to speak, then that creates new possibilities for the scale of problem that can be solved in a single context window.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It would mean less compaction (whether <a href="https://www.humanlayer.dev/blog/advanced-context-engineering" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">frequent intentional compaction</a> or auto-compact), and less "context pressure" to solve the problem before your context window fills up.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">As Calvin French-Owen, who helped launch Codex last year, <a href="https://youtu.be/qwmmWzPnhog?si=ReRWTavUKTItIGGr&amp;t=918" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">puts it in an episode of YC's Lightcone podcast</a>:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">...imagine you're a college student. You're taking an exam. In the first five minutes of that exam, you're like, "Oh, I have all the time in the world. I'll do a great job. I'll think through each of these problems."</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Let's say you have like five minutes left and you still have half the exam left. You're like, "Oh man, I just got to do whatever I can." Like, that's the LLM with a context window</p>
</blockquote>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->More context, less instruction adherence</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">While the context window is dramatically larger, we noticed over the course of a couple of weeks that instruction adherence was dramatically degraded, and not just at longer context lengths.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Even well-within what we would consider the <a href="https://youtu.be/rmvDxxNubIg?si=O17nmS3SScaAkpp-&amp;t=355" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">smart zone</a> of a 200k-context frontier model, the model was less precise. It would ignore design documents and other inputs when writing a plan file. It would make trivial mistakes, or misunderstand simple instructions - or worse, directly disobey them.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">At longer context lengths, the degradation was even steeper - like the user instructions were getting drowned out by the intermediate tool results and mass of accumulated context.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->What determines instruction adherence?</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We've written about the concept of <a href="https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the instruction budget</a> before - a measurable property of LLMs which describes how many instructions they can follow reasonably well before instruction adherence drops off.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It's different for each model, but it's a function primarily of the quality of the model's instruction tuning, and more importantly for our purposes, it is <strong style="color:var(--text-primary)">strongly correlated with the size of the model</strong>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/writing-a-good-claude-md/instructionfollowing.png" alt="Instruction following" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">You can clearly see that the larger models from the <a href="https://arxiv.org/pdf/2507.11538" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">study</a> can follow dramatically more instructions before adherence drops off.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Instruction adherence at long context lengths</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Why does this matter?</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">When a lab offers an extended-context version of a model, you're usually not getting a bigger model with more parameters and therefore a larger "instruction budget" to go with the larger context window - you're likely getting the same model with some clever math (e.g. <a href="https://arxiv.org/pdf/2309.00071" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">YaRN</a>) to extend the sequence length the model can attend to, and probably some more post-training to stabilize the model at the longer sequence lengths.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">This means that while the context window size increases, the instruction budget remains the same. You can fit more context and more instructions in the context window, but the model isn't actually better at attending to those instructions over the context length.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Instruction-following as needle in a haystack</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">You can think of your context window as a haystack where all of your tool calls and documents and files are hay - every line in your CLAUDE.md file, every instruction in your tool descriptions, every tool result, every instruction in your system prompt, and every user message.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The quality &amp; correctness of the agent's next step depends on the LLM's ability to find a needle in there: namely, the instruction(s) in the context window that are most-relevant to the current state of the context window, which give it the information it needs to make the correct decision about its next action.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Now imagine we increase the size of the haystack by 500% - but the size of the needle remains the same. Unless our ability to find the needle also increases by 500%, we will have a dramatically harder time finding it. The extra context isn't really helping us - it's just digging us deeper into the dumb zone.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/long-context.jpg" alt="long context" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->What Works Instead</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Instead of trying to stuff as much information in a context window as possible and having the LLM reason over it, we found that the context management techniques we had been using had to be used even <em style="color:var(--text-secondary)">more</em> aggressively to keep Opus 4.6 1M on track.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">In my post on <a href="https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">harness engineering</a>, I wrote about this as the limit case for using sub-agents:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/limit-case.png" alt="limit case" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The day after I published it, I decided maybe it wasn't such a bad idea, and sat down and wrote this skill:</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">---
</span>name: subagent-orchestrator
<!-- -->description: orchestrate sub-agents to accomplish complex long-horizon tasks without losing coherency by delegating to sub-agents
<!-- -->---
<!-- -->
<!-- -->This skill provides you with **CRITICAL** instructions that will help you to maintain coherency in long-horizon context-heavy tasks.
<!-- -->
<!-- -->You have a large number of tools available to you. The most important one is the one that allows you to dispatch sub-agents: either `Agent` or `Task`.
<!-- -->
<!-- -->All non-trivial operations should be delegated to sub-agents. You should delegate research and codebase understanding tasks to codebase-analyzer, codebase-locator and pattern-locator sub-agents.
<!-- -->
<!-- -->You should delegate running bash commands (particularly ones that are likely to produce lots of output) such as investigating with the `aws` CLI, using the `gh` CLI, digging through logs to `Bash` sub-agents.
<!-- -->
<!-- -->You should use separate sub-agents for separate tasks, and you may launch them in parallel - but do not delegate multiple tasks that are likely to have significant overlap to separate sub-agents.
<!-- -->
<!-- -->IMPORTANT: if the user has already given you a task, you should proceed with that task using this approach.
<!-- -->
<!-- -->If you have not already been explicitly given a taks, you should ask the user what task they would like for you to work on - do not assume or begin working on a ticket automatically.</code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">I found that using this skill in combination with our existing workflow skills helped me keep Opus coherent at longer context lengths. Why?
As I wrote about in that post, sub-agents encapsulate context and ensure that only highly-relevant context (the prompt, and the focused sub-agent result) end up in the context window, avoiding <a href="https://research.trychroma.com/context-rot" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">context rot</a>:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/context-firewall.png" alt="context firewall" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->How we're incorporating this at HumanLayer</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We have had a feature in the tool for a while that warns the user when they're context is getting high. We used to set this at around %40 of sonnets 168k token window (200k - 32k reserved for output). This came out to about 100k tokens.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">To help users maximize instruction adherence and intelligence on hard codebase problems, we've updated our context warnings for long-context models to trigger at the 100k token mark instead of 40% of the usable context. For opus 1m this is only 10% of the context window.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->TL;DR</h2>
<div class="pl-8 mb-6"><ol class="list-decimal space-y-4" style="color:var(--text-secondary)">
<li>Long-context models degrade at all context lengths, not just long ones.</li>
<li>More context isn't more capability - the instruction budget doesn't scale with the context window.</li>
<li>Context isolation beats context expansion. Sub-agents, progressive disclosure, and <a href="https://www.humanlayer.dev/blog/context-efficient-backpressure" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">context-efficient backpressure</a> keep each context window small, focused, and in the smart zone.</li>
</ol></div></description>
<link>https://www.humanlayer.dev/blog/long-context-isnt-the-answer</link>
<guid isPermaLink="false">https://www.humanlayer.dev/blog/long-context-isnt-the-answer</guid>
<pubDate>Sun, 22 Mar 2026 16:00:00 GMT</pubDate>
<author>Kyle</author>
<category>agents</category>
<category>claudecode</category>
<category>best</category>
<category>context</category>
</item>
<item>
<title>Getting Claude to Actually Read Your CLAUDE.md</title>
<description><p style="display:block;color:var(--text-secondary)" class="mb-4">Claude Code wraps your CLAUDE.md in a <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;system_reminder&gt;</code> that explicitly tells the model the contents "may or may not be relevant." The longer your file gets, the more Claude seems to treat individual sections as optional.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">wrote before</a> about keeping these files concise and avoiding stuff that belongs in a linter. But even after trimming things down, I kept running into cases where Claude would ignore testing instructions while writing tests, or skip our API conventions when building endpoints.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Conditional <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;important if&gt;</code> blocks</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">What's been working for me: wrapping sections in <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;important if="condition"&gt;</code> tags.</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">&lt;important if="you are writing or modifying tests"&gt;
</span>- Use `createTestApp()` helper for integration tests
<!-- -->- Mock database with `dbMock` from `packages/db/test`
<!-- -->- Test fixtures live in `__fixtures__/` directories
<!-- -->&lt;/important&gt;</code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We don't have a rigorous explanation for why this helps. My guess is that the explicit condition gives Claude a clearer signal about when to apply the instructions, rather than leaving it to decide relevance on its own. Whatever the mechanism, we've seen noticeably better adherence on tasks where only some sections of my CLAUDE.md should apply.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">A few things I've learned:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">Don't wrap everything.</strong> Project identity, directory structure, and tech stack are relevant to basically every task. The conditional blocks are for testing setup or deployment procedures that only matter sometimes.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">Make conditions specific.</strong> <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">&lt;important if="you are writing code"&gt;</code> matches almost everything and defeats the purpose. I try to make each condition narrow enough that it only fires when I actually want those rules applied.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->A skill to automate this</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">I did a lot of restructuring CLAUDE.md files by hand, so I made a Claude Code skill that does the rewrite. It pulls out the foundational stuff, wraps domain-specific sections in conditional blocks, and cleans up some common problems (stale code snippets, style rules that should be in a linter, vague instructions that don't actually help).</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It's not perfect—you'll probably want to review what it produces—but it's a decent starting point.</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Try it</h2>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">npx skills add humanlayer/skills --skill improve-claude-md</span></code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Then in your project:</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">/improve-claude-md</span></code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It reads your existing CLAUDE.md and outputs a rewritten version. Source is at <a href="https://github.com/humanlayer/skills/tree/main/plugins/improve-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">github.com/humanlayer/skills</a>.</p></description>
<link>https://www.humanlayer.dev/blog/stop-claude-from-ignoring-your-claude-md</link>
<guid isPermaLink="false">https://www.humanlayer.dev/blog/stop-claude-from-ignoring-your-claude-md</guid>
<pubDate>Mon, 16 Mar 2026 16:00:00 GMT</pubDate>
<author>Dex</author>
<category>agents</category>
<category>claudecode</category>
<category>skills</category>
</item>
<item>
<title>Skill Issue: Harness Engineering for Coding Agents</title>
<description><p style="display:block;color:var(--text-secondary)" class="mb-4">We've spent the past year watching coding agents fail in every conceivable way: ignoring instructions, executing dangerous commands un-prompted, and going in circles on the simplest of tasks.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We've seen teams ship immense amounts of slop. We've even <a href="https://www.youtube.com/live/99Kxkemj1g8?si=tVsK88M3XPyo0urD&amp;t=20967" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">shipped a little bit of slop ourselves</a>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Every time, the instinct was the same:</p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li>"We just need better models, GPT-6 will fix it"</li>
<li>"We just need better instruction-following"</li>
<li>"It'll work once [niche library I'm using] is in the training data"</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">But over the course of dozens of projects and hundreds of agent sessions, we kept arriving at the same conclusion: it's not a model problem. It's a <strong style="color:var(--text-primary)">configuration problem</strong>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Yes, models will get smarter, and some existing failure modes will disappear. And then because they are smarter, we will give them new problems which are bigger and harder, and they will <strong style="color:var(--text-primary)">continue to fail in unexpected ways</strong>. Unexpected failures modes are a fundamental problem for non-deterministic systems.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/gpt-6.png" alt="gpt-6" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">So instead of praying for <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">gpt-6.4-codex-ultrahigh_extended</code> to save us all, we try to focus on answering the question of <em style="color:var(--text-secondary)">"how do we get the most out of <strong style="color:var(--text-primary)">today's</strong> models?"</em></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">There are lots of ways to get better performance out of your coding agent. If you use coding agents for moderately hard tasks, you've probably configured your coding agent a bit. Have you used skills? MCP servers? Sub-agents? Memory? AGENTS.md files?</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider border bg-transparent text-[var(--accent)] border-transparent hover:bg-[var(--accent)]/10 hover:border-[var(--accent)] focus-visible:border-[var(--accent)] focus-visible:ring-[var(--accent)]/50 size-9 absolute top-2 right-1 h-6 w-6 opacity-0 group-hover:opacity-100 transition-opacity duration-200 z-10" aria-label="Copy code" title="Copy code"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-copy h-3 w-3" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2" ry="2"></rect><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"></path></svg></button><code class="overflow-x-auto" style="white-space:pre"><span class="">coding agent = AI model(s) + harness</span></code></pre></pre>
<p style="display:block;color:var(--text-secondary)" class="mb-4">These are all technically separate concepts, but they are all part of the coding agent's configuration surface. We call this the <strong style="color:var(--text-primary)">coding agent's harness</strong>, and we think of it as <a href="https://www.vtrivedy.com/posts/claude-code-sdk-haas-harness-as-a-service" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the agent’s runtime</a>, or as its peripherals: what does the model use to interact with its environment?</p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Harness Engineering</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">Harness engineering</strong>, coined by <a href="https://x.com/Vtrivedy10" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Viv</a>, describes the practice of leveraging these configuration points to customize and improve your coding agent's output quality and reliability.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/harness-components.png" alt="harness components" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer">
<em style="color:var(--text-secondary)">Image from <a href="https://blog.langchain.com/the-anatomy-of-an-agent-harness/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Viv's post</a></em></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">As <a href="https://mitchellh.com/writing/my-ai-adoption-journey#step-5-engineer-the-harness" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Mitchell Hashimoto put it</a>, harness engineering</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">[...] is the idea that 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>
</blockquote>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->... as a Subset of Context Engineering</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We view harness engineering as a subset of <a href="https://www.humanlayer.dev/blog/advanced-context-engineering" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">context engineering</a>. Coined by my cofounder <a href="https://x.com/dexhorthy" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Dex</a> in <a href="https://github.com/humanlayer/12-factor-agents" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">12-factor agents</a>, context engineering is a superset of “prompt engineering” and a variety of other techniques for systematically improving AI agents’ reliability.&nbsp;You can find the original talk on <a href="https://www.youtube.com/watch?v=IS_y40zY-hc" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">here</a>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Harness engineering then is the subset of context engineering which primarily involves leveraging harness configuration points to carefully manage the context windows of coding agents.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/harness-engineering.png" alt="harness engineering as context engineering" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">It answers:</p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li>How do we give our coding agent new capabilities?</li>
<li>How do we teach it things about our codebase that aren’t in the training data?</li>
<li>How do we add determinism beyond <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">CRITICAL: always do XYZ</code> in the system message?</li>
<li>How do we adapt the agent’s behavior for our specific codebase?</li>
<li>How do we increase task success rates beyond “magic prompts”?</li>
<li>How do we prevent our context window from inflating too rapidly, or with too much bad context?</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Skills, MCP servers, sub-agents, hooks, and back-pressure mechanisms are all tactical solutions we’ve arrived at.</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->Views on Harness Engineering</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Viv’s posts on harness engineering are worth reading alongside this one — <a href="https://www.vtrivedy.com/posts/claude-code-sdk-haas-harness-as-a-service" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the first</a> frames the four customization levers (system prompt, tools/MCPs, context, sub-agents), and <a href="https://blog.langchain.com/the-anatomy-of-an-agent-harness/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the second</a> works backwards from what models <em style="color:var(--text-secondary)">can’t</em> do natively to derive why each harness component exists.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/backwards.png" alt="working backwards from what models can't do natively" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer">
<em style="color:var(--text-secondary)">Image from <a href="https://blog.langchain.com/the-anatomy-of-an-agent-harness/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Viv's post</a></em></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We’d add two levers he doesn’t emphasize:</p>
<div class="pl-8 mb-6"><ol class="list-decimal space-y-4" style="color:var(--text-secondary)">
<li><strong style="color:var(--text-primary)">hooks</strong> for automated integration and deterministic control flow</li>
<li><strong style="color:var(--text-primary)">skills</strong> for progressive disclosure of knowledge. (Dex likes to refer to them as "Instruction Modules" - more on this in another post.)</li>
</ol></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">After months of solving hard problems in complex brownfield enterprise-scale codebases, we have found that sub-agents are a particularly powerful lever. When working on hard problems that require many, many context windows to solve, <strong style="color:var(--text-primary)">sub-agents are the key to maintaining coherency across many sessions</strong>. Sub-agents <strong style="color:var(--text-primary)">function as a "context firewall"</strong> that ensures discrete tasks can run in isolated context windows so none of the intermediate noise accumulates in your parent thread which is responsible for orchestration, and you can maintain coherency for much, much longer.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/context-firewall.png" alt="context firewall" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">OpenAI recently wrote a <a href="https://openai.com/index/harness-engineering/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">blog post</a> on the topic as well. There's some great content in there, and it seems to indicate that they view harness engineering as configuring everything <em style="color:var(--text-secondary)">outside</em> of the agent's runtime. It's more focused on back-pressure and verification mechanisms. (Although this may be a mis-reading; the post is somewhat unclear: the word "harness" only appears once in the text of the post, and in reference to evals rather than harness engineering itself.)</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->But What About Post-Training?</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Given that frontier coding models are post-trained on their harnesses (e.g. Claude in Claude Code, GPT-5 Codex in Codex), some will argue that the best harness and/or configuration is the one that the model was trained on.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">For example, the Codex models are so tightly coupled with the Codex harness's <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">apply_patch</code> tool that <a href="https://opencode.ai/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">OpenCode</a> — built as an open-source alternative to Claude Code — had to <a href="https://github.com/anomalyco/opencode/pull/9127" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">add an <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">apply_patch</code> tool</a> specifically for GPT/Codex models to mimic the Codex harness to improve the Codex models' performance in the OpenCode harness - while Claude and other models still use normal <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">edit</code> and <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">write</code> tools.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">This <em style="color:var(--text-secondary)">can</em> mean that a model will perform better when coupled with the harness it was post-trained on, and some might infer that this means you shouldn't customize the harness at all.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">But it cuts both ways: <strong style="color:var(--text-primary)">models can be over-fitted to their harness</strong>. Viv cites <a href="https://terminalbench.com/" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">Terminal Bench 2.0</a> where Opus 4.6 in Claude Code comes in position #33, but when placed in a different harness that wasn't seen during post-training, it comes in at #5 (+/- about 4 positions in either direction).</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/terminal-bench.png" alt="terminal bench" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<h2 class="text-3xl mb-3 mt-20 font-bold" style="color:var(--text-primary)">## <!-- -->Engineering Your Harness</h2>
<p style="display:block;color:var(--text-secondary)" class="mb-4">With that in mind, let's walk through the configuration surfaces we've found most impactful.</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->CLAUDE.md &amp; AGENTS.md</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Before touching any other harness configuration points, it's usually worth customizing your CLAUDE.md / AGENTS.md files. These are markdown files at the top-level of your repository that get deterministically injected into the agent's system prompt by the harness.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We have already shared <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">some opinions about what makes a good CLAUDE.md</a> file and how to use it correctly, so give that a read if you're not familiar with it. Matt Pocock also wrote a <a href="https://www.aihero.dev/a-complete-guide-to-agents-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">great follow-up</a> that more generally applies to AGENTS.md.</p>
<h4 class="text-xl mb-1 mt-8 font-bold" style="color:var(--text-primary)">#### <!-- -->The ETH Zurich Study</h4>
<p style="display:block;color:var(--text-secondary)" class="mb-4">After ETH Zurich published their <a href="https://arxiv.org/abs/2602.11988" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">study testing 138 agentfiles across various repos</a> which indicated that most agentfiles were useless-or-worse, we got a lot of feedback on our <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">CLAUDE.md post</a>:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">See, CLAUDE.md files don't even help — they're a waste of time.</p>
</blockquote>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Indeed: the study tested many agentfiles across a wide variety of repos, and found:</p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li>that LLM-generated ones actually <em style="color:var(--text-secondary)">hurt</em> performance while costing 20%+ more</li>
<li>human-written ones only helped about 4%.</li>
<li>Agents spent 14-22% more reasoning tokens processing context file instructions, took more steps to complete tasks, and ran more tools — all without improving resolution rates.</li>
<li>Codebase overviews and directory listings didn't help at all; agents discover repository structure on their own just fine.</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">A careful reading of the study <strong style="color:var(--text-primary)">indicates that what we said in our post was correct:</strong></p>
<div class="pl-8 mb-6"><ul class="list-disc space-y-4" style="color:var(--text-secondary)">
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">Agent-generated files were worse. Yes, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">avoid auto-generating it. You should carefully craft its contents for best results.</p>
</blockquote>
</li>
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">Lots of files too-heavily-steered the model to use specific tools, causing worse outcomes. Yep, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">Less (instructions) is more. While you shouldn't omit necessary instructions, you should include as few instructions as reasonably possible in the file.</p>
</blockquote>
</li>
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">Files contained irrelevant context. Yep, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">Use Progressive Disclosure</p>
</blockquote>
</li>
<li><p style="display:block;color:var(--text-secondary)" class="mb-4">The human-written ones barely helped because of too many conditional rules. Yep, we said:</p>
<blockquote class="border-l-4 pl-4 my-4 italic" style="border-color:var(--accent);color:var(--text-muted)">
<p style="display:block;color:var(--text-secondary)" class="mb-4">Keep the contents of your CLAUDE.md concise and universally applicable.</p>
</blockquote>
</li>
</ul></div>
<p style="display:block;color:var(--text-secondary)" class="mb-4">Our CLAUDE.md is under 60 lines.</p>
<h3 class="text-2xl mb-2 mt-16 font-bold" style="color:var(--text-primary)">### <!-- -->MCP Servers Are for Tools</h3>
<p style="display:block;color:var(--text-secondary)" class="mb-4">MCP servers are&nbsp;primarily for plugging tools into your coding agent to extend its capabilities beyond file I/O and bash commands. The MCP specification includes additional features like resources, prompts, and elicitations, but <strong style="color:var(--text-primary)">these are generally not well-supported by MCP clients and coding agent harnesses</strong>.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The MCP spec supports servers that run on your (or the agent's) local machine which allow the agent to interact with its local environment, but it also supports HTTP-based MCP servers that can connect your agent with remote tools and services like Linear, Sentry, and more.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">When you plug an MCP server into your coding agent, the list of available tools, their descriptions, and the arguments needed to invoke them <strong style="color:var(--text-primary)">are injected into your coding agent's system prompt</strong>. As a result, the MCP server can use the tool descriptions to customize your agent’s behavior by providing your agent with instructions about when to use them.&nbsp;</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><strong style="color:var(--text-primary)">WARNING</strong>: because MCP servers’ tool descriptions are added to your coding agent’s system prompt, never connect to one you don’t trust. This can be a dangerous vector for prompt injection! STDIO servers and other servers that run client-side with npx or uvx can also execute code on your host in the absence of prompt injection.</p>
<h4 class="text-xl mb-1 mt-8 font-bold" style="color:var(--text-primary)">#### <!-- -->Too Many Tools Is Bad</h4>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We’ve seen this firsthand: plug too many MCP tools into your agent, and the context window fills up with tool descriptions, pushing you into <a href="https://youtu.be/rmvDxxNubIg?si=O17nmS3SScaAkpp-&amp;t=355" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">the dumb zone</a> much faster:</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4"><img src="https://www.humanlayer.dev/blog/skill-issue/too-many-tools.png" alt="too many tools" class="max-w-full h-auto my-4 rounded-none" style="border:1px solid var(--border-color)" referrerpolicy="no-referrer"></p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">The <a href="https://www.aihero.dev/a-complete-guide-to-agents-md#the-instruction-budget" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">instruction budget</a> matters too — every irrelevant tool description is an instruction the agent has to process without any benefit.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">In fact, these failure modes are so common that Anthropic released <a href="https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">experimental support for MCP tool search</a> to progressively disclose tools to Claude when the user has too many MCP tools connected. TL;DR: if you’re not actively using a server which provides a large number of tools, turn it off.</p>
<p style="display:block;color:var(--text-secondary)" class="mb-4">We also found that if an MCP server duplicates functionality that’s already available as a CLI well-represented in training data, it works better to just prompt the agent to use the CLI. For things like GitHub, Docker, or most databases, your coding agent can just use the right CLIs and shell commands. The model has seen these tools enough during training that it already knows how to use them, and you gain the added benefit of composability with tools like <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">grep</code> and <code class="px-2 py-0.5 rounded font-mono bg-[var(--code-bg)] text-[var(--accent)] border border-[var(--code-border)] tracking-tight shadow-sm mr-1 align-middle wrap-anywhere box-decoration-clone">jq</code> to enable additional context-efficiency.</p>
<h4 class="text-xl mb-1 mt-8 font-bold" style="color:var(--text-primary)">#### <!-- -->Always Be Context-Engineering</h4>
<p style="display:block;color:var(--text-secondary)" class="mb-4">At HumanLayer, we used the Linear MCP server for a while before realizing that we really only used a small subset of the tools it provides - so we wrote a small CLI that wraps the Linear API and provides very context-efficient responses, and we included 6 example usages in our <a href="https://www.humanlayer.dev/blog/writing-a-good-claude-md" target="_blank" rel="noopener noreferrer" class="underline hover:opacity-80 transition-opacity" style="color:var(--accent)">CLAUDE.md</a> file:</p>
<pre class="group"><pre class="prismjs rsh-code-block grid relative min-w-[250px] mb-6 bg-gray-400/5 p-4"><button data-slot="button" class="inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-none text-sm font-mono font-medium cursor-pointer disabled:cursor-not-allowed disabled:pointer-events-none disabled:opacity-50 [&amp;_svg]:pointer-events-none [&amp;_svg:not([class*='size-'])]:size-4 shrink-0 [&amp;_svg]:shrink-0 outline-none focus-visible:ring-[3px] uppercase tracking-wider bor |
TonyRL
reviewed
Apr 3, 2026
| const response = await ofetch(listUrl); | ||
| const $ = load(response); | ||
|
|
||
| const list = $('a.block.py-2.group[href^="/blog/"]:not([href^="/blog/tags/"])') |
Collaborator
There was a problem hiding this comment.
Once again redundant filtering using not(). Provide a screenshot if the site does return a[href^="/blog/tags/"] to you with class name block py-2 group.
Here's what I'm seeing
Comment on lines
+55
to
+56
| const category = parts | ||
| .slice(3) |
Collaborator
There was a problem hiding this comment.
Use parts[3] instead of copying it again.
| const category = parts | ||
| .slice(3) | ||
| .join(' ') | ||
| .match(/#\w+/g) |
Collaborator
There was a problem hiding this comment.
/#\w+/ cannot match words after - which you can see from the results.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Involved Issue / 该 PR 相关 Issue
Close #
Example for the Proposed Route(s) / 路由地址示例
New RSS Route Checklist / 新 RSS 路由检查表
PuppeteerNote / 说明
/humanlayer/blog— Scrapes humanlayer.dev/blog for blog posts on AI agents, context engineering, and coding best practices?limit=query parametervia HAPI
Co-Authored-By: HAPI noreply@hapi.run
🤖 Generated with Claude Code