AGENTS.md：为AI编程助手打造的开放规范指南

项目标题与描述

该项目由Agentic AI Foundation (AAIF) 在Linux基金会下负责管理，其核心理念是建立一个能被整个开发者社区采纳的开放标准，而不依赖于任何单一厂商。目前，该格式已被包括 OpenAI Codex、Google Jules、Cursor、Aider、Gemini CLI 在内的众多主流AI编程工具所支持。

功能特性

  • 标准化格式: 采用简单的Markdown格式，无强制字段要求，易于创建和维护。开发者可以使用任意的标题结构，AI助手会解析所提供的文本内容。
  • 提升协作效率: 为AI助手提供项目特有的开发环境提示、测试指令、代码风格指南和安全注意事项，使其能像资深开发者一样快速上手。
  • 分层指令支持: 支持在大型单体仓库（Monorepo）中嵌套使用。每个子项目目录下都可以有自己的 AGENTS.md 文件，AI助手会自动读取距离当前编辑文件最近的那个文件，确保指令的精确性。
  • 向后兼容与迁移: 设计考虑了现有工作流的迁移。可以方便地将已有的指导文件（如 AGENT.md）重命名为 AGENTS.md，并通过创建符号链接来保持向后兼容。
  • 社区驱动与广泛采用: 作为一个开放的社区标准，它已被超过 60,000个开源项目 所使用，并集成了众多流行的AI编程工具。

安装指南

AGENTS.md 作为一个文件格式规范，无需复杂的安装过程。其实现依赖于集成了该规范的AI编程工具。本项目包含一个展示该规范的Next.js官方网站，你可以通过以下步骤在本地运行该网站：

系统要求

  • Node.js 环境
  • npm、yarn 或 pnpm 包管理器

本地运行步骤

  1. 克隆或下载项目代码。
  2. 在项目根目录下安装依赖（建议使用pnpm以获得最佳体验）： 
    pnpm install
  3. 启动开发服务器： 
    pnpm run dev
  4. 打开浏览器并访问 http://localhost:3000 即可查看网站。

开发注意事项

  • 在开发过程中，请始终使用 npm run dev（或对应的 pnpm dev、yarn dev）来启动热重载（HMR）开发服务器。
  • 请避免 在交互式开发会话中运行 npm run build 命令，这会切换为生产构建并禁用热重载，可能导致开发环境状态不一致。

使用说明

基础使用

在项目的根目录下创建一个名为 AGENTS.md 的文件。你可以包含任何你认为对AI助手有帮助的信息。以下是一个基础示例：

# AGENTS.md

## 项目概览
这是一个使用Next.js和TypeScript构建的Web应用。

## 开发命令
- 安装依赖: `pnpm install`
- 启动开发服务器: `pnpm dev`
- 运行代码检查: `pnpm lint`
- 运行测试: `pnpm test`

## 代码风格
- 使用TypeScript严格模式。
- 使用单引号，省略分号。
- 尽可能使用函数式编程模式。

典型场景与配置

为Aider配置AGENTS.md：
在项目根目录创建或编辑 .aider.conf.yml 文件，添加以下内容以指引Aider读取 AGENTS.md：

read: AGENTS.md

为Gemini CLI配置AGENTS.md：
在 .gemini/settings.json 配置文件中指定上下文文件名：

{
  "contextFileName": "AGENTS.md"
}

在大型单体仓库中使用：
如果你的项目结构复杂，可以在不同的子包（package）目录下分别放置 AGENTS.md。AI助手会优先采用距离当前工作文件最近的指令文件。例如，主项目下可以有一个通用的指南，而 packages/frontend/ 和 packages/backend/ 目录下可以有更具体的、针对前后端的指南。

核心代码

以下是项目中几个核心组件的代码，它们构成了展示网站的功能基础：

1. 网站主页 Hero 组件 (/components/Hero.tsx)
此组件展示了网站的核心标题、描述和主要的行动号召按钮。

import React from "react";
import CodeExample, { HERO_AGENTS_MD } from "@/components/CodeExample";
import GitHubIcon from "@/components/icons/GitHubIcon";

export default function Hero() {
  return (
    <header className="px-6 py-20 bg-gray-50 dark:bg-gray-900/40 border-b border-gray-100 dark:border-gray-800">
      <div className="max-w-6xl mx-auto grid grid-cols-1 lg:grid-cols-2 gap-10 items-start">
        {/* 左侧文字内容区域 */}
        <div className="flex flex-col items-start text-left sm:items-start max-w-prose">
          <h1 className="text-5xl md:text-6xl font-bold tracking-tight">AGENTS.md</h1>
          <p className="mt-2 text-lg leading-relaxed text-gray-700 dark:text-gray-300">
            A simple, open format for guiding coding agents,{" "}
            <br className="hidden sm:block" />
            used by over{" "}
            <a
              href="https://github.com/search?q=path%3AAGENTS.md+NOT+is%3Afork+NOT+is%3Aarchived&type=code"
              target="_blank"
              rel="noopener noreferrer"
              className="underline hover:no-underline"
            >
              60k open-source projects
            </a>
            .
          </p>
          {/* ... 更多描述和按钮 ... */}
        </div>
        {/* 右侧代码示例区域 */}
        <div className="w-full md:max-w-none">
          <CodeExample
            compact
            heightClass="min-h-[160px] max-h-[300px]"
            code={HERO_AGENTS_MD}
            href="https://github.com/openai/codex/blob/main/AGENTS.md"
          />
        </div>
      </div>
    </header>
  );
}

2. 代码示例展示组件 (/components/CodeExample.tsx)
这是一个可复用的组件，用于美观地展示 AGENTS.md 的示例代码片段，并支持复制功能。

import React from "react";
import ClipboardIcon from "./icons/ClipboardIcon";
import CopyIcon from "./icons/CopyIcon";

interface CodeExampleProps {
  /** 要显示的Markdown内容；如果未提供则使用默认示例 */
  code?: string;
  /** “在GitHub上查看”链接的可选URL */
  href?: string;
  /** 如果为true，则只渲染代码块，不包含外部包装 */
  compact?: boolean;
  /** 覆盖 <pre> 块的Tailwind高度类 */
  heightClass?: string;
  /** 为单行命令提供垂直居中对齐 */
  centerVertically?: boolean;
}

// 默认的示例代码常量
const EXAMPLE_AGENTS_MD = `# Sample AGENTS.md file

## Dev environment tips
- Use \`pnpm dlx turbo run where <project_name>\` to jump to a package...
- Run \`pnpm install --filter <project_name>\` to add the package to your workspace...`;

export const CodeExample: React.FC<CodeExampleProps> = ({
  code = EXAMPLE_AGENTS_MD,
  href,
  compact = false,
  heightClass = "min-h-[200px]",
  centerVertically = false,
}) => {
  const [copied, setCopied] = React.useState(false);
  const handleCopy = () => {
    navigator.clipboard.writeText(code);
    setCopied(true);
    setTimeout(() => setCopied(false), 2000);
  };

  // 渲染核心的代码块和复制按钮
  const codeBlock = (
    <div className={`relative rounded-xl border bg-gray-50 dark:bg-gray-900/50 border-gray-200 dark:border-gray-800 overflow-hidden ${!compact ? 'p-6' : ''}`}>
      <pre className={`overflow-auto p-4 text-sm ${heightClass} ${centerVertically ? 'flex items-center' : ''}`}>
        <code className="font-mono text-gray-800 dark:text-gray-200">{code}</code>
      </pre>
      <button
        onClick={handleCopy}
        className="absolute top-4 right-4 p-2 rounded-lg bg-white/80 dark:bg-gray-800/80 border border-gray-300 dark:border-gray-700 hover:bg-white dark:hover:bg-gray-800"
        aria-label="Copy code"
      >
        {copied ? <ClipboardIcon /> : <CopyIcon />}
      </button>
    </div>
  );

  if (compact) return codeBlock;

  // 完整模式下的渲染，包含标题和GitHub链接
  return (
    <div className="space-y-4">
      <div className="flex justify-between items-center">
        <h3 className="text-lg font-semibold text-gray-900 dark:text-white">AGENTS.md</h3>
        {href && (
          <a
            href={href}
            target="_blank"
            rel="noopener noreferrer"
            className="text-sm text-gray-600 dark:text-gray-400 hover:text-gray-900 dark:hover:text-gray-300 inline-flex items-center gap-1"
          >
            View on GitHub
          </a>
        )}
      </div>
      {codeBlock}
    </div>
  );
};

export default CodeExample;

3. 通用内容区块组件 (/components/Section.tsx)
这是一个布局组件，用于确保网站各个部分（如“为什么使用”、“如何用”、“FAQ”）具有统一和响应式的样式。

import React from "react";

export type SectionProps = React.PropsWithChildren<{
  id?: string;
  className?: string;
  title: string;
  /** 水平居中标题和内部内容 */
  center?: boolean;
  /** 覆盖默认容器宽度的Tailwind max-width工具类 */
  maxWidthClass?: string;
}>;

export default function Section({
  className = "",
  id,
  title,
  children,
  center = false,
  maxWidthClass = "max-w-6xl",
}: SectionProps) {
  const containerClasses = `${maxWidthClass} mx-auto flex flex-col gap-6`;

  return (
    <section id={id} className={className + " px-6"}>
      <div className={containerClasses}>
        <h2
          className={`text-3xl font-semibold tracking-tight ${center ? "mx-auto text-center" : ""}`}
        >
          {title}
        </h2>
        <div className="prose prose-neutral dark:prose-invert max-w-none">
          {children}
        </div>
      </div>
    </section>
  );
}

更多精彩内容 请关注我的个人公众号 公众号（办公AI智能小助手）
对网络安全、黑客技术感兴趣的朋友可以关注我的安全公众号（网络安全技术点滴分享）

Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

Claude Code 通信机制逆向分析

使用 Proxyman 抓包工具对 Claude Code 的 API 通信进行完整逆向分析，浅谈 AI Agent 的工作机制。

avatar AI编程社区
cover

Codex又又又更新了！这次似乎不需要Xcode了？Codex更新、Codex遥控器、Codex手机版、iOS Builder、Xcode替代方案、AI编程工具、Codex客户端下载、Mac远程控制、

avatar AI编程社区
cover

告别拖拽做工作流：两个Skill让Dify应用全流程自动化

avatar AI编程社区