DEV Community: Mitesh Sharma

What's Actually in My AGENTS.md

Mitesh Sharma — Mon, 22 Jun 2026 12:18:07 +0000

The instruction file that runs my codebase started as a junk drawer. The rules that ended up mattering weren't the ones I expected.

A note on credit before I start: most of what follows isn't original to me. I picked up these ideas from other engineers sharing what worked for them — scattered across Twitter/X threads, blog posts, and conversations — then tested them against my own codebase to see what actually held up. This is a synthesis, not an invention. Where something came from the community rather than from me, I've tried to say so. Consider it a thank-you to everyone quietly posting what they've learned.

The first time I wrote an AGENTS.md, I treated it like a README's annoying cousin. Tech stack, a few style notes, a line begging the agent to run the tests. Then I watched the agent ignore half of it and confidently do the wrong thing with the other half.

So I kept editing. Months later, the file looks nothing like where it started. And the surprising part is which rules earned their place. It wasn't the formatting conventions or the careful style guidance. It was a small number of rules that fight an agent's worst instincts, plus one hard lesson about the difference between asking and enforcing.

Here's what I found actually mattered.

The first rule isn't about code. It's about permission to stop.

The very first thing in my file has nothing to do with syntax. It tells the agent that when something is unclear, it should stop and ask. State your assumptions. If two interpretations exist, name both instead of silently picking one. If a simpler approach exists, say so.

I put this first because the default failure mode of a coding agent isn't bad code. It's confident code built on a wrong reading of an ambiguous request. Left alone, a model resolves ambiguity quietly and keeps going, and you don't find out until you're reviewing two hundred lines that solve the wrong problem.

What surprised me was that the agent needed permission to stop. Without it, the model optimizes for looking helpful, and looking helpful means producing something rather than admitting confusion. Telling it that stopping to ask is the desired outcome — not a failure — changed its behavior more than any other single line.

The lesson generalized: an agent will fill silence with confidence unless you tell it that "I'm not sure" is an acceptable answer.

Most of the useful rules just name a bad habit and forbid it

Once I started paying attention, I noticed that my most valuable rules all had the same shape. Each one named a specific, predictable bad instinct and told the agent not to do it. None of them were clever. They were just earned.

Agents over-build. Ask for a function and you can get a configurable framework with options nobody requested. So one rule is blunt about it: minimum code that solves the problem, nothing speculative, and if you wrote two hundred lines where fifty would do, rewrite it. Naming the tax is what keeps it from being paid.

Agents over-reach. An agent that helpfully reformats the whole file alongside its actual change turns a ten-line diff into a two-hundred-line one you can't safely review. So another rule constrains the blast radius: touch only what you must, match the existing style even if you'd do it differently, and make every changed line trace back to the request. This one is really about protecting review, not code. A diff you can't read is a diff you can't trust.

The rule I'd most recommend stealing is one I didn't appreciate until it bit me. When an agent finds two competing patterns in a codebase, its instinct is to find a middle path that honors both. The result belongs to neither pattern and confuses everyone who reads it later. So the rule is: don't average conflicting patterns. Pick one, explain why, flag the other for cleanup. Average code that satisfies two contradictory rules is the worst code in the repo.

There's a companion to all of these that I keep coming back to: if the agent can't explain why existing code is shaped the way it is, it should ask before adding next to it. "Looks unrelated to me" is the most expensive assumption in any mature codebase. Most subtle breakages come from changes that looked perfectly isolated to the person making them.

The lesson that reshaped the whole file

If I could keep only one thing I learned, it's this, and it took the longest to accept.

I once had a hard requirement written in plain, unmissable language at the top of the file. The agent still skipped it sometimes. Not often — just often enough to cause real problems. When I dug into why, the answer was deflating in its simplicity: models drift from instructions. A rule in a markdown file is a strong suggestion, not a contract. Over enough runs, any instruction gets ignored eventually.

That one realization split my entire file into two tiers.

There's guidance — the style preferences, the philosophy, the "prefer this over that." Guidance lives in prose and gets followed most of the time, and most of the time is fine for that category.

Then there's the stuff that has to hold every single time. And what I learned is that this stuff does not belong in prose at all. If something absolutely must happen, don't rely on instructions. Enforce it. Put it in a hook, a script, a CI check — something deterministic that makes the violation impossible to merge, not merely discouraged.

My file still says "run the checks before you call it done." But the real guarantee isn't that sentence. It's that CI fails on lint errors no matter what the agent intended. The instruction is a courtesy. The gate is the guarantee.

The practical test I use now: every time I write "always" or "never" in an instruction file, I ask whether there's a mechanism enforcing it. If there isn't, I don't have a rule. I have a hope.

Make the agent prove it, not promise it

Two more rules in the file are really about the gap between "I did it" and "it works."

The first changes how a task is framed. Instead of "add validation," the instruction is to define what success looks like and loop until it's met: write tests for the invalid inputs, then make them pass. "Fix the bug" becomes "write a test that reproduces it, then make it pass." A vague directive becomes one with a finish line the agent can check itself against, instead of declaring victory on vibes.

The second is blunt about trust: don't claim tests pass from memory — re-run them. I added this after watching the agent report a clean run that wasn't, and after watching sub-agent reviews invent bugs that didn't exist in the source. Both are the same failure: a claim untethered from a fresh check. So the rule ties every claim back to a command actually run, and tells the agent to verify a reported bug against the real code before acting on it.

The principle underneath both: trust the check, not the claim. An agent's confidence is not evidence.

Keep the laws out of the manual

One structural decision kept the whole file maintainable: my AGENTS.md doesn't try to contain the architecture.

The structural laws — dependency direction, frozen contracts, the boundaries that can't be crossed — live in a separate constitution document. The working file just points at it: read this before you add a package, cross a layer, or touch anything safety-critical. And it's explicit that if a change conflicts with the constitution, the move is to refactor or open an amendment, never to slip in a violation to ship faster, because that cost compounds.

The reason to separate them is pace. The working manual is full of conventions and gotchas that change constantly and should be edited freely. The constitution holds laws that should be slow to change and mechanically enforced. Cram both into one file and the stable laws get buried under operational churn. Keep them apart, and each can move at its own speed.

The takeaway: things that change weekly and things that should never change don't belong in the same document.

Write down the scars

The back half of my file is the part I'd most encourage every team to keep: a running log of non-obvious lessons. Not conventions — scars. The specific things that cost someone half a day and would cost the next person the same half-day if they weren't written down.

They're deliberately concrete. The database pseudo-column that isn't selected by default, and the exact error you get when you forget it. The streaming API that keys its events by index instead of ID and arrives in a surprising order. The native dependency that silently fails to compile unless it's on an allowlist. None of these are principles. They're landmines, mapped.

This section matters more with agents than it ever did with people, because an agent has no scar tissue. A human who lost a day to something tends to remember it. An agent will rediscover the same landmine the hard way every single time, unless the knowledge is written where it'll read it. That's the quiet value here: it's how a codebase's painful, accumulated knowledge gets inherited instead of relearned.

Every unexpected hour you lose is only worth paying once. Writing it down is how you make sure of that.

What the file is really for

After all the editing, here's how I think about it now. This file isn't a style guide. The formatter handles tabs and semicolons. What the file actually does is encode judgment — the judgment that used to live only in the heads of the few people who'd been around long enough to have it.

The rules that matter are the ones that counteract an agent's predictable instincts: over-building, over-reaching, guessing silently, blending conflicting patterns, claiming success it never verified. And the most important distinction in the whole file is the line between guidance you state and guarantees you enforce.

So if you're writing one of these, that's where I'd spend the effort. Give the agent permission to stop and ask. Name the bad habits you keep seeing and forbid them by name. Move anything that must always hold out of prose and into a check that fails the build. Point at your architecture instead of restating it. And keep a growing log of your scars, because the agent will step on every landmine you don't map.

The formatting rules write themselves. The judgment is the part worth writing down.

Give Your Codebase a Constitution

Mitesh Sharma — Sat, 20 Jun 2026 09:14:24 +0000

Architecture that lives only in people's heads doesn't survive agents.

For most of my career, the real rules of a codebase weren't written down.

People knew them.

Senior engineers knew which layers could talk to which. They knew which dependencies were forbidden, which schemas were effectively frozen, and which shortcuts would create problems six months later. New engineers learned those rules the traditional way: break one, get caught in review, get the explanation, and eventually remember not to do it again.

It wasn't perfect, but it mostly worked.

What I didn't fully appreciate until I started working heavily with coding agents is how dependent that model is on tribal knowledge. Humans accumulate context over time. Agents don't.

They don't remember the migration that went sideways three years ago. They weren't around when the team spent weeks untangling a dependency cycle. They don't know why a particular boundary exists.

They only know what they can see.

Which means if a rule isn't written down, from the agent's perspective, the rule doesn't exist.

I've seen agents wire inner layers directly to outer layers. I've seen them introduce dependencies we intentionally avoided and extend contracts everyone on the team considered settled. The code often worked, which was the dangerous part.

The problem wasn't correctness.

The problem was architectural drift.

That's when something clicked for me.

Architecture can't remain folklore once agents start writing code.

It has to become law.

Not a convention. Not a suggestion. Not something a reviewer remembers at 6 PM on a Friday.

A law.

Written down, explicit, and enforceable.

That's what I mean by a constitution.

A Constitution Is Not Documentation

The first mistake I made was treating the constitution like another documentation file.

It isn't.

Documentation explains how the system works today. A constitution defines what the system is allowed to become. Those sound similar, but they serve very different purposes.

Package names change. Directories move. Frameworks get replaced. Implementations come and go.

None of that belongs in a constitution.

The constitution should contain only things that should survive a major refactor: the laws, the invariants, and the boundaries that define the shape of the system.

A useful test is simple. If a statement could become false next quarter and nobody would care, it probably doesn't belong in the constitution.

That's documentation.

Not law.

The best constitutions I've seen share three properties. They're short, restrictive, and slow to change.

Short because nobody reads a 50-page constitution.

Restrictive because a law that forbids nothing protects nothing.

Slow to change because laws only create trust when people can rely on them.

What Ended Up In Mine

I didn't design the structure upfront.

Most of it came from repeatedly explaining the same architectural rules in reviews. After the tenth explanation, I stopped explaining and started writing.

The first section contains a handful of principles. Very few. Five or six at most.

Things like:

Dependency direction is one-way
Contracts are defined before implementations
Inner layers must not know about outer layers

These aren't implementation details.

They're foundational assumptions.

If one of them changes, you're not editing architecture. You're redefining it.

The second section defines the layers and their allowed dependencies. One rule turned out to be surprisingly important:

Layer membership is determined by role, not directory.

Directories change all the time. Roles don't.

A module that opens a network listener is still an entry point even if someone moves it tomorrow. A domain model is still a domain model regardless of which folder it lives in.

Tying architecture to directories makes it fragile.

Tying architecture to responsibilities makes it durable.

Every law also gets a reason.

This turned out to be more important than I expected. A rule without a rationale eventually gets deleted by someone who doesn't understand why it exists. The rule teaches behavior. The rationale teaches judgment.

You need both.

The Part That Actually Makes It Work

Everything above helps.

None of it is enough.

The biggest lesson I've learned working with agents is one I keep relearning in different forms:

Instructions are guidance. Enforcement is reality.

You can write "inner layers must never depend on outer layers" in the clearest prose imaginable.

An agent will still violate it occasionally.

Humans will too.

Not because they're careless. Because instructions drift.

That's when I realized every rule falls into one of two categories:

Guidance
Enforcement

Guidance belongs in documents.

Enforcement belongs in code.

If something absolutely must happen, don't rely on instructions. Enforce it.

Put it in CI. Put it in a validator. Put it in a lint rule. Put it in a pre-merge check. Use whatever mechanism makes the violation impossible to merge.

A law that can't be enforced is just a comment with good intentions.

That's why every important rule in my constitution has two forms:

The human version
The machine-enforced version

The human version explains the intent.

The machine version guarantees compliance.

One creates understanding.

The other creates trust.

Both matter.

Why This Matters More Than Ever

It's easy to look at all this and see process.

I see leverage.

The goal isn't to slow agents down. The goal is to trust them more.

Once architecture becomes enforceable, I don't need to manually inspect every decision. The validator does that for me. An agent can touch ten files across multiple layers and I don't have to wonder whether dependency boundaries stayed intact.

The system already checked.

That's the unlock.

The constitution isn't what limits autonomy.

It's what makes autonomy possible.

Because once the important boundaries are guaranteed, you can safely delegate everything else.

The same thing happens with onboarding.

New engineers no longer need months of tribal knowledge. Agents no longer need endless prompt engineering. Everyone starts from the same set of laws, and the machine enforces them equally.

Knowledge stops being gatekept by tenure.

How To Start

Don't start by writing fifty laws.

Start by paying attention.

Every time you hear yourself say:

"We don't do that because..."

You've probably found a candidate law.

Every time an agent makes a change that makes you uncomfortable, ask yourself why. More often than not, you've discovered a boundary that exists in your head but nowhere else.

Start with the handful of rules whose violation would genuinely hurt:

Dependency direction
Secret handling
Critical contracts
Boundary ownership

Write the rule.

Write the reason.

Then add the check that makes it impossible to ignore.

Because that's the part people usually skip.

A law without enforcement is a suggestion.

A constitution without enforcement is documentation.

And architecture that exists only in people's heads doesn't survive agents.

Give your codebase a constitution.

Then give it teeth.

Working With AI: What Actually Works For Me

Mitesh Sharma — Tue, 16 Jun 2026 15:36:21 +0000

I think a lot of people still imagine AI coding as opening ChatGPT, asking for code, and copy-pasting the result. That's not really how I work anymore.

The biggest shift for me is that planning matters far more than coding.

Earlier, execution was expensive, so most of the effort went into writing code. Now execution is cheap. I can have an agent implement something in minutes. The hard part is making sure the plan is correct.

Most of my effort goes into thinking through the architecture, edge cases, failure modes, test strategy, and how the change fits into the broader system. If the plan is vague, the agent will confidently implement the wrong thing. The quality of the result is mostly determined by the quality of the plan.

Once I have a plan, I break it into small independent pieces. Each piece should be executable without additional clarification. If an agent needs to stop and ask questions, the task probably isn't broken down enough.

Those pieces become tickets.

Then an agent picks up a ticket and implements it.

The important thing is that the agent isn't operating in a vacuum. I try to give it a good environment to work in:

Clear architectural rules
Reusable skills and workflows
Guardrails
Hooks for things that must always happen

One lesson that really stuck with me is that instructions are guidance, not guarantees.

At one point I had "always use a git worktree" written in AGENTS.md. The model still ignored it occasionally. When I dug into it, the answer was simple: models can drift from instructions.

So if something absolutely must happen, don't rely on instructions. Enforce it. Put it in a hook, script, validation step, CI check, or some other deterministic mechanism.

If it is important, make it impossible to skip.

Once the implementation is done, the agent opens a PR.

This is where another useful pattern comes in: don't let the same model review the code it wrote.

I usually have one model implement and another model review.

Different models catch different things. They have different strengths, weaknesses, and blind spots. The disagreements between them are often where the real issues are hiding.

A surprising amount of feedback can be handled at this stage before a human ever looks at the PR.

After that, human review depends on what changed.

If the change touches critical infrastructure, security, core architecture, data correctness, or anything with a large blast radius, I want human eyes on it.

For lower-risk changes, I care about two things:

Does it work?
Does it follow the architectural rules?

If both are true, I don't think every change needs a mandatory human line-by-line review.

The other thing that has become important is having a written constitution for the codebase.

For me this is usually an architecture document that defines the rules of the system.

For example, if the architecture says inner layers cannot depend on outer layers, then that rule should be written down explicitly. Not tribal knowledge. Not something that only senior engineers know.

When the rules are documented, every agent can follow them consistently.

The workflow ends up looking something like:

Plan → Break into small tasks → Create tickets → Agent implements → Different model reviews → Human reviews critical changes → Merge

What's interesting is how little of my time is spent writing implementation code.

Most of my time goes into:

Planning
Architecture
Reviewing critical decisions
Improving the harness

And that's probably the biggest change.

The real leverage isn't getting AI to write code.

The real leverage is continuously improving the system around the AI:

Better plans
Better skills
Better guardrails
Better hooks
Better architectural rules
Better review workflows

The better the harness becomes, the better every future task becomes.

That's where most of the compounding value comes from.

AI Coding at Scale: What Actually Works

Mitesh Sharma — Sun, 14 Jun 2026 08:27:35 +0000

AI Coding at Scale: What Actually Works

I've been building Ethos, a personality-first AI agent, and like many engineers today, I rely heavily on AI coding tools. Claude Code, Codex, and others have become part of my daily workflow.

What I've learned is that simply adding AI to software development doesn't automatically make development faster or better.

Without structure, AI tends to:

Generate more code than necessary
Skip established conventions
Take implementation shortcuts
Create large changes that are difficult to review
Optimize for completion rather than maintainability

After experimenting with different workflows, a few of us sat down and discussed what actually works when AI becomes part of a real engineering process.

The conclusion was surprisingly simple:

Spend most of the effort on planning
Build automated feedback loops into execution
Enforce deterministic checks
Keep tasks and PRs small
Standardize engineering practices

None of these principles are new. The interesting part is how much more important they become when AI is writing a significant portion of the code.

1. Planning is the Highest-Leverage Activity

The biggest shift for me has been treating planning as the primary activity rather than a precursor to coding.

Most implementation mistakes are not coding mistakes. They are understanding mistakes.

If the feature requirements are unclear, architecture decisions are incomplete, edge cases are unexplored, or test strategies are undefined, AI simply executes the ambiguity faster.

I now spend the majority of effort upfront:

Understanding the problem
Identifying architecture implications
Finding gaps in requirements
Thinking through failure scenarios
Defining validation and testing strategies

A problem discovered during planning is a discussion.

The same problem discovered after implementation is usually a rewrite.

Model selection matters here as well. Planning is where reasoning quality has the highest impact, so I use the strongest model available for planning. Execution can often be delegated to a cheaper and faster model once the direction is clear.

2. Execution Should Include Feedback Loops

AI-generated code should not go directly from implementation to merge.

Execution needs review loops.

One approach that has worked well is using different models for implementation and review. If one model writes the code, another reviews it.

Different models tend to have different strengths and blind spots. Having a second model review the output often surfaces issues that would otherwise make it into a PR.

The goal is not to remove human review.

The goal is to ensure humans spend their time reviewing decisions and outcomes rather than catching avoidable mistakes.

3. Deterministic Checks Matter More Than AI Reviews

AI reviews are helpful.

Deterministic checks are mandatory.

Linting, formatting, tests, type checks, and validation should run automatically and consistently.

The key insight is simple:

If something must happen every single time, do not rely on AI to remember it.

Automate it.

Start with one check if necessary. A single enforced linting rule provides more value than an elaborate workflow that nobody adopts.

Once that foundation exists, expand gradually.

4. Small Tasks Produce Better Results

Large tasks create large outputs.

Large outputs create difficult reviews.

Whether the reviewer is a human or an AI model, review quality drops as scope increases.

Breaking work into milestones, small tickets, and focused PRs improves:

Implementation quality
Review quality
Iteration speed
Rollback safety

A smaller change is easier to reason about, easier to validate, and easier to ship.

5. Standardize Principles, Not Tools

One mistake teams often make is trying to standardize every tool and workflow.

What matters more is standardizing the engineering principles.

Different engineers can use different tools as long as they follow the same expectations:

Plan before implementing
Build feedback loops into execution
Use deterministic validation
Keep changes small
Follow shared engineering practices

Consistency of thinking matters more than consistency of tooling.

My Current Workflow

Today, my workflow is fairly straightforward.

I work inside a development sandbox and use both Claude Code and Codex depending on the task.

Before opening a PR:

Local hooks run validation
Tests execute locally
Linting and formatting are enforced
The same checks that run in CI run locally first

After implementation:

One model reviews the generated code
A second model reviews the review

The result is significantly less back-and-forth during code review and higher confidence before a human reviewer ever looks at the change.

I also use Git worktrees extensively to isolate parallel streams of work.

That led to one of the more important lessons I've learned about AI-assisted development.

Natural Language for Guidance. Hooks for Guarantees.

Initially, I documented a simple rule in AGENTS.md:

Always use worktrees.

For a while, it worked.

Then it didn't.

When I asked Claude why it occasionally ignored the instruction, the answer was surprisingly accurate: instructions are guidance, not enforcement.

A model can follow them.

A model can also drift from them.

This is the distinction that matters when building reliable AI workflows.

Use natural-language instructions for preferences.

Use deterministic systems for requirements.

If something is mandatory, enforce it with hooks, automation, validation, or policy.

Do not rely on a probabilistic system to provide deterministic guarantees.

Once I moved worktree enforcement into hooks, the issue disappeared.

Closing Thoughts

The most useful mental model I've found is to treat AI like another engineer on the team.

A very fast engineer.

A very capable engineer.

But still an engineer operating within a system.

Good engineering organizations do not rely on individual engineers to remember every rule, every process, and every validation step.

They create systems that make the right thing easy and the wrong thing difficult.

The same principle applies to AI.

Use strong models for planning.

Use automated feedback loops during execution.

Enforce deterministic validation.

Keep changes small.

And whenever something absolutely must happen every time, automate it.

PS: I'm building Ethos in public — an AI agent with a soul: locked core values, evolving expression, governed self-improvement. If this kind of thing interests you, come say hi: @EthosAgentAI.