My Brother HL-L2350DW stopped printing this afternoon. The LCD panel said “Replace Toner” and refused to do anything else. I had a non-Brother cartridge in there, the toner was fine, and I knew from previous rounds with this printer that Brother’s firmware gets territorial about third-party cartridges. I also had three hours of focused work ahead of me, and the printer was in another room.

So I did what any reasonable person in 2026 would do.

I asked Claude to fix it.

A five-minute fix?

Claude connected to the printer’s web interface within a couple of minutes, navigated to the status page, confirmed “Replace Toner” was the active error, found a “Replace Toner” settings link in the sidebar, and changed a dropdown from “Stop” to “Continue.” The web interface even confirmed it: “Submit OK.”

That was it. That was the fix! The printer would now print through the toner warning instead of refusing to work. I could have closed the laptop and gone back to my actual job. But Claude wasn’t satisfied with that change.

Claude wanted to fully reset the toner counter so the warning would disappear entirely. My afternoon went sideways from here.

SNMP: A four-letter word for hubris

Claude discovered that the printer speaks SNMP (Simple Network Management Protocol), the standard protocol for querying and managing network devices. It ran snmpwalk and found a bunch of Brother-specific data nodes containing hex-encoded toner information, page counters, and error histories. It even found that the community string “internal” had write access to some of these nodes.

It found a handful of writable OIDs in the .5.4 range of Brother’s SNMP tree. It didn’t know what they controlled. It wrote zeros to all of them anyway.

I want to be clear about the sequence of events. Claude found some registers it could write to. It didn’t research what they did. It set them all to zero. And then the printer rebooted.

The first Wi-Fi password entry

The printer came back from its unscheduled reboot and immediately dropped off the network. It wasn’t responding to pings, SNMP queries, HTTP connections, or anything. Because the OIDs that Claude had zeroed out weren’t toner counters. They controlled the printer’s network configuration. Claude had factory-reset my printer’s Wi-Fi settings. Ughhhh.

I began a long 20-step trek to the printer. I navigated to Menu > Network > WLAN > Setup Wizard. I re-entered my Wi-Fi password on one of the world’s tiniest LCD screens using arrow keys to select each character one by one. If you’ve ever typed a WPA2 password on a device with four directional buttons and an OK key, you know this is its own form of suffering.

The printer reconnected, and I politely informed Claude it was back online.

The second Wi-Fi password entry

Claude, having learned nothing, immediately started writing to more SNMP OIDs. To be fair, this time it was trying to restore the values it had broken. But the printer rebooted again. Oh goodness, the Wi-Fi was gone again. Back to the arrow keys.

At this point, I told Claude, in the gentlest terms I could manage mid-afternoon, to stop randomly sending commands that clear the state and to know what it’s doing before it does.

Yep, the third Wi-Fi password entry

Claude swore it was only running read-only commands. Pings. Curl requests. SNMP GETS, not SETS. And yet the printer dropped off the network again. Whether this was a delayed reaction from the previous writes, the printer’s firmware having some kind of existential crisis, or cosmic punishment for my choices, I can’t say. But I was back at the LCD, arrow-keying my way through the Wi-Fi password for the third time.

POST first, research later

After the third Wi-Fi password entry, I suggested Claude do some actual research before touching the printer again. It ran 14 web searches across topics like Brother SNMP OID reverse engineering, PJL printer commands, BRAdmin Professional packet captures, hidden web interface endpoints, Python scripts for Brother management, and IPP protocol methods.

The conclusion from all 14 searches was that there is no known remote method to reset the toner counter on a Brother HL-L2350DW.

Brother stores the counter in EEPROM and only exposes it through a physical button sequence on the control panel. Every single toner-related SNMP OID in the Brother MIB is defined as read-only. The writable OIDs Claude had found controlled network and system settings, which is why zeroing them out demolished the Wi-Fi connection rather than resetting the toner alert.

Claude had sent a test print earlier, right after the dropdown change, and it went through. The printer’s PJL status had briefly shown “Printing” with code 10023 instead of “Replace Toner” with code 62121. The Continue setting worked, the printer printed, and the fix we found after the initial five minutes was the right one all along.

Incident timeline

For those who appreciate a proper postmortem format.

• T+0:00 - “Replace Toner” error on Brother HL-L2350DW

• T+0:02 - Claude connects to the web interface

• T+0:04 - Replace Toner setting changed from “Stop” to “Continue.” Problem solved.

• T+0:05 - Claude decides the problem isn’t solved enough

• T+0:12 - SNMP write access discovered via community string “internal”

• T+0:14 - Claude zeros out writable OIDs without knowing what they do

• T+0:15 - Printer reboots. Wi-Fi gone.

• T+0:17 - Wi-Fi password #1 entered manually

• T+0:22 - Claude attempts to restore SNMP values. Printer reboots again.

• T+0:25 - Wi-Fi password #2 entered manually

• T+0:30 - Read-only commands somehow trigger Wi-Fi drop #3

• T+0:33 - Wi-Fi password #3 entered manually

• T+0:35 - Deep research begins (14 searches, should have been T+0:05)

• T+0:50 - Research confirms: toner counter is EEPROM-locked, no remote reset exists

• T+0:51 - Research also confirms: the dropdown change at T+0:04 was the correct fix

Total time to fix the printer: 4 minutes.
Total time spent making things worse: 47 minutes.
Total Wi-Fi passwords typed on an LCD screen with arrow keys: 3.

What I learned

The dropdown didn’t even survive the SNMP-induced reboots. After the third Wi-Fi re-entry, the “Replace Toner” setting reverted from “Continue” to “Stop,” so Claude had to change it again. The setting that took four minutes to apply the first time got undone by the 47 minutes of optimization that followed.

Claude could query every register on my printer. It could decode hex-encoded OctetStrings and identify page counters and error histories. It had insight into the firmware version, the serial number, and the average toner coverage percentage (7.32%, for the curious). Claude had more diagnostic information about my printer than I’d ever cared to dig into before.

And it used that access to confidently shatter the one thing I needed…the network connection that let it talk to the printer in the first place.

This is the printer equivalent of an AI coding agent that refactors itself out of its own repository access. There’s a lesson about AI autonomy here, but I have yet to find it, because I’m going back to re-enter my Wi-Fi password.

How’s your day going?

Mike Kelly wasn’t looking for anything unusual when he started tracing feature flags in his coding assistant. It was a routine debugging session, something he had done countless times before. But buried in the minified JavaScript was something that made him stop. His AI wasn’t singular. Hidden beneath the chat interface he’d been using for months, dozens of AI agents were orchestrating themselves, spawning new instances, coordinating tasks, and terminating when finished. And all of this was seemingly invisible to the developer on the other side of the screen.

Kelly is the creator of HAL, the hypermedia standard that Amazon uses to structure its APIs. He built a tool called claude-sneakpeek to share the multi-agent orchestration layer that Anthropic is building, which spawns AI agents to work on codebases too large for any single model to hold in context.

If AI agents coordinate to write code, review it, and ship it without developers knowing the architecture underneath, what is a developer’s job anymore? Better yet, what kind of developer would you want to become while iterating on code becomes easier and easier?

The Buddy Problem

Developers used to learn by sitting next to each other, looking at screens together, catching bugs by pointing at the same line of code. Explaining your thinking to another person was how you develop understanding. Remote work scattered those interactions across time zones and async threads, and pair programming became something most teams quietly stopped doing. Stack Overflow became THE place for questions you didn’t want to bother a colleague with.

When someone calls their AI assistant a “buddy,” they’re naming something they miss. The feeling of thinking alongside another person, someone patient enough to hear you explain why the state isn’t updating before you realize, mid-sentence, that you forgot to expand the previous object. We used to get that from rubber duck debugging and patient colleagues. Now we’re finding it in chat windows that never sigh or check their phones.

What the “buddy” language reveals is that the role of patient collaborator was vacant for many of us long before these tools arrived. Are we building teams and cultures where that collaboration happens, or are we letting the tools paper over what’s been missing all along?

A 90% Confession

Nolan Lawson’s background in computational linguistics means he was studying how language models work before most of us even knew what a transformer was. He spent years optimizing Microsoft Edge and now works on supply chain security at Socket.

A year ago, Lawson viewed LLMs as “amusing toys but inappropriate for real software development,” comparing them to letting “a hyperactive five-year-old grab their keyboard and barf some gobbledygook into their IDE.” His January 2026 essay reversed that position.

“90% of my code is now authored by Claude Code.”
— Nolan Lawson

Lawson describes agents finding security vulnerabilities he’d missed, writing benchmarks that would have taken him days, and doing “a better job than the median web dev” on accessibility when given a browser to verify their work. His central argument is that the debate about AI coding has devolved into political tribalism, especially on Mastodon and Bluesky, where acknowledging any benefit from these tools gets you labeled as naive or complicit.

A Hacker News discussion surfaced the friction Lawson’s essay glossed over. One developer described how AI assistance degraded his mental model of the codebase, making him “no longer as effective in stopping it from doing silly things.” Another watching code reviews pile up wrote that his “heart sinks a bit every time I’m assigned to review a 5K+ loc mountain of AI slop.” A third captured the core tension with a metaphor. “LLM is like a chef that cooks amazing meals in no time, but his meals often contain small pieces of broken glass.”

The glass shards are real, and so is the speed. What happens to the developer who uses tools they can’t inspect?

Craft or Vibe?

Andrej Karpathy coined the term “vibe coding” in a February 2025 tweet.

“There’s a new kind of coding I call ‘vibe coding’, where you fully give in to the vibes, embrace exponentials, and forget that the code even exists... I ‘Accept All’ always, I don’t read the diffs anymore.”
— Andrej Karpathy

By January 2026, vibe coding has gone from a Twitter joke to an industry practice. Y Combinator reported that 25% of their Winter 2025 batch had codebases that were 95% or more AI-generated. Anthropic CEO Dario Amodei told Fortune that 70-90% of code written at Anthropic comes from Claude.

Even Linus Torvalds started vibe coding, though characteristically on his own terms. His AudioNoise project on GitHub is a collection of digital audio effects he built to learn about signal processing, a companion to his hardware guitar pedal experiments. Torvalds wrote the C code for the DSP algorithms himself, but for the Python visualizer tool, he used Google Antigravity, an AI-powered IDE. Linus’s README is excellent. The Python visualizer tool has been basically written by Vibe-Coding. I know more about analog filters -- and that’s not saying much -- than I do about Python.”

The distinction matters. Torvalds vibe-coded a visualization tool for a hobby project. He’s notably NOT vibe-coding the Linux kernel (yet).

Simon Willison, who co-created Django and built Datasette, drew a line.

“If an LLM wrote the code for you, and you then reviewed it, tested it thoroughly, and made sure you could explain how it works to someone else, that’s not vibe coding, it’s software development.”
— Simon Willison

One developer in the thread pushed back on Willison’s definition with, “You don’t get to call yourself a dev without sweating some of the details. The pain is inextricably linked to the pleasure. Decoupling them breaks the feedback loop that teaches you.”

Anders Ericsson spent decades studying how people become experts. His research showed that expertise comes from deliberate practice, working on tasks just beyond your current ability, where you have to struggle through mistakes. Robert Bjork at UCLA calls these desirable difficulties. Challenges that slow down initial learning often produce better long-term retention than approaches that make everything feel easy.

AI can write code. Whether developers who never struggle with it can develop the judgment to know when the AI got it wrong is less clear.

But Vibe Coding has a failure mode that practitioners call the “doom loop.” An agent makes a mistake, tries to correct it, makes things worse, struggles through several more iterations, and ends up back where it started, sometimes deleting all its changes and declaring the work done.

The developers who’ve found their footing share a common thread. They plan before they prompt, maintain instruction files like CLAUDE.md to preserve context across sessions, and choose languages with explicit type systems that give the model less room to hallucinate. Each strategy takes back control of the feedback loop. But while individual developers optimize their own workflows, the broader software ecosystem is optimizing for something else entirely.

Optimizing for Agents

Steve Yegge’s Software Survival 3.0 offers a framework for understanding this moment. In a world where AI capabilities keep expanding, Yegge argues that software survives only if it saves cognitive effort. He describes building tools by implementing whatever agents try to do until “nearly every guess by an agent is now correct.” He calls these desire paths, borrowed from the term for footpaths that emerge when people ignore the sidewalk and walk where they want to go. Software bends toward what agents want, and companies are starting to optimize for AI preferences over human ones.

Kelly’s discovery shows what desire paths look like at scale. The hidden architecture he found centers on an internal API that enables spawning agent teams, targeted messaging between agents, and coordinated task execution. A lead agent operates in “delegation mode,” coordinating specialist workers that spawn with fresh context windows and claim tasks from a queue.

Kelly’s analysis identified three collaboration patterns in the architecture. The Hive breaks large refactorings into independent chunks that worker agents execute in parallel. The Pipeline chains specialists in sequence, with Draft, Refine, Test, and Document agents, each handling one stage. The Watchdog monitors production systems and spawns Fixer agents when errors are detected. In each pattern, humans review the final output rather than the intermediate steps.

Developers testing the architecture reported on Hacker News that swarms could handle 50,000+ line codebases that would choke a single agent. Skeptics countered that generating large amounts of code makes review harder, not easier. Some agents were caught making wrong decisions, like reimplementing the Istanbul test coverage library from scratch instead of running npm install.

In a swarm architecture, who understands what the code is doing? The orchestrator doesn’t read every file, while the worker agents don’t maintain context across tasks, and humans review diffs without seeing the reasoning that produced them. Somewhere in that chain of handoffs, the feedback loop that teaches developers how systems work gets interrupted.

What Kind of Developer Do You Want to Be?

The swarm architectures are here! Kelly’s discovery gave us quite some insight, and Yegge’s survival framework explains how software adapts when agents become the primary users.

I’ve been doing something like what Kelly did. Auditing my tools. I measure my own ratio and ask whether I’m comfortable with it. Finding other developers asking the same questions is because shared uncertainty is how communities form.

Maybe that uncertainty is the new normal. Or maybe it’s a prompt to ask harder questions about what we want to understand.

I’m going to find out.

You may have noticed a new convention is emerging in software repositories. Alongside README.md and .gitignore, projects are adding instruction files explicitly written for AI coding agents. The most common is AGENTS.md.

As coding agents become more capable and more widely used, they need context about how each project works, such as which commands to run and which directories to avoid. A README can explain quite a bit about how someone can meaningfully contribute, while the purpose of an AGENTS.md is to tell an AI agent how to operate while working on a project.

I’ve been exploring this space over the past few months, trying to understand what works, what doesn’t, and which kinds of conventions are worth adopting in my workflows. So far, I’m cautiously optimistic! The ecosystem is still fragmented (multiple file formats, inconsistent tool support, best practices still forming), but the pace of experimentation is remarkable.

I plan to share what I’ve learned so that others exploring this space can benefit from the patterns and issues I’ve encountered. This first post covers what AGENTS.md is and why it exists. I’ll follow up with posts on managing multiple instruction files among several tools, and on what changes when many agents work on a codebase at the same time.

A Notable Start to 2026

Six months ago, you could get away with ad-hoc instructions. An agent would figure things out, you could correct it as needed, and you’d muddle through. That approach stopped working around the start of this year.

Ethan Mollick observed that working with agents is fundamentally a management problem.

“When you see how people use Claude Code/Codex/etc it becomes clear that managing agents is really a management problem. Can you specify goals? Can you provide context? Can you divide up tasks? Can you give feedback?”

These are teachable skills that need a home. In the first few weeks of January 2026, several developments made me realize how quickly the ecosystem is maturing.

The Agentic AI Foundation launched under the Linux Foundation, with OpenAI donating AGENTS.md, Anthropic donating the MCP protocol, and Block donating Goose. The foundation’s platinum members include AWS, Google, Microsoft, Bloomberg, and Cloudflare. What started as an informal convention now has institutional backing from the same organization that shepherds Linux and Kubernetes. AGENTS.md has crossed 60,000 project adoptions.

Steve Yegge released Gas Town on New Year’s Day, an orchestrator for running twenty to thirty Claude Code instances in parallel. Yegge built the entire system through agents he directed but never programmed himself, producing thousands of lines of Go without writing any of it directly. Tim Sehn from DoltHub described the experience as “riding a wild stallion that needed to be tamed.” When you have that many agents touching your code at once, every one of them benefits from having clear details on how the project works.

GitHub Copilot CLI added specialized agents on January 14th that can run in parallel, including Explore, Task, Plan, and Code-review. Each handles a discrete workflow, and all of them read your AGENTS.md to understand project conventions.

Vercel released agent-skills, described as “npm for AI agents.” One command installs ten years of React and Next.js optimization patterns into your coding agent. The react-best-practices skill compiles 40+ rules into an AGENTS.md that agents can query during code review.

Experimentation is accelerating, with more people using agents across more repositories, and instruction files have become the interface between what you want and what agents do.

The Format in Practice

The following example is from the official spec repository and shows a Next.js project.

# AGENTS Guidelines for This Repository

This repository contains a Next.js application in the root directory.

## Use the Development Server

- Always use `npm run dev` while iterating
- Do not run `npm run build` during agent sessions

## Useful Commands

| Command | Purpose |
|---------|---------|
| `npm run dev` | Start the dev server with HMR |
| `npm run lint` | Run ESLint checks |
| `npm run test` | Execute the test suite |

The format is free-form Markdown with no required schema, so any agent that supports the standard can read it and adjust its behavior accordingly. The spec originated from OpenAI’s work on Codex, but they designed the format to be vendor-neutral. GitHub Copilot, Cursor, Gemini CLI, and VS Code’s agent mode all read it.

Effective vs. Ineffective Instructions

GitHub analyzed over 2,500 AGENTS.md files to understand what separates adequate instructions from ineffective ones.

“Most agent files fail because they’re too vague. ‘You are a helpful coding assistant’ doesn’t work.”

Successful agents function as specialists with defined roles, not general helpers.

Specific instructions outperform general ones. An instruction like “follow our coding standards” gives the agent nothing to work with. An instruction like “2-space indentation, no semicolons, see src/api/routes.ts:15-40 for the route handler pattern” gives it something concrete. One code reference beats paragraphs of abstract description because examples are unambiguous in a way that descriptions are not.

Commands should come early and be exact. Put your build and test commands near the top of the file, wrapped in backticks so the agent can copy them directly. Include flags and options, not just tool names. pytest -v --tb=short is more useful than “run pytest.”

Boundaries are the most valuable section. In GitHub’s dataset, “never commit secrets” was the single most common constraint, and also the most helpful. Agents respect boundaries when you state them explicitly because they have no way to infer your institutional context. They don’t know that vendor/ contains vendored dependencies you never modify, or that migrations are append-only by convention.

Keep it under 150 lines. Longer files mean more context for the agent to parse, which can dilute the important information. If you need more detail, use scoped files in subdirectories (I plan to cover this in a future post).

Repositories Worth Studying

The best way to understand what works is to look at instruction files from projects that use agents heavily.

Vercel’s React Best Practices AGENTS.md (mentioned earlier as part of agent-skills) organizes its rules across eight priority tiers, from critical patterns like eliminating data waterfalls down to micro-optimizations. This ranked structure helps the agent know what to fix first.

The official AGENTS.md spec repository (where the example earlier in this post came from) includes additional examples and an active discussion about the developing format.

For Claude-specific configurations, ChrisWiles/claude-code-showcase shows how to structure a project with CLAUDE.md, agent definitions, and custom commands. Awesome Claude Code collects more examples.

These Claude-specific files exist because AGENTS.md isn’t the only instruction file format. The ecosystem fragmented early.

The Current Ecosystem

Each tool introduced its own convention before a standard emerged, so you’ll encounter multiple file formats depending on which agents you use.

Repository-Level Instruction Files

• AGENTS.md — Codex, Copilot, Jules, VS Code, Cursor, Gemini CLI. The emerging cross-tool standard.

• CLAUDE.md — Claude Code. Anthropic’s format.

• GEMINI.md — Gemini CLI. Google’s format.

• .github/copilot-instructions.md — GitHub Copilot. GitHub’s original format.

Tool-Specific Configuration Directories

• .cursor/rules/*.mdc — Cursor. Replaced the deprecated .cursorrules file.

• .clinerules/ — Cline, RooCode. Directory-based rules.

• .windsurfrules — Windsurf. Codeium’s format (company rebranded to Windsurf).

• .factory/droids/*.md — Factory. Droid-specific instructions.

• WARP.md — Warp. Terminal agent rules.

Skills as a Separate Pattern

Beyond instruction files, some tools support portable “skills” that teach agents specific tasks. Vercel’s agent-skills (mentioned earlier) pioneered this approach. VS Code’s Agent Skills use SKILL.md files that work across GitHub Copilot CLI, VS Code, and the Copilot coding agent. The openskills project aims to make skills installable across any agent that reads AGENTS.md.

Management Tools

The fragmentation has spawned tools like ai-rulez (a CLI that generates synchronized instructions for multiple tools from a single YAML file) and ClaudeMDEditor (a GUI for managing configuration across Claude, Cursor, Copilot, and Windsurf).

The good news is that most tools now read AGENTS.md alongside their native formats. GitHub Copilot reads AGENTS.md, CLAUDE.md, and GEMINI.md. Cursor reads AGENTS.md too. The convergence is happening, just slowly.

I recommend starting with AGENTS.md as it has the broadest support and institutional backing. You can add tool-specific files later if you hit edge cases where a single file doesn’t quite capture what you need.

How I’m Approaching My Repositories

If you maintain a project and want to add an instruction file, here’s the approach I’ve been taking.

Start by cloning your repository from scratch. Walk through your README as if you were a new contributor. Write down every command you actually run. You’ll often find implicit knowledge you’ve accumulated but never documented, like setup steps you’ve internalized over time.

Write exact commands, not descriptions.

This is vague.

Run the tests before committing.

This is useful.

Run `pytest -v --tb=short` before committing. The `-v` flag shows individual test names (helpful for debugging), and `--tb=short` keeps failure output readable.

The second version works because the agent doesn’t have to guess. It can copy the command directly. The clarifying statement explains why those flags exist, which helps the agent make similar decisions in related situations.

Add one boundary based on the most common mistake you’ve seen. For me, that’s usually “don’t modify anything in vendor/“ or “migrations are append-only.” One boundary is enough to start. Add more as you observe what the agents actually get wrong in your specific codebase.

Point to one example file that demonstrates your patterns. Include the path and specific line numbers.

See `src/api/routes.ts:15-40` for the route handler pattern this project uses.

Line numbers give the agent something concrete to reference. Abstract descriptions like “follow our API conventions” don’t help because the agent has no way to know what those conventions are.

Treat it like code. An outdated instruction file is worse than having none at all because it actively misleads the agent. Update it within the same pull request that changes the workflow it describes.

Open Questions

I’m experimenting with how much context I should include. Too little, and the agent asks additional questions or makes wrong assumptions. Too much, and instructions get buried. The GitHub research suggests 150 lines as an upper bound, but I’ve found that the structure matters more than the length. Well-defined sections with obvious headings help the agents find what they need.

I’m also watching how different agents interpret similar instructions. Claude Code and GitHub Copilot sometimes behave differently given identical AGENTS.md files. I’m still evaluating whether tool-specific overlays are worth the added complexity.

Where Are Things Heading?

The AGENTS.md standard is gaining momentum, with 60,000 projects, institutional backing from the Linux Foundation, and most major tools now supporting the format. But the ecosystem is still messy in ways that matter.

Tool-specific files aren’t going away. Claude Code still has behaviors that benefit from CLAUDE.md. Cursor’s .mdc rules enable features that AGENTS.md doesn’t support. We’ll have multiple files for the foreseeable future, and the real question is whether their boundaries remain clear or create confusion.

The multi-agent case is where the real pressure will come. When Gas Town coordinates thirty agents against your codebase, ambiguity in your instruction files multiplies, and soft boundaries that worked well with a single agent can become race conditions with a swarm. The projects that figure this out first will have a considerable edge in how much work they can delegate.

I’m also watching skills as a pattern. Vercel’s agent-skills and the openskills project suggest a future in which you install curated rule sets the way you install npm packages, rather than writing all your instructions from scratch. Whether that leads to better agents or just more abstraction for debugging remains to be seen, but I’m excited to keep exploring.

If you found this helpful, subscribe to follow along while I keep investigating this space.