An agent-friendly codebase beats a clever prompt

The fastest way to make an agent safe to delegate to is not a smarter prompt, it is a repo that writes down its own rules. An agent-friendly codebase is a repo whose boundaries, scopes, and verification commands live in files instead of in someone's chat history. Cursor, Anysphere's AI code editor, will follow what the repo says far more reliably than what you meant. If you cannot narrate the scope of a change, you cannot hand it off safely.

You have probably felt this in a pairing session. The tech lead can review the code but not the boundary, because the boundary never left the agent's chat. Put the boundary in a file and the review gets easy.

Why a better prompt rarely fixes a wandering agent

Wider tool access feels like the unlock. Give seniors more connectors, more autonomy, and surely they move faster. In practice the connectors multiply faster than anyone's mental map of what they touch, and the incidents write themselves.

The problem is hidden coordination. A short prompt can sit on top of a deep pile of unwritten obligations, so the interface looks simple while the work underneath stays invisible. John Ousterhout's vocabulary for software complexity names this well: a shallow module looks easy and costs a lot.

So the move is to make the repo carry the rules. Structure it so a reviewer can read the scope of a change instead of guessing at it.

Write four artifacts that make a repo legible

A legible repo answers four questions in files: what may run, who owns it, what changed, and how it was verified. Each of the four problems below has a small markdown answer.

The first is MCP blast radius. Wire connectors quickly and one of them ends up touching data nobody put on the diagram. The Model Context Protocol spec defines the plumbing, and the OWASP LLM Top 10 is the threat reading to do before adding more. The fix is a connector card: one markdown card per MCP server listing allowed actions, forbidden actions, owner, and rollback. Incidents shrink because operators know what "off" looks like.

The second is recursive handoff blur. Chained agents return tidy summaries that quietly omit the paths a child agent actually touched. The fix is a child receipt block: every child returns paths touched, commands run, and the tests that prove the regression guards held. Parents stop green-lighting mystery diffs, because the receipt either matches the diff or it does not.

The third is review queue theater. CI is green, yet reviewers keep asking "why this approach?" with no written answer anywhere. The fix is a decision stub: the PR template forces three lines, constraints considered, rejected alternatives, and verification proof. The debate moves from vibes to a tradeoff someone can argue with.

The fourth is Cursor scope fog. The .mdc rule language sounds precise until reviewers argue about what a rule meant. The Cursor agent docs cover the mechanics but not your contract. The fix is a scope ledger: the parent chat carries five lines, goal, allowed paths, forbidden paths, verification command, and merge owner. Review turns into checking the ledger against the diff.

Here is the boundary file we seed repos with. Adapt the globs to your layout.

---
description: Delegation boundary snapshot (adapt globs to your repo)
globs:
  - "**/*"
alwaysApply: false
---

- Cursor: keep scopes explicit in `.mdc`; forbid undeclared MCP domains.
- Claude Code: cite `CLAUDE.md` precedence before expanding bash scope.
- Codex: ensure `AGENTS.md` carries replay-friendly verification notes for CLI runs.

Think of an agent-friendly repo as a labeled breaker panel. Any electrician can cut the right circuit without calling the person who wired the building. That is the whole goal: the handoff survives without the original operator in the room. The same spine runs through agentic coding governance, and the live-repo version of the argument is in best practices for agentic coding in real environments.

Keep four questions at the merge gate

Hard constraints still belong to people. Threat models, customer promises, and blast radius decisions stay off autopilot. Everything else passes through four questions, and the artifacts above are what let you answer them quickly.

If you can answer all four from files in the PR, the change is safe to merge. If you cannot, that gap is the work.

Common questions

• What makes a codebase agent-friendly?

  Written boundaries an agent can read: .mdc scopes for Cursor, CLAUDE.md precedence, AGENTS.md verification notes, plus a connector card per MCP server. An agent-friendly codebase keeps scope, ownership, and verification in files, so delegation does not depend on whoever happened to run the session that day.

• Where should agent boundaries live in the repo?

  In the rule files each tool already reads: .mdc for Cursor, CLAUDE.md for Claude Code, and AGENTS.md for Codex CLI runs. Keep them short, explicit about allowed and forbidden paths, and reviewed like code. Agents follow what is written, not what was meant, so the file is the contract.

• Does this require new tooling?

  No. The four artifacts are plain markdown: a connector card, a child receipt block, a decision stub in the PR template, and a five-line scope ledger. The work is editorial discipline, which is exactly why teams skip it and then pay for the skip later in incidents.

• What stays human-owned in an agent-friendly repo?

  Threat models, customer promises, and blast radius decisions stay off autopilot. Agents speed up execution inside boundaries that people wrote. The repo can make scope legible, but choosing the scope is architecture, and architecture is still a human job, on purpose.

Start with one artifact

Pick the question your team argues about most and write the matching artifact first: a connector card, a child receipt, a decision stub, or a scope ledger. If you want a worked example, our training walks a team through wiring these into a real Cursor repo.