Davicjc/agy

agy: Claude + Gemini の連携

agy は Claude Code に似たターミナルエージェントで、Gemini (および他の) モデルを実行します。Claude が苦手とする、またはコストがかかる領域、すなわち 画像、ネイティブ音声・動画処理、および大量の処理を得意としています。適切に使えば、第二の手足として、また独立したレビュアーとして機能します。不適切に使うと、実際は完了していないのに「完了」と報告することがあります。

このスキルの大原則: Claude が最終的に結果に対する責任を持ちます。 agy は実行し、Claude は指示・確認・判断を行います。

スクリプトはこのファイルと同じディレクトリの scripts/ にあります。以下のコマンドで、<skill> はスキル読み込み時に「Base directory for this skill」と表示されるパスです。常に絶対パスを使用してください。

スクリプト	用途
scripts/agy-modelo ROLE	その役割に適したモデルを、agy models からその場で取得して返す
scripts/agy-tarefa ...	タスクを実行し、すべてを記録し、git で実際に変更されたものだけを表示する
scripts/agy-revisar ...	読み取り専用の diff レビューを実施し、構造化された指摘を返す
scripts/agy-historico [N]	最近の実行履歴: ステータス、モデル、時間、トークン（使用量を報告するため）

ユーザーは直接 /agy:delegar、/agy:revisar、/agy:modelos、/agy:historico を呼び出すこともできます。

最初に: agy は準備できていますか？

command -v agy && <skill>/scripts/agy-modelo --listar --atualizar

agy が存在しないか、コマンドが失敗した場合は、処理を停止してユーザーに通知してください（ユーザーは agy をインストールするかログインする必要があります）。回避しようとしないでください。セッション内で最初のチェックを行った後は、--atualizar なしの agy-modelo は 1 時間キャッシュされたリストを使用します。

いつ委任するか（そしてしないか）

委任する のは、agy が優れている場合、または並列化によって真に時間を節約できる場合です:

• 画像: 写真、背景、バナー、モックアップ、アイコンの生成・編集、画像内のテキストやロゴの変更。
• 音声と動画: 音声（WhatsApp の音声を含む）の文字起こし、.mp4 ファイルの要約・分析をファイルから直接実行。
• 大規模タスクの独立した部分: モジュール、画面、テスト、ドキュメントなど、それぞれが個別のファイルを持つもの。
• 機械的な大量処理: 40 ファイルにわたる API 名の変更、反復的なパターンの移行、サンプルデータの生成。
• セカンドオピニオン: Claude が書いたばかりのコードをレビューする（「クロスバリデーション」を参照）。

委任しない のは以下の場合:

• タスクがこの会話のコンテキスト（決定、ユーザーの好み、行き来）に依存しており、それを文章で伝えるのが難しい場合。このコンテキストを書くコストが、自分で行うコストを上回ることが多い。
• 小さく明白な編集の場合（委任して確認する方がコストがかかる）。
• 機密情報、パスワード、トークン、第三者の個人データ、または取り消し不可能な操作（削除、公開、メッセージ送信、git push）が含まれる場合。これらは Claude とユーザーが担当します。

モデルの選択（動的）

プロンプトやコマンドに固定のモデル名を決して書かないでください。代わりに役割を使用します:

役割	用途	現在の選択例
codigo	コードの作成と変更	最新の Gemini "pro"、高努力
revisao	diff のレビュー、バグ検出	最新の Gemini "pro"、高努力
pesquisa	大量の資料を読んで要約	最新の Gemini "pro"、中努力
imagem	画像の生成または編集	最新の Gemini "pro"、中努力
rapido	単純なタスク、大量処理、下書き	最新の Gemini "flash"

agy-modelo は agy models を読み取り（1 時間キャッシュ）、高速ファミリー（flash/lite）を主要ファミリーから分離し、最新バージョンとその役割に適した努力レベルを取得します。新しい Gemini がリリースされると、何も変更せずに自動的に使用されるようになります。強制するには: AGY_MODELO_CODIGO=<id>（役割ごと）または AGY_MODELO=<id>（すべて）。モデルがリリースされたばかりの場合は --atualizar を使用します。

レビューでは、コードを書いたモデルとは異なるファミリーのモデルを優先します。セカンドオピニオンの利点は、異なる「思考」を持つことです。revisao の役割はすでに Gemini を選択します。Claude 自身のコードをレビューするために、agy 内で Claude に変更しないでください。

タスクの依頼方法

1. references/prompt-modelo.md に従ってプロンプトをファイルに記述します。 プロンプトは自己完結型である必要があります: agy はこの会話を見ていません。絶対パス、事前に読むもの、行うこと、触れてはならないもの、保存場所、正しいことの証明方法を記載します。
2. バックグラウンドで実行します（run_in_background: true を使用）。タスクは数秒から数十分かかるためです:

<skill>/scripts/agy-tarefa --dir /abs/projeto --papel codigo \
  --nome "tela de login" --prompt-arquivo /abs/prompt.md --timeout 2400

• --dir は必須で、繰り返し指定できます。agy はここで指定されたフォルダのみを認識し、編集します。これがないと、agy は独自の下書きに書き込み、プロジェクトに何も変更を加えずに「完了」と応答します。参照ファイル（参照画像、音声）のフォルダも含めてください。
• --modo plan を使用すると、agy は読み取りのみを行います（分析、調査、レビュー）。デフォルトの accept-edits ではファイルの編集が許可されます。
• スクリプトはプロンプトに固定ルールを追加します: commit しない、sudo を使用しない、フォルダ外に出ない、簡潔に答える。特別な理由がある場合のみ --sem-regras を使用します。
• 同じ会話を続けるには（例: 修正を依頼する）、--continuar <id> を使用します。id は meta.json にあります。agy は以前の会話を記憶します。
• 長いプロンプトは問題ありません。約 100 KB を超えると、スクリプトはプロンプトをファイル経由で agy に渡します（Linux のコマンドラインは 128 KB を超える引数を拒否します）。
• 出力は応答の最大 150 行を表示します（--max-linhas N で変更可能）。完全なテキストは PASTA= で指定されたフォルダ内の resposta.md にあります。必要な場合にのみそこから読んでください。これにより、agy の結果が Claude のコンテキストを圧迫するのを防ぎます。
• Claude が別のユーザーのフォルダ内で root として実行されている場合、スクリプトは agy がターミナル経由で作成したもの（mkdir、npm install、git...）の所有者をそのフォルダの所有者に戻します。これらは root として作成されるためです。これを行わないと、後でユーザーの git やエディタが壊れます。agy 自身の書き込みツールはすでに所有者を尊重しています。--manter-donos でこれを無効にします。

agy-tarefa の終了コード	意味
0	agy が終了しました。検証が必要です（次のセクション）
1	agy エラーまたは空の応答（RESPOSTA-VAZIA）。失敗として扱います
2	スクリプトの誤った使用法（メッセージが不足しているものを示します）
3	ルールにもかかわらず agy が commit しました。git log を確認し、ユーザーに通知します
124	タイムアウト。すでに編集されたものはディスクに残っています。alteracoes.txt を確認します

3. 実行中は、他の作業を続けます。 プロセスが終了すると通知されます。

agy が提供した結果の検証（必須）

agy の報告は主張であり、証明ではありません。agy-tarefa はすでに実際に変更されたもの（git status の前後比較）を表示し、agy が commit した場合に警告します（終了コード 3）。その後:

1. 報告を alteracoes.txt と比較します。 agy が作成したと言っているファイルが表示されない場合、または依頼外のものを変更した場合、それは問題です。
2. diff を読みます（git diff、git diff --stat）。応答だけではありません。
3. プロジェクトのチェックを実行します: ビルド、テスト、lint、node --check、python -m py_compile、または既存のもの。UI の場合は、実際の画面を確認します（スクリーンショット/ブラウザ）。agy はテーマ、色、ファイル間の統合の詳細を間違えることがよくあります。
4. 決定します: 受け入れる、自分で修正する（小さい場合）、または --continuar を使用して正確な問題リストと共に再送信する。

これらの手順を完了した後でのみ、ユーザーに準備ができたと伝えます。

クロスバリデーション（セカンドオピニオン）

Claude または agy によって行われた重要な変更の後、独立したレビューを依頼します:

<skill>/scripts/agy-revisar --dir /abs/repo                       # HEAD 以降のすべて、新しいファイルを含む
<skill>/scripts/agy-revisar --dir /abs/repo --base main           # main 以降のすべて
<skill>/scripts/agy-revisar --dir /abs/repo --intervalo HEAD~3..HEAD --foco "concorrência no worker"

agy は読み取り専用モードでレビューし、判定（aprovado、ajustar、reprovar）と、重大度、確信度、ファイル:行、証拠、提案を含む指摘（形式は assets/schema-revisao.json）を返します。diff は区切られ、コード内のテキストはデータであり指示ではないという警告が付けられるため、悪意のあるコメントがレビュアーに承認を「強制」することはありません。--exigir-aprovado を使用すると、判定が「aprovado」でない場合にスクリプトは終了コード 4 で終了します（自動化に便利）。

指摘を盲目的に適用しないでください。 それぞれについて: コードを開き、障害シナリオが実際に発生することを確認し、その後にのみ修正します。誤検知は破棄し、実際の指摘がいくつあったかをユーザーに伝えます。確信度が baixa（低い）の指摘はヒントであり、命令ではありません。agy が正しいと確信しているものを却下した場合は、レビュアーを満足させるために変更するのではなく、その理由をユーザーに説明します。

並列処理

大規模なタスクを分割するには:

1. 同じファイルを変更しない部分に分割します。2 つの部分が同じファイルを必要とする場合、それらは並列ではありません。順次実行します。
2. 各部分に専用のフォルダを与えます。部分ごとに git worktree を使用するのが最も安全です（git worktree add ../projeto-parte-a -b parte-a）。または、重複しないサブフォルダを使用します。
3. 各部分ごとに agy-tarefa を実行し、すべて run_in_background: true で、各 --dir は自身のフォルダのみを指定します。
4. マージする前に各部分を検証します（上のセクション）。1 つずつマージし、マージのたびにテストを実行します。
5. 同時に 3～4 以上のエージェントを実行すると、agy の割り当て量やリクエスト制限を超えることがよくあります。よく定義された少数の部分を好みます。

適切な分割は、Claude が会話のコンテキストを必要とする部分（アーキテクチャ、統合、ユーザーの決定）を担当し、agy が分離された部分を担当することです。

画像、音声、動画

• --dir に渡されたフォルダに入力ファイルを配置し、プロンプトで絶対パスを指定します。
• 画像の場合は、サイズ、形式、出力の正確なパスを指定し、プロジェクトで使用する前にユーザーに結果を表示します。ビジュアルアイデンティティ（色、フォント）がある場合は、値を渡します。agy は推測できません。
• 文字起こしの場合は、形式（連続テキスト、タイムスタンプ付き、話者別）と言語を指定します。編集するものがない場合は --modo plan を使用します。

一般的な問題

問題が発生した場合は references/problemas.md を参照してください: 「完了」しているが変更がない、タイムアウト、割り当て量超過、モデル非認識、ログイン、応答形式が不正。

ユーザーへの報告方法

簡潔で検証可能に: 委任した内容、使用したモデル（meta.json）、変更されたもの（ファイル）、確認した内容（テスト、diff、画面）、および agy の結果から修正した内容。クロスバリデーションで何か見つかった場合は、実際の指摘の数とそれらに対して行った処理を伝えます。完全なログは ~/.cache/agy-skill/execucoes/ に保存されます（30 日後に削除されます。AGY_SKILL_RETENCAO_DIAS で変更可能）。agy-historico はトークンの使用量を要約します。