mcpField
W
writing-a-good-agents-md

writing-a-good-agents-md

github.com/bseneエージェントワークフロー7133 回インストール1 週間前に更新
リポジトリ

writing-a-good-agents-md について

AGENTS.md と関連するハーネス用ファイルの作成、監査、改善を支援するスキルです。AGENTS.md を実装者向けのオンボーディング文書と位置づけ、簡潔な構成や段階的な情報開示、指示の重複回避を確認できます。

主な機能

  1. 01AGENTS.md の役割を明確化
  2. 02監査チェックリストと長さの目安
  3. 03共有文書とハーネス用アダプターの分離
  4. 04必要に応じたドメイン文書の参照
  5. 05構成と保守に関する問題の整理

活用シーン

  1. 01プロジェクト用 AGENTS.md の作成
  2. 02既存のエージェント向け指示の監査と短縮
  3. 03複数のコーディングツール向け共有指示の整理

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/bsene/skills --skill writing-a-good-agents-md

インストール後、Claude Code で/writing-a-good-agents-mdを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
anti-patterns-and-local-files.md
real-world-structure-patterns.md
six-principles-detailed.md
subagent-context-loading.md

詳細

優れた AGENTS.md の書き方

ユーザーが AGENTS.md と、それに付随する、またはインポートするハーネス固有のファイルを作成、監査、改善できるよう支援します。

基本モデル

AGENTS.md はオンボーディング文書であり、設定の羅列ではありません。次の3つの問いに答えます。

  • WHY — プロジェクトとそのコンポーネントの目的
  • WHAT — 探索者向けの案内ではなく、実装者 が作業するために必要な技術スタックと構成（サブエージェントのコンテキスト読み込みを参照）
  • HOW — エージェントが実行するビルド、テスト、検証コマンド

それ以外は別の場所に置きます。リンターの設定、サブドキュメント、個別の指示、概要資料（README／ADR）は、検索エージェントが自分で見つけます。

監査チェックリスト

チェック項目質問
普遍性すべての指示があらゆるタスクに当てはまりますか？
対象読者すべての行が作成者または評価エージェント向けで、探索者向けではありませんか？
長さ約150行未満ですか？ 理想は50～100行です。
リンターで対応可能かフォーマッターで適用できるコードスタイルの規則が含まれていませんか？
古くなるコード例古くなる可能性のあるコードを貼り付けていませんか？ file:line 参照を使いましょう
指示の数個別のルールが20～30件以上に近づいていませんか？
自動生成/init の出力をそのまま使用していませんか（従来形式または対話形式）？ 間引くのではなく、最初から書き直しましょう
段階的な開示ドメイン別ドキュメントを本文に埋め込まず、参照していますか？
ホットフィックスの蓄積構造を整える代わりに、その場しのぎの回避策を重ねていませんか？
ツール間の重複同じ内容をインポートせずに CLAUDE.md／.cursorrules に貼り付けていませんか？

テンプレート：最小限の AGENTS.md

# Project Name

Brief description of what this project does and why it exists (2-3 sentences).

## Stack & Structure

- **Frontend**: [framework, location]
- **Backend**: [framework, location]
- **Shared packages**: [names and purpose]
- **Key config**: [important files/locations]

## Working on This Project

Build: `<command>`
Test: `<command>`
Typecheck: `<command>`
Lint: `<command>`

Always verify your changes compile and tests pass before considering a task done.

## Boundaries

- Never modify files in `<generated-dir>/`.
- Never commit `.env` or any file containing secrets.

## Git

- [Merge strategy, commit message format, branch naming]

## Reference Docs

Read these files when relevant to your current task — don't read all of them upfront:

| File                         | When to read                |
| ---------------------------- | --------------------------- |
| `agent_docs/architecture.md` | Understanding system design |
| `agent_docs/database.md`     | Working with data models    |
| `agent_docs/testing.md`      | Writing or running tests    |
| `agent_docs/deployment.md`   | Deploying or CI/CD work     |

フロントマターも必須項目もありません。ハーネスを問わず移植できるよう、プレーンな Markdown で作成します。

ハーネスアダプター

AGENTS.md を共有の信頼できる情報源とし、ハーネスのファイルはコピーではなく、薄いアダプターにします。

ハーネスアダプター
Claude Code1行目でインポートする CLAUDE.md：@AGENTS.md
Cursor参照先を示す短い .mdc ルール。Glob の適用範囲を指定するのは Cursor 固有のルールのみ
Gemini CLIGEMINI.md — CLAUDE.md と同じ関係
Codex、Windsurf、Zed、OpenCodeAGENTS.md をネイティブに読み込みます。アダプターは不要です

ツールが1つなら、AGENTS.md だけを書きます。ツールが複数なら、アダプターを使い、コピー＆ペーストは避けます。3つにコピーすれば、必ず内容にずれが生じます。

必要に応じて読む

読むタイミングファイル
原則の詳細、調査の根拠、推論6つの原則の詳細
実際にファイルを読み込むのは誰か（Explore/Plan は読み込まない）、対象読者の区分サブエージェントのコンテキスト読み込み
執筆ワークフロー、アンチパターンの修正、ディレクトリ単位のファイル、乖離アンチパターンとローカルファイル
実際の本番環境の AGENTS ファイルの構成（追加セクション）実際の構成パターン

ベンチマーク

シナリオ：.benchmarks/scenarios/writing-a-good-agents-md-001-consolidate.md · 実行日：2026-08-31 · ログ：.benchmarks/runs/2026-08-31/writing-a-good-agents-md-001-consolidate.json

モデルなしあり差分
claude-opus-4-850%100%+50%
claude-sonnet-4-667%100%+33%
claude-haiku-4-583%100%+17%

合格（実行日：2026-08-31）。すべてのモデルで改善し、統合基準を満たしています。.agents/skills/skill-optimizer/rules/release-gates.md に従ってゲートを適用します。

コメント

Markdown 対応