Agents.md

介绍

AGENTS.md 是一个简单、开放的 Markdown 文件规范，用来在仓库里为“编码智能体/AI 编程助手”提供稳定的上下文与工作指引。你可以把它理解为“给智能体看的 README”：放置项目概览、安装/启动/测试命令、代码风格与注意事项等，减少反复沟通成本。

官网：https://agents.md/ 仓库：https://github.com/agentsmd/agents.md

怎么用（最实用的用法）

AGENTS.md 的“用法”非常简单：把它当作项目里的“智能体工作说明书”，放在仓库根目录（或子项目目录）即可。之后你在和 AI 编程助手对话时，它会把这个文件当作项目上下文的一部分，按里面的命令与约定来执行。

你可以按下面 3 步落地：

1. 在仓库根目录创建 AGENTS.md
2. 写清楚“怎么跑起来 + 怎么验证 + 代码约定”
3. 需要更细粒度时，在子目录再放一份 AGENTS.md（离目标文件更近的优先）

该写什么（按“让智能体少猜”来写）

优先写这些能直接减少试错的信息：

• Setup commands：安装依赖、启动、构建、测试的命令
• Project overview：关键目录、入口文件、路由/状态管理位置
• Code style：格式化/Lint/命名/提交前检查的要求
• Testing instructions：如何跑全量检查、如何只跑某个测试
• Gotchas：常见坑（环境变量、端口、鉴权、mock、代理、特定脚本限制等）

针对本仓库的示例（可直接改成你的 AGENTS.md）

下面这份更贴近你当前仓库（Vue 3 + Vite 应用 + VitePress 文档）：

# AGENTS.md

## Project overview
- `src/` is the Vue 3 app (router in `src/router`, store in `src/store`, API in `src/api`).
- `docs/` is the VitePress site (config in `docs/.vitepress/config.js`).
- Vite alias: `@` -> `src` (see `vite.config.js`).
- Env: `VITE_API_BASE_URL` in `.env`.

## Setup commands
- Install deps: `npm install`
- Dev (app): `npm run dev` (port 8080)
- Build (app): `npm run build`
- Test: `npm run test`
- Dev (docs): `npm run dev:docs`
- Build (docs): `npm run build:docs`

## Working rules
- Prefer reusing existing patterns in the codebase.
- Do not log secrets or commit sensitive data.

怎么判断“用上了”

• 你不需要在代码里“引入”它：AGENTS.md 本质就是一个约定位置的说明文件
• 当你问“怎么启动/怎么跑测试/改动该遵循什么约定”时，智能体会优先按 AGENTS.md 里的内容来做（如果与你的聊天指令冲突，以聊天指令为准）

为什么需要 AGENTS.md

• README.md 更偏向给人类读（项目介绍、快速开始、贡献指南等）
• AGENTS.md 专门面向智能体，放更偏“执行型”的信息（命令、约定、排查路径等），避免把 README 写得过于冗长
• 使用独立、可预期的文件名，便于不同工具统一寻找与解析

常见内容结构

一个实用的 AGENTS.md 通常会包含：

• 项目概览：目录结构、关键模块、运行方式
• 环境与依赖：Node/包管理器版本、必需的系统依赖
• 常用命令：安装依赖、启动、构建、测试、Lint/格式化
• 代码风格：例如单引号、是否分号、函数式偏好、TypeScript 严格模式等
• 测试与 CI：CI 入口、如何跑全量/单测、如何只跑某个用例
• 安全注意：不要记录或打印密钥、不要提交敏感信息等

最小示例

# AGENTS.md

## Setup commands

- Install deps: `pnpm install`
- Start dev server: `pnpm dev`
- Run tests: `pnpm test`

## Code style

- TypeScript strict mode
- Single quotes, no semicolons
- Use functional patterns where possible

适用场景

• 新同事/新智能体快速上手：不用“读遍全仓库”才能知道怎么跑
• 多项目/多包仓库：可以在子目录放置就近的 AGENTS.md，让不同子项目有各自的指引
• 约定统一化：减少“这个项目怎么格式化/怎么跑测试/CI 怎么配”的重复问答

规则优先级（常见约定）

• 离当前工作目录最近的 AGENTS.md 优先
• 明确的用户对话指令优先于文件内约定