ZCodeのMCP・AGENTS.md・Subagentsを整理：外部ツール連携を安全に始める前に
ZCodeでMCP、AGENTS.md、Subagentsを使う前に、設定場所、Claude Code・Codex CLI・OpenCode・.agentsからのMCP import、安全な権限分離を整理します。
公開 2026.07.05 / 更新 2026.09.26
この記事のポイント
- ZCodeは~/.zcode/AGENTS.mdとworkspace AGENTS.mdを読み、workspace側を現在taskの主要なproject sourceとして扱う
- CLAUDE.mdは継続的に読むのではなく、Claude Code projectのonboarding時の移行元として扱われる
- MCPやSubagentsは能力拡張であり、安全装置ではないため、read-only / writableを分ける
ZCodeのAGENTS.md
| source | path / lookup | 使いどころ | 注意点 |
|---|---|---|---|
| User global | ~/.zcode/AGENTS.md | 全project共通の好み、禁止操作、報告形式 | 個別repoの細かいルールを詰め込みすぎない |
| Workspace | 現在workspaceのAGENTS.md | project固有の構成、build/check、禁止操作 | workspace側が現在taskの主要なproject sourceになる |
| CLAUDE.md | 既存Claude Code projectの移行元 | onboarding時にAGENTS.mdへ移す材料 | 毎回継続的に読むとは書かない |
MCP Serversと外部Agentからのimport
ZCodeのMCP Serversでは、手動追加したconfigured MCP serversとplugin由来のMCP serversを分けて管理します。2026-09-26に確認した公式Docsでは、Claude Code、Codex CLI、OpenCodeに加えて~/.agents/mcp.jsonからも設定をscanしてimportできると案内しています。
- import前にserver名、transport、command、読み書き範囲を見る
- globalとworkspaceのimport scopeを分ける
- importしたserverはenabledになるため、使うserverだけを選び、import後も確認する
- 元の外部Agent設定は変更されず、選んだscopeのZCode設定へ保存される
- APIキーや認証情報を扱うserverは、ZCode側の権限モードとも合わせて確認する
Subagentsは分離された作業文脈として見る
| Subagent | 公式説明の要点 | 向く作業 | 安全上の注意 |
|---|---|---|---|
| general-purpose | 幅広いtask向け。read/edit/commandも扱える | 小さなfeature、整理、検証 | 権限が広い前提で扱う |
| Explore | read-only researchやevidence gathering向け | 調査、call-chain把握、仕様確認 | 最初の調査はこちらを優先 |
| custom subagents | user-level subagentsをSettingsから定義 | 繰り返す専門作業 | betaや提供範囲は公式表示を確認 |
よくある質問
ZCodeはAGENTS.mdを読みますか？
はい。2026-09-26に確認した公式Agent Docsでは、~/.zcode/AGENTS.mdと現在workspaceのAGENTS.mdを読むと説明されています。CLAUDE.mdはClaude Code project onboarding時の移行元として扱われるため、継続runtimeの指示書と混同しないでください。
CLAUDE.mdも毎回読まれますか？
いいえ。公式docsでは、CLAUDE.mdはClaude Code projectのonboarding時の一度限りの移行元として扱われ、将来のrunはAGENTS.mdを使うと説明されています。
MCP importは安全ですか？
便利ですが安全装置ではありません。2026-09-26に確認した公式Docsでは、importしたserverはenabledになると説明されています。~/.agents/mcp.jsonなど元の設定、command、credential、scopeを確認し、必要なserverだけを選んでください。元の設定fileは書き換えられません。
Subagentsを使えば安全に分業できますか？
文脈分離には役立ちますが、general-purposeは広いtool accessを持つため、read-only調査はExploreを優先するなど権限を分けます。
関連記事
- MCPとは？AIエージェントに外部ツールをつなぐ仕組みと注意点
MCPはAIに外部ツールをつなぐ共通プロトコルです。仕様とCodexの設定・認証・tool権限を分けて、安全な導入判断を整理します。
- AGENTS.mdとは？Codex・Copilot code reviewにプロジェクトルールを伝える基本
AGENTS.mdとは、CodexのようなAIエージェントにプロジェクトの作業ルールを伝えるための指示ファイルです。毎回チャットで説明するより、運用が安定します。
- Claude Code Skillsとは？SKILL.md・CLAUDE.md・Agent Skillsの違いと使い方
Claude Code Skillsは、SKILL.mdを中心に専門タスクを再利用する仕組みです。CLAUDE.mdやAGENTS.mdの常時ルールと分け、frontmatter、scope、呼び出し条件を確認して安全に運用します。
- MCPの権限はどこまで許可する？AIエージェント連携を安全に始める最小権限ガイド
MCPはAIが使える道具を増やす仕組みです。便利さの前に、読み取り・書き込み・削除・外部送信を分けます。