Getting useful results from your AI assistant often comes down to the instructions you give it. Most developers treat that step casually, then wonder why the output is mediocre.

One of the simplest ways1 to improve this is to keep one set of master instructions in an AGENTS.md file. In it, you define persistent rules that shape every interaction with the agent.

Writing those instructions once is easy enough. Keeping them in sync is the annoying part.

If you use more than one tool, things drift fast. So I keep one repo as the source of truth for my AI setup, then wire my tools and projects back to it.

This post is the simple version of that setup.

Good news

Most coding tools have since consolidated around AGENTS.md as the standard. That makes this much simpler than it used to be.

I talked about this topic in detail on my AI development podcast:

How I organize my AI instructions #

I keep my setup at two levels:

  1. User-level instructions: my personal defaults that I want available everywhere
  2. Project-level instructions: the rules and context that only apply to one repo

User level: one source of truth #

I keep my shared AI setup in a single repo. That repo holds the things I want to maintain in one place:

Then I wire my local tools back to that repo with one command from the repo’s Makefile:

make setup

That command creates the symlinks for me. I am not updating the same instructions by hand for Claude, Codex, and OpenCode. I edit the shared files once in my repo, and the tools point back to them.

At the user level, I keep it direct. The repo is the source of truth, so the tool-specific paths symlink straight to it. For example:

~/.claude/agents -> ~/my-local-directory/aikado/agents
~/.config/opencode/agents -> ~/my-local-directory/aikado/agents

So the maintenance story is simple:

Project level: thin local scaffolding #

For each codebase, I still want a project-local AGENTS.md and a place for project-specific assets.

So when I start a new repo, I run the project setup target from that same Makefile:

make setup-project dir=~/dev/oss/some-repo

That command creates the local directories and symlinks, and the result looks like this:

AGENTS.md
CLAUDE.md
.agents/
  agents/
  skills/
  commands/
  plans/
  tmp/
.claude/
  agents -> ../.agents/agents
  commands -> ../.agents/commands
  skills -> ../.agents/skills
.opencode/
  agents -> ../.agents/agents
.codex/
  prompts -> ../.agents/commands

The role of each piece is straightforward:

That gives me a clean split:

I do not force the exact same structure at both levels.

Generating your first AGENTS.md

If you do not already have a good project AGENTS.md, start with an init command that analyzes the repo and writes a first draft. I use a custom /initialize command for this.

Nested AGENTS.md

Most AI tools support nested AGENTS.md files. If one subdirectory needs extra instructions, add another one there and keep the root file lean.

Claude still needs a shim

Most tools now read AGENTS.md directly. Claude still wants CLAUDE.md, so I keep a tiny compatibility file that just says See @AGENTS.md.

Fine-Tuning Your Rules #

To see what context your AI is actually using, ask it: “What custom instructions or context files are you currently using for this project?” Use that feedback to prune redundancy and clarify ambiguous rules.

Revisions #

  1. I wrote a later post distilling the three things that matter most for getting good AI coding results. ↩︎