Getting useful results from your AI assistant often hinges on providing the right instructions. Yet most developers take this step casually, then wonder why their AI outputs are mediocre.

One of the simplest ways1 you can do this is with your master instructions or AGENTS.md file. In this file, you provide persistent rules that shape every interaction you will have with the agent.

You need to be pruning and tweaking these instructions to get the best results. If - like me - you use multiple tools (Claude, Cursor, Gemini CLI, Codex, Firebender2), then updating the same rules for each of these tools, quickly becomes untenable.

In this post, I’ll show you how I consolidate it all and edit it one place, while keeping it sync everywhere else.

How I organize my AI instructions

Every AI tool wants its own special instruction file:

Good news

Most coding tools have since consolidated around AGENTS.md as the standard. So it makes sense to use that now.

Start by creating the master instructions file:

touch AGENTS.md
Generating your first AGENTS.md file

Claude Code’s /init command generates an excellent starting template for your project by analyzing your project structure and creating sensible defaults.

But if you don’t use Claude Code, I wrote a more recent post on how you can do it yourself pretty easily with a custom /initialize command.

# Damn you Claude!
# https://github.com/anthropics/claude-code/issues/6235
echo 'See @AGENTS.md' > CLAUDE.md

# Point Gemini to AGENTS.md
mkdir -p .gemini
echo '{"context":{"fileName":["AGENTS.md"]}}' > .gemini/settings.json

# Point Firebender(for Intellij) to AGENTS.md
mkdir -p .firebender
echo '{"rules":[{"filePathMatches":"*","rulesPaths":"~/AGENTS.md"}]}' > .firebender/firebender.json

You now have a centralized AGENTS.md: you edit in one place, and all tools stay synchronized.

Nested AGENTS.md support

Most AI tools have also started to support “nested” AGENTS.md files. This means you can have a specific instructions for the agent based on the module or folder it’s operating in.

This helps you from having an overly stuffed parent AGENTS.md file which can sometimes unnecessarily fill up your context. With nested AGENTS.md files, coding agents know to pick up the additional context from nested folders only when necessary and relevant.

Global user level instructions

While more often than not, you’ll follow the above instructions to setup agent instructions at the project level, certain agents also allow you to setup instructions at a user level. Think of these as your personal preferences.

# Codex
mkdir -p .codex
ln -s ../AGENTS.md ~/.codex/AGENTS.md         # ⚠️ symlink for dirs are relative path

# Damn you Claude!
# https://github.com/anthropics/claude-code/issues/6235
echo 'See @~/AGENTS.md' > ~/.claude/CLAUDE.md

Other AI assets

In addition to the main system instructions, I also like organizing my AI related “assets” in an .ai folder:

# Optional: organize related AI assets
mkdir -p .ai/commands    # *.md prompt templates for frequent tasks (call directly)
mkdir -p .ai/plans       # technical execution plans for large changes
mkdir -p .ai/plans/tmp    # tmp location for agent to use that's .gitignored

# Claude specific setup
mkdir -p .claude
ln -s ../.ai/commands .claude/commands   # ⚠️ symlink for dirs are relative path

# Codex specific setup
mkdir -p .codex
ln -s ../.ai/commands .codex/prompts   # ⚠️ symlink for dirs are relative path

Is this worth it?

The short answer: yes. While I haven’t done rigorous A/B testing on each rule or instruction, the improvements are noticeable. Without instructions, AI tools default to generic patterns and I’ve found myself having to repeat basic instructions more often. Folks online also seem to agree on this.

Fine-Tuning Your Rules

Want to see what context your AI is actually using? Try asking:

What custom instructions or context files are you currently using for this project?
List any .ai/, AGENTS.md, or tool-specific rule files you can see.

Different tools have varying levels of transparency here. Claude and Cursor are generally forthcoming about loaded context, while others may be more opaque. Use this feedback to refine your instructions, removing redundancy and clarifying ambiguous rules.

Revisions

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

  2. for the IntelliJ users ↩︎

  3. conveniently they own the domain https://agents.md and have graciously been trying to rally everyone behind this ↩︎