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 to do this is to keep a single set of master instructions in an AGENTS.md file. In it, you define persistent rules that shape every interaction you have with the agent.

You need to prune and tweak these instructions over time 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 tool quickly becomes untenable.

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

Good news

Most coding tools have since consolidated around AGENTS.md as the standard. So i’m updating the instructions to be relevant and removing the old sections.

How I organize my AI instructions #

You can set up your AI instructions at two levels:

  1. Project level instructions: typically the most relevant and specific to the codebase you’re working on
  2. User level instructions: your personal preferences that apply across all projects

Project level instructions #

AGENTS.md #

Your main agent instructions go in the root of your project, in an AGENTS.md file. This file contains the rules and instructions you want your AI agents to follow when working on this project.

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.

Every tool except Claude Code has rallied behind the AGENTS.md standard. Claude still wants its own CLAUDE.md, so we point it to AGENTS.md:

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

Edit AGENTS.md in one place, all tools stay in sync.

Nested AGENTS.md support

Most AI tools support nested AGENTS.md files — place one in any subdirectory for module-specific instructions. Agents pick up the additional context only when working in that directory, keeping your root AGENTS.md lean.

Other AI assets #

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

# Optional: organize related AI assets
mkdir -p .agents/skills   # on-demand instructions with "progressive disclosure"; see https://kau.sh/blog/claude-skills/
mkdir -p .agents/plans    # technical execution plans for large changes
mkdir -p .agents/tmp      # tmp location that's .gitignored for files generated this session

# Claude-specific setup (Claude doesn't natively read .agents/)
mkdir -p .claude
ln -s ../.agents/skills .claude/skills  # ⚠️ source path is relative to symlink

# Codex-specific setup
mkdir -p .codex

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

Global user level instructions #

Project-level instructions cover most cases. But you might also want personal preferences that apply across all projects without forcing them on teammates.

# One canonical place (keep under version control if you like)
mkdir -p ~/.agents
# put your master instructions in ~/.agents/AGENTS.md

# Codex: global rules + prompt files
mkdir -p ~/.codex
ln -sfn ~/.agents/AGENTS.md ~/.codex/AGENTS.md

# Claude Code: global memory (Claude doesn't natively read ~/.agents/)
mkdir -p ~/.claude
ln -sfn ~/.agents/AGENTS.md ~/.claude/CLAUDE.md
ln -sfn ~/.agents/skills ~/.claude/skills

# Firebender: auto-discovers project-level AGENTS.md; global needs explicit path
mkdir -p ~/.firebender
ln -sfn ~/.agents/AGENTS.md ~/.firebender/AGENTS.md

# Gemini CLI: read AGENTS.md as a context file
mkdir -p ~/.gemini
echo '{"context":{"fileName":["AGENTS.md"]}}' > ~/.gemini/settings.json

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. ↩︎

  2. for the IntelliJ users ↩︎