agents.cli | Blog

Write it down once. Every AI coding tool reads the same kind of file.

Wed, 20 May 2026 00:00:00 GMT

You’ve told Copilot “we use pnpm, not npm” a hundred times. Once per session. Maybe more if the session is long enough that it forgets.

The fix is older than agents themselves: write it down. In one file. Check it in. Let the tool read it.

Every major AI coding tool added this primitive in the same year — and they’re all essentially the same file under different names:

GitHub Copilot — .github/copilot-instructions.md
Cursor — .cursorrules (single file) or .cursor/rules/*.mdc (multiple, scoped)
Claude Code — CLAUDE.md (project root, with imports for @AGENTS.md)
Codex — AGENTS.md (the open spec, agents.md)
opencode — AGENTS.md (same open spec)

Same idea. Different filenames. Convergence on a pattern that should embarrass anyone who said this would never standardise.

What goes in it? Whatever the agent gets wrong twice. Real examples from real teams:

“Tests live in __tests__/, not next to source.”
“All DB calls go through db/repo/. Never direct queries from route handlers.”
“Use pnpm validate before declaring done. Never push to main.”
“The auth flow is in docs/auth.md — read it before touching anything under services/auth.”

The test: if you’ve corrected the agent on the same thing twice across two sessions, that’s a candidate for the file. The cost of writing one line of context now is much smaller than the cost of correcting the agent for the next year.

The portability move: Codex and opencode read AGENTS.md natively. Claude Code reads CLAUDE.md but can @import AGENTS.md. Cursor and Copilot read their own files. The clean pattern, if you’re using multiple tools, is one canonical AGENTS.md at your repo root, then minimal tool-specific files that import or reference it. One source of truth; every agent in your stack walks in already knowing.

For the full mechanics — layering, path-scoping, nested files, the differences between how each tool merges multiple sources — see Rules.

Your AI agent can't read your Jira. MCP is how you fix that.

Wed, 20 May 2026 00:00:00 GMT

The agent writes the function flawlessly. The function calls a column that doesn’t exist.

You sigh, open psql, run \d users, copy the actual schema back into the chat. The agent apologises. The function is now correct. You did the integration by hand, again, like you’ve done a hundred times this year. Open a tab, copy something, paste it back. Switch to Jira, find the ticket, paste the title in. Open Figma, screenshot the frame, drag it in.

The agent is brilliant at the code. The agent is blind to every system your code talks to.

MCP — the Model Context Protocol — is the fix. It’s a wire format for letting agents call typed tools that talk to external systems. Instead of you copy-pasting the Postgres schema, the agent runs postgres.describe_table("users") itself, sees the result, and writes a function against the actual columns. Instead of you reading the Jira ticket, it runs jira.get_ticket("AUTH-412") and reads the title, description, and acceptance criteria directly.

This isn’t theoretical anymore. Every major AI coding tool added MCP support this year — Claude Code, Codex, opencode, Copilot, Cursor. Whatever you use, the protocol is the same. The MCP server you install for Jira works across all of them.

What people actually run:

Issue trackers — Jira, Linear, GitHub Issues. The agent reads the ticket it’s working on, posts updates, closes it on merge.
Databases — Postgres, MySQL, SQLite. “Check the actual schema before you write this query.” No more guessing column names.
Cloud consoles — AWS, Cloudflare, Vercel. List buckets, check deployment status, read logs without leaving the editor.
Design tools — Figma. The agent reads the component spec directly instead of you describing it in prose.
Browser automation — Playwright. The agent navigates a staging site, fills a form, screenshots the result.

The test: if the answer to “why did you do it that way?” is “I had to guess because I couldn’t see the source,” there’s probably an MCP server that closes the gap. The integration moves from “you, by hand” to “the agent, in-flow.”

For the per-tool setup (where servers are configured, scopes, transport options) see MCP servers.

Your AI agent is smarter than you. And knows less than you.

Wed, 20 May 2026 00:00:00 GMT

The AI agent you’re using has read more code than you have. More languages, more frameworks, more decades of open source. It can sketch a React app, refactor a Rust crate, write a SQL query against a schema it’s never seen. Pattern-matched against a corpus larger than any single human will ever encounter.

It also doesn’t know that your team uses pnpm, not npm. It doesn’t know the auth service moved out of services/auth six months ago. It doesn’t know which of the five “utils” folders is actually authoritative, or that the Logger class is preferred over console.log, or that your migrations have an unwritten rule about never being edited after merge.

That asymmetry is the gap. The agent is broad and shallow. The SME — you, your tech lead, the engineer who wrote the original module — is narrow and deep. The agent’s failures aren’t usually intelligence failures. They’re context failures. It chose a reasonable pattern; it just wasn’t the pattern your team uses. It picked a perfectly good library; it just wasn’t the one already vendored in your repo.

A smarter model doesn’t fix this. A bigger model doesn’t fix this. The next generation of agent will still walk into your codebase blind to the things that aren’t written down.

Context engineering is the practice of closing that gap. Writing down what only you know, in a form the agent can read. Connecting the agent to the systems your team’s knowledge actually lives in (Jira, Postgres, Figma). Encoding the rules that can’t be inferred from the code alone. Isolating the agent’s context so one bad thread doesn’t pollute the next.

Every chapter on this site is a technique for it. Rules. Skills. MCP servers. Subagents. Hooks. Permissions. Plan mode. They’re not features to admire — they’re levers for closing the gap between what the agent is capable of and what it actually knows about your work.

Start with Rules — the simplest lever, the one every major AI coding tool added in the same year. We’ll cover the rest from there.