AGENTS.md:AIによってプログラムされた知能のガイダンスを提供するオープンフォーマットのファイル

AGENTS.md は、OpenAIらによってまとめられたシンプルなオープンソースフォーマットである。 これは、AIのプログラミング・インテリジェンス（コーディング・エージェント）のためのガイダンスを提供するように設計されており、特別に設計されたAIの読書と同様に機能する。README.mdドキュメンテーション ソフトウェア・プロジェクトではREADME.mdドキュメンテーションは通常、人間の開発者のために書かれ、プロジェクトの説明、始め方、貢献のガイドラインなどをカバーする。 一方AGENTS.mdその代わりに、詳細なビルド手順、テストコマンド、コードベース固有の仕様など、AIインテリジェンスが理解しプロジェクトに参加するために必要な、より具体的で技術的な指示を提供することに重点を置いている。このようなAI専用の指示を、専門化されたAGENTS.mdファイルではREADME.mdAIインテリジェンスがコーディングタスクをより効率的かつ正確に実行できるように、明確で予測可能な指示源を提供しながら、シンプルに保つ。

機能一覧

• 明確な指示AIインテリジェンスのために特別に設計されたファイルとして、AIがコードを処理する際に従う必要のあるすべての命令とコンテキストを一元化し、明確に定義した場所を提供する。
• プロジェクト文書の合理化AIに特化した技術的な説明（ビルドやテストの詳細など）をメインから削除する。README.mdファイルが分離されREADME.md人間の開発者に核心的な情報を提供することにもっと集中できる。
• 標準フォーマット:: オープンフォーマットとして。AGENTS.md標準的なMarkdown構文を使用し、必須のフィールド要件はなく、開発者はプロジェクトのニーズに応じて自由にコンテンツを整理することができる。
• 複雑なプロジェクトのサポート大規模なモノレポリポジトリではAGENTS.mdファイル。このインテリジェンスは、現在の作業ディレクトリに最も近いものを自動的に読み込むので、異なるモジュールに対してきめ細かいガイダンスが可能になる。
• エコシステム対応このフォーマットは、OpenAIやGoogleなどが提供する幅広いAIプログラミング・インテリジェンスを含む、AIプログラミング・ツールの成長するエコシステムと互換性があるように設計されています。

ヘルプの使用

AGENTS.mdドキュメントは、AIプログラミング知能がコードベースを理解し、操作するための「取扱説明書」となることを意図している。明確な指示を提供することで、AIが環境設定からコード提出までのタスクを効率的に完了できるよう支援します。以下、使い方や操作方法について詳しく説明する。

ステップ1：AGENTS.mdファイルの作成

コードベースのルート・ディレクトリに、手動でAGENTS.mdファイル。このファイルは、AI知能が指示を探す場所である。ほとんどのAIプログラミング・インテリジェンスは、このファイルを自動的に認識して読み取るように設計されている。

ステップ2：コア・コンテンツを書く

AGENTS.md標準的なMarkdownフォーマットを使って、通常の文書を書くように見出しやリストを作成することができます。コンテンツは、AIのための明確で実行可能なステップを提供することに重点を置くべきです。以下は、カバーすべき主要なセクションの提案です：

1.開発環境のヒント
このセクションでは、特に特定のパッケージ・マネージャーを使用するプロジェクトのために、ローカル開発環境を準備する方法について説明します。

• サンプルコード::

  # AGENTS.md 示例
  ## 开发环境提示
  - 使用 `pnpm dlx turbo run where <project_name>` 命令跳转到特定包的目录，而不是用 `ls` 扫描。
  - 运行 `pnpm install --filter <project_name>` 为工作区添加依赖，确保Vite、ESLint和TypeScript能够识别它。
  - 使用 `pnpm create vite@latest <project_name> -- --template react-ts` 快速创建一个包含TypeScript配置的React + Vite新包。
  - 检查每个包内 `package.json` 文件中的 `name` 字段来确认包的正确名称，忽略顶层的 `package.json`。
  

2.テストの指示
このセクションでは、AIが生成するコードがプロジェクトの品質基準を満たしていることを確認するためのテストの実行方法をAIに指示します。AIはこれらのコマンドの実行を試み、テストの結果に基づいてコードを修正します。

• サンプルコード::

  ## 测试指令
  - CI计划文件位于 `.github/workflows` 文件夹中。
  - 运行 `pnpm turbo run test --filter <project_name>` 来执行该包定义的所有检查。
  - 在包的根目录中，可以直接调用 `pnpm test`。合并代码前必须通过所有测试。
  - 若要专注于某个特定的测试，可以添加Vitest匹配模式：`pnpm vitest run -t "<test name>"`。
  - 修复所有测试或类型错误，直到整个测试套件全部通过。
  - 修改文件或导入后，运行 `pnpm lint --filter <project_name>` 来确保ESLint和TypeScript规则仍然通过。
  - 即使没有被要求，也为你修改的代码添加或更新测试。
  

3.プルリクエストの指示（PR指示）
AIの提出をチームの仕様に準拠させたい場合は、ここにその旨を明記してください。

• サンプルコード::

  ## PR 指令
  - 标题格式: [<project_name>] <标题>
  - 在提交（commit）之前，务必运行 `pnpm lint` 和 `pnpm test`。
  

ステップ3：大規模プロジェクトのための特別な構成

プロジェクトが単一のコードベース（monorepo）で、複数の独立したサブプロジェクトやパッケージを含む場合、各サブプロジェクトのルートにAGENTS.mdドキュメンテーション

• 動作原理AIインテリジェンスがサブディレクトリで作業しているとき、AIインテリジェンスは優先的に最も近いディレクトリを読み込む。AGENTS.mdファイルであることを意味する。つまり、ルート・ディレクトリのAGENTS.mdグローバル・コマンドを提供することができ、各サブプロジェクトのAGENTS.mdその後、そのモジュールに特化したより具体的な指示を出すことができる。
• 典型例プロジェクトの構成は以下を想定している：

  /my-monorepo
  ├── AGENTS.md         # 全局指令
  ├── /packages
  │   ├── /frontend
  │   │   ├── AGENTS.md # 前端专用指令
  │   │   └── ...
  │   └── /backend
  │       ├── AGENTS.md # 后端专用指令
  │       └── ...
  └── ...
  

  AIが/packages/frontendディレクトリにある場合はAGENTS.mdという指示がある。

ステップ4：継続的な更新

AGENTS.mdこれは動的な「生きたドキュメント」として扱われるべきである。プロジェクトのビルド・プロセス、テスト・コマンド、コーディング仕様が変更されたら、AIインテリジェンスが常に最も正確な指示を得られるように、このドキュメントを同期して更新することを忘れないこと。

アプリケーションシナリオ

1. 新プロジェクト始動とAIとのコラボレーション
   新しいプロジェクトを開始する際、最初からAGENTS.mdドキュメント。このファイルでは、プロジェクトのテクノロジー・スタック、環境構築コマンド、コード・スタイル、テスト・プロセスを定義することができる。こうすることで、プロジェクトに関与する後続のAIプログラミング・インテリジェンスは、プロジェクトの仕様を即座に「読んで理解」し、コーディング作業を直接開始することができ、初期コード・ベースの標準化と一貫性が保証される。
2. 大規模な単一コードベース（Monorepo）のメンテナンス
   複数のフロントエンド・アプリケーション、バックエンド・サービス、共有ライブラリを含む大規模なコードベースでは、モジュールごとにビルドやテストのコマンドが異なることがよくある。排他的なAGENTS.mdこのファイルは、AIインテリジェンスに、特定のモジュールを修正する際に実行すべき特定のコマンドに関する正確な文脈ガイダンスを提供し、混乱やエラーを回避することができる。
3. コードのリファクタリングとマイグレーションの自動化
   フレームワークのバージョンアップや非推奨ライブラリの置き換えなど、大規模なコード・リファクタリングが必要な場合、詳細な手順や注意すべきルールをAGENTS.mdAIインテリジェンスは、この「行動マニュアル」に基づいてコードベース全体を体系的に修正し、指定されたテストコマンドを実行して各ステップの正しさを検証できるため、リファクタリングの効率が大幅に向上する。

品質保証

1. AGENTS.md 文書に必須項目はありますか？
   そうだ。AGENTS.md 標準的なMarkdown形式が使用され、非常に柔軟性がある。どんな見出しや内容でも使うことができ、AIインテリジェンスはあなたが提供したテキストを解析し、その指示に従います。
2. ユーザーのチャットプロンプトが AGENTS.md の指示はどうなるのか？
   ユーザーの明示的なチャット・プロンプト（プロンプト）が最優先され、ファイル内のすべての指示に優先する。ユーザーからの直接の指示がない場合、AIはAGENTS.mdルールに従います。ネストされたファイルの場合、現在編集中のファイルに最も近いものAGENTS.md遺言書の指示が有効となる。
3. AIインテリジェンスが自動的に実行する AGENTS.md に記載されているコマンドをテストしますか？
   AIインテリジェンスは、タスクを完了し、失敗したテストの結果に基づいてコードを修正する前に、関連する手続き上のチェック（単体テスト、型チェックなど）を実行しようとする。
4. AGENTS.md ファイルは作成後に変更できますか？
   もちろんです。あなたはAGENTS.md動的に更新される "生きた文書 "と考えてほしい。プロジェクトが進展するにつれて、ドキュメントは更新され、プロジェクトの現状と仕様を正確に反映するようになる。