Overview

The purpose of an AGENTS.md file is not to encode every working habit, tool command, or project detail. Its purpose is to give AI agents clear, stable, and maintainable boundaries for collaboration.

For teams working across multiple repositories and technology stacks, a global AGENTS.md should answer only the questions that remain true everywhere: how an agent interprets instructions, when it should ask before acting, how it controls risk, how it verifies results, and how local rules extend the global baseline.

Build commands, directory structures, architecture constraints, release processes, and business-specific requirements belong in repository-level or directory-level AGENTS.md files.

How to Design a Reusable Global AGENTS.md-CXT - Enjoy Life | 生活、技术、交友、分享

Why Global Guidance Should Stay Short

Overly detailed global guidance creates three problems:

  1. It turns local project practices into unnecessary global constraints.
  2. It becomes difficult to maintain, and important principles are buried in detail.
  3. It can accidentally expose personal preferences, internal processes, or organization-specific information.

A good global file is closer to a collaboration charter than a project operating manual. It defines default principles while leaving room for local guidance to supply the details.

A Five-Section Structure

The following five sections are usually enough for a concise and reusable global AGENTS.md:

  • Role and Instruction Priority: Define the agent's role and how it resolves conflicting instructions.
  • Scope and Safety: Clarify which actions are autonomous and which require explicit authorization.
  • Working Principles: Set general expectations for understanding context and making changes.
  • Verification and Delivery: Establish minimum expectations for validation and final reporting.
  • Local Rules and Collaboration: Explain how project-specific rules extend the global guidance.

Public Template

# Global Agent Guidelines

> This file defines default guidance for AI agents across projects.
> Repository-level and directory-level `AGENTS.md` files may add more specific instructions.

## 1. Role and Instruction Priority

<!--
Suggested content:
- Define the agent's general responsibility.
- Describe how instruction conflicts are resolved.
- State when clarification is required before proceeding.
-->

## 2. Scope and Safety

<!--
Suggested content:
- Define actions agents may perform autonomously.
- Identify actions that require explicit authorization.
- State expectations for sensitive data, destructive actions, and external systems.
- Describe when agents must stop and report a blocker.
-->

## 3. Working Principles

<!--
Suggested content:
- Require agents to inspect relevant context before making changes.
- Encourage focused, minimal, maintainable changes.
- Ask agents to preserve existing architecture and unrelated user changes.
- Define any general expectations for documentation or communication.
-->

## 4. Verification and Delivery

<!--
Suggested content:
- Define verification expectations based on change risk.
- Require review of affected changes before completion.
- Specify what a final report should include, such as changed files,
  checks performed, results, and remaining risks.
-->

## 5. Local Rules and Collaboration

<!--
Suggested content:
- Explain how repository-level and directory-level rules extend this file.
- Define general collaboration and ownership expectations when multiple agents work together.
- Keep project-specific commands, paths, architecture, and release processes
  in local project guidance rather than this global file.
-->

Language and Canonical Version

For instructions intended to be executed by agents, publish and maintain the English version as the canonical source. In mixed model and tool environments, English generally provides more consistent interpretation of technical terms, structured instructions, identifiers, and command-oriented language.

Translations can still be valuable for human readers. Treat them as localized reference material, and keep any code blocks, paths, commands, schema fields, identifiers, status values, and other contract-bearing text identical to the English source. When a translation conflicts with the English version, the English version should take precedence.

Using the Template Across Projects

Use a layered structure:

Global AGENTS.md
        |
        +-- Repository AGENTS.md
        |       |
        |       +-- Module-level AGENTS.md
        |
        +-- Another Repository AGENTS.md

The global file owns durable principles. Repository-level files own the technology stack, commands, directory conventions, and delivery process. Module-level files should exist only where a subsystem has distinct interface, data, test, or safety requirements.

This structure gives agents consistent guidance without sacrificing each project's autonomy.

Conclusion

When publishing an AGENTS.md template, completeness is not the goal. The goal is to leave clear space for every team to express its own engineering culture without turning one person's habits or one project's constraints into universal rules.