The world is changing fast. Today, almost every developer or data engineer uses some kind of AI assistant — like Gemini, Claude, or Cursor — to write, debug, and test code, or process data and metadata. These tools are amazing, but they all need one thing: clear instructions. If you’ve ever found yourself copying and pasting the same four paragraphs of project rules into a dozen different chat windows, you know the problem well.
We’re here to solve that problem with one simple file: AGENTS.md.
AGENTS.md is quickly becoming the industry standard for giving AI tools the “big picture” about your project. Think of it as the master instruction manual for all your AI coding helpers. When you change a rule in AGENTS.md, every AI tool that reads it instantly knows the new rules. This guide will show you how to set up this master file and connect it to the three biggest AI code assistants, ensuring your whole team and all your AI helpers are always on the same page.
The Problem: Repeating Yourself
In software development, there’s a famous saying: DRY (Don’t Repeat Yourself). It means that every piece of information should have a single, clear source. If a rule exists in five different places, and you need to change it, you have to remember to update all five spots. If you miss one, your code becomes inconsistent. This is the opposite of DRY; it’s called WET (Write Everything Twice), or even more times!
When you use different AI tools, the WET problem gets worse:
Gemini CLI needs a GEMINI.md file.
Claude Code needs a CLAUDE.md file.
Copilot needs a .github/copilot-instructions.md file
Cursor naturally looks for an AGENTS.md file.
If your project uses multiple models simultaneously, you’d have to update three separate files (or re-explain it in every single chat) if you change the configuration. That’s time-consuming, boring, and risky. This is especially true for open-source projects, where developers using different AI models need a single, reliable configuration source to ensure consistency.
The Vision: A Single Source of Truth
Our goal is to follow the DRY principle. We want one master file, AGENTS.md, that contains all the essential rules for your project. Then, we’ll use smart methods to make the other tools — Gemini and Claude — “read” this master file instead of needing their own unique instructions.
The Foundation: Your AGENTS.md File
This file belongs in the very root folder of your project (where you find files like package.json). It should be clear, simple, and tool-agnostic, meaning it doesn’t mention Gemini or Claude specifically.
Here’s an example of what your master file should look like:
# Agent Development Guidelines
This document outlines the standard practices and requirements for developing, testing, and maintaining conversational agents or AI services across various platforms and programming languages. Adhering to these guidelines ensures consistency, quality, and maintainability.
## 1. Technical Stack & Configuration
**Platform Agnostic:** The core logic of the agent should be separable from the deployment platform (e.g., Webhook, Cloud Function, dedicated server).
**Configuration Management:** All environment-specific variables (API keys, endpoint URLs, secrets) must be loaded from secure environment variables or a dedicated configuration service, never hardcoded.
**Dependencies:** List all external libraries and services required for the agent to function.
## 2. Coding Standards & Conventions
**Code Style:** Follow established language-specific style guides (e.g., ESLint for JavaScript, Black for Python). Automated formatting tools are mandatory.
**Modularity:** Code must be organized into logical, small, and reusable functions/modules. Business logic should be strictly separated from input/output handling.
**Readability:** Use clear, descriptive names for variables, functions, and classes. Add meaningful comments where the *why* of the code is not immediately obvious.
## 3. Testing & Quality Assurance
**Unit Tests:** Every new feature or fix must be accompanied by comprehensive unit tests that cover core functionality and edge cases.
*Requirement:* Code coverage must not decrease below the established project threshold (e.g., 80%).
**Integration Tests:** Implement tests to verify the agent’s interaction with external APIs and databases.
**Test Framework:** Specify the required testing framework (e.g., Jest, Pytest).
**Mocking:** Use mocking for external service dependencies to ensure tests are fast, reliable, and isolated.
## 4. Deployment & Verification
**Continuous Integration (CI):** All commits to the main branch must first pass all defined CI checks (linting, testing, type-checking, if applicable).
**Linting/Static Analysis:** Run a linter and static analysis tool on all code before merging.
*Command:* `npm run lint` or equivalent.
**Pre-Deployment Check:** A build or compilation step (if applicable) must be executed to ensure the code is free of basic errors before deployment.
*Command:* `npm run build` or equivalent.
**Logging & Metrics:** Implement robust logging for all critical operations (errors, API calls, state transitions) and utilize standard metrics for monitoring performance.Now you have one powerful file. The next step is to connect it to tools that don’t automatically detect it.
The “Hook” Method (Recommended)
The “Hook” Method is the simplest and most reliable way to connect your master AGENTS.md to every other tool. It works because most AI tools have an “import” feature, often marked by the @ symbol, that tells the tool to read instructions from another file.
This method requires you to create two small files that contain almost no content.
For Gemini (GEMINI.md)
The Gemini CLI (Command Line Interface) and plugins like the one in Android Studio look specifically for a file named GEMINI.md. Instead of copying the whole AGENTS.md content into it, you simply add the hook: @AGENTS.md
That’s it. When Gemini starts, it sees GEMINI.md, reads the single line, and knows to pull all its instructions directly from your master AGENTS.md file.
For Claude (CLAUDE.md)
Claude Code (Anthropic’s tool) works the exact same way, looking for CLAUDE.md. You use the identical hook: @AGENTS.md
For Co-Pilot
Add the following to your .github/copilot-instructions.md file:
# Project Rules
Follow the coding standards and project context defined in [AGENTS.md](../AGENTS.md).For Cursor and Others
Tools like Cursor and Cline are often built to look for AGENTS.md natively in the project root. For these tools, you don’t need any extra files or setup — they will automatically follow your master rules.
Why the Hook Method Wins
The Hook Method is recommended for almost every team because of its major advantages:
Universal Compatibility: It works perfectly on Windows, Mac, and Linux without any special permissions or settings.
Tool-Specific Overrides: This is a powerful benefit. What if you need to give Claude a rule that Gemini doesn’t need? You can add it after the hook. Claude gets all the master rules plus the specific instructions, while Gemini only gets the master rules. This keeps your main AGENTS.md clean.
Git Friendly: These small files are checked into Git just like your code, ensuring everyone on your team has the same setup.
The “Soft Link” Method (For Power Users)
The second strategy uses a feature called a Symbolic Link (often called a “Symlink” or “Soft Link”). This is a trick the computer uses to make a single file appear to exist in multiple places.
Imagine you have a single document on your desk. A soft link is like creating two perfect mirrors of that document, placing one mirror where Gemini looks and one where Claude looks. Any changes to the original document instantly appear in the mirrors.
Creating the Links via Terminal
You create these links using commands in your computer’s Terminal (or Command Prompt). The command is ln -s, which stands for “link — symbolic.”
If you’re on a Mac or Linux:
# Point Gemini to Agents
ln -s AGENTS.md GEMINI.md
# Point Claude to Agents
ln -s AGENTS.md CLAUDE.mdAfter running these commands, you will see GEMINI.md and CLAUDE.md in your folder, but they won’t take up any extra space. They are just pointers to the master file.
Note that the soft link method does not work with Copilot. In late 2025, VS Code introduced an experimental setting to allow Copilot to read AGENTS.md directly by enabling chat.useAgentsMdFile in settings.
The Setup Trade-Offs
While this method creates a very clean filesystem (zero content duplication), it has major drawbacks that make it less beginner-friendly:
The Hurdle with Soft Links: Symbolic links are a pain on Windows. Standard users often can’t create them without special administrator permissions, which slows down new team members who are trying to set up their projects.
Recommendation: Use the Soft Link method only if you are confident with your operating system and need the absolute cleanest file structure, or if you are working exclusively in a Mac/Linux environment where all team members are comfortable with the command line.
Comparison and Summary
Both methods achieve the same goal: a single, master instruction file for your AI agents. The key is choosing the one that best fits your skills and operating systems.
The Power of Synchronization
No matter which method you choose, using a single AGENTS.md has several advantages:
Zero Duplication: You change a rule once, and it’s updated everywhere. Say goodbye to the confusion of conflicting instructions.
Version Control: Your AI instructions are now checked into Git right alongside your code. This means that if you go back to an older version of your code, your AI instructions automatically revert to the version they need as well.
Team Consistency: Every new team member who clones the repository gets the exact same AI experience, whether they prefer Gemini, Claude, or Cursor. The AI doesn’t rely on tribal knowledge or a quick chat; it relies on the documented rules.
By adopting AGENTS.md as your single source of truth and using the easy-to-implement “Hook Method,” you can make your AI assistants smarter, your codebase cleaner, and your team much more efficient. The era of repetitive instructions is over. Your AI tools will finally know what they’re doing, every time.
