AGENTS.md

AGENTS.md 是一个开放格式：在仓库根目录放一个 Markdown 文件，写清楚 Agent 在这个项目里工作需要知道的事。README 写给人看，AGENTS.md 写给 Agent 看。它由 OpenAI Codex、Cursor、Google Jules、Amp、Factory 等多家工具共同推动，现在由 Linux 基金会旗下的 Agentic AI Foundation 维护，已被六万多个开源项目使用。

为什么是首选

• 跨工具通用。 Cursor、Codex、Pi 等工具都会直接读取；换工具时不用重写。Claude Code 默认读 CLAUDE.md，可以让 CLAUDE.md 只写一行引用 AGENTS.md，或建立软链接，保持单一事实源。
• 没有格式负担。 就是普通 Markdown，没有必填字段，标题随你定。
• 可以分层。 大型仓库里，子目录可以有自己的 AGENTS.md，离被修改文件最近的那一份优先。

写什么

1. 命令。 安装、开发、测试、检查分别怎么跑。这是 Agent 最需要、也最容易猜错的信息。
2. 约定。 代码风格、目录职责、命名、提交信息格式。
3. 边界。 哪些操作必须先问（提交、删除、改公共接口），哪些文件不能碰。
4. 验证。 完成一项改动后必须通过哪些检查。

不写什么

• 人类读者需要的背景故事和营销文案。
• 模型本来就知道的通用知识（“写清晰的代码”）。
• 只在少数任务才用到的长流程——拆成 Skills。

# AGENTS.md

## 项目概览
- <项目一句话说明>
- 技术栈：<例如 Vite + React + TypeScript，pnpm>
- 目录职责：
  - `src/features/` 按业务功能划分的模块
  - `src/components/` 跨功能复用的界面组件
  - `src/lib/` 与框架无关的工具函数

## 命令
- 安装：`pnpm install`
- 开发：`pnpm dev`
- 单元测试：`pnpm test`
- 全部检查：`pnpm check`

## 约定
- TypeScript 严格模式，不使用 `any`；外部输入在边界处校验。
- 组件文件用 PascalCase，其余文件用 kebab-case。
- 提交信息遵循 Conventional Commits。

## 边界
- 提交、推送、删除文件、修改公共接口前先征求同意。
- 不要读取或输出 `.env*` 中的密钥。
- 不要手动修改生成代码与锁文件。

## 完成标准
- `pnpm check` 通过；新增行为有测试；修复缺陷时先补一个能复现问题的测试。