Database branching for AI coding agents: a minimal, CLI-first setup that actually works

When you’re wiring LLM-based coding agents into real repos, the biggest wins usually come from boring clarity: a small set of instructions that are easy to follow and hard to misuse.

With that in mind, we asked ourselves the following question:

This is a topic we’ve been investigating over the last few weeks. Previously we explored:

• Writing our own agent and giving it access to GitHub, sandbox and Xata platform
• Teaching Claude Code to use Xata platform with Agent Skills

In addition to the above, we also explored using Xata with Claude Code (without using Agent Skill) and Amp Code by simply providing instructions to use the xata CLI in the relevant agent file (AGENTS.md for Amp and CLAUDE.md for Claude Code).

In practice, we’ve found you can get surprisingly far without custom ‘skills’ or MCP plumbing: put a short set of Xata CLI rules in the agent’s instruction file (AGENTS.md for Amp, CLAUDE.md for Claude Code), and keep the branching workflow explicit. The agent can then follow those rules and call the CLI as needed, assuming it has access to the repo and the CLI is installed.

A quick demo (because otherwise this is just vibes)

Here’s what it looks like with Amp Code.

The repo includes two files:

1. AGENTS.md — the agent’s entry point, plus a pointer to the playbook
2. PLAYBOOK.md — the actual “how to branch safely” instructions

AGENTS.md - besides the usuals, we instruct it to use the playbook.md file at the bottom.

PLAYBOOK.md - this is where we teach it to use Xata CLI i.e. database branching. Seriously, this is all we need:

To skill or not to skill

This post describes a direct AGENTS.md file approach and contrasts it with using agent skills, as discussed here which outlines the advantages of skills over MCP and AGENTS.md. So which approach should you use in your projects? To answer that, it’s important to understand context management. This excellent blog post explains the concept for Amp but the same principles apply to other AI agents as well.

The key question is what you want in the context window. If most features in your repository benefit from database branches for example, running performance regression tests on an isolated branch for every PR, then putting this logic in AGENTS.md gives it “more weight”. However, if say only 20% of your features benefit from database branching, adding it to AGENTS.md will add noise the context window 80% of the time.

Moreover, agent skills might not be available in all coding agents, making the markdown file approach more flexible. MCP can be a good middle ground but ultimately your project’s context will determine whether using skills, MCP or inlining the prompt is the best way to teach a coding agent the art of database branching.

Conclusion

Thank you for reading this blog post. In this post, we explored how simply pointing AI agents to Xata CLI is enough to teach them to do database branching effectively and we also explored comparison of this approach with Skills and MCP servers.

If you try this pattern and run into edge cases (auth, branch readiness, accidental prod URLs), that’s where stricter tooling like skills/MCP, approvals, or guardrails in scripts tends to pay off. If you want to experiment with Xata branching in your own repo, the CLI docs and branching workflow are the place to start.