宣言型エージェント定義 — Claude Code 2.1.168 からの移植

Claude Code の宣言型エージェント（markdown + YAML frontmatter）スキーマを qwen-code に移植するための内部設計ドキュメント。issue #4821  に対応し、issue #4721  / PR #4732  のワークフロー移植と連携する。

実装ステータス（垂直スライス）

PR #4842  により、当時エンドツーエンドのランタイムパスを持つフィールドが出荷された。その後、PR #4870  でブロックスカラをサポートするために YAML パーサーが置き換えられた。このフォローアップ PR は両者を基盤としている。YAML stringifier を置き換え（PR #4870 では手書きのままだった — docs/design/yaml-parser-replacement.md を参照）、SubagentConfig に mcpServers と hooks を公開し、サブエージェント実行時にエージェントごとの MCP サーバーとフックが実際に発火するようにランタイムに接続する。

以下の完全なリバースエンジニアリングの記録は、延期されたフィールドの設計リファレンスとして保持されている。スキーマ定数、DL7/Ig5 のセマンティクス、エラーメッセージ、およびワークフローとの連携マトリックスは、その作業において依然として不可欠である。

フェーズ 0 — 境界

フェーズ 1 — リバースエンジニアリングの知見

ここでのすべての主張は、claude.strings に対して独立に grep され、反証可能な検証を生き残った。信頼度レベル: C = Confirmed（直接バイナリ証拠あり）、I = Inferred（複数の確認済み事実から合成）、O = Open（まだ不確実）。

スキーマ — 15 のフィールド、反証と再確認

エージェントの frontmatter シャドウスキーマは Ig5 であり、tengu_frontmatter_shadow_unknown_key / _mismatch テレメトリのために ug5.agent 内で使用される。本番ローダーは DL7（parseAgentFromMarkdown）であり、カスタムエラーメッセージを使用して手書きのフィールドごとのバリデーションを実行する。別の JSON 形式スキーマ JL7（fL7 / parseAgentFromJson で使用）はより厳密だが、異なるコードパスである（--agents <json> と settings.agents で使用）。

反証を生き残った微妙な観察: skills は「オプション」であるにもかかわらず、DL7 の出力句は ...I !== void 0 && {skills: I} であり、ml(undefined) は []（非 undefined）を返すため、frontmatter がフィールドを省略している場合でも、最終的に出力されるレコードには skills: [] が含まれる。これは下流の等価性チェックに影響を与えるため、qwen-code への移植時のフラグとする。

15 個を超える可能性のある追加フィールド

ローダー — ファイルと関数のマップ

Gm("agents", _) は 3 つの baseDirs（policySettings、userSettings、projectSettings）を読み取り、それぞれレコードにタグを付けます。その後、inode によって重複を排除します（シンボリックリンク/ハードリンクからの同一 inode の重複を削除し、Skipping duplicate file '<path>' from <source> (same inode already loaded from <firstSource>) をログに出力します）。 テレメトリ: managedFilesFound、userFilesFound、projectFilesFound、projectDirsSearched、subdir を含む tengu_dir_search。

解決順序 — 確定的な優先順位

関数 DS() は入力を source でフィルタリングし、次に固定順の配列を agentType をキーとする Map に反復処理します。Map.set は上書きするため、最後に処理されたバケットが優先されます:

[built-in, plugin, userSettings, projectSettings, flagSettings, policySettings]
                                                                       ^
                                                                  最高優先順位

競合はサイレントに解決されます。tengu_plugin_name_collision テレメトリイベントが発生するのみで（winner_source: T.at(-1)）、ユーザーに「X が組み込みをオーバーライドしました」といった警告は表示されません。（strings:308742 hMH。）

微妙な動作: iV_() は cwd から上に向かって最も内側から先に走査しますが、Map.set は最後が優先されるため、projectSettings 内では外側のツリーの .claude/agents/ が内側のツリーより優先されます。これは驚くべき動作です — 未解決の質問としてフラグを立てておきます。

Frontmatter パーサー

配線 — エージェントツール + CLI フラグ

ライフサイクル — コールドロード + ホットリロード

未解決の質問 (Phase 1)

Phase 2 — qwen-code の実装計画

現状 — 概要

qwen-code にはすでに大規模なサブエージェントインフラが搭載されています。 SubagentManager (packages/core/src/subagents/subagent-manager.ts) は、 カスタム YAML パーサー (packages/core/src/utils/yaml-parser.ts — gray-matter / yaml への依存なし、package.json で確認済み) を使用して、.qwen/agents/ (プロジェクト) および ~/.qwen/agents/ (ユーザー) 内の markdown+YAML frontmatter ファイルに対する CRUD を実装しています。 SubagentConfig (packages/core/src/subagents/types.ts:41-122) にはすでに name、 description、tools、disallowedTools、approvalMode、systemPrompt、 model、runConfig、color、background が含まれています。SubagentLevel はすでに 5 つのスコープ (session, project, user, extension, builtin) をサポートしており、優先順位は session > project > user > extension > builtin です (subagent-manager.ts:189-220)。Agent ツール (packages/core/src/tools/agent/agent.ts) は subagent_type を宣言し、 subagentManager.changeListener を介してスキーマ列挙型を動的に更新します。 convertClaudeAgentConfig() ブリッジは、ツール名のマッピングと permissionMode → approvalMode のマッピングを備えて、 packages/core/src/extension/claude-converter.ts:162-220 にすでに存在します。ギャップは以下の通りです: (a) スキーマに #4821 の 8 つのフィールド (effort、ファーストクラスとしての permissionMode、mcpServers、hooks、トップレベルとしての maxTurns、 skills、initialPrompt、memory、isolation) が欠けていること。(b) --agent <name> CLI フラグがないこと。(c) chokidar スタイルのホットリロードがないこと（extension スタイルの無効化は存在するが、ファイルシステムエージェント用ではない）。(d) maxTurns が現在 runConfig.max_turns の下にネストされていること — #2409 に従ってトップレベルに昇格させる必要がある。

アーキテクチャの決定事項

D1. frontmatter に既存の yaml-parser を再利用する

決定: packages/core/src/utils/yaml-parser.ts を再利用する（すでに SubagentManager.parseSubagentContent と skill ローダーで使用されている）。 理由: Claude Code の lz は、skills + commands + agents に使用されるのと同じ共有パーサーであり、 qwen-code はすでにそのパターンをミラーリングしている。gray-matter や js-yaml を追加するのは 不要な変更である。既存のパーサーは --- … --- の分割を処理し、不正な入力に対しては沈黙する （lz の warn-and-return-empty の姿勢と一致する）。

D2. 解決 / 優先順位

決定: `session > project (.qwen/agents/) > user (~/.qwen/agents/)

extension > builtinを使用します。つまり、**既存の qwen-code の SubagentLevel の順序を維持し、v1 では Claude Code のflagSettings/policySettings バケットを ミラーリングしません**。 **理由:** Claude Code の policySettings（管理ディレクトリ）はエンタープライズデプロイのストーリーであり、 qwen-code にはない。フラグで注入されたエージェント（—agents ）はパワーユーザー向け機能であり、 P4 で実装できる。既存の 5 段階の qwen-code の優先順位は、#4821 が重視するケース （プロジェクトがユーザーをオーバーライドし、ユーザーがビルトインをオーバーライドする）をすでにカバーしている。 extension` レベルは、ユーザーと > ビルトインの間にきれいに収まる。

D3. バリデーション — 既存の SubagentValidator を維持する

決定: SubagentValidator (packages/core/src/subagents/) を拡張して、8 つの新しいフィールドを バリデーションします。skillManager のパイプラインがすでに使用していない限り、 zod を導入しません。既存のバリデーターがハンドロールされている場合は、 ハンドロールのままにします。 理由: Claude Code の Ig5 はシャドウのみであり、ランタイムバリデーションはハンドロールされた DL7 である。そのパターンに合わせることで、別の依存関係を持ち込まずに、エラーメッセージを 読みやすく保つことができる（例: Agent file <path> has invalid permissionMode '<x>'. Valid options: …）。 skillManager がすでに zod を使用している場合は、一貫性のためにその選択に従う — P1 準備で skill コードを読んで TBD（To Be Determined）。

D4. ホットリロード — 延期。コールドロード + 明示的なリロードに依存する

決定: v1 には chokidar watcher を搭載しません。キャッシュ無効化フックはすでに存在します （subagentManager には changeListener と明示的な CRUD 駆動の更新がある）。 プロジェクトレベルのリロードはセッション開始時に発生し、セッション内の /agents UI を介した編集は 無効化されます。ユーザーの需要があれば、/reload-agents（または /reload-plugins に乗っかる） スラッシュコマンドを P4 で実装できます。 理由: FS watcher によるホットリロードはコストが高い（chokidar はアダプティブスケジューリングを伴う ポーリングループを追加する — Claude Code の実装だけで約 150 行の管理コードがある）。 起動時のコールドロードは v1 には十分であり、現在の SubagentManager の配線方法と一致する。 P4 への道を開く。

D5. --agent <name> CLI フラグの組み込み — v1 のスコープ内

決定: packages/cli/src/config/config.ts の CliArgs に --agent <name> を追加します。 動作: 解決されたレジストリに対してルックアップし、エージェントをメインスレッドのエージェントとして設定し、 名前が解決されない場合は明確なエラーをスローします。Claude Code のセマンティクスに一致させます （エージェントが appendSystemPrompt: true を持たない限り、デフォルトのシステムプロンプトを置き換える）。 CLAUDE_CODE_AGENT 環境変数による間接参照は使用しません — qwen-code の Config オブジェクトが 直接保持できます。 理由: これは #4821 のユーザー向けハンドルです — これがないと、宣言型エージェントは Agent ツールの subagent_type パラメータ経由でのみアクセス可能となり、「デフォルトのエージェントを設定する」という ユースケースには間接的すぎます。--agents <json>（複数形）は P4 に先送りできます。

D6. Workflow.agentType の調整 — インターフェース契約

決定: PR #4732 の createProductionDispatch がマージされたときに呼び出せる、 安定したリゾルバーインターフェースを公開します。具体的には:

ツール名の正規化: ToolNames.SEND_MESSAGE と ToolNames.EXIT_PLAN_MODE を使用します（PR #4732 の差分で検証済み）。これらはマージ後に packages/core/src/agents/runtime/workflow-orchestrator.ts から名前付き定数としてエクスポートされます。宣言的エージェントの移植自体はこれらをインポートする必要はありません。これらはワークフローのフロアであり、ワークフローのディスパッチサイトで適用されるためです。

モジュール構成

D7. permissionMode と approvalMode — 置き換えではなくブリッジ

決定: フロントマターで permissionMode（Claude 互換）と既存の approvalMode（qwen 互換）の両方を受け入れます。パース時に permissionMode が設定されている場合、claude-converter.ts:195-208 の既存テーブル（default → default, plan → plan, acceptEdits → auto-edit, dontAsk → default, bypassPermissions → yolo）を使用して approvalMode にマッピングします。両方が存在する場合は approvalMode が優先され（qwen-code により特化しているため）、両方が設定されたことを示す tengu_frontmatter_shadow_* 形式のテレメトリエベントを発行します。 理由: approvalMode を使用する既存の .qwen/agents/*.md との後方互換性を維持しつつ、Claude Code の permissionMode をそのまま受け入れることで、ユーザーは Claude Code のエージェントファイルをそのまま変更せずにドロップインできます。

スキーママッピングテーブル

TDD テスト計画

フェーズ分けされた PR 計画

各 PR のターゲットは差分 ≤ 800 LOC（テストを除く）。P1 が最大で、バリデーターとテストで約 600 LOC。

フェーズ 3 — ワークフロー移植との連携マトリクス (#4721 / PR #4732)

フェーズ4 — リスクと未解決の質問

リスク

未解決の質問 — 提案される解決策

調整アクションアイテム