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 Anthropic has rallied behind the AGENTS.md standard. But Claude Code still wants its own special CLAUDE.md file. So we create that, then point it to AGENTS.md for consistency.

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


# 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 it 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.

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/skills   # on-demand instructions with "progressive disclosure"; see https://kau.sh/blog/claude-skills/
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/tmp      # tmp location that's .gitignored for files generated this session

# Claude-specific setup
mkdir -p .claude
ln -s ../.ai/commands .claude/commands # ⚠️ source path is relative to symlink
ln -s ../.ai/skills .claude/skills

# Codex-specific setup
mkdir -p .codex
ln -s ../.ai/commands .codex/prompts # ⚠️ source path is relative to symlink
ln -s ../.ai/skills .codex/skills

# Gemini-specific setup (same as before)
mkdir -p .gemini
echo '{"context":{"fileName":["AGENTS.md"]},"experimental":{"skills": true, "enableAgents": true}}' > .gemini/settings.json
ln -s ../.ai/skills .gemini/skills # ⚠️ source path is relative to symlink

Global user level instructions #

More often than not, you’re working at the project level, so the instructions above should suffice. Sometimes you might want to have custom instructions to the agent, unique to you, that you may not want to force on other team members.

Some agents allow instructions at a user level. Think of these as your personal preferences.

# Codex
mkdir -p ~/.codex
ln -s ../AGENTS.md ~/.codex/AGENTS.md   # ⚠️ source path is relative to symlink

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

Is this worth it? #

The short answer: yes. I haven’t done rigorous A/B tests on each rule or instruction, but the improvements are noticeable. Without instructions, AI tools default to generic patterns and I find myself repeating basic instructions more often. Folks online also seem to agree.

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

  2. for the IntelliJ users ↩︎