docker-compose

Docker Compose スキル

インストール

このスキルは docker compose を実行します。最も簡単な方法は、Docker Desktop をインストールすることです（Docker Engine と Compose が含まれています）。

• Windows：Windows 向け Docker Desktop（WSL 2 または Hyper-V）
• Mac：Mac 向け Docker Desktop（Apple Silicon または Intel）
• Linux：Linux 向け Docker Desktop、または Docker のリポジトリから Docker Engine と Compose プラグインをインストールします

確認：docker compose version

チートシートとベストプラクティス

コマンド： docker compose up -d / down；docker compose ps / logs -f <service>；docker compose exec <service> sh；docker compose build --no-cache；docker compose -f compose.prod.yaml config — 検証します。

YAML： データベースには名前付きボリュームを使用します（postgres_data:/var/lib/postgresql/data）。ヘルスチェックを使用します（test、interval、timeout、retries を含む healthcheck:）。ネットワークはデフォルトで 1 つです。サービス名で参照します（例：http://api:3000）。env_file または environment を使用し、シークレットは secrets: に保管します。

便利な使い方： -f compose.yaml -f override.yaml でファイルをマージします（後のファイルが優先されます）。分離には --project-name を使用します。開発では build: context: . dockerfile: Dockerfile を推奨し、本番環境ではイメージタグを固定します。エラーを検出するため、up の前に docker compose config を実行します。

認定資格とトレーニング

Docker Certified Associate（DCA）： オーケストレーション 25％、イメージ／レジストリ 20％、インストール／設定 15％、ネットワーク 15％、セキュリティ 15％、ストレージ 10％。無料教材：公式 DCA 学習ガイド、Coursera DCA 試験対策コース（監査受講）。スキルデータ： Compose YAML（サービス、ボリューム、ネットワーク、ヘルスチェック）、CLI（up/down/ps/logs/exec）。

フックとワークフロー

推奨フック： 起動前：docker compose config（検証）。停止後：必要に応じてクリーンアップ。devops または devops-troubleshooter に振り分けられた場合に使用します。

ワークフロー： devops（主）、devops-troubleshooter（主）と併用します。流れ：Compose の検証 → タスクに応じて up/down/exec。コンテナのデバッグについては operations/incident-response を参照してください。

概要

このスキルは Docker Compose を包括的に管理し、AI エージェントによる複数コンテナアプリケーションのオーケストレーション、サービス管理、ログの調査、コンテナ化環境のトラブルシューティングを可能にします。また、コンテキストを効率的に使用できるよう、段階的な情報開示にも対応しています。

コンテキストの節約： 約 92％ 削減

• MCP モード： 約 25,000 トークンを常時読み込み（複数のツールとスキーマ）
• スキルモード： メタデータ約 700 トークンと必要に応じた読み込み

使用する場面

• ローカル開発環境の管理
• 複数コンテナアプリケーションのオーケストレーション
• サービスの接続性とネットワークのデバッグ
• コンテナのログとヘルス状態の監視
• サービスイメージのビルドと更新
• コンテナ化されたアプリケーションスタックのテスト
• サービス障害のトラブルシューティング
• アプリケーションのライフサイクル（起動、停止、再起動）の管理

要件

• Docker Engine がインストールされ、実行されていること
• Docker Compose V2（docker compose プラグイン。V1 の docker-compose はサポート終了）
• プロジェクト内に有効な compose.yaml（推奨）、または compose.yml / docker-compose.yml があること
• Docker ソケットへのアクセスに必要な権限

クイックリファレンス

# List running services
docker compose ps

# View service logs
docker compose logs <service>

# Start services
docker compose up -d

# Stop services
docker compose down

# Rebuild services
docker compose build

# Execute command in container
docker compose exec <service> <command>

# Live development reloading (Compose Watch)
docker compose watch

# Start with a profile active
docker compose --profile debug up -d

# Validate merged config
docker compose config

2026 年の主な機能

compose.yaml — 標準のファイル名

Docker Compose V2 では、従来の docker-compose.yml よりも compose.yaml（および compose.yml）が優先されます。 トップレベルの version: フィールドは非推奨のため、新しいファイルでは完全に省略してください。

# compose.yaml  (preferred — no version: field needed)
services:
  web:
    build: .
    ports:
      - '8080:80'
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - postgres_data:/var/lib/postgresql/data

volumes:
  postgres_data:

Compose Watch — ライブ開発リロード

Compose Watch（Compose 2.22 以降で GA）は、開発中の手動での再ビルドと再起動のサイクルを置き換えます。各サービスに develop.watch ブロックを設定します。使用できるアクションは 3 つです。

アクション	動作
sync	変更されたファイルを実行中のコンテナに即座にコピーします
rebuild	docker compose build を実行し、コンテナを再作成します
sync+restart	ファイルを同期してから、コンテナのプロセスを再起動します（完全な再ビルドは不要です）

services:
  api:
    build: .
    ports:
      - '3000:3000'
    develop:
      watch:
        # Sync source instantly — no rebuild needed for interpreted code
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - node_modules/
        # Rebuild when dependency manifest changes
        - action: rebuild
          path: package.json
        # Restart only when config changes
        - action: sync+restart
          path: ./config
          target: /app/config

次のコマンドで開始します。

# Watch mode (keeps output in foreground)
docker compose watch

# Or combined with up
docker compose up --watch

各アクションの使い分け：

• sync — ランタイムが変更を検知するインタープリター言語（Node.js、Python、Ruby）
• sync+restart — 完全な再ビルドは不要ですが、プロセスの再起動が必要な設定ファイルやテンプレートファイル
• rebuild — 依存関係マニフェストの変更（package.json、requirements.txt、go.mod）

Profiles — 環境ごとのサービス

Profiles を使うと、単一の compose.yaml で複数の環境に対応できます。プロファイルが設定されていないサービスは常に起動します。プロファイルが設定されているサービスは、そのプロファイルが有効化された場合にのみ起動します。

services:
  # Always starts — no profile
  api:
    build: .
    ports:
      - '3000:3000'
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 3s
      retries: 5
    volumes:
      - db_data:/var/lib/postgresql/data

  # Only with --profile debug
  pgadmin:
    image: dpage/pgadmin4:latest
    profiles: ['debug']
    ports:
      - '5050:80'
    environment:
      PGADMIN_DEFAULT_EMAIL: [email protected]
      PGADMIN_DEFAULT_PASSWORD: admin

  # Only with --profile monitoring
  prometheus:
    image: prom/prometheus:latest
    profiles: ['monitoring']
    ports:
      - '9090:9090'

  grafana:
    image: grafana/grafana:latest
    profiles: ['monitoring']
    ports:
      - '3001:3000'

volumes:
  db_data:

# Default: api + db only
docker compose up -d

# Debug: api + db + pgadmin
docker compose --profile debug up -d

# Monitoring: api + db + prometheus + grafana
docker compose --profile monitoring up -d

# Multiple profiles
docker compose --profile debug --profile monitoring up -d

# Via environment variable
COMPOSE_PROFILES=debug,monitoring docker compose up -d

プロファイルの命名規則： [a-zA-Z0-9][a-zA-Z0-9_.-]+ — 小文字のケバブケースを推奨します。

Include — 構成可能な設定

トップレベルキーの include（Compose 2.20 で導入）を使うと、大きな Compose ファイルをモジュール化し、チームごとに管理できます。各インクルードファイルは、それぞれのプロジェクトディレクトリのコンテキストで読み込まれるため、相対パスが正しく解決されます。

# compose.yaml (root — application layer)
include:
  - ./infra/compose.yaml # DB, Redis, message broker
  - ./monitoring/compose.yaml # Prometheus, Grafana

services:
  api:
    build: .
    depends_on:
      - db # defined in infra/compose.yaml
      - redis # defined in infra/compose.yaml

# infra/compose.yaml (infrastructure layer — owned by platform team)
services:
  db:
    image: postgres:16-alpine
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U postgres']
      interval: 5s
      timeout: 3s
      retries: 5
    volumes:
      - db_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 5s
      timeout: 3s
      retries: 5

volumes:
  db_data:

include は再帰的に使用できます。インクルードされたファイルから、さらに別のファイルをインクルードできます。リソース名が競合するとエラーになり、暗黙的にマージされることはありません。

ヘルスチェックのベストプラクティス

ステートフルなサービスには必ずヘルスチェックを定義し、depends_on: condition: service_healthy が正しく動作するようにします。ヘルスチェックがないと、依存先のサービスの準備が整う前に、依存するサービスが起動する場合があります。

services:
  db:
    image: postgres:16-alpine
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready -U ${POSTGRES_USER:-postgres}']
      interval: 10s # How often to check
      timeout: 5s # Time to wait for response
      retries: 5 # Failures before marking unhealthy
      start_period: 30s # Grace period during container startup

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ['CMD', 'redis-cli', 'ping']
      interval: 10s
      timeout: 3s
      retries: 3

  api:
    build: .
    depends_on:
      db:
        condition: service_healthy # waits until db passes healthcheck
      redis:
        condition: service_healthy

ヘルスチェックのガイドライン：

• 可能な場合は、CMD-SHELL（文字列形式）ではなく CMD（配列形式）を使います。シェルインジェクションのリスクを避けられます
• シェル機能（pg_isready、curl -f など）が必要な場合に限り、CMD-SHELL を使います
• 起動に時間がかかるサービス（JVM アプリ、初回実行時のマイグレーション）には start_period を設定します
• 明示的にインストールされていない限り、Alpine ベースのイメージでは curl を避けます。代わりに wget -q --spider またはネイティブのチェックを使用します
• HTTP サービスの場合：test: ["CMD-SHELL", "wget -q --spider http://localhost:3000/health || exit 1"]

マルチステージビルドのパターン

マルチステージ Dockerfile を使い、本番用イメージを最小限かつ安全に保ちます。開発用には、compose.yaml で特定のビルドステージを指定します。

# Dockerfile
# Stage 1: deps — install dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci

# Stage 2: builder — compile/transpile
FROM deps AS builder
COPY . .
RUN npm run build

# Stage 3: runner — minimal production image
FROM node:20-alpine AS runner
RUN addgroup -g 1001 -S appgroup && adduser -S -u 1001 -G appgroup appuser
WORKDIR /app
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=deps    --chown=appuser:appgroup /app/node_modules ./node_modules
USER appuser
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=5s --retries=3 \
  CMD wget -q --spider http://localhost:3000/health || exit 1
CMD ["node", "dist/index.js"]

# compose.yaml — dev targets the builder stage for faster iteration
services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
      target: builder # Stop at builder stage in dev (includes devDeps)
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
          ignore:
            - node_modules/
        - action: rebuild
          path: package.json

# compose.prod.yaml — production uses the full runner stage
services:
  api:
    build:
      context: .
      dockerfile: Dockerfile
      target: runner # Minimal, non-root production image
    restart: unless-stopped

リソース制限（ベストプラクティス）

コンテナのリソース枯渇を防ぐため、必ずリソース制限を定義します。

services:
  api:
    image: myapp:latest
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
        reservations:
          cpus: '0.25'
          memory: 128M
    restart: unless-stopped

ツール

このスキルでは、サービス管理、監視、ビルド操作、トラブルシューティングのカテゴリにわたる 15 個のツールを提供します。

サービス管理（5 個のツール）

up

compose.yaml で定義されたサービスを起動します。

パラメーター	型	説明	デフォルト
detached	boolean	デタッチモードで実行します	true
build	boolean	起動前にイメージをビルドします	false
force_recreate	boolean	コンテナを再作成します	false
project_name	string	プロジェクト名の上書き	ディレクトリ名
services	array	起動する特定のサービス	すべてのサービス
profiles	array	有効化するプロファイル	なし
watch	boolean	Compose Watch モードを有効化します	false

例：

docker compose up -d
docker compose up --build
docker compose up web api
docker compose --profile debug up -d
docker compose up --watch

安全性：本番環境では確認が必要です。

down

コンテナーとネットワーク、ボリュームを停止して削除します。

Parameter	Type	Description	Default
volumes	boolean	ボリュームを削除する（ブロックされています）	false
remove_orphans	boolean	孤立したコンテナーを削除する	false
project_name	string	プロジェクト名の上書き	directory name

例：

docker compose down
docker compose down --remove-orphans

安全性：ボリュームの削除（-v フラグ）はデフォルトでブロックされています。実行には確認が必要です。

start

既存のコンテナーを再作成せずに起動します。

Parameter	Type	Description	Default
services	array	起動する特定のサービス	all services
project_name	string	プロジェクト名の上書き	directory name

例：

docker compose start
docker compose start web

stop

実行中のコンテナーを削除せずに停止します。

Parameter	Type	Description	Default
timeout	number	シャットダウンのタイムアウト（秒）	10
services	array	停止する特定のサービス	all services
project_name	string	プロジェクト名の上書き	directory name

例：

docker compose stop
docker compose stop --timeout 30 web

restart

サービスを再起動します（停止＋起動）。

Parameter	Type	Description	Default
timeout	number	シャットダウンのタイムアウト（秒）	10
services	array	再起動する特定のサービス	all services
project_name	string	プロジェクト名の上書き	directory name

例：

docker compose restart
docker compose restart api

ステータスとログ（3 ツール）

ps

ステータス情報とともにコンテナーの一覧を表示します。

Parameter	Type	Description	Default
all	boolean	停止中のコンテナーを含むすべてのコンテナーを表示する	false
services	array	サービスで絞り込む	all services
project_name	string	プロジェクト名の上書き	directory name

例：

docker compose ps
docker compose ps --all

出力フィールド：NAME、IMAGE、STATUS、PORTS

logs

ストリーミングに対応したサービスログを表示します。

Parameter	Type	Description	Default
services	array	ログを表示するサービス	all services
follow	boolean	ログ出力を追跡する（ストリーム）	false
tail	number	表示する行数	100
timestamps	boolean	タイムスタンプを表示する	false
since	string	指定したタイムスタンプ／期間以降のログを表示する	none
project_name	string	プロジェクト名の上書き	directory name

例：

docker compose logs web
docker compose logs --tail 50 --follow api
docker compose logs --since "2026-01-01T10:00:00"

注：無期限のストリーミングを防ぐため、フォローモードは 60 秒後に自動的に終了します。

top

コンテナー内で実行中のプロセスを表示します。

Parameter	Type	Description	Default
services	array	調査するサービス	all services
project_name	string	プロジェクト名の上書き	directory name

例：

docker compose top
docker compose top web

出力：PID、USER、TIME、COMMAND を含むプロセス一覧

ビルドとイメージ（3 ツール）

build

サービスイメージをビルドまたは再ビルドします。

パラメーター	タイプ	説明	デフォルト
no_cache	boolean	キャッシュを使わずにビルド	false
pull	boolean	より新しいイメージバージョンを取得	false
parallel	boolean	並列でビルド	true
services	array	ビルドするサービス	すべてのサービス
project_name	string	プロジェクト名の上書き	ディレクトリ名

例：

docker compose build
docker compose build --no-cache web
docker compose build --pull

安全性：キャッシュを使わないビルドはリソースを大量に消費するため、確認が必要です。

pull

レジストリからサービスイメージを取得します。

パラメーター	タイプ	説明	デフォルト
ignore_pull_failures	boolean	取得に失敗しても続行	false
services	array	取得するサービス	すべてのサービス
project_name	string	プロジェクト名の上書き	ディレクトリ名

例：

docker compose pull
docker compose pull web api

安全性：本番環境では確認が必要です。

images

サービスで使用されているイメージを一覧表示します。

パラメーター	タイプ	説明	デフォルト
project_name	string	プロジェクト名の上書き	ディレクトリ名

例：

docker compose images

出力フィールド：CONTAINER、REPOSITORY、TAG、IMAGE ID、SIZE

実行（2 ツール）

exec

実行中のコンテナー内でコマンドを実行します。

パラメーター	タイプ	説明	必須
service	string	サービス名	はい
command	array	実行するコマンド	はい
user	string	実行ユーザー	コンテナーのデフォルト
workdir	string	作業ディレクトリ	コンテナーのデフォルト
env	object	環境変数	なし
project_name	string	プロジェクト名の上書き	ディレクトリ名

例：

docker compose exec web bash
docker compose exec -u root api ls -la /app
docker compose exec db psql -U postgres

安全性：

• 破壊的なコマンド（rm -rf、dd、mkfs）はブロックされます
• root ユーザーでの実行には確認が必要です
• デフォルトのタイムアウト：30 秒

run

新しいコンテナーで単発のコマンドを実行します。

パラメーター	タイプ	説明	デフォルト
service	string	実行するサービス	必須
command	array	実行するコマンド	サービスのデフォルト
rm	boolean	実行後にコンテナーを削除	true
no_deps	boolean	依存するサービスを起動しない	false
user	string	実行ユーザー	コンテナーのデフォルト
env	object	環境変数	なし
project_name	string	プロジェクト名の上書き	ディレクトリ名

例：

docker compose run --rm web npm test
docker compose run --no-deps api python manage.py migrate

安全性：データを変更するコマンドには確認が必要です。

設定（2 ツール）

config

Compose ファイルの設定を検証して表示します。

パラメーター	タイプ	説明	デフォルト
resolve_image_digests	boolean	イメージタグをダイジェストに固定	false
no_interpolate	boolean	環境変数を展開しない	false
project_name	string	プロジェクト名の上書き	ディレクトリ名

例：

docker compose config
docker compose config --resolve-image-digests

出力：解析・マージされた Compose 設定

port

サービスのポートに割り当てられたパブリックポートを表示します。

パラメーター	型	説明	必須
service	string	サービス名	はい
private_port	number	コンテナーポート	はい
protocol	string	プロトコル（tcp/udp）	tcp
project_name	string	プロジェクト名の上書き	ディレクトリー名

例：

docker compose port web 80
docker compose port db 5432

出力：<host>:<port> のバインディング

一般的なワークフロー

開発環境を起動する

# 1. Validate configuration
docker compose config

# 2. Pull latest images
docker compose pull

# 3. Build custom images
docker compose build

# 4. Start services in detached mode
docker compose up -d

# 5. Check service status
docker compose ps

# 6. View logs
docker compose logs --tail 100

Compose Watch でライブ開発する

# 1. Ensure develop.watch blocks are configured in compose.yaml

# 2. Start with watch mode (foreground, shows sync events)
docker compose watch

# 3. Or start detached then watch
docker compose up -d
docker compose watch --no-up

失敗しているサービスのトラブルシューティング

# 1. Check container status
docker compose ps --all

# 2. View service logs
docker compose logs --tail 200 failing-service

# 3. Inspect running processes
docker compose top failing-service

# 4. Check configuration
docker compose config

# 5. Restart the service
docker compose restart failing-service

# 6. If needed, recreate container
docker compose up -d --force-recreate failing-service

サービスイメージを更新する

# 1. Pull latest images
docker compose pull

# 2. Stop services
docker compose down

# 3. Rebuild if using custom Dockerfiles
docker compose build --pull

# 4. Start with new images
docker compose up -d

# 5. Verify services
docker compose ps

サービスの接続をデバッグする

# 1. Check running services
docker compose ps

# 2. Inspect port mappings
docker compose port web 80
docker compose port api 3000

# 3. Exec into container
docker compose exec web sh

# 4. Test connectivity (from inside container)
docker compose exec web curl api:3000/health

# 5. Check logs for errors
docker compose logs web api

環境をクリーンアップする

# 1. Stop all services
docker compose down

# 2. Remove orphaned containers
docker compose down --remove-orphans

# 3. View images
docker compose images

# 4. Clean up (manual - volume removal BLOCKED)
# Volumes require manual cleanup with explicit confirmation

プロファイルを使って環境ごとのサービスを設定する

# Development: default services only
docker compose up -d

# Development + debug tools
docker compose --profile debug up -d

# Start monitoring stack
docker compose --profile monitoring up -d

# Via env var (useful in CI)
COMPOSE_PROFILES=monitoring docker compose up -d

# Stop and clean a specific profile
docker compose --profile debug down

設定

環境変数

変数	説明	デフォルト
COMPOSE_PROJECT_NAME	デフォルトのプロジェクト名	ディレクトリー名
COMPOSE_FILE	Compose ファイルのパス	compose.yaml
COMPOSE_PROFILES	有効にするプロファイル（カンマ区切り）	（なし）
COMPOSE_PATH_SEPARATOR	複数ファイルのパス区切り文字	:（Linux/Mac）、;（Windows）
DOCKER_HOST	Docker デーモンのソケット	unix:///var/run/docker.sock
COMPOSE_HTTP_TIMEOUT	API 呼び出しの HTTP タイムアウト	60
COMPOSE_PARALLEL_LIMIT	並列操作の最大数	無制限

セットアップ

1. Docker Engine をインストールします：

   # macOS
   brew install --cask docker
   
   # Linux (Ubuntu/Debian)
   sudo apt-get update
   sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin
   
   # Windows
   # Download Docker Desktop from docker.com
   

2. Docker Compose を確認します：

   # Check Docker version
   docker --version
   
   # Check Compose version (must be V2, e.g. 2.24+)
   docker compose version
   

3. compose.yaml を作成します（version: フィールドは不要です。V2 では必要ありません）：

   services:
     web:
       build: .
       ports:
         - '8080:80'
       depends_on:
         db:
           condition: service_healthy
     db:
       image: postgres:16-alpine
       environment:
         POSTGRES_PASSWORD: example
       healthcheck:
         test: ['CMD-SHELL', 'pg_isready -U postgres']
         interval: 10s
         timeout: 5s
         retries: 5
   

4. スキルをテストします：

   docker compose config
   docker compose ps
   

安全機能

ブロックされる操作

誤ってデータを失わないよう、以下の操作はデフォルトでブロックされます。

• ボリュームの削除：docker compose down -v（ブロックされています。手動での確認が必要です）
• 完全なクリーンアップ：docker compose down -v --rmi all（ブロックされています。非常に破壊的な操作です）
• 破壊的な exec：コンテナー内での rm -rf、dd、mkfs、sudo rm（ブロックされています）
• 強制削除：docker compose rm -f（ブロックされています。先に停止してから rm を実行してください）

確認が必要な操作

以下の操作には明示的な確認が必要です。

• --no-cache を指定したビルド（リソースを大量に消費します）
• 本番環境でのイメージのプル
• --force-recreate を指定したサービスの起動
• root ユーザーとしてのコマンド実行
• データベースを変更するコマンドの実行
• タイムアウトが非常に短い場合のサービス停止

自動終了する操作

リソースの問題を防ぐため、以下の操作は自動的に終了します。

• ログの追跡（--follow）：60 秒でタイムアウト
• サービスの実行（exec）：30 秒でタイムアウト
• 単発コマンド（run）：60 秒でタイムアウト

エラー処理

よくあるエラー：

エラー	原因	対処方法
docker: command not found	Docker がインストールされていない	Docker Engine をインストールします
Cannot connect to Docker daemon	Docker が起動していない	Docker サービスを起動します
network ... not found	ネットワークのクリーンアップに関する問題	docker compose down を実行してから up を実行します
port is already allocated	ポートの競合	ポートマッピングを変更するか、競合するサービスを停止します
no configuration file provided	Compose ファイルがない	compose.yaml を作成します
service ... must be built	イメージがビルドされていない	docker compose build を実行します
service unhealthy	ヘルスチェックに失敗している	docker compose logs <service> を確認します
include path not found	インクルードされたファイルがない	include: ブロック内のパスを確認します

復旧：

• 設定を検証します：docker compose config
• Docker の状態を確認します：docker info
• サービスのログを表示します：docker compose logs
• 強制的に再作成します：docker compose up -d --force-recreate
• クリーンな状態で再起動します：docker compose down && docker compose up -d

エージェントとの連携

このスキルは、以下のエージェントと連携します。

主要なエージェント

• devops：ローカル開発、CI/CD 連携、コンテナーオーケストレーション
• developer：アプリケーション開発、テスト、デバッグ

その他のエージェント

• qa：統合テスト、テスト環境のセットアップ
• incident-responder：本番環境の問題のデバッグ、サービスの復旧
• cloud-integrator：クラウドへのデプロイ、Kubernetes への移行
• performance-engineer：パフォーマンステスト、リソースの最適化

段階的な開示

このスキルでは、コンテキストの使用量を最小限に抑えるため、段階的な開示を採用しています。

1. 初期読み込み：メタデータとツール名のみ（約 700 トークン）
2. ツールの呼び出し：必要に応じて特定のツールスキーマを読み込み（約 100～150 トークン）
3. 結果のストリーミング：大きな出力（ログ）を段階的にストリーミング
4. コンテキストのクリーンアップ：使用後に古い結果を消去

コンテキストの最適化：

• --tail を使用してログ出力を制限します
• サービスフィルターを使用して対象のコンテナーを指定します
• アクティブなサービスのみを表示するには、ps --all ではなく ps を使用します
• 時間を限定したログクエリには --since を使用します

トラブルシューティング

スキルの問題

Docker Compose が見つからない場合：

# Check Docker Compose version
docker compose version

# V1 (docker-compose) is end-of-life — upgrade to V2
# Docker Compose V2 is integrated into Docker CLI as a plugin

アクセスが拒否された場合：

# Add user to docker group (Linux)
sudo usermod -aG docker $USER
newgrp docker

# Verify permissions
docker ps

Compose ファイルに関する問題：

# Validate syntax
docker compose config

# Check for errors (quiet mode — exit code only)
docker compose config -q

# View resolved configuration
docker compose config --resolve-image-digests

ネットワークに関する問題：

# List networks
docker network ls

# Remove unused networks
docker network prune

# Recreate services
docker compose down
docker compose up -d

ヘルスチェックの失敗：

# Inspect healthcheck status
docker inspect <container_id> | grep -A 10 Health

# View healthcheck output
docker compose logs <service>

# Manually run the healthcheck command
docker compose exec <service> pg_isready -U postgres

Compose Watch が同期されない場合：

# Verify develop.watch block is present in compose.yaml
docker compose config | grep -A 20 develop

# Ensure Compose version is 2.22+
docker compose version

# Watch requires build: attribute (not image: only)

パフォーマンスに関する考慮事項

• ビルドキャッシュ：ビルドを高速化するにはレイヤーキャッシュを使用します。必要がない限り --no-cache は使用しないでください
• マルチステージビルド：本番用イメージのサイズを大幅に削減できます（多くの場合 80％ 以上）
• 並列処理：Docker Compose V2 ではデフォルトで並列化されます。制御するには COMPOSE_PARALLEL_LIMIT を使用します
• リソース制限：リソースの枯渇を防ぐため、Compose ファイルで CPU／メモリの制限を定義します
• ログローテーション：ディスク容量の問題を防ぐため、ロギングドライバーを使用します
• ボリュームのクリーンアップ：使用していないボリュームを定期的にクリーンアップします（手動での確認が必要です）
• Compose Watch とバインドマウント：クロスプラットフォーム開発では develop.watch を優先してください。macOS／Windows ではバインドマウントに I/O パフォーマンスの問題があります

関連資料

• Docker Compose ドキュメント：https://docs.docker.com/compose/
• Compose ファイルリファレンス：https://docs.docker.com/compose/compose-file/
• Compose Watch ドキュメント：https://docs.docker.com/compose/how-tos/file-watch/
• Compose Profiles ドキュメント：https://docs.docker.com/compose/how-tos/profiles/
• Compose Include ドキュメント：https://docs.docker.com/compose/how-tos/multiple-compose-files/include/
• Docker CLI：https://docs.docker.com/engine/reference/commandline/cli/
• Kubernetes への移行：.claude/skills/kubernetes-flux/（Kubernetes オーケストレーション）

参考資料

• Docker Compose ドキュメント
• Docker Compose V2
• Compose 仕様
• Docker のベストプラクティス
• Compose Watch の使用
• Compose Profiles の使用
• Compose Include ディレクティブ

関連スキル

• cloud-devops-expert - クラウドプラットフォーム（AWS、GCP、Azure）と Terraform インフラストラクチャ

絶対遵守事項

1. 必ず docker compose（V2 プラグイン）を使用してください。非推奨で削除予定の docker-compose（V1 スタンドアロン）は使用しないでください。
2. **compose ファイルやコミット済みの .env ファイルに、シークレットや認証情報を直接含めないでください。**外部のシークレット管理を使用するか、ドキュメント専用の .env.example テンプレートを使用してください。
3. **他のサービスが依存するサービスには、必ずヘルスチェックを定義してください。**ヘルスチェックがない場合、依存サービスの準備が整う前にサービスが起動してしまいます。
4. **Compose ネットワークの外部からアクセスする必要がない限り、サービスのポートをホストに公開しないでください。**不要なホストポートの公開は、攻撃対象領域を広げます。
5. **本番環境で使用するサービスには、必ずリソース制限（CPU とメモリ）を指定してください。**コンテナを無制限にすると、他のサービスのリソースを奪い、ホストがクラッシュする可能性があります。

アンチパターン

アンチパターン	失敗する理由	正しい方法
docker-compose V1 コマンドを使用する	V1 は非推奨です。V2 の機能（profiles、merge、watch）がなく、削除予定です。	docker compose（ハイフンではなくスペース）を使用し、docker compose version で確認します。
compose ファイルにシークレットをハードコードする	Git にコミットされたシークレットは、履歴内で永久に公開されたままになります。	未追跡の .env から読み込む環境変数参照（${SECRET}）を使用します。
データベース／キャッシュサービスにヘルスチェックがない	アプリコンテナが DB の準備完了前に起動し、起動時の競合状態やクラッシュを引き起こします。	適切なテストコマンドを指定した healthcheck: を追加し、depends_on: condition: service_healthy を使用します。
すべてのポートをホストに公開する（0.0.0.0）	パブリックインターフェースを含む、あらゆるネットワークインターフェースからサービスにアクセスできてしまいます。	開発時は 127.0.0.1 にバインドし、サービス間通信には内部ネットワークを使用します。
再起動ポリシーがない	本番環境では、クラッシュやホストの再起動後にコンテナが停止したままになります。	自動復旧が必要なサービスには restart: unless-stopped を使用します。

メモリプロトコル（必須）

開始前： .claude/context/memory/learnings.md を読みます

完了後：

• 新しいパターン -> .claude/context/memory/learnings.md
• 問題の発見 -> .claude/context/memory/issues.md
• 決定事項 -> .claude/context/memory/decisions.md

中断を想定してください：メモリに記録されていなければ、起きていないのと同じです。