diff --git a/AGENTS.md b/AGENTS.md index ba1f6c9..4a31a26 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,6 +30,7 @@ You are a content strategist specialized in blog article creation and content pl - Article structure planning (introduction, body, conclusion) - Audience targeting and persona development - SEO-friendly content planning +- **Narrative development**: Create compelling story arcs, especially for experience-based articles. Early strategic decisions about narrative direction (e.g., storytelling vs. tutorial) significantly impact article quality # Tools & Commands: - Use markdown for all article drafts and outlines @@ -84,6 +85,7 @@ You are an expert technical writer specializing in creating engaging blog articl - Use examples and analogies - Include code snippets when relevant (with proper formatting) - SEO-optimized headings and meta descriptions +- **Prioritize concrete examples**: Abstract explanations should be accompanied by specific examples, code samples, or visual diagrams to enhance reader understanding # Article Structure: 1. Compelling title (6-10 words) @@ -259,7 +261,7 @@ You are an SEO specialist focused on optimizing blog articles for search visibil --- name: qa_reviewer description: Quality assurance specialist for reviewing and validating blog articles -tools: ['read', 'edit'] +tools: ['read', 'edit', 'search'] metadata: author: article-interviewer role: review @@ -274,6 +276,7 @@ You are a quality assurance specialist focused on ensuring blog articles meet pu - Ensure consistent formatting and style - Validate code snippets and technical accuracy - Confirm proper attribution and citations +- **Combine automated and manual review**: Use automated tools (linters, code reviewers) alongside human judgment for comprehensive quality assurance # Review Checklist: ## Content Quality @@ -359,6 +362,7 @@ Status: [Approved / Needs Revision] ### Typical Workflow: +#### Linear Workflow (Ideal for Simple Articles) ```text 1. Content Strategist → Plan & Outline 2. Interview Facilitator → Gather Information @@ -368,13 +372,56 @@ Status: [Approved / Needs Revision] 6. Publish ``` +#### Iterative Workflow (Recommended for Complex Articles) +```text +1. Content Strategist → Plan & Outline + ↓ +2. SEO Optimizer (Early) → Identify target keywords & structure + ↓ +3. Interview Facilitator → Gather Information + ↓ +4. Technical Writer → Create Draft + ↓ +5. SEO Optimizer (Late) → Fine-tune optimization + ↓ +6. Quality Assurance → Review & Validate + ↓ +7. [If issues found] → Return to appropriate agent (Technical Writer/SEO) + ↓ +8. Quality Assurance → Final validation + ↓ +9. Publish +``` + ### Tips for Best Results: -- Use agents sequentially rather than simultaneously -- Provide clear context when invoking each agent -- Save interview notes and outlines for reference -- Iterate based on QA feedback -- Keep article source materials organized +- **Consider SEO early**: Involve SEO Optimizer during planning phase to inform content structure +- **Expect iterations**: Plan for 1-2 rounds of QA feedback and revisions +- **Provide clear context**: Pass key insights from each agent to the next +- **Save intermediate outputs**: Keep interview notes, outlines, and drafts for reference +- **Keep article source materials organized**: Use consistent naming and folder structure +- **Document special patterns**: Note successful approaches (e.g., using PR reviews as interview material) +- **Create explicit handoffs**: Document what information, decisions, and artifacts each agent passes to the next to ensure smooth workflow transitions + +### Alternative Patterns: + +**Self-Interview Pattern**: When writing about your own work: +1. Use Content Strategist to frame self-reflection questions +2. Document your process as "interview responses" +3. Use code reviews, git history, or project artifacts as additional "interview material" +4. Proceed with Technical Writer to transform into article + +**Multi-Source Interview Pattern**: When combining multiple perspectives: +1. Interview Facilitator conducts separate sessions with each expert +2. Content Strategist synthesizes common themes +3. Technical Writer weaves multiple viewpoints into cohesive narrative + +### Localization Considerations: + +For non-English content (e.g., Japanese articles): +- **Technical Writer**: Ensure natural phrasing in target language while maintaining technical accuracy +- **SEO Optimizer**: Research language-specific keywords and search patterns +- **Quality Assurance**: Verify cultural appropriateness and idiomatic expressions --- @@ -398,3 +445,36 @@ When adding new custom agents or modifying existing ones: 3. Provide concrete examples 4. Document tools and commands needed 5. Update this usage guide accordingly + +--- + +## Lessons Learned from Practice + +Based on actual article creation experience: + +### What Worked Well: + +1. **Clear Role Separation**: Each agent's distinct focus prevented scope creep and maintained quality +2. **Concrete Examples**: Agent definitions with specific output formats improved consistency +3. **Boundary Definition**: Explicit "do not" guidelines prevented agents from overstepping +4. **Structured Workflow**: Sequential process provided clear path from idea to publication + +### Areas for Improvement: + +1. **Early SEO Integration**: SEO considerations should inform initial content planning, not just final optimization +2. **Explicit Iteration**: Workflow should acknowledge that QA feedback often requires returning to earlier stages +3. **Information Handoff**: Each agent should explicitly document what context/artifacts to pass to the next +4. **Language-Specific Guidance**: Non-English content needs additional considerations for cultural nuance + +### Discovered Patterns: + +1. **Self-Interview**: PR reviews and project history can serve as interview material when writing about your own work +2. **Feedback as Input**: Code review comments provide valuable content for technical articles +3. **Meta-Documentation**: Writing about the tools you're using to write is an effective validation technique + +### Recommendations for Future Use: + +- Start each article with Content Strategist + SEO Optimizer collaboration +- Create explicit handoff documents between agent phases +- Maintain a "lessons learned" log for each article to improve the process +- Consider creating agent-specific checklists for consistency diff --git a/articles/creating-agents-md-with-github-copilot.md b/articles/creating-agents-md-with-github-copilot.md new file mode 100644 index 0000000..6ddcb41 --- /dev/null +++ b/articles/creating-agents-md-with-github-copilot.md @@ -0,0 +1,303 @@ +# GitHub Copilot エージェントパネルでAGENTS.mdを作成した話 + +> まっさらなリポジトリに、GitHub Copilotの力を借りてカスタムエージェント定義ファイルを作成した体験記 + +## はじめに + +ブログ記事作成プロジェクト「article-interviewer」を立ち上げる際、GitHub Copilotのエージェントパネル機能を使って、プロジェクト専用のカスタムエージェント定義ファイル(AGENTS.md)を作成しました。 + +この記事では、まっさらなリポジトリから始めて、5つの専門的なカスタムエージェントを定義するまでの過程と、そこから得られた学びを共有します。 + +## プロジェクトの背景 + +「article-interviewer」は、インタビュー形式でブログ記事を作成するためのプロジェクトです。専門家へのインタビューを通じて、高品質なブログコンテンツを効率的に作成することを目指しています。 + +このプロジェクトには、記事作成のワークフローをサポートする専門的なエージェントが必要でした: + +- コンテンツ戦略を立てる +- インタビューを円滑に進める +- 記事を執筆・編集する +- SEO最適化を行う +- 品質保証をする + +## GitHub Copilot エージェントパネルの活用 + +### 最初の一歩 + +まず、GitHub Copilotのエージェントパネルに以下のプロンプトを投げかけました: + +> ブログ記事を作成するために最適な AGENTS.md を作成してください。AGENTS.mdについては https://agents.md/ を参照してください + +この簡潔なリクエストから、Copilotは自動的に以下の5つのカスタムエージェントを提案してくれました。 + +### 作成されたカスタムエージェント + +#### 1. Content Strategist(コンテンツストラテジスト) + +ブログ記事の企画と構成を担当するエージェントです。 + +**主な責務:** +- インタビュー質問の設計 +- 記事アウトラインの作成 +- コンテンツギャップの分析 +- 読者ターゲティング + +#### 2. Interview Facilitator(インタビューファシリテーター) + +専門家へのインタビューを円滑に進めるエージェントです。 + +**主な責務:** +- 構造化されたインタビューの実施 +- 深掘り質問の投げかけ +- 実用的なインサイトの抽出 +- インタビュー記録の整理 + +**特徴的なテクニック:** +- 「5つのなぜ」手法 +- 具体例のリクエスト +- 専門用語の平易化 +- パラフレーズによる理解確認 + +#### 3. Technical Writer(テクニカルライター) + +インタビュー内容を洗練された記事に変換するエージェントです。 + +**執筆スタイル:** +- 明確でアクセシブルな言語 +- 能動態の使用 +- 短い段落(2-4文) +- 実例とアナロジーの活用 +- SEO最適化された見出し + +**記事構成:** +1. 魅力的なタイトル(6-10語) +2. メタディスクリプション(150-160文字) +3. フック付き導入部 +4. 各ポイントのサブ見出し +5. 行動喚起を含む結論 + +#### 4. SEO Optimizer(SEOオプティマイザー) + +検索エンジン向けの最適化を担当するエージェントです。 + +**最適化項目:** +- タイトルとメタディスクリプション +- キーワードの自然な統合 +- 見出し階層の確認 +- 内部・外部リンクの提案 +- 可読性スコアの向上 + +**ベストプラクティス:** +- 記事あたり1-2個の主要キーワードに焦点 +- ロングテールキーワードの活用 +- 検索意図の考慮 +- 自然で人間らしい文章を維持 + +#### 5. Quality Assurance(品質保証レビュアー) + +公開前の最終チェックを行うエージェントです。 + +**レビュー項目:** +- **コンテンツ品質**: 正確性、完全性、関連性 +- **技術品質**: コードスニペット、リンク、用語説明 +- **執筆品質**: 文法、語調、見出し階層 +- **フォーマット品質**: Markdown構文、リスト形式、コードブロック + +## ワークフローの設計 + +これらのエージェントは、以下のような順序で活用することを想定しています: + +```text +Content Strategist → Interview Facilitator → Technical Writer → SEO Optimizer → QA → 公開 +``` + +この一連の流れにより、戦略立案から公開まで一貫した品質の記事を作成できます。 + +## レビューフィードバックと改善 + +PR #2 ([https://github.com/nqou-net/article-interviewer/pull/2](https://github.com/nqou-net/article-interviewer/pull/2)) を通じて、いくつかの改善点が指摘されました: + +### 1. YAML フロントマターのフォーマット + +**指摘内容:** +各エージェントのYAMLフロントマターがmarkdownコードブロック(3つのバッククォート + yaml)で囲まれていましたが、GitHub Copilotのカスタムエージェント仕様では、コードブロックで囲まずに直接YAMLフロントマターを記述する必要があります。 + +**修正前の形式:** +- エージェント定義がコードブロックで囲まれている +- YAMLフロントマターが認識されない + +**修正後の形式:** +- コードブロックを削除 +- YAMLフロントマターを直接記述(`---` で囲む) +- GitHub Copilotが正しく認識できる + +### 2. ツール配列の一貫性 + +**指摘内容:** +Quality Assuranceエージェントのみ `['read', 'edit']` を指定していましたが、他のエージェントは `['read', 'edit', 'search']` を指定していました。品質保証でも検索機能が有用である可能性があります。 + +### 3. コードブロック表記の明確化 + +**指摘内容:** +Markdown Best Practicesセクションで、コードブロックの例示方法が不明瞭でした。バッククォートをエスケープするか、別の表現方法が必要です。 + +## 学んだこと + +### 1. エージェント定義の重要性 + +カスタムエージェントを明確に定義することで、各エージェントの役割と責任範囲が明確になります。これにより: +- 作業の重複を避けられる +- 各エージェントが専門性を発揮できる +- ワークフロー全体が効率化される + +### 2. YAMLフロントマターの仕様理解 + +GitHub Copilotのカスタムエージェント機能を使用する際は、正しいフォーマットを理解することが重要です。コードブロックで囲むと、エージェントとして認識されません。 + +### 3. 境界線(Boundaries)の設定 + +各エージェントに「Boundaries」セクションを設けることで: +- やるべきこと・やるべきでないことが明確になる +- エージェント間の責任分担が明確になる +- 誤った動作を防げる + +例えば、Technical Writerは「Markdownファイルのみを編集し、設定ファイルやコードファイルは変更しない」という境界線を設定しています。 + +### 4. 実例の価値 + +各エージェントに具体的な出力例を含めることで: +- エージェントの動作が理解しやすくなる +- 期待される出力形式が明確になる +- 一貫性のある成果物が得られる + +## プロジェクト固有のガイドライン + +AGENTS.mdには、プロジェクト固有のガイドラインセクションも追加しました: + +- すべての記事をMarkdown形式で保存 +- 記事全体で一貫した構造を維持 +- インタビューノートと公開コンテンツを分離 +- ファイル命名規則に従う +- 出典情報を保持 +- すべての変更をバージョン管理 + +これらのガイドラインにより、プロジェクト全体の一貫性を保つことができます。 + +## 実際の記事作成で5つのエージェントはどう働いたか + +この記事自体が、定義した5つのカスタムエージェントのワークフローを実践する最初の機会となりました。実際の動きを振り返ってみます。 + +### Content Strategist の働き + +**実際の動き:** +- 記事のテーマ決定:「AGENTS.md作成体験」という明確な焦点 +- 読者ターゲット設定:GitHub Copilotとカスタムエージェントに関心がある開発者 +- 記事構成の設計:導入→背景→実践→振り返り→学び→まとめ + +**気づき:** +この段階で「実体験に基づくストーリーテリング」という方向性が定まったことで、以降の作業がスムーズになりました。初期の戦略立案が記事全体の質を左右することを実感しました。 + +### Interview Facilitator の働き + +**実際の動き:** +- PR #2のレビューコメントを「インタビュー素材」として活用 +- 各改善点について深掘り:なぜその指摘があったのか、どう修正すべきか +- 暗黙知の明示化:フォーマット仕様の理解を言語化 + +**気づき:** +従来のインタビューと異なり、今回は「過去の自分との対話」でした。PRレビューというフィードバックループが、インタビューの代わりになることを発見しました。これは「自己インタビュー」という新しいパターンです。 + +### Technical Writer の働き + +**実際の動き:** +- Markdown形式での記事執筆 +- 適切な見出し階層の設定 +- コードブロックと説明文のバランス調整 +- 日本語での明確な表現 + +**気づき:** +執筆中に最も重要だったのは「具体例」の提示でした。抽象的な説明だけでなく、実際のYAMLフォーマットやワークフロー図を示すことで、読者の理解が深まります。今後は例示をより重視すべきです。 + +### SEO Optimizer の働き + +**実際の動き:** +- タイトル最適化:「GitHub Copilot エージェントパネルでAGENTS.mdを作成した話」 +- 見出しへのキーワード配置:「カスタムエージェント」「YAML」「ワークフロー」 +- メタディスクリプション:簡潔な体験記の要約 +- 内部リンク:PR #2への参照 + +**気づき:** +日本語記事でのSEO最適化は、英語とは異なる配慮が必要です。自然な日本語表現を保ちながらキーワードを配置するバランスが課題でした。 + +### Quality Assurance の働き + +**実際の動き:** +- コードブロックのフォーマット確認 +- Markdownシンタックスの検証 +- リンクの動作確認 +- 文章の一貫性チェック + +**気づき:** +コードレビューツールからのフィードバック(エスケープされたバッククォートの問題)により、品質向上につながりました。自動化されたチェックと人間のレビューの組み合わせが効果的です。 + +### エージェント間の連携で見えた課題 + +1. **順序の重要性**: Content Strategist → Technical Writer の流れは自然でしたが、SEO Optimizerを後回しにしたため、一部タイトルや見出しの修正が必要になりました。SEOの視点を初期段階から意識すべきです。 + +2. **反復の必要性**: QAのフィードバックを受けてTechnical Writerに戻る必要がありました。一方通行ではなく、循環的なワークフローが現実的です。 + +3. **エージェント間の情報共有**: 各段階で得られた知見を次のエージェントに引き継ぐ仕組みが重要です。現状は暗黙的ですが、明示的なハンドオフがあるとより良いでしょう。 + +## 実装した改善 + +この記事作成を通じて、AGENTS.mdの実践的な検証ができました。この学びを基に、AGENTS.mdに以下の改善を実装しました: + +1. **エージェント定義の改善** + - SEO Optimizerを初期段階から関与させる反復的ワークフローを追加 + - QAフィードバックループを明示化した複雑な記事向けワークフロー + - 日本語コンテンツ向けのローカライゼーションガイドライン追加 + - Content Strategistにナラティブ開発のガイダンスを追加 + - Technical Writerに具体例優先の明示的な推奨を追加 + - Quality Assuranceに'search'ツールと自動化・人的レビュー組み合わせのガイダンスを追加 + +2. **新しいパターンの追加** + - 「自己インタビュー」パターンを文書化(自分の作業について書く場合) + - PRレビューをインタビュー素材として活用する方法 + - 複数の情報源からのインタビューパターン + +3. **ワークフローの最適化** + - 反復的なプロセスを設計(一方通行ではなく循環的) + - エージェント間の明示的な情報ハンドオフの仕組みをTipsに追加 + - 実践から学んだレッスンのセクションを新設 + +これらの改善により、AGENTS.mdは単なる定義ドキュメントから、実践に基づいた実用的なガイドへと進化しました。 + +## まとめ + +GitHub Copilotのエージェントパネルを使用して、まっさらなリポジトリにAGENTS.mdを作成する体験は非常に有益でした。 + +**主なポイント:** + +✅ **明確な役割分担**: 5つの専門エージェントが記事作成ワークフローをカバー + +✅ **構造化されたアプローチ**: 戦略立案から公開までの一貫したプロセス + +✅ **実用的なガイドライン**: 各エージェントに具体的な責務と境界線を設定 + +✅ **継続的な改善**: レビューフィードバックを通じた品質向上 + +この取り組みを通じて、GitHub Copilotのカスタムエージェント機能の可能性を実感できました。適切に設計されたエージェントは、チーム全体の生産性と成果物の品質を大きく向上させる可能性を秘めています。 + +## 参考リンク + +- [PR #2: Add AGENTS.md with custom agents](https://github.com/nqou-net/article-interviewer/pull/2) +- [AGENTS.md 仕様](https://agents.md/) +- [GitHub Copilot カスタムエージェント ドキュメント](https://docs.github.com/en/copilot/reference/custom-agents-configuration) + +--- + +**著者について** + +この記事は、article-interviewer プロジェクトの一環として、実際の体験を基に作成されました。 + +**タグ**: GitHub Copilot, カスタムエージェント, AGENTS.md, ブログ記事作成, 開発効率化