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 包管理器
本地运行步骤
- 克隆或下载项目代码。
- 在项目根目录下安装依赖（建议使用pnpm以获得最佳体验）：
pnpm install - 启动开发服务器：
pnpm run dev - 打开浏览器并访问
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{" "}<ahref="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"><CodeExamplecompactheightClass="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><buttononClick={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 && (<ahref={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}><h2className={`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智能小助手）
对网络安全、黑客技术感兴趣的朋友可以关注我的安全公众号（网络安全技术点滴分享）
公众号二维码
公众号二维码
