如何编写高效的 AI 代理指令文档 AGENTS.md

解决 AI 指令冗余问题：通过构建极简的 AGENTS.md 规范文档，为 AI 代理提供高信号的项目上下文，避免因文档过长导致指令遵循能力下降。

为什么需要这个技能

当 AI 代理（如 Claude, Cursor, GitHub Copilot）在处理复杂项目时，如果缺乏统一的指令文档，AI 可能会在包管理器选择、提交规范或测试命令上产生幻觉或重复询问。

然而，过长的提示词或文档反而会降低 AI 的执行质量。本技能的核心在于通过“极简主义”原则，将文档控制在 60-100 行以内，仅保留最关键的工具链信息和项目约定，确保 AI 能够快速定位并准确执行任务。

适用场景

• 项目初始化时需要创建 AGENTS.md 或 CLAUDE.md。
• 现有 AI 指令文档过于臃肿，导致 AI 经常忽略某些关键步骤。
• 需要统一团队中不同 AI 代理对项目构建、Lint 和提交规范的认知。
• 维护一个能够随项目演进而动态更新的 AI 协作指南。

核心工作流

1. 环境分析：扫描项目根目录，识别包管理器（如 pnpm-lock.yaml）、Lint 配置（如 .eslintrc）和 CI 脚本，确保文档内容与实际代码库一致。
2. 建立映射：在根目录创建 AGENTS.md，并创建软链接 ln -s AGENTS.md CLAUDE.md 以兼容不同 AI 工具。
3. 执行极简写作：
   • 禁用段落：仅使用标题和列表，禁止写“欢迎来到本项目”等废话。
   • 引用而非嵌入：直接指向 CONTRIBUTING.md 等现有文档，而不是复制内容。
   • 优先文件级命令：提供针对单个文件的类型检查或测试命令（如 pnpm tsc --noEmit path/to/file.ts），而非全局构建。
4. 配置核心板块：
   • Package Manager：明确工具及核心命令。
   • Commit Attribution：强制要求 AI 在提交时添加 Co-Authored-By 身份标识。
   • File-Scoped Commands：用表格形式列出高效的单文件校验指令。
   • Key Conventions：仅列出最关键的项目特定模式。

下载和安装

下载 agents-md 中文版 Skill ZIP

解压后将目录放入你的 AI 工具 skills 文件夹，重启工具后即可使用。具体路径参考内附的 USAGE.zh.md。

你可能还需要

暂无推荐