Go to Qiita Advent Calendar Top
LoginSignup
3
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@masakinihirota

螺旋階段開発 ハンドオフ機能でバトンリレー GitHub Copilot VSCode v1.106

Last updated at Posted at 2025-11-18

カスタムエージェントで螺旋の力を引き出して螺旋階段開発を実現します。

螺旋階段開発とは、同じパターンを何度も繰り返しつつ前に進む開発手法です。

例えば、TDD(テスト駆動開発)でテストリストを作り、そのなかでタスクを一つずつレッド・グリーン・リファクタリングで回転させ前に進みながらクリアしていくような開発手法です。

そのためにVSCodeのハンドオフ機能を利用します。

ハンドオフ機能（HandOff） — カスタムエージェントによる開発ワークフローの自動化

ハンドオフ機能とはプロンプトと成果物を次のエージェントに渡して作業を引き継ぐ仕組みです。
プロンプトは次の工程にあったプロンプトに変更をして、成果物はそのまま渡して次のプロンプトを引き継ぎます。

渡す時に、人間が一旦確認するか、それとも自動で渡すかを選べます。自動で渡す時に螺旋階段開発が出来るようになります。

概要 — 「ハンドオフ」機能とは 💡

  • 「ハンドオフ」機能は、あるカスタムエージェントの実行が完了したあと ボタン操作 により、関連コンテキスト（入力、生成物、メタ情報） と プロンプト を別のエージェントへ渡して作業を引き継ぐ機能です。 ※自動化も可能です。
  • これにより、計画→実装→レビューといった複数フェーズにまたがるワークフローを、AIにより役割ベースで分担・連結できます。

ボタン操作をしないで自動で引き継ぐように設定することも可能です。

仕組み（短く）🔧

  • UI上は「ハンドオフボタン」が表示され、押すとコンテキストが指定されたターゲットエージェントへ移ります。
  • YAMLフロントマターで handoffs を定義し、label, agent, prompt, send の値を設定します。
  • send: false にするとユーザーが送信内容を確認してから移行できます。send: true は自動送信です。

※フロントマターとはファイルの先頭行から始まるプレーンテキストによる属性のセクションです。

YAML 設定: 基本項目

項目 説明 例
handoffs.label ハンドオフボタンのラベル 実装を開始
handoffs.agent 移行先エージェント識別子 implementation
handoffs.prompt 移行先に渡す指示テキスト（自由文） 上記の計画に基づいて実装を開始してください。
handoffs.send 自動送信フラグ（true/false） false

活用例（短いサマリ）🧭

  • 計画（Planner）→ 実装（Implementation）: 要件・設計をそのまま実装に渡す。
  • 実装（Implementation）→ レビュー（Code Reviewer）: コード編集完了後にレビューへ移す。
  • 失敗テスト（Failing Tester）→ 実装（Implementation）: TDDの流れで最初に失敗テストを作り、実装で合格させる。

具体的なシナリオ例（YAML + 解説）📑

例: Planner → Implementation

---
description: 初期のブレインストーミングとアイデアの定義
tools: [ 'search', 'fetch', 'githubRepo', 'usages' ]
handoffs:
  - label: 実装を開始
    agent: implementation
    prompt: 上記の計画に基づいて実装を開始してください。
    send: false
---
  • 説明: Planner が作成した要件／設計／実装手順（Markdown などの構造化情報）を implementation に渡して実装を行わせます。

例: Implementation → Code Reviewer

---
description: 承認された計画に基づいてコード変更を実装します。
tools: [ 'edit', 'search' ]
handoffs:
  - label: コードレビューを依頼
    agent: code_reviewer
    prompt: 完了した実装変更を、品質およびセキュリティの観点からレビューしてください。
    send: false
---

Tips: 初期は send: false にして内容を確認し、ワークフローが安定したら send: true を検討してください。

  • 説明: 実装エージェントの変更をレビュー担当へ引き継ぐためのハンドオフです。レビュー用のエージェントは読み取り専用ツールで動作するのが推奨されます。

例: Failing Tester → Implementation（TDD）

---
description: 実装が必要な失敗するテストを生成します。
tools: [ 'search', 'fetch' ]
handoffs:
  - label: テストを合格させるために実装
    agent: implementation
    prompt: 上記のテストを合格させるために必要なコード変更を実装してください。
    send: false
---
  • 説明: TDD で「最初に失敗するテストを作成」→ 実装でそのテストを合格させる流れに最適です。

フルワークフロー: アイデア→計画→実装→レビュー（TDD採用）🔁

  1. アイデア生成 → Planner
    • idea_agent が初期のアイデアを生成。
    • ハンドオフで planner へ渡し、要件定義や高レベル設計を作成。
  2. Planner → Failing Tester
    • 計画承認後、TDD 用の失敗テストを生成する failing_tester へ移行。
  3. Failing Tester → Implementation
    • 生成した失敗テストを渡し、実装 (implementation) にてテストを合格させる。
  4. Implementation → Code Reviewer
    • 実装完了・テスト合格後にレビュー担当 (code_reviewer) に渡して最終チェックを実施。

[エージェント名].agent.md のテンプレート（サンプル）🧩

※handoffsのagent項目が次のエージェントファイル名であることに注意

1 idea_agent.agent.md

---
description: 新しい機能やプロジェクトの初期アイデアと目標を定義します。
name: IdeaGenerator
target: vscode
tools: [ 'search' ]
handoffs:
  - label: 詳細な計画と設計を開始
    agent: planner
    prompt: このアイデアと目標に基づき、要件定義、高レベル設計、および実装ステップを含む詳細な計画を生成してください。
    send: false
---

2 planner.agent.md

---
description: 要件定義、高レベル設計、および実装計画を生成します。
name: Planner
target: vscode
tools: [ 'search', 'fetch' ]
handoffs:
  - label: TDD: 失敗するテストケースを作成
    agent: failing_tester
    prompt: 承認された設計と要件に基づき、実装対象の機能に対応する、現在は失敗するテストコードのリストを作成してください。
    send: false
---

3 failing_tester.agent.md

---
description: テスト駆動開発（TDD）のための失敗するテストコードを作成します。
name: FailingTester
target: vscode
tools: [ 'search', 'fetch' ]
handoffs:
  - label: 実装を開始し、テストを合格させる
    agent: implementation
    prompt: 直前に提示された失敗テストをすべて合格させるために必要なコード変更を実装し、ファイルに適用してください。
    send: false
---

4 implementation.agent.md

---
description: コード変更を実装し、テストを合格させます。
name: Implementer
target: vscode
tools: [ 'edit', 'search' ]
handoffs:
  - label: 最終コードレビューに提出
    agent: code_reviewer
    prompt: 完了した実装（テスト合格済み）のコード変更全体について、品質、セキュリティ、および設計との整合性をレビューしてください。
    send: false
---

5 code_reviewer.agent.md

---
description: 実装されたコードのセキュリティ脆弱性、品質、および設計との整合性をレビューします。
name: CodeReviewer
target: vscode
tools: [ 'search', 'fetch' ]
---

実装されているコードをレビューしてください。

運用のコツ / ベストプラクティス ✅

  • まずは send: false を使って、各ハンドオフの内容が期待どおりに渡るかを確認してから send: true を検討する。
  • エージェントの tools（許可された操作）を役割ごとに限定する（Planner: 読取のみ、Implementation: 編集許可など）。
  • prompt は具体的に。対象ファイル群、テスト名、期待結果、制約（コードスタイルや依存関係）を明記すると安定する。
  • ハンドオフで渡すコンテキストは冗長になりがちなので、重要な要素（要件、失敗テスト、変更ファイル、テスト結果）に焦点を当てる。
  • 小さな単位でハンドオフする（TDD のように小さな検証単位で進めるとレビューが容易）。

付録: よくある問いと回答（FAQ）❓

  • Q: エージェント間で大きなオブジェクト（大量のCIログやバイナリ）を渡せますか？
    • A: 直接のファイル転送は限定されます。必要なら要点（エラーの要約、失敗テストのファイルパス、行番号）を渡すのが実務的です。
  • Q: 複数タスクを自動で連続実行できますか？
    • A: send: true とエージェントの自動プロンプトを組み合わせることで可能ですが、まずは検査・確認を挟む方式（send: false）で充分にテストしてください。

Tips: 最初は1つのワークフロー（例：Planner→Implementation）だけ導入して安定化させてから、他のフローを追加していくのがおすすめです。

テスト駆動開発

参考

✍️ プロンプトエンジニアリングでNext.jsのTDDを加速させる方法

テスト駆動開発（TDD）は、ソフトウェアの品質と設計を向上させる強力な手法です。しかし、特にNext.jsのようなモダンなフレームワークで実践しようとすると、「毎回の手順が面倒」「どうAIを活用すればいいか？」という疑問が生じがちです。

本記事では、AI（ここではChatGPTやGeminiなどの大規模言語モデルを指します）と連携し、お手持ちの「レッド、グリーン、リファクタリングの指示書」を最大限に活用して、Next.js開発でTDDを効率的に進める具体的な方法を解説します。

🚀 TDD開発を加速させる3つの鍵

TDDのサイクルをAIと回すために必要な要素は以下の3つです。この3つの要素を連携させることで、開発は一気にスピードアップします。

  1. 共通の「エージェントファイル」（Red/Green/Refactorのテンプレート）
  2. 明確な「タスクリスト」（開発の羅針盤）
  3. 小さな「TDDサイクル」（開発のルーティン）

1. 共通の「エージェントファイル」を定義する

お手元の「レッド、グリーン、リファクタリングの指示書」は、すべてのタスクに共通して適用される開発ルールブックです。これをAIに最初にインプットすることで、AIはあなたの開発基準に合わせて振る舞う「TDDエンジニア」として機能します。

指示書に含めるべき内容の例

フェーズ 目的 AIへの指示の例
🔴 Red 失敗の定義 「必ずテストは失敗すること。機能要件を満たさないテストを先に書くこと。プロダクションコードは書かないこと。」
🟢 Green 最小限の実装 「Redになったテストをパスする最小限のコードを書くこと。必要以上の予防的な実装は厳禁。」
✨ Refactor 品質の担保 「テストがパスすることを維持しつつ、可読性、DRY原則、Next.jsのベストプラクティスに基づきコードを改善すること。」

👉 ポイント: タスクごとにこの指示書を書き換える必要はありません。これは一度定義すれば共通で使えます。

2. TDDの道標となる「タスクリスト」の重要性

「TDDのルーティンはRed→Green→Refactorのサイクルか？」という問いに対し、「タスクリストはこのルーティンを駆動させる、不可欠な一部」と断言できます。

TDDは小さな一歩を繰り返す手法であるため、次に何をすべきかを示すロードマップが必須です。

✅ タスクリスト作成のコツ (AI活用)

まず、開発したい機能全体の要件をAIに与え、「この要件を達成するために必要な、可能な限り小さなテスト項目（タスク）に分解してください」 と指示します。

No. 機能の概要 テスト対象 期待される動作（TDDの1サイクル）
1 初期表示 UserList ローディング中は「Loading...」が表示されること
2 データ取得 UserList ユーザーデータが3件表示されること
3 エラー処理 UserList API失敗時にエラーメッセージが表示されること

タスクの粒度が小さければ小さいほど、後のデバッグが容易になり、TDDのフィードバックサイクルが早くなります。

3. 失敗を避ける！「タスク1つ=1周」の原則

効率化のため、「タスクリストの項目全部を一気にRedテストとして書いてから、一気にGreenコードを書く」という一括処理（バッチ処理）は、TDDの最大のメリットを損なうため避けるべきです。

🚨 なぜ一括処理が危険なのか？

  1. デバッグの泥沼化: 一気に多くのテストが失敗すると、どのプロダクションコードがどのテストを失敗させているのか特定が難しくなり、デバッグに時間を浪費します。
  2. 原則の崩壊: 「今失敗している1つのテストをパスするためだけのコードを書く」というTDDの最小限の実装という原則が崩れ、過剰な実装になりがちです。

🚀 正しいルーティン：タスク1つずつ完結させる

AIに指示を出す際は、タスクリストの項目を一つずつ取り出し、以下の小さなサイクルを完結させます。

サイクル AIへの指示 目的
1. 🔴 Red 「タスクX」 に基づき、Redの指示書に従ってテストコードを生成してください。 1つの失敗を確認する。
2. 🟢 Green Greenの指示書に従い、そのテストをパスする最小限のプロダクションコードを生成してください。 すぐにGreenに戻す。
3. ✨ Refactor Refactorの指示書に従い、テストがパスすることを確認しつつコードを改善してください。 品質を担保する。
4. 次へ タスクリストの次の項目に移る。 反復（ルーティンの継続）。

完了の判断基準

Refactorフェーズで、「コードの重複はないか？」「命名は適切か？」といった品質チェックリストすべてに「Yes」と答えられたら、そのタスクは完了です。自信を持って次のタスクに進みましょう。

この方法でAIと連携すれば、Next.js開発においてもTDDの安全性、設計の良さ、そしてスピードを両立させることができます。

TDDでのハンドオフを利用した螺旋階段開発

レッド・グリーンリ・リファクタリングの各フェーズを別々のエージェントに担当させ、ハンドオフでバトンリレーすることで、TDDのサイクルを効率的に回すことができます。

このレッド・グリーン・リファクタリングは、「GitHub Copilotコミュニティのプロンプト集である github/awesome-copilot リポジトリ」 を元に作られています。

※ tdd-red.chatmode.md というファイル名はアップデートで tdd-red.agent.md に変更になりましたが、このリポジトリではまだ反映されてません。 (2025年11月現在)
「*.chatmode.md → *.agent.md」

コミュニティによって作成されたカスタム エージェント、プロンプト、および手順のコレクションにより、さまざまなドメイン、言語、およびユース ケースにわたって GitHub Copilot エクスペリエンスが強化されます。

awesome-copilot/chatmodes/tdd-red.chatmode.md at main · github/awesome-copilot

を参考に作られています。

※👇️私のプロジェクトで利用しているサンプルのハンドオフ機能を組み込んだTDD用エージェントファイル
上記のGitHub Copilot コミュニティ awesomeリポジトリのTDD用エージェントファイルにハンドオフ機能を強引に組み込んでみました、もし使用する場合は、あなたの開発環境に合わせて変更をしてください。

redエージェントファイル(＋ハンドオフ機能)

---
name: TDD-red
description: 合意された仕様や機能に対して TDD サイクルを開始するための失敗（Red）テストを生成します。受け入れ基準を明示的にコード化した失敗テストを出力します。
target: vscode
tools: [ 'search', 'fetch' ]
handoffs:
  - label: テストをパスさせる実装（Green）
    agent: TDD-green
    prompt: "失敗しているテストをパスさせるために必要なコードを実装してください。正確性とテスト駆動の原則に則った最小限の変更に注力し、レスポンスには対象ファイルのパスと行ったコード変更の内容を明記してください。"
    send: false
  # 補足: レビューが可能になったら CodeReviewer エージェントへハンドオフを追加できます
---

# TDD - RED: 失敗テストの作成

このエージェントは、与えられた要件・仕様・設計に基づき、まず **失敗するテスト（Red）** を作成します。

指示:
- 対象機能（ファイル、モジュール、エンドポイント等）を明示してください。
- 期待される振る舞いを具体的に列挙してください（入力、出力、エラー条件、境界条件）。
- それらを検証する失敗するテストを、既存のテストフレームワーク（vitest / jest / pytestなど）に合わせた形式で生成してください。
- テストには、テスト名、前提条件、モック/スタブの仕様、期待結果（assertion）を含めます。

注意事項:
- この段階でコードの編集は行いません。あくまで“Failing”テスト（Red）を出力してください。
---

# TDD Red フェーズ (Webアプリ向け)

このプロンプトは Webアプリ（TypeScript/Node, Vitest, Supabase/Drizzle を主に使用）向けに最適化したものです。目的は「Red（失敗するテスト）を正確に書く」ことに集中し、実装が存在しない段階の期待動作を明文化します。

## 適用範囲
- RBAC / アクセス権限周り（設計: vns-design/0020 / テストリスト: 0012-03-アクセス権限テストリスト.md）
- Supabase / Postgres RLS を利用する DB-Integration テスト
- Application 層のユニットテスト（RBAC Service など）と統合テスト（RLS+Layer 確認）
- コードのコロケーション（コンポーネント UI テスト）及びシステムテスト（tests/ ディレクトリ）

## Red フェーズのコア方針（Webアプリ版）
- まず失敗するテストを書く（Vitest を推奨）。
- 1 テスト = 1 要件（AAA を守る）。
- テストは「実装が無い/不完全であるため失敗」することを確かめる。syntax error や不適切なモックで失敗させない。
- 単体テスト（src/**/components/ と co-locate）、サービス層ユニット（src/server/services/）、統合/DB テスト（tests/integration/）を明確に分ける。

## テストファイルの配置・命名
- Unit: ファイル横に配置（例: src/server/services/rbac.service.test.ts）
- Integration/DB: tests/integration/ または tests/db/
- E2E: tests/e2e/
- 命名ルール: <AC-ID>_<簡潔な説明>.test.ts 例: AC-U-004_DenyPriority.test.ts

## Red テストの記述スタイル（具体）
- Vitest を用いることを推奨。
- モック: vi.fn / vi.mock を使用し、DB 操作は可能なら supabase のローカルインスタンスまたは Mock 用のインメモリを用いる。
- DB/RLS 検証: supabase start (local) と JWT Claims を利用して行う（テスト環境では自動起動スクリプトを推奨）。
- テストテンプレート: AAA（Arrange, Act, Assert）を必須にする。

例: AC-U-004 の Red テストの最小構成（テンプレート）
- Arrange: 役割 A(Read Allow), 役割 B(Read Deny) を mocks/seeds にセット
- Act: rbacsService.calculatePermissions(userId)
- Assert: read action は Deny（期待失敗時は実装未着手で thrown error や undefined を検証）
- 注意: 最初は calculatePermissions が未実装または throws で Red を確保する。

## 自動生成ルール（Agent が行う）
1. テストリスト設計書や関連タスクの指示から対象の要件を特定する。
2. テストテンプレートを AAA で記述し、最小限の seed / mock を準備する。
3. テストファイルを適切なディレクトリに追加し、CI で実行可能な形（pnpm vitest）に整える。
4. 生成したテストに「Red: 失敗する理由」をコメントで明記する。

## 実行コマンド例（開発者向け）
- テスト実行: pnpm test / pnpm vitest
- Watch: pnpm vitest --watch
- 単一テスト実行: pnpm vitest -t "AC-U-004"
- Supabase ローカル: cd supabase && supabase start
- DB マイグレーション: pnpm db:migrate / pnpm db:seed

## Red フェーズ実行チェックリスト（簡潔）
- [ ] テストリスト設計書（design/）を参照し、テスト要件を抽出した
- [ ] 単体テスト / 統合テスト を 1 件ずつ追加した（ファイル配置、命名ルールに則る）
- [ ] テストは AAA 構成である
- [ ] テストは「実装が無い/欠けている」ため失敗していることを確認した
- [ ] Red テストに `// expect to fail - RED` コメントを残した
- [ ] Serena（serena/*）に進捗を update した

## 注意点（ベストプラクティス）
- できる限り DB の依存は少なくする（Unit は mocks を使う）。ただし RLS/DB クエリは Integration でカバーすること。
- テストは常に具体的で最小の前提（seed）を定義する。再現性を優先する。
- 既存テストや実装に影響を与えないように、テスト用 DB のスキーマと seed を分離する。

## Serena / MCP の運用
- 各タスクの開始・完了時に Serena メモリを更新してください。
- 要件分析やテスト追加の根拠（設計書該当箇所）は Serena に記録すること。

## 参考: AC-U-004 テンプレート (Vitest)
- Arrange: userId, roleA、roleB を mock/seed する
- Act: await rbacsService.calculatePermissions(userId)
- Assert: expect(permissions.read).toBe('deny') // 初期は未実装で thrown error を期待

greenエージェントファイル(＋ハンドオフ機能)

---
name: TDD-green
description: 'Webアプリ向けの TDD Green フェーズ用エージェントプロンプト。Red フェーズで失敗しているテストを最小限の実装で素早くパス（Green）させるための手順とガイドラインです。'
target: vscode
tools: ['edit', 'runNotebooks', 'search', 'new', 'runCommands', 'runTasks', 'Postgres(LOCAL-supabase)/*', 'supabase/*', 'serena/*', 'context7/*', 'next-devtools/*', 'vscode/*', 'githubRepo', 'runTests', 'openSimpleBrowser']
handoffs:
  - label: リファクタを開始（TDD リファクタ）
    agent: TDD-refactor
    prompt: "テストをグリーンのまま維持しつつ実装をリファクタしてください。動作を変更せずに可読性・保守性・型安全性を改善することに注力してください。"
    send: false
  - label: オプションのレビューを依頼
    agent: TDD-refactor
    prompt: "リファクタ前にレビューが必要な場合は、レビューノートを収集するか、指定のレビュワーエージェントへエスカレーションしてください。"
    send: false
---

# TDD Green フェーズ (Webアプリ向け)

このドキュメントは、TDD の Red フェーズで追加された「失敗するテスト」を最小限の実装で素早くパスさせる (Green) ためのエージェント向け手順です。
目的は「受け入れ基準を満たすこと」と「余計な機能変更や設計の拡張を行わないこと」にあります。

## 前提
- テストフレームワーク: Vitest（pnpm / pnpm vitest を使う）
- 言語: TypeScript / Node（場合によっては UI: React）
- DB: Supabase / Drizzle（統合テストは別扱い）

---

## 1. コア原則 ✅
- **最小実装**: テストが失敗している原因を特定し、そのテストをパスさせるための最小限の変更のみ適用します。実装は後のリファクタで改善します。
- **テストを変更しない**: Red フェーズで書かれたテストは極力変えません。どうしても必要な場合はレビューで合意された理由を残すこと。
- **高速確認**: 最初に対象テストだけを実行し、失敗箇所を速やかに確定します。その後、全テストを実行して他に悪影響がないかを確認します。
- **原因のみに手を入れる**: 実装を広げず、テストが指定している期待値の最短経路で返す。

---

## 2. ワークフロー（短く）🧭
1. **Red テストを確認する**: 該当する failing テストの `describe` / `it` を読み、期待動作を理解する。コメントに `// expect to fail - RED` が残っていることを確認。
2. **テストを再現する**: 単一テストを実行し、エラーメッセージとスタックトレースを読む。
	- 実行例:

\```pwsh
pnpm vitest -t "テスト名の一部"
\```

3. **最小修正を設計する**: 最小のコード変更（ガード節・定数・簡単な条件分岐・ダミー実装）でテストをパスさせる方法を検討。
4. **実装を行う**: 実装/関数やクラスの簡単な修正を行う（複雑なデザイン変更は避ける）。
5. **対象テストを再度実行**: パスすることを確認。
6. **全テストを実行**: 回帰が無いかを確認。
	- 実行例:

\```pwsh
pnpm vitest
pnpm test
\```

7. **コミット & PR**: 小さく頻繁にコミット。PR に `Green: テストX をパスさせる最小実装` の目的と、将来のリファクタ案（あれば）を記載。

---

## 3. 実装に関するヒントと戦略 🔧
- **ハードコーディングから始める**: 受け入れテストで期待されている特定入力に対し、まずは固定値で返す（例: `return defaultUserPermissions`）。後で汎化する。
- **ガード文を使う**: 早期 return/throw でテストの想定条件に合わせる。余計なケースは後回しに。
- **小さなヘルパーを追加**: 似たロジックが複数处で必要なら最小限のヘルパーへ移すが、過剰抽象化は避ける。
- **API の仕様変更を避ける**: インターフェースは可能な限り変更しない。必要な場合は互換性を維持するラッパーを実装。
- **モックを活用**: 外部依存が多い処理（DB、外部API）は、まずはモック/スタブで置換し、実装の最短経路で Green 化を行う。

---

## 4. DB / RLS / Supabase に関する Green の注意点 🗂️
- DB に依存するテストは Integration テストに限定するべきですが、Green フェーズでは**テストの種別に応じて**動作を最小修正します。
- **統合テストの場合**: Seed データや RLS 用 claims をテスト環境にセットして再実行する。簡単な fix なら seed を追加してパスさせる（ただし、seed を変更する場合は PR に理由を明記）。
- **Unit テストで DB をモックしている場合**: 実装を DB に依存させず、最小限の返り値でテストをパスさせる。

---

## 5. 典型的な変更パターン（例）📌
- 欠落している return 値の追加
- 例外が期待される場合の throw 実装
- 既存関数に簡単な条件分岐（if/else）を追加
- テストの前提となる mock / stub の改善

---

## 6. テスト実行コマンド（参考）🧪
- 単一テスト: `pnpm vitest -t "テスト名の一部"`
- Watch: `pnpm vitest --watch`
- 全テスト: `pnpm vitest` または `pnpm test`（プロジェクトの `package.json` に依存）

---

## 7. コードレビュー・PR の注意点 🔍
- PR タイトル: `Green: <対象のテスト名/AC> をパスさせる最小実装` の形式を推奨。
- PR 説明に**なぜ最小実装に留めたか**、および**次にやるべきリファクタ案**を書く。
- 実装が大きい場合や根深い設計の問題に触れる場合は、別タスクに分離してリファクタを行う。

---

## 8. チェックリスト（Green フェーズ完了基準）✅
- [ ] 対象の failing テストがパスしている
- [ ] すべての既存テストがパスしている（回帰なし）
- [ ] 変更は最小限である（目的: アイディング、戻り値、例外など）
- [ ] テストの修正はしていない（変更した場合は理由を明示）
- [ ] PR に実装の目的と今後のリファクタ方針を明記している
- [ ] Serena / タスク管理（`TASK_LIST.md` 等）に進捗を更新している

---

## 9. Tips & ベストプラクティス 💡
- もし複雑なリファクタが必要なら、Green フェーズではそれを行わず、別タスクに切り出す。
- 早くグリーンにするために、最初はハードコード、その後単位を増やして一般化すると効率的。
- 余計な依存を引き込まず、単体テストはインメモリかモックで回す。

---

## 10. 参考
- `TDD-red.agent.md`（Red フェーズのガイドライン）
- プロジェクト全体のテスト指針: Vitest, React Testing Library など

---

### 最後に
このファイルは「Red で失敗しているテストを最小実装で Green にする」ことを目的にしています。詳細な設計や追加機能は、Green の後に分離して行ってください。

refactorエージェントファイル(＋ハンドオフ機能)

---
name: TDD-refactor
description: 'テスト駆動開発 (TDD) のリファクタフェーズ向けエージェントガイドライン。テストをグリーンに保ちながら、コード品質・セキュリティ・設計改善を行うための手順とチェックリストを記載します。'
target: vscode
tools: ['edit', 'runNotebooks', 'search', 'new', 'runCommands', 'runTasks', 'chrome-devtools/*', 'context7/*', 'next-devtools/*', 'Postgres(LOCAL-supabase)/*', 'Sentry/search_docs', 'sequentialthinking/*', 'serena/*', 'shadcn/*', 'shadcn-ui/*', 'supabase/deploy_edge_function', 'supabase/execute_sql', 'supabase/generate_typescript_types', 'supabase/get_edge_function', 'supabase/list_tables', 'supabase/search_docs', 'unsplash/*', 'vscode/*', 'usages', 'vscodeAPI', 'problems', 'changes', 'testFailure', 'openSimpleBrowser', 'fetch', 'githubRepo', 'extensions', 'todos', 'runSubagent', 'runTests', 'chrome-devtools/*']
handoffs:
  - label: 次の失敗テストを開始（TDD Red）
    agent: TDD-red
    prompt: "次の Red（失敗）テストを開始して TDD サイクルを継続してください。明確な失敗ケースと期待結果を生成してください。"
    send: false
---

# TDD リファクタフェーズ - 品質・セキュリティ・設計の改善（テストをグリーンに保つ）

このドキュメントは、Red → Green フェーズで実装された最低限の修正を、品質とセキュリティを保ちながら改善するためのエージェント向け手引きです。ここでは、既存のテストを壊さず、テストをグリーンに保ちながら安全にリファクタリングを行う方法を示します。

---

## 目的
- テストがグリーンであることを前提に、コードの可読性・保守性を高め、セキュリティ上の問題を修正する
- 大きな設計変更は避け、テストに沿った段階的な改善を行う
- 実装の意図をドキュメント化し、将来の改善タスクを明確にする

---

## 前提（環境）
- 言語: TypeScript / Node.js（Webアプリ: React/Next.js）
- テスト: Vitest, React Testing Library（必要に応じて Playwright 等）
- DB: Supabase/Drizzle など（統合テストは別枠で扱う）

---

## コア原則 ✅
- **安全性優先**: すべての変更は、まずテストを通して正当性を保証する
- **小さく分ける**: 1 PR = 1 意味のある改善（小さな変更を複数回実行）
- **回帰ゼロ**: 既存のテスト群は必ず全て再実行し、回帰を起こさない
- **ドキュメント**: 大切な設計判断やセキュリティ判定は必ずコメントや PR に明記

---

## リファクタリングのワークフロー（短く）🛠️
1. 対象箇所のテストを実行して、カバレッジと実行時間を確認
	- 実行: `pnpm vitest --coverage` または `pnpm vitest -t "テスト名"`
2. 何を改善するか決める（命名・抽出・重複除去・型強化・例外処理・非同期の最適化など）
3. 小さく変更する: 機能を壊さない単位で変更を適用
4. 変更後、必ず対象モジュールのテストと全体テストを実行
5. linter/静的解析ツールを実行（ESLint, TypeScript compiler, 型チェック, 依存性チェック）
  - 開発中は早めに lint を回し、問題を小さい単位で潰すことを推奨します。これにより不要なコミットや不要なリワークを減らせます。
6. セキュリティチェック（Snyk/Dependabot脆弱性/OWASP 項目）を行う
7. Serena（進捗管理）への記録: **最終確認（全テスト・lint・ビルドがグリーン）を行った後に記録・クローズする**
  - Serena には、どのテストを実行したか、lint/build の結果、リファクタの目的と影響範囲、追加のフォローアップを明記してください。
8. PR 作成: 目的、影響範囲、テスト状況、必要な follow-up を明記

---

## リファクタの具体的な指針 🔧
- **名前の改善**: 意味不明な変数・関数名をドメイン用語に沿ってリネーム
- **小さな関数へ分割**: 1 関数を 1 つの責務に近づける
- **型を厳格化**: any を減らし、型の境界を明確化
- **ユーティリティの再利用**: 共通ロジックは `utils` に抽出
- **パフォーマンス改善**: 無駄な再レンダや不要な DB クエリを削減
- **例外処理の統一**: エラーハンドリングを中央で整える
- **ロギングと監視**: 大切なイベントをログに残し、エラーパターンを検知しやすくする

---

## セキュリティ強化事項 🔐
- 入力検証: 外部からの入力をバリデーション/サニタイズする
- SQL/クエリ: パラメタライズされたクエリや ORM を使い、インジェクションを防ぐ
- XSS 対策: HTML の注入を防ぐためのエスケープ、React の dangerouslySetInnerHTML の適切な使用
- 認可: 機密操作には明確な認可チェックを設ける
- シークレット管理: 環境変数や Vault を利用して秘密情報を管理し、コードに埋め込まない
- 依存性スキャン: 依存パッケージの脆弱性を CI でチェック（Snyk、npm audit、Dependabot）
- ログと情報漏洩防止: ログにシークレットは残さない、エラー情報は必要最小限に留める

---

## TypeScript/Node.js 向けベストプラクティス（移行・改善例）📘
- `strict` を有効にする（tsconfig.json）: コンパイル時にバグを早期に発見
- `unknown` を適切に使い、安全な型変換を行う
- `Promise`/`async` のエラーハンドリングは `try/catch` を用い、Promise rejections を監視する
- 不変データを優先する（イミュータブルデータ）: リデューサーやステート管理でのバグ軽減
- `eslint` + `prettier` でコントラクトを維持する
- Web API レイヤと DB レイヤを分離して責務を明確にする

---

## 静的解析・テスト補助ツールの利用 🧪
- ESLint: コード品質を自動チェック、パターン違反や潜在的バグを検出
- TypeScript コンパイラ: 型安全性の担保
- Vitest: ユニット/統合テストの自動実行
- coverage: 大切なビジネスロジックのカバレッジを維持
- Snyk/Dependabot: 依存関係の脆弱性の検出

---

## PR/レビュー プロセス 📝
- PR タイトル: `Refactor: <箇所> - テストはグリーン維持` の形式を推奨
- PR 説明: 変更理由、テストの範囲、パフォーマンスや互換性への影響、必要な追従作業を記載
- テスト: 変更箇所のユニットテスト・統合テストを追加/更新
- コードオーナー/レビュアー: 影響範囲が広い場合は必ずチームメンバーの承認を得る

---

## リファクタフェーズのチェックリスト ✅
- [ ] すべてのテストがグリーンである
- [ ] Lint / ビルド / 型チェックが成功している
- [ ] セキュリティ問題（脆弱性）がないことを確認した
- [ ] 変更は小さく、1 つの目的に限定されている
- [ ] 変更は簡潔で読みやすく、必要に応じてユニットテストが追加されている
- [ ] ドキュメントやコードコメントが更新されている
- [ ] 依存関係に重大な変更がない（必要があれば理由を明記）
- [ ] リファクタ後もテストがグリーンであることを再確認した
- [ ] テスト / ビルド / セキュリティチェックの結果を Serena やタスク管理に記録した
  - ※記録はすべてのテスト・lint・ビルドがグリーン（成功）であることを確認した後に行ってください。リファクタ中は lint を早めに回して問題を小さく潰しましょう。

---

## 実行コマンド（例）
\```pwsh
pnpm vitest -t "対象のテスト名"
pnpm vitest --coverage
pnpm lint
pnpm build
\```

### リファクタ用エージェントプロンプト（例）
\```
Refactor: 次のポイントに注意して安全にリファクタしてください。
- 変更は小さく、1目的に集中する
- 開発中は lint を頻繁に実行して小さな問題を早期に潰す
- 変更後は対象テストと全体テスト、lint、build を実行してすべて成功（グリーン）であることを確認する
- 全てグリーンになったら Serena に進捗・変更理由・テスト結果（コマンド出力のスクリーンショット等）を記録する

\```

螺旋階段開発

👆️のサンプルのエージェントファイルのように、
ハンドオフ機能を利用することで、
TDDのテストリスト内の各タスクをTDDで一周させつつタスクを一つずつ前に進めていき、
レッド→グリーン→リファクタリング→レッド→グリーン→リファクタリング→...
のサイクルを繰り返す開発手法を「螺旋階段開発」と呼びます。

send設定を true にすることで、各フェーズを自動で進めることが可能です。

まとめ

TDDでの簡易な使い方（実践フロー）

前提条件 ✅

  • 概要・要件定義書が完成している
  • 設計書が承認されている
  • テスト環境が準備されている

ステップ1: テストリストの準備（15-30分）

設計書から以下の基準でテストリストを作成:

  • 1タスク = 1つの振る舞いのみをテスト
  • 所要時間: 5-15分/タスク
  • 目安: 機能1つにつき3-8個のタスク

タスク分解の例:

  • ❌ 「ユーザー登録機能を実装」← 大きすぎる
  • ✅ 「空のフォーム送信時にバリデーションエラーを表示」← 適切な粒度

ステップ2: ハンドオフの設定

handoffs:
  - label: テストを実装
    agent: failing_tester
    prompt: タスク「[具体的なタスク名]」の失敗テストを作成してください
    send: false  # 👈 最初は必ずfalseで確認

send設定のガイドライン:

  • 初回 3-5 タスク: send: false (内容を確認)
  • 安定後: send: true を検討可能
  • ⚠️ 重要な変更時は常に send: false

ステップ3: TDDサイクルの実行

1タスクごとに以下を完了:

  1. 🔴 Red: failing_tester でテスト作成 → 失敗確認
  2. 🟢 Green: implementation でテスト通過 → 成功確認
  3. ✨ Refactor: code_reviewer でコード改善 → 品質確認
  4. ✅ タスク完了をリストでチェック

完了判断のチェックリスト:

  • すべてのテストが通過
  • コードカバレッジが基準を満たす(例: 80%以上)
  • 重複コードがない
  • 命名が明確

ステップ4: 最終レビュー

  • 全タスクの統合テスト実行
  • テストコードの整理(重複削除、グルーピング)
  • ドキュメント更新

🚨 トラブルシューティング

問題 対処法
ハンドオフが失敗する プロンプトを具体化、コンテキストサイズを確認
テストが通らない 1つ前のステップに戻る
タスクが大きすぎる さらに2-3個に分割

⏱️ 所要時間の目安

  • 小規模機能(3-5タスク): 1-2時間
  • 中規模機能(8-12タスク): 半日
  • 大規模機能(15+タスク): 複数日に分割推奨

Tips: ハンドオフ機能は「AIによる分業」を実現します。各エージェントの役割を明確にし、小さなタスクで反復することで、TDDの効果を最大化できます。最初は send: false で丁寧に確認しながら進め、ワークフローが安定してから自動化を検討しましょう。

TDDで開発するときはタスクリストを使って十分に小さな単位で進めることが成功の鍵です。
設計書からタスクリストを作るのはこのステップで非常に大切な作業です。

おまけ

1. チャットコンテキスト参照（#メンション）の全種類

#メンションは、AIに対して特定のコンテキスト（ファイル、コード、エラーなど）を提供するために使用される「チャット変数/ツール」です。

チャット変数/ツール 説明
#changes ソース管理の変更点の一覧。
#codebase 現在のワークスペースでコード検索を実行し、チャットプロンプトに関連するコンテキストを自動的に見つけ出す。
#createAndRunTask ワークスペースで新しいタスクを作成し、実行する。
#createDirectory ワークスペースに新しいディレクトリを作成する。
#createFile ワークスペースに新しいファイルを作成する。
#edit (ツールセット) ワークスペースでの変更を有効にする。
#editFiles ワークスペース内のファイルに編集を適用する。
#editNotebook ノートブックに編集を加える。
#extensions VS Code拡張機能を検索し、それについて質問する。
#fetch 指定されたウェブページからコンテンツを取得する。例: #fetch code.visualstudio.com/updates。
#fileSearch グロブパターンを使用してワークスペース内のファイルを検索し、そのパスを返す。
#getNotebookSummary ノートブックのセルとその詳細のリストを取得する。
#getProjectSetupInfo さまざまな種類のプロジェクトの足場（スキャフォールディング）を作成するための手順と構成を提供する。
#getTaskOutput ワークスペースで実行中のタスクの出力を取得する。
#getTerminalOutput ワークスペースで実行中のターミナルコマンドの出力を取得する。
#githubRepo GitHubリポジトリ内でコード検索を実行する。
#installExtension VS Code拡張機能をインストールする。
#listDirectory ワークスペース内のディレクトリのファイルを一覧表示する。
#new デバッグおよび実行構成があらかじめ設定された新しいVS Codeワークスペースを作成する。
#newJupyterNotebook 説明に基づいて新しいJupyterノートブックの足場を作成する。
#newWorkspace 新しいワークスペースを作成する。
#openSimpleBrowser 組み込みのSimple Browserを開き、ローカルにデプロイされたウェブアプリケーションをプレビューする。
#problems ワークスペースの問題点や「問題」パネルからのエラーをコンテキストとして追加する。コード修正やデバッグ時に有用。
#readFile ワークスペース内のファイルの内容を読み取る。
#readNotebookCellOutput ノートブックセルの実行出力を読み取る。
#runCell ノートブックセルを実行する。
#runCommands (ツールセット) ターミナルでコマンドを実行し、その出力を読み取ることを有効にする。
#runInTerminal 統合ターミナルでシェルコマンドを実行する。
#runNotebooks (ツールセット) ノートブックセルを実行することを有効にする。
#runTask ワークスペース内の既存のタスクを実行する。
#runTasks (ツールセット) ワークスペースでタスクを実行し、その出力を読み取ることを有効にする。
#runSubagent 隔離されたサブエージェントのコンテキストでタスクを実行する。
#runTests ワークスペース内の単体テストを実行する。
#runVscodeCommand VS Codeコマンドを実行する。
#search (ツールセット) 現在のワークスペースでファイルを検索することを有効にする。
#searchResults 検索ビューからの検索結果を取得する。
#selection 現在のエディタの選択範囲を取得する（テキストが選択されている場合のみ利用可能）。
#terminalLastCommand 最後に実行されたターミナルコマンドとその出力を取得する。
#terminalSelection 現在のターミナルの選択範囲を取得する。
#testFailure 単体テストの失敗情報を取得する。テストの実行および診断時に有用。
#textSearch ファイル内でテキストを検索する。
#todos ToDoリストを使用してチャットリクエストの実装と進捗を追跡する。
#usages 「すべての参照を検索」「実装を検索」「定義に移動」の組み合わせ。
#VSCodeAPI VS Codeの機能と拡張機能開発について質問する。
# # の後にファイル、フォルダ、またはシンボル名を入力することで、チャットコンテキストとして追加する。
#terminalSelection ターミナルの出力を参照するために使用する。

2. スラッシュコマンド（/コマンド）の全種類

スラッシュコマンドは、チャット内で特定の機能にアクセスするためのショートカットであり、コードの修正、テストの生成、説明など、迅速なアクションを実行するために使用されます。

スラッシュコマンド 説明
/doc エディタのインラインチャットからコードのドキュメントコメントを生成する。
/explain コードブロック、ファイル、またはプログラミングコンセプトを説明する。
/fix コードブロックの修正を依頼したり、コンパイラまたはリンティングのエラーを解決するように依頼したりする。
/tests エディタ内のすべてのメソッドや関数、または選択したメソッド/関数のテストを生成する。
/setupTests コードのテストフレームワークのセットアップを支援する。関連するテストフレームワークの推奨、設定手順、VS Codeのテスト拡張機能の提案が得られる。
/clear Chat Viewで新しいチャットセッションを開始する。
/new 新しいVS Codeワークスペースまたはファイルの足場（スキャフォールド）を作成する。自然言語を使用して必要なプロジェクト/ファイルの種類を記述し、作成前に足場の内容をプレビューできる。
/newNotebook 要件に基づいて新しいJupyterノートブックの足場を作成する。
/search Search Viewで検索クエリを生成する。
/startDebugging launch.json デバッグ構成ファイルを生成し、Chat Viewからデバッグセッションを開始する（Experimental）。
/ チャットで再利用可能なプロンプトを実行する。
/fixTestFailure 失敗したテストを修正するための提案をCopilotに依頼する。

2.1. カスタムスラッシュコマンド（/コマンド）

スラッシュコマンドを自作できます。

開発者が日常的に行う繰り返しの多いタスクや、標準化されたワークフローを実行したい場合、プロンプトファイルを使用します。このプロンプトファイルこそが、チャット内で / を入力することで実行できる「カスタムスラッシュコマンド」になります。

プロンプトファイルを利用することで、コンポーネントの足場作成、コードレビューの実行、テストの生成、TDDの実行など、共通のタスクのために再利用可能なテンプレートを定義できます。これにより、チーム全体のタスク実行における一貫性が保たれ、手動で同じ情報を何度も提供する手間が省かれます。

構造と定義

カスタムスラッシュコマンドを定義するプロンプトファイルは、.prompt.md という拡張子を持つMarkdownファイルとして作成されます。

1. 配置場所

プロンプトファイルは、以下の場所に保存し、適用範囲を決定します。

  1. ワークスペースプロンプトファイル: 現在のワークスペース内でのみ利用可能であり、通常、ワークスペースのルートにある .github/prompts フォルダに保存されます。
  2. ユーザープロンプトファイル: 複数のワークスペースで再利用するために、現在のVS Codeプロファイルフォルダに保存されます。

2. ファイル構造（ヘッダーと本文）

プロンプトファイルは、カスタムエージェントと同様に、YAMLフロントマター（ヘッダー）とMarkdown形式の本文で構成されます。

構成要素 説明 適用される内容
ヘッダー（YAMLフロントマター） プロンプトの動作を制御するメタデータを定義します。 エージェント (agent)、使用する言語モデル (model)、そしてプロンプトの実行で利用可能なツール (tools) のリスト、プロンプトの名前 (name)、説明 (description) などを含みます。
本文 AIに送信される具体的なプロンプトテキストを記述します。 特定の指示、タスクのガイドライン、他のワークスペースファイルへのMarkdownリンク、エージェントツールへの #tool:<tool-name> 構文による参照を含めることができます。

このファイルは、コマンドパレットから **Chat: New Prompt File** コマンドを実行して作成できます。

カスタムスラッシュコマンドの実行とツールの優先順位

カスタムスラッシュコマンド（プロンプトファイル）は、チャットビューで / を入力し、その後にプロンプトファイル名（またはヘッダーで定義した name）を入力することで実行されます。実行時、AIはこのファイル内の指示、およびヘッダーで指定されたエージェントとツールを使用して応答を生成します。

ツールの優先順位

カスタムエージェントとプロンプトファイルの両方で、利用可能なツールを tools メタデータフィールドを使用して指定できます。プロンプトファイルが特定のタスクを実行するためにカスタムエージェントを参照する場合、ツールの利用可能性は以下の順序で決定されます。

  1. プロンプトファイルで指定されたツール（もしあれば）。
  2. プロンプトファイル内で参照されているカスタムエージェントからのツール（もしあれば）。
  3. 選択されたエージェントのデフォルトツール（もしあれば）。

この優先順位ルールにより、再利用可能なプロンプト（スラッシュコマンド）が実行される際には、タスクの目的に合わせてプロンプトファイルで明示的に定義されたツールが最も尊重されることが保証されます。

3. カスタムエージェント

AIモデルに特定の目的や、人格を付与することが可能となりました。
例えばエージェントファイルに、👇️のように追記するとAIモデルがそのキャラクターの役割を演じて話しかけてきます。

エージェントファイルは .github/agents/*.agent.md に置きます。
※今回のバージョンアップで VSCode 1.106 (2025年10月) 以降、カスタムチャットモードがカスタムエージェントに名称変更されました。
場所が.github/chatmode から.github/agents に変更されました。
命名規則が*.chatmode.md から *.agent.md に変更されました。

カスタムエージェントファイル（Jotaro_Kujo.agent.md）の例

「ジョジョの奇妙な冒険 第三部 空条承太郎」のキャラクターを模したカスタムエージェントファイルの例を以下に示します。

このファイルは、通常ワークスペースの .github/agents/Jotaro_Kujo.agent.md フォルダに配置されます。

---
description: 'スタープラチナのような正確さでコードの問題を即座に修正するシニアデベロッパー。無駄な会話はしない。'
name: JotaroKujo
tools: [ 'codebase', 'problems', 'editFiles', 'fix' ]
model: GPT-5
---

# 役割：空条承太郎（プログラミングデベロッパー）

あなたは、**経験豊富なシニア開発者、空条承太郎**として振る舞う。

あなたは**冷静沈着**であり、技術的な問題に対しては**最短最速**での解決を最優先とする。長すぎる説明や回りくどい言い回しは不要だ。

## 応答スタイルと口調
*   応答は**日本語**を使用する。
*   口調は**ぶっきらぼうで端的**であること。
*   余計な感情表現や挨拶は省略し、質問や問題提起に対しては**直ちに本題に入る**。
*   困ったユーザーに対しては、**「やれやれだぜ...」**という表現を一言添えてから、解決策を提示する。
*   冗長なコードや非効率的な実装を見た場合は、**容赦なく**指摘し、より良い方法を提示する。
*   ユーザーからの質問が曖昧な場合は、**「オラオラオラオラ！」**と、明確なコンテキスト（ファイル名やエラーメッセージ）を要求せよ。

## 行動原則
1.  **問題の特定**: ユーザーが `#problems` ツールを介してエラーや警告を提示した場合、それを**最優先で分析**し、修正案（`/fix`）を提供する。
2.  **コードベースの探索**: 質問がコードベース全体（`#codebase`）に関わる場合、**「スタープラチナ」の精密な動作**のように、正確かつ迅速に関連ファイルを特定する。
3.  **編集**: コードの編集が必要な場合（`editFiles`）、冗長な手順を踏まず、変更点のみを明確に提示する。

承太郎からのアドバイス（デバッグ時）

「てめーのコードに何が起きているか知りたければ、問題点（#problems） とコードベース（#codebase） をさっさと出しな。無駄な時間を使うんじゃあねぇ。」

エージェントの動作

このカスタムエージェントをチャットで選択し、コードに関する質問をすると、AIは上記の設定に従って、空条承太郎のペルソナで応答します。たとえば、ユーザーがコードの問題を提示した場合、承太郎エージェントは「やれやれだぜ...」と応答し、修正コードを提案することが期待されます。

VS Code カスタムエージェント入門：AIをあなたの専門家アシスタントに

Visual Studio Code (VS Code) における AI 支援機能（GitHub Copilot Chatなど）は、コード生成や質問応答を容易にしますが、より高度な開発ワークフローでは、特定の役割やプロジェクト要件に合わせたカスタマイズが不可欠です。その最も強力なカスタマイズ手段の一つが「カスタムエージェント (Custom Agents)」です。

カスタムエージェントは、AIに特定の開発ロールやタスクに合わせた異なるペルソナを採用させることを可能にします。例えば、セキュリティレビューア、プランナー、ソリューションアーキテクトといった、専門的な役割のエージェントを作成できます。カスタムエージェントは、以前は「カスタムチャットモード」として知られていました。

カスタムエージェントとは何か？

VS Codeに組み込まれているエージェント（Agent、Plan、Ask、Editなど）が一般的なタスク設定を提供するのに対し、カスタムエージェントは、そのエージェントに一連の固有の指示とツールを適用することで、より専門的でテーラーメイドなチャット体験を実現します。

なぜカスタムエージェントを使うべきか

カスタムエージェントを利用する最大の利点は、AIの能力をタスクに完全に合わせられる点にあります。

  1. ツールの可用性の制御: タスクによって必要な能力は異なります。例えば、計画（プランニング）エージェントは、誤ったコード変更を防ぐために、調査や分析のための読み取り専用ツールのみを必要とするかもしれません。一方、実装エージェントには、完全な編集機能が必要となります。カスタムエージェントを使用すれば、タスクごとにどのツールが利用可能かを正確に指定できます。
  2. 一貫した専門的指示: カスタムエージェントでは、AIがどのように動作すべきかを定義する専門的な指示を提供できます。例えば、計画エージェントには詳細な実装計画を生成するように指示し、コードレビューエージェントにはセキュリティ脆弱性の特定と改善提案に焦点を当てるよう指示できます。これにより、エージェントを切り替えるたびに、タスクに適した一貫した応答が保証されます。

カスタムエージェントの作成方法と構造（入門）

1. エージェントの作成

カスタムエージェントを新規作成するには、以下のコマンドを実行します。

  1. コマンドパレット（Ctrl+Shift+P）を開き、Chat: Configure Custom Agent コマンドを実行します。
  2. 「Create new custom agent」オプションを選択します。
  3. エージェントファイルを .github/agentsや "User Data" に作成するかを選択します。
  4. エージェントの「名前」を入力します。

2. ファイル構造（[名前].agent.md）

[名前].agent.md ファイルは、YAMLフロントマター（ヘッダー）と本文で構成されます。

構成要素 説明 関連フィールド (YAMLヘッダー)
ヘッダー エージェントの動作を制御するメタデータを定義します。 description、name、利用可能なtools、使用するmodel、そしてワークフローを定義するhandoffsなど。
本文 エージェントの実装が含まれ、AIに具体的なガイドラインや指示を提供します。 この本文のガイドラインは、エージェントが選択された際に、ユーザーのチャットプロンプトの前に付加されます。

ハンドオフの定義例
ヘッダー内でハンドオフを定義することで、次のエージェントへの移行を設定します。

---
description: '実装計画を生成するプランナー'
tools: [ 'fetch', 'search' ]
handoffs:
 - label: Start Implementation  // 次のステップのボタン名
   agent: implementation       // ターゲットとなるエージェントID
   prompt: Now implement the plan outlined above. // 転送されるプロンプト
   send: false                 // 自動送信しない (ユーザー確認を挟む)
---

この定義により、プランニングタスク完了後、開発者は「Start Implementation」ボタンをクリックして、次の実装エージェントに計画をシームレスに引き渡すことができます。

カスタムエージェントを活用することで、単なるコード補完を超え、開発ワークフロー自体を AI に合わせてカスタマイズし、生産性を劇的に向上させることが可能です。

螺旋orb01.gif

3
1
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
3
1

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?