For much of my career, I have stared at a code diff and wondered how the work got so far from the request. A small change becomes a framework. A bug fix becomes a refactor across unrelated files. Someone says the task is done because they finished typing, not because they proved the result.

Coding agents make that old problem move faster. They can also make it easier to see.

I saw this recently in the workspace we use to develop and review articles. I had asked my AI to review drafts for weak reasoning, unsupported claims, and places where the argument needed more evidence. The review agent could identify abstract or underdeveloped passages, but it often treated the diagnosis as the finished work. It might recommend "add an example" without checking whether the example needed to establish a particular link in the argument or whether it came from my actual experience.

After our copywriter reviewed five articles, I clarified the principle: criticism should be actionable and tied to the evidence the passage needs. When a firsthand example would help, the review should name what that example must contain—the decision, signal, missing context, consequence, or repair—not just ask for an anecdote.

On the next review, my AI's prompts changed. Instead of asking generally for more detail, it asked for specific evidence: a low-stakes stability test, a work decision affected by missing context, and a personal incident traced from signal through consequence and recovery. The review agent was not simply producing more comments. It was giving us a clearer way to verify that a revision would actually do the work the article required.

Expectations need a home

Teams have always carried operating principles. Some are written down. Others are learned during code review, incident response, or an uncomfortable conversation after a bad release. They help people make compatible decisions without asking for permission at every turn.

Agents need the same clarity. A file such as CLAUDE.md or AGENTS.md—instruction files the agent reads before it starts work—is not a magic prompt. It is one place to make working expectations visible: ask when a decision is ambiguous, keep a change scoped, verify before declaring success, and explain meaningful risk before taking an irreversible action.

Those filenames are examples of homes, not the only homes. The shared expectation is the point.

Adapt, do not copy

Other builders have helped popularize small, explicit instruction artifacts for coding agents.12 Their value is not that every team should copy the same rules. A rule only helps when the team understands the problem it is meant to prevent.

Before adopting a principle, ask:

  • What failure are we trying to avoid?
  • What local constraint does this rule need to respect?
  • What evidence would tell us that it helped?

Those questions keep a team from replacing one kind of cargo cult—copying the form without the reason—with another. They also give an agent a useful job: compare a proposed rule with the project's existing constraints and flag a conflict before the change becomes habit.

Connect a working principle to the failure it should prevent, the local constraints it must respect, and evidence from subsequent behavior. Use that evidence to revisit the rule. Conceptual diagram created with Codex for Renaissance Solutions. CC0-1.0.

Treat principles as hypotheses

Written principles should evolve. A useful one makes a recurring expectation easier to follow and easier to review. A weak one adds ceremony, duplicates another rule, or creates a new ambiguity.

That is why the next question matters: do these principles reduce friction, or do they merely make the process feel more orderly?

We have begun examining our own collaboration records for recurring patterns: assumptions that should have been surfaced, scope that spread beyond the request, verification that never happened, and instructions that were too vague to guide the next task. The work is early. The goal is not to produce a score that replaces judgment. What stays human is that judgment—choosing which expectation to clarify next, and whether a rule is doing real work.

Shared principles create better collaborators when they remain connected to actual behavior. The evidence is in the next diff, the next review, and the next time a team avoids having the same preventable conversation.

Footnotes

  1. Andrej Karpathy on diagnosis and observations for agent workflows (not the author of Chang’s CLAUDE.md): https://x.com/karpathy/status/2015883857489522876 ↩

  2. Forrest Chang — instruction-file packaging (including a Karpathy-skills CLAUDE.md collection): https://github.com/forrestchang/andrej-karpathy-skills ↩