DEV Community: Build Loops

Your Coding Agent Has More Access Than You Think. Here's the Audit.

Build Loops — Mon, 10 Aug 2026 11:38:12 +0000

DEV.to has a trend right now called "sandboxing your AI coding agent." Nineteen posts in a week. New accounts, template titles, and one of them openly admits it's vendor outreach. It's noise — but the signal under it is real: developers are realizing their coding agent has actual power over their machine, and they don't know where it ends.

I can tell you where it ends, because the answer is public. And it's not where most people think.

Do you know what your agent can actually touch — read, write, run, and phone home?

That's the question this post answers. Not with vibes, not with a sales pitch, and not with "just trust it." With the real permission defaults, the real failure receipts, and a five-check audit you can run in an afternoon.

Your agent is more powerful than you think

Coding agents ship with the same three powers that make security people nervous: a shell, file write access, and network access. The difference between tools isn't whether they have those powers — it's what they do before using them.

Take the two agents most people are actually using right now.

OpenCode defaults to allow. From their own docs: "If you don't specify anything, OpenCode starts from permissive defaults — most permissions default to allow." The only two things that prompt you by default are accesses outside your working directory and repeated tool calls. .env files are denied — the one hard rule baked in. Everything else, including a full bash shell, runs without asking.

And here's the part almost nobody knows: OpenCode has no sandbox. It's their own words.

"OpenCode does not sandbox the agent. The permission system exists as a UX feature… it is not designed to provide security isolation. If you need true isolation, run OpenCode inside a Docker container or VM."

That's from their SECURITY.md. The permission prompt is a convenience, not a cage.

Claude Code is the cautious one — relatively. Bash commands ask before running, except a fixed read-only subset (cat, grep, pwd, diff, read-only git…). Permission rules are evaluated deny → ask → allow. It has a real sandboxed Bash tool (bubblewrap on Linux, Seatbelt on macOS) that isolates filesystem and network. Anthropic claims it cuts permission prompts by 84% internally.

But even "cautious" means: shell access, write access, network access — all present, all gated by prompts you habitually click through.

This gap between "the tool asks me sometimes" and "the tool is actually contained" is exactly what OWASP calls excessive agency — the #1 blind spot in agent security.

Developers already sense it. In the 2025 Stack Overflow survey, 81% of developers said they're concerned about AI security — yet 52% either don't use agents or stick to simple ones, and 38% have no adoption plan. Concern is high, verification is rare. That gap is this post.

Where it breaks: the receipts

This isn't hypothetical. Every major agent has a patched CVE or a user-reported incident on the same handful of failure modes.

Prompt injection turns approved commands into remote code execution. Trail of Bits showed argument injection against pre-approved commands achieving one-shot RCE on popular agents. Academic research measured up to 84% command-execution success against Cursor and Copilot with prompt injection.

Repo files execute code before you approve anything. This is the scariest cluster, because it happens before the trust dialog:

CVE-2025-65099 — a malicious Yarn config in a project ran code before Claude Code's trust prompt.
CVE-2026-21852 — a repo's ANTHROPIC_BASE_URL redirected API traffic and siphoned the API key before the trust prompt. CVSS 7.5.
CVE-2026-33068 — a repo silently set permissions.defaultMode: bypassPermissions and skipped the trust dialog entirely. CVSS 8.8.
CVE-2025-54795 — command injection via echo parsing let a prompt-injected agent run arbitrary commands. CVSS 9.8.

"Secure" modes leak. A bypassPermissions rule, a misread glob, a model-generated path, and the boundary is gone: Cursor's allowlist bypass, and Codex's sandbox bypass where the model-controlled working directory became the writable root.

And the user-reported incidents read like a horror list:

An agent deleted a user's main GitHub repository after misreading a rename command. Restored via GitHub's 90-day window.
rm -rf src wiped a Vue project in standard, non-auto mode.
An agent launched in an empty directory wrote 40+ files into a sibling repo without saying anything.
Cursor read and echoed .env credentials despite a .cursorignore file.

The pattern across all of them: the boundary held until it didn't, and nothing noticed until after the damage. That's why the audit below exists.

The audit: five checks, one afternoon

No security degree required. Run these once now, and re-run after every agent or tool update — because each update can silently change the defaults.

Check 1 — Read your permission config

Find out exactly what runs without asking. In Claude Code, run /permissions and inspect settings.json — the deny → ask → allow order means a single ask rule can silently upgrade. In OpenCode, review the permission block in your config and your agent files. You're hunting for three things: blanket rules like Bash(*), any auto or bypass mode, and network tools (webfetch, websearch, curl). Ask yourself: is there a single command here I would never want auto-approved? If yes, that rule gets a deny.

Check 2 — Plant canaries

A canary is a decoy your agent has no legitimate reason to touch. Drop a fake credential into a file (sk-test-DONOTREAD-…), a bait .env, or a tripwire file outside the workspace. Check after your sessions: if the canary moved, got read, or shows up in agent logs — the boundary leaked. Canary tokens turn this into an alert. The read is invisible to you otherwise: file reads leave no trace, which is exactly why a canary is the right tool.

Check 3 — Test egress

Can the agent reach the network? Blocked HTTP with open DNS is still an exfiltration pipe. Two probes: request the cloud metadata endpoint 169.254.169.254 (it should fail), and check whether your DNS resolver logs hits on a hostname only the agent could have looked up. If you care about this, default-deny the network with a proxy or firewall rules — don't assume the agent's "network access" setting means anything on your machine.

Check 4 — Verify the sandbox is real

If you rely on a sandbox, confirm it's enforced, not just configured. A container with --privileged, --cap-add=SYS_ADMIN, seccomp=unconfined, or a mounted docker.sock is not a sandbox — it's a room with the door off. Check with docker inspect, look at /proc/self/attr/current for AppArmor, and probe a blocked syscall. Tools like cagecheck automate this. And remember the OpenCode case: if your tool has no sandbox, the only honest isolation is a container or VM.

Check 5 — Make read-only real

Plan mode and read-only agents are prompt-based, not enforced — a misbehaving model can still write. If you want a hard guarantee, enforce it structurally: a PreToolUse hook that returns deny for edit/write tools outside approved modes, or run exploration agents against a read-only mount. Enforce with a hook, don't hope with a prompt.

Where trust really breaks

The audit catches what's misconfigured. But there's a deeper failure that no checklist fixes — and it's the one the trend posts never mention:

Permission rules are enforced by the tool, not by the model.

An allow rule is a contract the tool will honor. The model, on the other hand, is a probabilistic text-completer that can be prompt-injected, can misread a path, or can interpret "clean up" as "delete everything in src." The load doesn't guarantee the obey. Every incident above is a loaded rule that wasn't obeyed — which is exactly why a session log matters (I wrote the system for that), and why I keep saying migration is a re-declaration, not a file copy (the diary version).

The practical consequence: boundaries are a systems-design problem, not a model-politeness problem. Your agent's cage is your config, your hooks, and your harness — not the model's mood. That's the framework behind the whole AGENTS.md approach I write about.

The verdict

You don't need to fear your coding agent. You do need to audit it — because the defaults are wider than you think, the failures are documented and recurring, and nobody else is going to check for you.

Five checks. One afternoon. Re-run on every tool update.

Read your permission config. Plant canaries. Test egress. Verify the sandbox. Enforce read-only.

Then ask yourself the question from the top of this post, and actually know the answer: what can my agent read, write, run, and phone home?

The "sandbox your agent" trend is full of posts from accounts that were created last week. The signal under the noise is real, and it's this: nobody's checking what their agent can touch. This is the check.

What's the one thing you'd never want your agent to touch — and have you tested whether it can?

The weird part of the boundary story is that your own rules file is the biggest boundary you already control. Start there: Why Your Coding Agent Keeps Making the Same Mistakes — AGENTS.md Fixes It.

I write about AI engineering stacks, autonomous developer tools, and structural agent design. If you're building in this space, follow @buildloops for weekly breakdowns!

Loaded Obeyed: Why Your Agent Quotes Rules It Doesn't Follow

Build Loops — Sun, 09 Aug 2026 13:00:00 +0000

The file was loaded. The rules just weren't followed. Here's the two-failure diagnostic that tells you which one you have — and what to do for each.

My agent used to follow my rules. The output-format rules, written once into a CLAUDE.md, were obeyed like law — for months, in Claude Code.

Then I migrated to OpenCode, and the rules quietly stopped meaning anything. The agent quoted them back flawlessly. It recited them every time I asked. And it ignored them, day after day, rule after rule. The file was loaded. The rules just weren't obeyed.

The fix wasn't stronger wording, and it wasn't a better prompt. It was re-declaring every rule, one by one, into a fresh AGENTS.md — and it held.

That's the lesson this post is built on: a rule that isn't followed is one of two failures. Either it never loaded, or it loaded and lost. Here's how to tell which, and what to do for each.

The days of the break

I didn't run that test once. I ran it in fresh sessions, multiple times, for days. Every time, the same answer: a perfect recital. Every time, the same next output: the format rules broken.

In the middle of it, the token usage climbed — noticeably higher than expected. Not because the work was harder. Because the rules were being re-derived and re-explained instead of followed, every session, on top of a MEMORY.md that was already bloated. Token waste and trust damage from the same root cause.

This is the exact state readers end up in with their own agents, and the reason most of them are on GitHub filing issues that never get answered.

So let's name what that means.

The two lanes — the diagnostic

Here's the model that ended my guesswork. A rule that isn't followed is one of two failures:

	Lane A — never loaded	Lane B — loaded and lost
What it is	A file/loading problem: wrong file, nested or path-scoped rule, compacted away, not read at all	A model-behavior problem: the rule reached the context window and still didn't steer
The truth about it	The harness never applied weight to this rule	Rules are context, not enforced configuration
The fix	Re-declare it into the file the harness actually reads, then verify	Redesign the rule's shape, or move it to a mechanism that can't lose
Cost of guessing wrong	You reword a rule that never mattered	You reword a rule forever, because wording was never the lever

The whole point of the model is that these are two different problems with two different fixes. Most advice treats them as one problem — "write better rules" — which is why so much of that advice doesn't change anything.

My migration had both lanes in play. But the one that broke me was neither, exactly. It was the state in between.

The gray zone — "loaded but not load-bearing"

Here's what my migration actually looked like. OpenCode reads AGENTS.md as its first-class rules file, and it falls back to CLAUDE.md if there's no AGENTS.md — which is why the agent could quote my old rules at all. The fallback file was present enough to recite.

Present enough to quote. Not enough to act on.

The telling detail was what the agent couldn't do. It could recite the general rules. It couldn't tie them to a file or a plan — it couldn't tell me where they lived or what it would do to follow them. That's the gray zone's fingerprint: quoting without any load-bearing behind it.

I call that state loaded but not load-bearing — and it quietly breaks the most common piece of advice in this space: "ask your agent what your rules are." I asked, every single day. The answer was always a perfect recital. The recital proved a file existed. It proved nothing about whether the rule carried any weight.

That's the trap the two-lane model has to catch before it can help you: the gray zone — a rule that is loaded, quotable, and useless.

The verification hierarchy — the only test that works

The reason "what are my rules?" failed me is that it's the bottom rung of a three-rung ladder:

Quoted. "What are my rules?" — proves a file of some kind was read. Proves nothing about which file, or whether it steers.
Quoted and located. "Quote the exact rule and show me where it lives." — this catches the gray zone. If the agent can quote the rule and point at the file that's actually being loaded, you know you're in Lane B. If it can't, you're in Lane A (or the gray zone).
Behavioral output. The rule is followed in real work, consistently, without you re-asking. This is the only proof of obedience.

The one line you can run today:

"Quote the exact rule, show me where it lives, and tell me what you'll do with it."

And what a passing answer looks like — this is the test I ran after the re-declaration:

"The output-format rule is the first block under Output format in AGENTS.md. It requires a per-file summary (path, what changed, why) and a fenced, language-tagged code block for every diff. I'll apply it: every change in this session gets that summary and a tagged diff block."

That's quoted + located + plan statement — level 2 proven. Then you watch the next output for level 3.

The asymmetry matters here: Claude Code can show you loading proof directly — /context lists what actually loaded. OpenCode doesn't have an equivalent shipped (there's an open issue asking for loading verification). Which means on OpenCode, this test isn't optional. It's the whole test.

The docs say it's by design

This is the part that ended the blame-game for me, because the mechanism is documented.

Anthropic's own memory docs describe CLAUDE.md as providing "context, not enforced configuration." And they're explicit about what that means: there's "no guarantee of strict compliance" — the wording is right there in the docs for anyone to read.

Your agent ignoring a rule you wrote is not a personal prompt failure. It's the documented behavior of a system where instructions are context rather than commands. That reframes the whole problem: the question isn't "why is my agent broken," it's "which lane is this rule in, and what does the fix look like when instructions aren't commands?"

And it's not just me saying it. The issue trackers are full of this exact failure — users reporting "my agent quoted my rules back and ignored them," and the admissions go further. In one thread, a user counted 14+ corrections on a single rule before anything stuck. The demand set is real, current, and cross-harness: it's the "I Told You" Developer's situation, at scale.

Lane A fix — re-declare, then verify

What finally fixed my migration wasn't a better prompt or stronger wording. It was re-declaring every rule, one by one, into a fresh AGENTS.md — the file OpenCode actually applies weight to.

Copying files across hadn't worked. The old CLAUDE.md came along, was read as a fallback, and was quotable without being load-bearing. The re-declaration was different because it moved the rules into the first-class file — and then I verified each one at level 2, and watched the output for level 3.

Here's the shape the rule needed to take. This is a faithful reconstruction of the kind of rule that lived in the fallback CLAUDE.md — a paragraph buried in a file that held rules, context, and everything else:

Always present your output in a clear and professional format. Use code blocks where appropriate and make sure diffs are easy to read. Pay attention to formatting quality in all responses.

Vague, not checkable, one paragraph competing with every other paragraph in the file.

And this is how the same rule reads re-declared in the fresh AGENTS.md:

Output format (required, no exceptions):

Every change is summarized as: file path, what changed, why.

Every diff is a fenced code block tagged with the language.

Never inline a diff without a code block.

When in doubt about the format, ask before outputting — do not improvise.

Every line is checkable — the summary either has the three parts or it doesn't; the diff either is fenced or isn't. Self-verifying by observation.

It was a one-time fix. The rules went into a fresh AGENTS.md once, and the loaded-but-not-load-bearing state never came back. Since that day I've been fully settled on OpenCode — the fixes since have been minor.

Here's the part I had to learn the hard way: re-declaration fixes loading, not obedience. If a rule is in Lane A, re-declaring it into the right file is the fix. If a rule is already in Lane B — loaded into the right file and still ignored — re-declaring it does nothing. Which brings us to the second fix.

Lane B fix — redesign, or move it to the mechanical floor

Once you've confirmed a rule is genuinely loaded and still losing, the choice comes down to a single question:

Can I afford for this rule to lose?

If the answer is yes — and the output-format rule from the previous section is exactly this kind — keep it in prose, but make sure it's shaped well: short, specific, prohibition-framed, impossible to misread. You can see the output either follows it or doesn't, so it's the right fit for the load-bearing file.

If the answer is no, prose is the wrong home for it. The rule can't afford a single loss, so it moves to the mechanical floor: hooks, deny rules, permission configs. Mechanisms can't be ignored because they're not asking the model to comply; they're intercepting the action. (Reporails' line captures it: prompts steer, hooks enforce.)

Your own secrets rule is the perfect example — "don't push secrets to git repos." (GitHub's analysis of 2,500+ repos found it the single most common rule in AGENTS.md files.) As prose, it's the weakest kind of rule:

Never push secrets to the repository. Check for API keys and credentials before every commit.

It's not self-verifying by observation — a leaked secret looks like a normal commit. It's catastrophic when lost even once. And the docs' "no guarantee of strict compliance" means the model is never forced to check. It's a rule that begs to be ignored in a rushed session — which is exactly when secrets leak.

So the mechanical version:

A pre-push secret scan (a git-secrets / gitleaks style hook) that blocks the push if a secret pattern matches.

A deny rule on the harness side (e.g., deny reading .env, deny the push action until the scan passes).

.env in .gitignore as defense-in-depth.

The mechanism intercepts the action — the model isn't being asked to comply, so there's no "strict compliance" gap to exploit. The choice stops being abstract: one rule earns shaped prose, the other earns the floor.

I'll be straight with you: I don't run a mechanical enforcement layer. My safety net is the memory loop — AGENTS.md tells the agent to read MEMORY.md at the start of every session and update it at the end (the exact three-file system I built), and that log is how I'd notice a rule starting to get ignored (the entries would begin to diverge from what the rules require). The escalation above is for rules you can't afford to lose, not the setup I run.

And the takeaway that ties the series together: rules are another thing you have to re-declare, not carry. When your agent keeps making the same mistakes, the fix is the file that tells it how to work — and knowing what that file can and can't enforce is the difference between a rule that steers and a rule that decorates.

The blurry line — compaction and nested files

One more thing, because it's the case that misleads everyone.

Compaction — when the context window gets rebuilt mid-session — re-injects the root CLAUDE.md. What it does not re-inject is nested or path-scoped rules, or rules that lived in files outside the root. The same goes for nested files in general: if a rule lives in a subdirectory that only loads in certain paths, and you switch harnesses, it can quietly drop out of the bundle.

The result looks exactly like Lane B. "The agent just ignored my rule," you'll think, and start rewording a rule that never actually loaded — a Lane A costume on a Lane A failure. This is where the two-lane test matters most: diagnose before you reword. Quote-and-locate first. Only then decide whether the fix is re-declaration, redesign, or the mechanical floor.

Closing the loop

The mystery at the top of this post — rules that worked, then quoted-and-ignored — resolved into something much simpler than I expected. Loaded ≠ obeyed. The file was loaded; the rules just weren't load-bearing. And once you see the failure as two lanes instead of one, the fix stops being a guessing game: re-declare if it never loaded; redesign or enforce if it loaded and lost.

The migration made both lanes visible at once. That's the only reason I can hand you the diagnostic instead of a longer list of things that didn't work. If your agent quotes your rules and ignores them, run the test — quote, locate, watch the output — and you'll know which lane you're in before you change a single word.

Rules are another thing you have to re-declare, not carry. If your agent keeps making the same mistakes, the fix is the file that tells it how to work — I wrote the playbook here: Why Your Coding Agent Keeps Making the Same Mistakes — AGENTS.md Fixes It.

This closes Break 1 of the migration diary (what broke when I switched from Claude Code to OpenCode). Next up: why skills silently degrade — the same failure class, different file.

Which of the two lanes are you stuck in? Quote the rule that still isn't obeyed in the comments and I'll tell you which one it is.

I Built a Session Log That Survived My Migration. Here's the Three-File System.

Build Loops — Sat, 08 Aug 2026 07:59:04 +0000

My Claude Code setup was small, which is exactly why its failure surprised me. One root CLAUDE.md. A MEMORY.md beside it. A folder of reference docs, and a second CLAUDE.md doing the job of a rules file. It hummed along for months. Then, with no changes at all, it started leaking.

Claude mixed up the files — rules surfaced as instructions, memory got treated as reference material — and I watched my token count climb on every session. I hadn't touched anything. That was the most frustrating part: it proved the setup had been fragile from day one; the cracks just took months to show.

So I moved. Both feet. I brought every file to OpenCode and started talking to it. It remembered me. It ignored my instructions.

This is what broke after that — ranked, with the rebuild for each one. The short version: the migration isn't a file copy, it's a re-declaration.

What broke, ranked in the order it hurt

The list is ranked by how much each break cost me, not by how loud it was. The quiet ones hurt the most.

Break 1 — My instructions didn't come with me

OpenCode had my memory loaded — it referenced my notes and conventions from MEMORY.md correctly. But my rules from CLAUDE.md weren't in effect. Whether that April version of OpenCode never loaded the file, or loaded it and ignored it, the outcome was identical: my instructions weren't being followed.

The reason became obvious once I stopped to think: CLAUDE.md is Claude's rule file. OpenCode reads AGENTS.md.

On paper that's a one-line rename. In practice it was the first confirmation that this migration was a translation, and the translation work landed on me — not the tool.

The rebuild: re-declare your rules in AGENTS.md. Don't copy — re-declare, because some of what your old rules assumed is now load-bearing. Then verify the rules are actually in effect. Run /init (OpenCode reads CLAUDE.md and seeds AGENTS.md from it — docs), then ask the agent in a fresh session: "what are my rules?" If it can't quote them, they're not loaded. Loaded is not the same as obeyed.

Break 2 — I asked OpenCode to migrate its own predecessor's config

I treated the migration as "bring the files, tell the new agent what I had." Then I went one step further: I asked OpenCode to migrate my skills and MCP servers for me.

The problem with asking a tool to migrate its own predecessor's tooling: it doesn't know what it doesn't know. It can't inventory what it never had. It has no idea which of my skills were load-bearing, which MCPs I used once and forgot, or where the config actually lived. It told me what it could — and couldn't tell me what was missing, because the missing stuff never existed in its world.

The rebuild: inventory first. Before you touch the new tool, list every skill, command, and MCP server you actually use. Write them down while the old tool is still alive to ask. Then decide consciously what gets rebuilt versus what gets dropped. The list is the migration plan — without it, you're migrating whatever happens to survive.

Break 3 — What did migrate degraded silently

The skills that did make it over didn't behave the same. OpenCode read them but ignored chunks of their frontmatter — model assignments, allowed tools, argument handling. And it didn't auto-fire them the way Claude Code did; skills load on demand here, when the agent decides to reach for them.

Nothing errored loudly. They just worked less. That's the worst kind of break: the silent one, because it doesn't surface until you trust the skill and it quietly does the wrong thing.

This one is even documented: OpenCode only recognizes name, description, license, compatibility, and metadata in a skill's frontmatter (skills docs). Everything else is silently ignored.

The rebuild: assume every ported skill is degraded until proven otherwise. Rebuild the ones you actually use and delete the rest (more on this in the "rebuild, don't port" section).

Break 4 — The friction tax

Manually toggling between plan and build modes with Tab, instead of Claude Code's automatic transition. Different keybinds. Different scroll behavior. None of it is a bug — but it's a constant low-grade "this feels wrong" that lasts for the first few weeks.

This one never shows up in migration guides, because it never shows up in a feature table. It's a tax, not a defect.

The rebuild: budget the adjustment period like you'd budget a learning curve — plan on two to three weeks of reduced flow, not two days. On day one, map your three most-used Claude Code keybinds to their OpenCode equivalents. Force yourself through the change instead of reaching for the old muscle memory.

Break 5 — The one that didn't break for me, but will for you: no auto-memory

OpenCode has no native cross-session memory. No silent "remembers what you said last week" like Claude Code has. There's an open feature request for it (#20322), and it's not shipped.

My MEMORY.md survived the migration because it was a file. Yours might not be. If you've been relying on the agent just remembering things across sessions, that memory evaporates the day you switch.

The rebuild: give the agent a session log. Add one instruction to AGENTS.md:

## Session log
At the end of every session, append a short summary to `session-log.md`:
what was done, what's pending, and any decisions made. Never lose a decision.

That one instruction replaced the silent memory I lost — and made my memory better, because now it's explicit, greppable, and portable to whatever tool I use next.

What I gained (the counterweight)

A list of four breaks with no counterweight is a hit piece. Here's the honest other half.

Permission-first by default. OpenCode runs on my hardware — I bring my own keys. And out of the box it asks before acting: it wants to read a folder outside the current directory, it stops and asks. I approve, it proceeds. It rebuilt my trust in the tool faster than any benchmark table could. The honest limits: inside the working directory it's permissive by default, and .env files are denied by default — which is the right default. And keep it updated: the 2026-22812 and 22813 CVEs were patched, and a stale harness is the one risk in an otherwise local-first setup.

One key, many models. My setup is deliberately boring: the built-in model plus a single API key for OpenRouter. One key, dozens of models. Switching models for a task is a config line — not a harness, not a subscription, not a signup flow. After Claude Code, where the model was whatever Anthropic shipped, that felt like the ceiling coming off.

Cost reality. January 9, 2026 is a date a lot of us remember — the day Anthropic restricted third-party tools from using Claude subscription OAuth, with a full cutoff that April. It was the day my project stalled: I sat down to continue work I'd started two or three weeks earlier and couldn't do a thing. A workday gone, a project stuck, and a subscription that no longer worked the way I'd paid for it. On the other side, my token bill became something I could actually reason about instead of a flat subscription that either worked or didn't.

The one lesson that mattered: rebuild, don't port

The inversion that reframed everything: the skills I carried over degraded silently, but a freshly installed skill worked on the first go. No debugging, no frontmatter fighting, no "why won't this load." Drop it in, call it, done.

That flipped how I thought about the whole migration. Don't port your skills — rebuild the ones you actually use.

This applies beyond skills. It applies to rules, memory, and MCP config. And it explains why the ported stuff behaved differently in the first place: the harness matters more than people admit. Same model, different wrapper, measurably different results — in one 2026 benchmark, OpenCode finished in 7 minutes with zero mistakes; Claude Code took 14 minutes and made two, on the same model. Separately, tracker-sourced SWE-bench numbers show a ~3.6-point swing between two harnesses running the same model. The agent is only as good as what's declared to it.

Carry the knowledge. Rebuild the tooling.

Would I do it again? Yes. Here's my day-one do-over

Straight answer: yes. Not once did the breakage list add up to enough to pull me back. Running locally, the permission-first default, a skill workflow that rebuilt better than the original, and the cost — those four outweighed every item on the broke list. That surprised me more than the breaks themselves.

But I'd change day one. In order:

Build the AGENTS.md first — the file that owns the state. Spend the morning on it, not the migration.
Add the session-log instruction ("log what you did each session") so nothing is forgotten and no decision falls through the cracks.
Rebuild the three skills you actually use. Delete the rest.
Re-declare MCPs manually. Audit versions before you trust them.
Decide the model and permission posture consciously — what you run, where you keep keys, where you let it read.

Most of what broke in my migration wasn't the tooling. It was that my knowledge lived in places the new tool couldn't read. The fix isn't a better importer. It's one file that owns the state, written from day one.

Migrate if / stay if

Migrate if you want multi-provider freedom or local models; you're burned by subscription-OAuth economics; you value a permission-first workflow; you're willing to re-declare your rules instead of copying them.
Stay if you're maximally invested in Claude's ecosystem — skills, hooks, auto-memory; you want speed and polish out of the box; you're happy on a flat subscription; you can't spend the adjustment weeks.
Or run both. The honest middle option: Claude Code for fast interactive work, OpenCode for provider experiments. Several reviewers recommend exactly this, and nothing about my migration contradicts it.

Don't do these (the checklist)

Copying files instead of re-declaring rules. Migration is re-declaration, not a file copy.
Trusting "drop-in / full parity" claims. Real parity needs wrappers, plugins, and manual re-declaration.
Assuming rules are in effect because the file loaded. Loaded ≠ obeyed. Verify.
Asking the new agent to migrate the old config. It can't inventory what it never had.
Ignoring the cost shift: per-token models, prompt-cache misses, and the new subscription math.
Skipping the security and version audit. The 2026-22812/22813 CVEs were patched; keep it updated.

The verdict

Four breaks, four wins, no regrets. Everything that broke traced back to the same root: the knowledge was there, it just lived in a place the new tool couldn't read. And the fix was the same for every single one of them — declare it, and log it.

The migration wasn't about which harness is better. It was about making my workflow portable on purpose. That's the only way a migration sticks — whether you move now, later, or never.

FAQ

Does OpenCode read CLAUDE.md?

OpenCode reads AGENTS.md. CLAUDE.md is only used as a fallback when no AGENTS.md exists — which is why copying your CLAUDE.md over and expecting your rules to work is the #1 migration mistake. Re-declare them.

Do my Claude Code skills work in OpenCode?

Partially. OpenCode only recognizes name, description, license, compatibility, and metadata in a skill's frontmatter — everything else is silently ignored, and skills load on demand rather than auto-firing. Rebuild the ones you actually use.

Does OpenCode have auto-memory like Claude Code?

No native cross-session memory (feature request #20322 is open). Add a session-log instruction to AGENTS.md so nothing is forgotten between sessions.

Is migrating worth it?

If you want provider freedom, local-first operation, and a permission-first workflow — yes. If you're maximally invested in Claude's ecosystem (hooks, auto-memory, flat subscription) — stay, or run both.

Can I use the same model in both?

Yes — OpenCode supports 75+ providers including Anthropic and OpenRouter, so you can A/B test the harness effect with the same model.

If you've been fighting the same battle — instructions that aren't followed, memory that disappears between sessions — I wrote the full playbook for fixing it here: AGENTS.md Is Programming for Your AI Agent, Not Documentation for Humans.

What broke when you migrated? Name the one thing you lost that nobody warned you about — and if nothing broke, tell me that too, especially where I'm wrong. I'll collect the rebuilds people reply with in a follow-up.

This is the first post in my agent-workflow migration series.

I write about AI engineering stacks, autonomous developer tools, and structural agent design. If you're building in this space, follow @buildloops for weekly breakdowns!

I Migrated My Claude Code Workflow to OpenCode. Here's What Broke.

Build Loops — Thu, 06 Aug 2026 12:24:49 +0000

So I moved. Both feet. I brought every file to OpenCode and started talking to it. It remembered me. It ignored my instructions.

This is what broke after that — ranked, with the rebuild for each one. The short version: the migration isn't a file copy, it's a re-declaration.

What broke, ranked in the order it hurt

The list is ranked by how much each break cost me, not by how loud it was. The quiet ones hurt the most.

Break 1 — My instructions didn't come with me

The reason became obvious once I stopped to think: CLAUDE.md is Claude's rule file. OpenCode reads AGENTS.md.

On paper that's a one-line rename. In practice it was the first confirmation that this migration was a translation, and the translation work landed on me — not the tool.

Break 2 — I asked OpenCode to migrate its own predecessor's config

I treated the migration as "bring the files, tell the new agent what I had." Then I went one step further: I asked OpenCode to migrate my skills and MCP servers for me.

Break 3 — What did migrate degraded silently

Nothing errored loudly. They just worked less. That's the worst kind of break: the silent one, because it doesn't surface until you trust the skill and it quietly does the wrong thing.

This one is even documented: OpenCode only recognizes name, description, license, compatibility, and metadata in a skill's frontmatter (skills docs). Everything else is silently ignored.

The rebuild: assume every ported skill is degraded until proven otherwise. Rebuild the ones you actually use and delete the rest (more on this in the "rebuild, don't port" section).

Break 4 — The friction tax

This one never shows up in migration guides, because it never shows up in a feature table. It's a tax, not a defect.

Break 5 — The one that didn't break for me, but will for you: no auto-memory

OpenCode has no native cross-session memory. No silent "remembers what you said last week" like Claude Code has. There's an open feature request for it (#20322), and it's not shipped.

The rebuild: give the agent a session log. Add one instruction to AGENTS.md:

## Session log
At the end of every session, append a short summary to `session-log.md`:
what was done, what's pending, and any decisions made. Never lose a decision.

That one instruction replaced the silent memory I lost — and made my memory better, because now it's explicit, greppable, and portable to whatever tool I use next.

What I gained (the counterweight)

A list of four breaks with no counterweight is a hit piece. Here's the honest other half.

The one lesson that mattered: rebuild, don't port

That flipped how I thought about the whole migration. Don't port your skills — rebuild the ones you actually use.

Carry the knowledge. Rebuild the tooling.

Would I do it again? Yes. Here's my day-one do-over

But I'd change day one. In order:

Build the AGENTS.md first — the file that owns the state. Spend the morning on it, not the migration.
Add the session-log instruction ("log what you did each session") so nothing is forgotten and no decision falls through the cracks.
Rebuild the three skills you actually use. Delete the rest.
Re-declare MCPs manually. Audit versions before you trust them.
Decide the model and permission posture consciously — what you run, where you keep keys, where you let it read.

Migrate if / stay if

Migrate if you want multi-provider freedom or local models; you're burned by subscription-OAuth economics; you value a permission-first workflow; you're willing to re-declare your rules instead of copying them.
Stay if you're maximally invested in Claude's ecosystem — skills, hooks, auto-memory; you want speed and polish out of the box; you're happy on a flat subscription; you can't spend the adjustment weeks.
Or run both. The honest middle option: Claude Code for fast interactive work, OpenCode for provider experiments. Several reviewers recommend exactly this, and nothing about my migration contradicts it.

Don't do these (the checklist)

Copying files instead of re-declaring rules. Migration is re-declaration, not a file copy.
Trusting "drop-in / full parity" claims. Real parity needs wrappers, plugins, and manual re-declaration.
Assuming rules are in effect because the file loaded. Loaded ≠ obeyed. Verify.
Asking the new agent to migrate the old config. It can't inventory what it never had.
Ignoring the cost shift: per-token models, prompt-cache misses, and the new subscription math.
Skipping the security and version audit. The 2026-22812/22813 CVEs were patched; keep it updated.

The verdict

The migration wasn't about which harness is better. It was about making my workflow portable on purpose. That's the only way a migration sticks — whether you move now, later, or never.

FAQ

Does OpenCode read CLAUDE.md?

Do my Claude Code skills work in OpenCode?

Does OpenCode have auto-memory like Claude Code?

No native cross-session memory (feature request #20322 is open). Add a session-log instruction to AGENTS.md so nothing is forgotten between sessions.

Is migrating worth it?

Can I use the same model in both?

Yes — OpenCode supports 75+ providers including Anthropic and OpenRouter, so you can A/B test the harness effect with the same model.

This is the first post in my agent-workflow migration series.

I write about AI engineering stacks, autonomous developer tools, and structural agent design. If you're building in this space, follow @buildloops for weekly breakdowns!

Why Your Coding Agent Keeps Making the Same Mistakes — AGENTS.md Fixes It

Build Loops — Wed, 05 Aug 2026 13:15:07 +0000

If you use a coding agent for any real length of time, you hit the same wall: it makes the same mistakes you already corrected. Wrong package manager. Banned patterns. Edits to files that shouldn't be touched. Fix it, and tomorrow it happens again.

The standard advice is "write better prompts" — but that treats a memory problem as a wording problem. The fix is a file called AGENTS.md, which your agent re-reads at the start of every session. The catch: most people write it like documentation, and documentation doesn't change behavior. Here's the difference in one line:

# What most files say (does nothing)
Write clean, maintainable code.

# What changes behavior (works)
Never use npm — install and run everything with pnpm.

AGENTS.md is programming for an AI agent, not documentation for humans. The rest of this article gives you the full template, explains why each section exists, and shows the mistakes that silently make the file useless. Roughly 6 minutes.

TL;DR: a short, specific, maintained file beats a long, detailed one — if a line wouldn't change the agent's output, delete it. Want the file first and the theory second? Scroll to the The drop-in template section below.

What is AGENTS.md?

AGENTS.md is the open-standard file that AI coding agents read at the start of every session — the project's permanent memory for the agent. It's plain Markdown at your repo root, committed to git, and re-read (not remembered) every session, so instructions in it don't decay the way chat context does. The drop-in template is below; the rest of this article explains why each section exists.

Why your agent forgets everything

Coding agents are stateless: every session starts from a blank context, plus guesses derived from other people's code. Your project uses pnpm, your tests need a running database, dist/ is generated and must never be edited — the agent doesn't know any of that, so it guesses, and the correction evaporates when the session ends. That's not the model being bad; it's the agent having no memory.

The mechanism that fixes it is one almost no guide explains: the agent re-reads the file at the start of every session. Chat instructions get buried under newer tokens and drift out of attention — context drift, in every long conversation. Instructions in a file don't decay, because they're re-read, not remembered. Think of it as onboarding for an AI employee: a README tells humans what the project is; AGENTS.md tells the agent how to work here — the exact commands, the conventions, the "don't touch" zones, and the traps that have already hurt someone.

AGENTS.md is code, not prose

Here's the mental shift that changes everything. Documentation describes a system. Code causes behavior. When you write AGENTS.md like a README — descriptive, warm, comprehensive — you're writing prose the agent reads and mostly ignores, because prose is ambiguous and the agent already has a default behavior baked in.

When you write it like code, every line has a job. A line that doesn't change an edit, doesn't earn its place. The rules for writing it well are the same rules you'd apply to good code:

Token cost is real. Every word in this file is loaded into context at the start of every single session, for every single task. A 500-word backstory about your team's engineering philosophy displaces 500 words of actual task context. And context bloat isn't free — Chroma's 2025 study found that all 18 frontier models tested degrade in accuracy as input grows, some dropping from 95% to 60% past a threshold. A bloated file isn't neutral; it's actively making the agent worse. Keep it under ~200 lines. If removing a line wouldn't change the agent's output, delete it.

Specificity beats aspiration. "Write clean, maintainable code" does nothing — the agent already tries to do that. Only include rules that are specific to your project and that the agent couldn't figure out from reading the code. "Use pnpm, not npm" changes behavior. "Follow best practices" doesn't.

Every "never" needs an "instead." Pure prohibitions create dead ends. "Never use any" leaves the agent guessing what to do. "Never use any — use unknown and narrow it with type guards" gives it an escape route. The same rule in miniature: "Use pnpm" is a fact the agent will forget; "Never use npm — install and run everything with pnpm" changes a behavior and names the alternative in one line.

Structure aids parsing. Headers, bullets, and exact commands are easier to prioritize than paragraphs. The same content, organized, is ten times more useful.

One more thing worth being honest about: this is leverage, not magic. As Martin Fowler puts it, context engineering raises the probability of useful results — it can never guarantee them. No matter how good your file is, an LLM is still an LLM. When a rule absolutely must hold, don't write it in Markdown; enforce it deterministically with a hook. Treat the file as your agent's guidance, and hooks as its guardrails.

The drop-in template

Don't read this line by line — copy it, delete what doesn't apply to your project, and keep going. The explanations below matter more than the file itself.

Here's the skeleton. It deliberately mixes two kinds of content. The lean core — sections 1, 5, 6, 7, 9 — is the part that changes edits: exact commands, conventions, guardrails. The workflow contract — sections 2, 3, 4, and the "when in doubt" checklist in section 8 — tells the agent how to operate: plan before code, an approval gate, a skills whitelist. That's not filler; it programs how the agent works with you. It reflects one popular workflow — supervised "vibe engineering," where the agent writes its own implementation prompts and you approve them. Run that workflow and it pays off; work more autonomously or manually and drop it — the lean core works everywhere. Either way, this is a template, not a finished file: anything that isn't true for your project gets deleted, not kept.

# AGENTS.md

You are a principal-level <role> engineer and AI implementation agent working on <PROJECT>, <one-line description>.

Your job is to understand the request, use the right project skills, create a clear implementation prompt, ask for approval, then implement.

---

# 1. Product

<PROJECT> <what it does>.

Build only:

- <feature>
- <feature>

Do not overbuild.

---

<!-- Optional: workflow contract. Sections 2–4 (and the "when in doubt" checklist in section 8) only pay off when you run a supervised, agent-driven workflow (plan, approve, implement). Lean-core-only users can delete them. -->

# 2. Workflow

For every implementation request:

1. Read `AGENTS.md`.
2. Read the skills explicitly mentioned by the user.
3. Read clearly needed supporting skills from the approved skill list.
4. Inspect relevant code.
5. Ask a focused question only if the task has meaningful ambiguity.
6. Create a detailed prompt file in `prompts/`.
7. Ask: "I prepared the implementation prompt at `prompts/<file-name>.md`. Is this good to execute?"
8. Implement only after user approval.
9. Run available checks.
10. Share exact steps to test or run the completed feature.

Do not code before creating the prompt unless the user explicitly says to skip prompt creation.

---

# 3. Skills

Use only these skills:

- `.agents/skills/<skill>`

Do not invent new skills.

---

# 4. Prompt files

Prompt files live in the `prompts/` directory.

Each prompt must include:

- goal
- skills read
- existing code inspected
- decisions or assumptions
- files likely to change
- implementation requirements
- security requirements
- acceptance criteria
- checks to run
- exact manual test steps expected after implementation

<!-- End of the optional workflow contract. Everything from here is lean core — keep it even without the workflow sections. -->

---

# 5. Architecture

Keep these layers separate:

- <layer>: <responsibility>
- <layer>: <responsibility>

<Boundary rule, e.g. "UI must display stored data only.">

---

# 6. Tech stack

Use:

- <stack>

Do not use:

- <stack>

---

# 7. Source of truth

<Name the authoritative source the agent should rely on — a database, a spec document, a config file, an API. It's whatever your project treats as ground truth.>

<What each record or entity stores, required fields, what must never be hardcoded or assumed.>

---

# 8. Security, code standards, and final rule

Never expose to browser code: <secrets>.
Never run from browser code: <side-effectful work>.

<Language / style rules: explicit types, no `any`, small functions.>

When in doubt:

1. Keep it small.
2. Use the relevant skill.
3. Preserve server/client boundaries.
4. Ask a focused question if needed.
5. Save a prompt before coding.
6. Ask if it is good to execute.
7. Implement after confirmation.
8. Run available checks.
9. Share exact test steps.

---

# 9. Commands and checks

"Run available checks" (sections 2 and 8) means running these from the project root and reporting the results:

- `<command>` — <what it does>
- `<command>` — <what it does>

Development and runtime:

- `<command>` — start the dev server
- `<command>` — run tests

After implementation, run the checks and report the exact output. Never claim a check passed without running it.

Your file should pass this test: (1) every line would change the agent's output, (2) every prohibition names an "instead," (3) commands are copy-paste runnable, (4) no line contradicts another, (5) it stays under ~200 lines and gets a monthly review.

Now the part people skip: why each section exists. Start with the lean core — the four sections that change edits:

Product / "Build only" — the agent works best when it knows exactly who it's supposed to be and what it's allowed to build. "Do not overbuild" is the anti-hallucination guardrail: it stops the agent from expanding a small request into a rewrite of the codebase.
Architecture + tech stack — the "Do not use" list matters as much as the "Use" list. It stops the agent from reaching for the dependency you deliberately avoided.
Source of truth — one authoritative place for the facts the agent relies on, whatever it is: a database, a spec, a config file. It turns a vague feature request into concrete decisions instead of guesswork.
Commands and checks — the highest-ROI section. Exact invocations, including the flag the agent would otherwise guess wrong. And "do not claim a check passed without running it" is the evidence rule: the agent must report real output, not assume success.

Then the workflow contract — only when you run a supervised, agent-driven workflow:

Workflow — this is what turns the file from documentation into programming. The numbered steps and the approval gate are the most important piece: the agent plans, you approve, it executes. That isn't documentation; it's a control loop.
Skills + prompt files — a whitelist ("Do not invent new skills") plus a mandatory plan-before-code step with a defined list of required sections. That's what makes the approval gate real: the agent can't show you a one-line plan.
Security + final rule — the fallback checklist for situations your rules didn't cover. It tells the agent how to behave when it doesn't know what to do — which is exactly when improvisation goes wrong.

The Airflow project shows how far this can go in the real world. Its AGENTS.md instructs: "Never run pytest, python, or airflow commands directly on the host — always use breeze." One line, and the agent stops polluting the developer's machine with a wrong-versioned Python environment. That's a guardrail that saves real pain, and it only works because it names the alternative, not just the prohibition.

If you use Claude Code specifically, one practical note: Claude Code reads CLAUDE.md natively, not AGENTS.md. Bridge them with a one-line import:

# CLAUDE.md
@AGENTS.md

The @AGENTS.md import expands at session start, so you keep a single source of truth and add Claude-specific rules below it.

What changed for me

Before I started using AGENTS.md, every project began the same way: initialize the repo, then type out a long prompt covering everything I wanted built, the conventions, the things not to touch. It worked — for that one session. The next day I'd open a new session and all of it was gone. I'd repeat myself, re-correct a mistake it had already made, and watch it make a similar one anyway. It got frustrating fast.

The turning point was writing a well-structured AGENTS.md before anything else. The agent stopped repeating those mistakes — not because I prompted better, but because it could re-read my instructions every session instead of trying to remember them. Work was easier, and there was a side effect I hadn't expected: I was burning fewer tokens. Re-explaining everything session after session is the biggest token waste there is, and when you're paying for a plan, that waste costs real money. A good AGENTS.md is cheap insurance against it.

Real-world proof that this scales

A single file might feel like a small thing. The adoption numbers say otherwise.

AGENTS.md is now an open standard, released by OpenAI in August 2025 and donated — jointly with Anthropic — to the Linux Foundation's Agentic AI Foundation in December 2025. It's used in more than 60,000 open-source repositories and read natively by every major agent: Codex, Cursor, Copilot, Claude Code (via import), Google's Jules, Gemini CLI, Windsurf, and more. One file, all tools. That's the point of a standard.

The most extreme use of it is inside OpenAI's own repository, which ships 88 nested AGENTS.md files — a root file for global conventions, and subdirectory files for each subproject. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence. That's how you scale from "one file for my side project" to "one hierarchy for a monorepo."

At the enterprise end, context configuration is part of the layer that makes the headline agent stories possible. Rakuten runs an autonomous code-repair system across 12.5 million lines of code; TELUS credits full-pipeline AI integration with half a million saved engineering hours. Systems like that have to be reliable — and reliable agents need to understand the codebase they're operating on, which is exactly what a well-written context file is for.

The message for a solo developer is simpler: if a 60,000-repo open standard and Fortune-500 engineering orgs both treat this file as infrastructure, it's worth the thirty minutes it takes to write yours properly.

The mistakes that make your file useless

Most AGENTS.md files fail for one of five reasons. Here's what they look like and how to fix them.

1. The novel. A 500-word essay about your codebase's history. It burns context on every session and buries the rules that matter. Fix: cut ruthlessly. If a sentence wouldn't change the agent's output, it's dead weight.

2. The wish list. "Write clean, well-documented code. Follow best practices." The agent already does this by default, so the file is pure noise. Fix: delete anything the agent would get right without being told.

3. Negative-only rules. "Never use any." "Don't commit to main." Without an alternative, the agent improvises — usually badly. Fix: every prohibition gets an "instead."

4. Contradictions. "Always write comprehensive tests" and "keep sessions fast, minimize token usage" are in tension. The agent oscillates between them. Fix: set explicit priorities and document the trade-offs.

5. Set and forget. This one is the silent killer. A recent study of 356 repositories found stale code references in 23% of AI configuration files — files pointing at renamed paths, deleted modules, and old commands. Stale instructions don't just waste tokens; they actively mislead. Fix: treat the file like code. Review it monthly, put a # last reviewed: YYYY-MM-DD comment at the top, and delete anything that no longer reflects reality.

How to write an AGENTS.md (in 30 minutes)

You can get the full benefit in about half an hour:

Write the file. Start with the template above and adapt it to your project: commands, conventions, guardrails. Cut anything that wouldn't change the agent's output.
Verify your commands. Run each one yourself. An AGENTS.md full of commands that don't work is worse than no file at all.
Run a real session. Give the agent a task that touches your conventions — a refactor, a new endpoint — and watch whether it follows the file.
Test a guardrail on purpose. Ask the agent to do something your file forbids (e.g., "add console.log here"). If it complies, the rule is too vague — rewrite it as a hard constraint or move it to a hook.

Then keep the freshness loop going: commit the file to git, review it monthly, and add a rule any time the agent repeats a mistake. One correction that turns into a rule is a correction you never make again.

The one-line takeaway

Your coding agent isn't limited by the model — it's limited by what it knows about your project. A short, specific, maintained AGENTS.md is the highest-leverage change you can make to your AI workflow. Not because the file is magic, but because it's the agent's only permanent memory.

Write it like documentation, and you've added a paragraph to a manual. Write it like code, and you've given a teammate a brain.

FAQ

Does AGENTS.md replace CLAUDE.md?

No. AGENTS.md is the tool-agnostic standard read by most agents. Claude Code reads CLAUDE.md natively — bridge them with a one-line @AGENTS.md import in CLAUDE.md so you keep a single source of truth.

How long should AGENTS.md be?

Under ~200 lines. Every word is loaded into context on every session, and context bloat degrades model accuracy. If removing a line wouldn't change the agent's output, delete it.

Why does my coding agent keep repeating mistakes?

Because it's stateless — it forgets everything between sessions and starts from training-data guesses about your project. AGENTS.md is re-read at the start of every session, so it acts as the agent's permanent memory.

Where should AGENTS.md live?

At the repository root. For monorepos, add one per subdirectory — agents read the nearest file, so the closest one takes precedence (OpenAI's repo ships 88 of them).

CTA: Copy the template into your repo and run one session. But before you do, think about your answer to this: what mistake does your coding agent repeat every session? That's the first line of your file. Start with just that one rule — the "instead" included — and test it. One correction that becomes a rule is a correction you never make again.

I write about AI engineering stacks, autonomous developer tools, and structural agent design. If you're building in this space, follow @buildloops for weekly breakdowns!