The dotfile bubble.
We built the wrong thing.

There is a folder on your machine — probably several — full of files that didn’t exist eighteen months ago.

.cursorrules. CLAUDE.md. .github/copilot-instructions.md. system_prompt.txt. A prompts/ directory with twelve files, each one a small monument to a session that went wrong. A AGENTS.md that you keep meaning to update. A .clinerules because you tried Cline for two weeks and that agent needed its own briefing document apparently.

You wrote all of these. You maintain all of these. You’ve spent real hours — if you’re honest, embarrassing hours — crafting, refining, and reorganizing these files. You treat them like secret weapons. You share snippets on Twitter. You star other people’s dotfile repos hoping to steal something useful.

Here’s what you built: a band-aid on a structural wound.

01What dotfiles actually are

Strip away the tooling specifics and a dotfile is always the same thing: a developer manually encoding context that the system should already have.

The codebase uses TypeScript strict mode. Your agent doesn’t know this unless you tell it. So you write it down.

Don’t touch the auth module without running the full test suite. Your agent doesn’t know this either. Into the file it goes.

We use the repository pattern for data access. Never write raw queries. Another line. Another instruction. Another thing that exists in your head and nowhere else that the tooling can actually use.

This is the fundamental absurdity of the dotfile era: we built the most sophisticated code generation tools in history, then handed them a text file and said here, read this first. We are briefing our agents like they’re contractors who just walked in the door. Every single session.

02The bubble mechanics

Bubbles form when people mistake a workaround for a solution.

The workaround: write better dotfiles. More complete instructions. More specific constraints. A better persona. The right system prompt. If you could just get the words right, the agent would behave correctly — consistently, across sessions, across providers, across the entire codebase.

The solution: the agent should have a persistent, structured model of the system it’s working in, maintained automatically, available to any tool without manual transcription.

The bubble is the collective belief — expressed in blog posts, YouTube tutorials, GitHub repos with thousands of stars — that we are one well-crafted .cursorrules away from solving the context problem. We are not. We are duct-taping intent onto tools that were never designed to hold it.

The tell is how dotfiles behave at the edges:

They don’t compose. Your .cursorrules and your CLAUDE.md and your system_prompt.txt are three separate files that may contradict each other, maintained independently, with no mechanism for resolving conflicts. The agent receives all of them and figures it out. Sometimes.

They don’t travel. Switch from Cursor to Claude Code. Your configuration doesn’t come with you. You’re either rewriting everything for the new tool’s format or pasting in raw text and hoping the model interprets it correctly. Your intent is trapped in a provider-specific format.

They don’t update. You refactor the auth module. The dotfile still says don’t touch the auth module without running the full test suite — which is now wrong, or incomplete, or referring to a test suite that was reorganized last sprint. Nobody updated the file. Nobody remembers to update the file. The agent is now operating on stale instructions and you won’t find out until something breaks.

They don’t scale. A small project can be described in a few hundred words of plaintext. A real system — with multiple domains, architectural constraints, active features, historical decisions, live dependencies — cannot. At scale, the dotfile becomes a maintenance liability that nobody owns and nobody trusts.

03The cost nobody is counting

Open your .cursorrules. Read it. Now ask: does this file accurately describe your system as it exists today?

If you’ve been building for more than three months, the answer is probably mostly, with some parts that are outdated and a few things I keep meaning to add. Which means your agent is operating on a partially accurate model of your system, and the errors are invisible until they compound into something you have to debug.

This is drift by another name. The dotfile was supposed to prevent drift. It became another surface that drifts.

The hours spent writing these files aren’t the real cost. The real cost is the sessions where the agent made a wrong assumption because the file was incomplete. The PRs you had to reject because the agent didn’t know about a constraint you forgot to document. The subtle architectural erosions that accumulated because the agent had no way to know that this pattern was deprecated, that this module was being replaced, that this decision was made for a reason that isn’t in any file anywhere.

You can’t see this cost in your velocity metrics. It shows up later, as confusion, as rework, as the slow feeling that the codebase is getting harder to understand even as it gets faster to write.

04What comes after the bubble

The dotfile era ends the same way every configuration era ends: with a system that manages configuration as a first-class concern instead of delegating it to a text file in a folder.

We stopped writing httpd.conf by hand when infrastructure-as-code tools made the desired state of a server declarable and versioned. We stopped manually configuring CI pipelines when the pipeline became code that lived with the project. The pattern is always the same: the thing we were maintaining manually gets absorbed into a system that maintains it automatically.

Dotfiles will get absorbed too. Not into better dotfiles — into a model of the system that generates the right configuration for each agent, each session, each task, automatically. A model that knows which tools are appropriate for which parts of the codebase. That knows which constraints apply to which features. That updates when the system changes instead of waiting for a developer to remember.

The agent shouldn’t need a briefing document. It should have a complete model of what the system is supposed to be and where it currently stands relative to that. Every session should start from that model, not from a file you wrote six months ago and haven’t touched since.

05The thing you already know

You know the dotfile isn’t the real answer. You know because you’ve rewritten it three times. You know because you have a nagging sense that there’s a smarter way to do this, that the context problem shouldn’t require this much manual maintenance, that somewhere there’s a more structural solution.

There is. It just requires treating agent configuration the same way we’ve learned to treat everything else: as a system concern, not a file concern. Declared, versioned, automatically maintained, and compiled to whatever format whatever tool needs at the moment it needs it.

That’s not a dotfile. That’s infrastructure.

The bubble will pop when enough developers realize they’ve been maintaining the wrong thing. Some of them already know. The rest will figure it out the next time they switch providers and spend an afternoon rewriting configuration that should have followed them automatically.