ai-coding-agents

AI コーディングエージェントのスキル

Codex CLI と Claude Code CLI（主要な AI コーディングエージェント 2 つ）に関する専門知識です。

注記： このスキルでは、参考情報として両方のツールについて説明します。VMark の開発では、主に Claude Code CLI を使用します。Codex CLI のセクションは、情報を網羅し、ツール間のワークフローを紹介するために残しています。

使用する場面

• CLI を介して複雑なコーディングタスクを調整する
• いずれかのツール向けに MCP サーバーを設定する
• 自動化パイプライン（CI/CD）を構築する
• 認証やサンドボックスの問題をトラブルシューティングする
• エージェント間の機能を比較する
• カスタムエージェント／サブエージェントを設定する

クイックリファレンス

セッションの開始

タスク	Codex CLI	Claude Code CLI
対話型セッション	codex	claude
プロンプトを指定	codex "fix the bug"	claude "fix the bug"
非対話型	codex exec "task"	claude -p "task"
直前のセッションを再開	codex resume --last	claude -c
ID を指定して再開	codex resume <id>	claude -r <id>

安全モード

モード	Codex CLI	Claude Code CLI
読み取り専用	-s read-only	--permission-mode plan
ワークスペースへの書き込み	-s workspace-write	（デフォルト）
フルアクセス	-s danger-full-access	--dangerously-skip-permissions
自動モード	--full-auto	--permission-mode default
YOLO モード	--yolo	--dangerously-skip-permissions

モデルの選択

タスク	Codex CLI	Claude Code CLI
モデルを選択	-m gpt-5-codex	--model opus
ローカルの OSS を使用	--oss	N/A
フォールバックモデル	N/A	--fallback-model sonnet

---

Codex CLI（OpenAI）

インストール

npm i -g @openai/codex
# or
brew install --cask codex

認証

codex login              # OAuth via ChatGPT
codex login --with-api-key   # Read API key from stdin
codex login status       # Check auth status
codex logout             # Remove credentials

主なコマンド

codex - 対話型モード

codex                           # Start TUI
codex "fix all TypeScript errors"  # With initial prompt
codex -i screenshot.png "explain"  # With image
codex --full-auto "refactor"    # Low-friction mode
codex --search "find docs"      # Enable web search

codex exec - 非対話型

codex exec "write tests"        # Run and exit
codex e "task"                  # Short alias
echo "task" | codex exec -      # From stdin
codex exec --json "task"        # JSONL output
codex exec -o result.txt "task" # Save to file
codex exec --output-schema schema.json "task"  # Validate output

codex resume - セッションの続行

codex resume                    # Interactive picker
codex resume --last             # Most recent
codex resume --all              # Show all (any directory)
codex resume <session-id>       # Specific session
codex resume <id> "continue with this"  # With prompt

codex review - コードレビュー

codex review                    # Review current branch vs main
codex review --uncommitted      # Review uncommitted changes
codex review --base develop     # Against specific branch
codex review --commit abc123    # Review specific commit
codex review "focus on security"  # Custom instructions

codex apply - クラウドタスクの適用

codex apply <task-id>           # Apply diff from cloud task

codex cloud - クラウドタスク（実験的）

codex cloud                     # Browse cloud tasks
codex cloud exec "task" --env <env-id>  # Submit task
codex cloud status <task-id>    # Check status
codex cloud diff <task-id>      # Show diff
codex cloud apply <task-id>     # Apply changes

codex mcp - MCP サーバーの管理

codex mcp list                  # List servers
codex mcp list --json           # JSON output
codex mcp get <name>            # Server details
codex mcp add <name> -- npx my-server   # Add stdio server
codex mcp add <name> --url https://... # Add HTTP server
codex mcp add <name> --env API_KEY=xxx -- cmd  # With env vars
codex mcp remove <name>         # Remove server
codex mcp login <name> --scopes read,write  # OAuth for HTTP
codex mcp logout <name>         # Remove OAuth

codex sandbox - サンドボックス内でコマンドを実行

# macOS
codex sandbox macos -- npm test
codex sandbox seatbelt --full-auto -- ./script.sh

# Linux
codex sandbox linux -- npm test
codex sandbox landlock -- ./script.sh

codex completion - シェル補完

codex completion bash >> ~/.bashrc
codex completion zsh >> ~/.zshrc
codex completion fish > ~/.config/fish/completions/codex.fish

スラッシュコマンド（対話型）

コマンド	用途
/model	モデルを切り替える（gpt-5-codex、gpt-5 など）
/approvals	承認ポリシーを変更する
/compact	会話を要約し、コンテキストを解放する
/diff	git diff を表示する
/review	作業ツリーを分析する
/status	設定とトークン使用量を表示する
/mcp	利用可能な MCP ツールを一覧表示する
/mention	ファイルを添付する
/fork	会話を分岐する
/resume	前のセッションを再開する
/new	新しい会話を開始する
/init	AGENTS.md のひな型を作成する
/feedback	ログ／診断情報を送信する
/quit, /exit	CLI を終了する

設定（~/.codex/config.toml）

model = "gpt-5-codex"
approval_policy = "on-request"

[sandbox]
mode = "workspace-write"

[features]
web_search = true

[profiles.ci]
model = "gpt-4.1"
approval_policy = "never"

グローバルフラグ

-m, --model <MODEL>          Model selection
-s, --sandbox <MODE>         read-only|workspace-write|danger-full-access
-a, --ask-for-approval <P>   untrusted|on-failure|on-request|never
-c, --config <KEY=VALUE>     Override config
-C, --cd <DIR>               Working directory
-i, --image <FILE>           Attach image(s)
-p, --profile <NAME>         Config profile
--full-auto                  Low-friction mode
--yolo                       Bypass all safety (DANGEROUS)
--search                     Enable web search
--add-dir <DIR>              Grant additional write access
--enable <FEATURE>           Enable feature flag
--disable <FEATURE>          Disable feature flag
--oss                        Use local OSS model

---

Claude Code CLI（Anthropic）

インストール

npm install -g @anthropic-ai/claude-code

認証

claude                      # First run prompts login
claude setup-token          # Set up long-lived token
# Requires Claude Pro/Max subscription OR API key

主なコマンド

claude - 対話型モード

claude                          # Start REPL
claude "explain this project"   # With prompt
claude -c                       # Continue last conversation
claude -r "session-name"        # Resume by name/ID
claude --model opus             # Select model
claude --chrome                 # Enable Chrome integration
claude --ide                    # Auto-connect to IDE

claude -p - 出力モード（非対話型）

claude -p "explain this function"   # Query and exit
cat file | claude -p "explain"      # Process piped input
claude -p --output-format json "q"  # JSON output
claude -p --output-format stream-json "q"  # Streaming JSON
claude -p --max-turns 3 "task"      # Limit agent turns
claude -p --max-budget-usd 5 "task" # Spending limit
claude -p --json-schema '{...}' "q" # Validate output schema

claude mcp - MCP サーバーの管理

claude mcp list                 # List servers
claude mcp get <name>           # Server details
claude mcp add <name> <cmd>     # Add stdio server
claude mcp add -t http <name> <url>  # Add HTTP server
claude mcp add -e KEY=val <name> -- cmd  # With env vars
claude mcp add -H "Auth: Bearer x" <name> <url>  # With headers
claude mcp add -s project <name> <cmd>  # Project scope
claude mcp remove <name>        # Remove server
claude mcp serve                # Run as MCP server
claude mcp add-from-claude-desktop   # Import from desktop app
claude mcp reset-project-choices     # Reset approvals

claude plugin - プラグインの管理

claude plugin list              # List plugins
claude plugin install <name>    # Install plugin
claude plugin install <name>@marketplace  # From specific marketplace
claude plugin uninstall <name>  # Remove plugin
claude plugin enable <name>     # Enable disabled plugin
claude plugin disable <name>    # Disable plugin
claude plugin update <name>     # Update plugin
claude plugin validate <path>   # Validate manifest
claude plugin marketplace       # Manage marketplaces

claude update - 自己更新

claude update                   # Check and install updates

claude doctor - 診断

claude doctor                   # Check health/issues

claude install - ネイティブビルド

claude install                  # Install native build
claude install stable           # Specific version
claude install latest           # Latest version

スラッシュコマンド（対話型）

コマンド	用途
/init	CLAUDE.md を生成する
/clear	コンテキストをリセットする
/compact	会話を要約する
/bug	問題を報告する
/doctor	診断を実行する
/model	モデルを切り替える
/config	設定を表示／編集する
/permissions	権限を管理する
/memory	メモリを表示／編集する
/project:<cmd>	プロジェクト固有のコマンド
/user:<cmd>	ユーザー固有のコマンド

カスタムコマンド

.claude/commands/fix-issue.md を作成します：

Fix GitHub issue #$ARGUMENTS

1. Read the issue details
2. Identify the problem
3. Implement the fix
4. Write tests
5. Create a commit

使用方法：/project:fix-issue 1234

設定

ユーザー設定（~/.claude/settings.json）：

{
  "model": "claude-sonnet-4-5-20250929",
  "verbose": false,
  "theme": "dark"
}

プロジェクト設定（.claude/settings.json）：

{
  "allowedTools": ["Bash(git:*)", "Read", "Edit"],
  "disallowedTools": ["Bash(rm:*)"]
}

CLI フラグ

基本

-p, --print                 Non-interactive mode
-c, --continue              Continue last conversation
-r, --resume <ID>           Resume specific session
-v, --version               Show version

モデルと設定

--model <MODEL>             sonnet|opus|haiku or full name
--fallback-model <MODEL>    Fallback when overloaded
--settings <FILE>           Load settings JSON
--setting-sources <LIST>    user,project,local
--session-id <UUID>         Use specific session ID

システムプロンプト

--system-prompt <TEXT>      Replace default prompt
--append-system-prompt <T>  Append to default
--system-prompt-file <F>    Replace with file (print only)
--append-system-prompt-file Replace with file (print only)

エージェントとツール

--agent <NAME>              Specify agent
--agents <JSON>             Define custom subagents
--tools <LIST>              Restrict built-in tools
--allowedTools <LIST>       Auto-approve tools
--disallowedTools <LIST>    Remove tools from context

権限

--permission-mode <MODE>    acceptEdits|bypassPermissions|default|delegate|dontAsk|plan
--dangerously-skip-permissions  Skip all prompts (DANGEROUS)
--allow-dangerously-skip-permissions  Enable bypass option

出力

--output-format <FMT>       text|json|stream-json
--input-format <FMT>        text|stream-json
--include-partial-messages  Include streaming chunks
--verbose                   Verbose logging
--debug [FILTER]            Debug mode with filtering

詳細設定

--max-turns <N>             Limit agent turns (print only)
--max-budget-usd <AMT>      Spending limit (print only)
--json-schema <SCHEMA>      Validate JSON output
--chrome / --no-chrome      Chrome integration
--ide                       IDE auto-connect
--fork-session              Create new session on resume
--no-session-persistence    Don't save session
--add-dir <DIRS>            Additional directories
--plugin-dir <DIRS>         Load plugins
--disable-slash-commands    Disable all skills
--mcp-config <FILES>        MCP server configs
--strict-mcp-config         Only use specified MCP
--betas <HEADERS>           Beta API headers

カスタムサブエージェント

claude --agents '{
  "reviewer": {
    "description": "Code reviewer. Use after changes.",
    "prompt": "You are a senior code reviewer...",
    "tools": ["Read", "Grep", "Glob"],
    "model": "sonnet"
  }
}'

---

よくあるパターンとエッジケース

CI/CD 統合

GitHub Actions での Codex：

- name: Run Codex
  run: |
    echo "${{ secrets.OPENAI_API_KEY }}" | codex login --with-api-key
    codex exec --json -o result.txt "fix linting errors"

CI での Claude：

- name: Run Claude
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    claude -p --output-format json "review this PR" > review.json

レート制限への対処

Codex： 自動バックオフが組み込まれています。

Claude： --fallback-model を使用します：

claude -p --fallback-model haiku "quick task"

大規模なコードベースでの作業

# Codex: Use /compact to free context
# In session: /compact

# Claude: Use /compact or start fresh
claude --no-session-persistence -p "analyze src/"

複数ディレクトリへのアクセス

# Codex
codex --add-dir ../shared-lib --add-dir ../config

# Claude
claude --add-dir ../shared-lib ../config

構造化出力

Codex：

codex exec --output-schema schema.json "generate API spec"

Claude：

claude -p --json-schema '{"type":"object","properties":{"name":{"type":"string"}}}' "extract data"

画像入力

Codex：

codex -i screenshot.png "explain this UI"
codex -i img1.png -i img2.png "compare these"

Claude：

# Via file reference in prompt
claude "analyze the image at ./screenshot.png"

セッションのフォーク

# Codex: /fork in session

# Claude
claude -r "session-id" --fork-session "try alternative approach"

MCP サーバーのデバッグ

Codex：

codex mcp list --json | jq .

Claude：

claude --debug "mcp" --mcp-config ./mcp.json

---

トラブルシューティング

認証の問題

問題	Codex	Claude
ログインしていない	codex login status	claude doctor
トークンの有効期限切れ	codex logout && codex login	claude setup-token
API キーの問題	OPENAI_API_KEY を確認	ANTHROPIC_API_KEY を確認

サンドボックスの問題

問題	解決策
権限が拒否された	特定のディレクトリには --add-dir を使用します
コマンドを実行できない	サンドボックスモードを確認し、workspace-write を使用します
ネットワークがブロックされている	サンドボックスがネットワークをブロックしている可能性があります。danger-full-access は慎重に使用してください

MCP サーバーの問題

問題	解決策
サーバーが見つからない	mcp list を確認し、インストールを検証します
接続に失敗した	サーバーログを確認し、URL／コマンドを検証します
認証が必要	mcp login（Codex）を使用するか、ヘッダーを追加します（Claude）

パフォーマンスの問題

問題	解決策
応答が遅い	より軽量なモデル（gpt-4.1-mini／haiku）を使用します
コンテキストのオーバーフロー	/compact を使用して要約します
コストが高い	--max-budget-usd を設定します（Claude）

---

ベストプラクティス

1. まず読み取り専用で開始し、調査を進め、必要に応じて権限を引き上げます
2. セッションを使用します。新しく開始するのではなく、作業を再開します
3. プロジェクト固有の指示を記載した AGENTS.md/CLAUDE.md を作成します
4. 外部との連携には MCP サーバーを活用します
5. CI/CD での解析には 構造化出力を使用します
6. --max-budget-usd で 支出上限を設定します
7. 適用する前に 差分を確認します（/diff、codex cloud diff）
8. 大きな変更の前に チェックポイントをコミットします