shadow-testing

シャドーテストスキル

目的 [LEVEL 1]

シャドーテストでは、ホストシステムに影響を与えたり、リモートリポジトリにプッシュしたりすることなく、ローカルの未コミット変更をテストできる隔離されたコンテナ環境を作成します。

基本原則：CI と同様のクリーンで隔離された環境で、マシン上にあるもの（未コミット変更を含む）をそのままテストします。

このスキルを使う場面 [LEVEL 1]

特に適した用途

• プッシュ前の検証：変更をコミット／プッシュする前にテストする
• 複数リポジトリの連携：複数のリポジトリにまたがる変更が連携して動作することを検証する
• クリーンな状態でのテスト：「新しいマシンで動作するか」を確認する
• ライブラリ開発：依存プロジェクトでライブラリの変更をテストする
• CI との同等性確認：プッシュ前に CI から見える内容を確認する
• 破壊的なテスト：システム状態を変更するテストがホストに影響しない

次のような場合にこのスキルを使います

• 他のプロジェクトが依存するライブラリに破壊的変更を加える
• 複数のリポジトリにまたがる変更を調整する
• 変更が CI で動作するか確信が持てない
• 特定のバージョンの依存関係でテストする必要がある
• インストール／セットアップ手順が機能することを確認したい
• クリーンな環境状態が必要な変更をテストする

次のような場合はこのスキルを使わないでください

• すでにコミット済みのコードでユニットテストを実行する（ローカルのテストランナーを使ってください）
• コードを変更しながらデバッグする必要がある（シャドーではスナップショットが取得されます）
• 本番環境へのデプロイをテストする（ステージング環境を使ってください）
• テストカバレッジが十分にある単純な単一ファイルの変更

基本概念 [LEVEL 1]

シャドー環境のアーキテクチャ

シャドー環境は、次の要素を備えた Docker/Podman コンテナです。

1. Git バンドルのスナップショット - 作業ツリーの正確な状態（未コミット変更を含む）
2. 組み込み Gitea サーバー - コンテナ内の localhost:3000 で動作するローカル Git サーバー
3. 選択的な URL 書き換え - Git の insteadOf ルールにより、特定のリポジトリをローカル Gitea にリダイレクト
4. パッケージマネージャーの分離 - UV、pip、npm、cargo、go のキャッシュをシャドーごとに分離
5. API キーの引き継ぎ - 一般的な API キーを自動的にコンテナに引き継ぎ

┌─────────────────────────────────────────────────────────┐
│  Shadow Container                                       │
│  ┌───────────────────────────────────────────────────┐  │
│  │  Gitea Server (localhost:3000)                    │  │
│  │  - myorg/my-library (your snapshot)               │  │
│  └───────────────────────────────────────────────────┘  │
│                                                         │
│  Git URL Rewriting:                                     │
│  github.com/myorg/my-library → Gitea (local)           │
│  github.com/myorg/other-repo → Real GitHub             │
│                                                         │
│  /workspace (pre-cloned local sources)                 │
└─────────────────────────────────────────────────────────┘

Git URL の書き換えの仕組み

~/repos/my-lib:myorg/my-lib を指定してシャドーを作成すると、次のようになります。

1. 作業ディレクトリがそのままの状態で取得されます（未コミット変更を含む）
2. スナップショットが完全な Git 履歴とともにバンドルされます
3. Gitea サーバーを起動してコンテナが立ち上がります
4. スナップショットが myorg/my-lib として Gitea にプッシュされます
5. Git 設定に insteadOf ルールが追加されます。

   [url "http://shadow:shadow@localhost:3000/myorg/my-lib.git"]
       insteadOf = https://github.com/myorg/my-lib.git
   

6. git clone https://github.com/myorg/my-lib を実行すると、あなたのローカルスナップショットが使われます
7. その他の GitHub URL はすべて、実際の GitHub から取得されます

結果：指定したリポジトリのみがローカルで使われ、それ以外はすべて本番のソースが使われます。

クイックスタート [LEVEL 1]

インストール

Amplifier ユーザー向け（ネイティブ統合）：

# Shadow tool is built-in - no installation needed
amplifier run --bundle amplihack

その他のエージェント向け（スタンドアロン CLI）：

# Install via uvx (recommended)
uvx amplifier-shadow --version

# Or via pip
pip install amplifier-bundle-shadow

# Verify installation
amplifier-shadow --version

前提条件：

• Docker または Podman がインストールされ、起動していること
• Git がインストールされていること

最初のシャドー（CLI）

# Create shadow with your local library changes
amplifier-shadow create --local ~/repos/my-library:myorg/my-library --name test-lib

# Inside the shadow, install via git URL
# → my-library uses YOUR LOCAL snapshot
# → all other dependencies fetch from REAL GitHub
amplifier-shadow exec test-lib "uv pip install git+https://github.com/myorg/my-library"

# Run tests
amplifier-shadow exec test-lib "cd /workspace && pytest"

# See what changed
amplifier-shadow diff test-lib

# Clean up when done
amplifier-shadow destroy test-lib

最初のシャドー（Amplifier ツール）

# Create shadow with local changes
shadow.create(local_sources=["~/repos/my-library:myorg/my-library"])

# Execute commands
shadow.exec(shadow_id, "uv pip install git+https://github.com/myorg/my-library")
shadow.exec(shadow_id, "pytest tests/")

# Extract results
shadow.extract(shadow_id, "/workspace/test-results", "./results")

# Cleanup
shadow.destroy(shadow_id)

エージェントの種類別ツールリファレンス [LEVEL 2]

Amplifier（ネイティブ統合）

最適な使用体験 - シャドーは自動セットアップに対応したファーストクラスのツールです。

# All operations via shadow tool
result = shadow.create(
    local_sources=["~/repos/lib:org/lib"],
    verify=True  # Automatic smoke test
)

# Integrated error handling and observability
if result.ready:
    shadow.exec(result.shadow_id, "pytest")

機能：

• API キーの自動引き継ぎ
• スモークテストとヘルスチェックを内蔵
• 他の Amplifier ツールと統合
• セッションを考慮したクリーンアップ

Claude Code スタンドアロン

bash ツールから CLI を直接使います。

# All operations via amplifier-shadow CLI
uvx amplifier-shadow create --local ~/repos/my-lib:org/my-lib --name test

uvx amplifier-shadow exec test "pip install -e /workspace/org/my-lib"
uvx amplifier-shadow exec test "pytest"

uvx amplifier-shadow destroy test

GitHub Copilot

Claude Code と同じ CLI インターフェースです。

# Install once
pip install amplifier-bundle-shadow

# Use in workflow
amplifier-shadow create --local ~/repos/lib:org/lib
amplifier-shadow exec shadow-xxx "npm install && npm test"

手動／DIY（任意のエージェント）

付属のシェルスクリプトと Docker Compose の例を使います（レベル 3 を参照）。

よくあるパターン [LEVEL 2]

パターン：公開前にライブラリの変更をテストする

# Test your library with its dependents
amplifier-shadow create --local ~/repos/my-library:myorg/my-library --name lib-test

# Clone dependent project and install
amplifier-shadow exec lib-test "
  cd /workspace &&
  git clone https://github.com/myorg/dependent-app &&
  cd dependent-app &&
  uv venv && . .venv/bin/activate &&
  uv pip install git+https://github.com/myorg/my-library &&
  pytest
"

パターン：複数リポジトリにまたがる変更

# Testing changes across multiple repos
amplifier-shadow create \
    --local ~/repos/core-lib:myorg/core-lib \
    --local ~/repos/cli-tool:myorg/cli-tool \
    --name multi-test

# Both local sources will be used
amplifier-shadow exec multi-test "uv pip install git+https://github.com/myorg/cli-tool"

パターン：失敗を繰り返し検証する

# 1. Create shadow and run tests
amplifier-shadow create --local ~/repos/lib:org/lib --name test
amplifier-shadow exec test "pytest" # Fails

# 2. Fix code locally on host

# 3. Destroy and recreate (picks up your local changes)
amplifier-shadow destroy test
amplifier-shadow create --local ~/repos/lib:org/lib --name test
amplifier-shadow exec test "pytest" # Passes

# 4. Commit with confidence!
git commit -m "Fix issue"

パターン：プッシュ前の CI 検証

# Run your CI script in shadow before pushing
amplifier-shadow create --local ~/repos/project:org/project --name ci-check

amplifier-shadow exec ci-check "
  cd /workspace/org/project &&
  ./scripts/ci.sh
"

# If CI script passes, your push will likely succeed

検証のベストプラクティス [LEVEL 2]

ローカルソースが使われていることを必ず確認する

シャドーを作成した後、実際にローカルコードが使われていることを確認します。

# Step 1: Check snapshot commits (from create output)
amplifier-shadow create --local ~/repos/lib:org/lib
# Output shows: snapshot_commits: {"org/lib": "abc1234..."}

# Step 2: Compare with install output
amplifier-shadow exec shadow-xxx "uv pip install git+https://github.com/org/lib"
# Look for: lib @ git+...@abc1234

# If commits match, your local code is being used!

事前にクローンされたリポジトリの場所

ローカルソースは自動的に /workspace/{org}/{repo} にクローンされます。

# Your local source microsoft/my-library is available at:
/workspace/microsoft/my-library

# Use for editable installs (Python)
amplifier-shadow exec shadow-xxx "pip install -e /workspace/microsoft/my-library"

# Or for Node.js
amplifier-shadow exec shadow-xxx "cd /workspace/microsoft/my-package && npm install"

必ず最初にこの場所を確認してください。リポジトリはすでにそこにあります。

環境変数の確認

# Don't assume - verify API keys are present!
amplifier-shadow exec shadow-xxx "env | grep API_KEY"

# Check all passed variables
amplifier-shadow status shadow-xxx
# Shows: env_vars_passed: ["ANTHROPIC_API_KEY", ...]

トラブルシューティング [LEVEL 2]

よくある問題

「UV tool install」がローカルソースではなくキャッシュを使用する：

問題：UV は、キャッシュされたパッケージに対する Git URL の書き換えを回避する場合があります。

解決策：

# Option 1: Install from pre-cloned workspace (recommended)
amplifier-shadow exec xxx "pip install -e /workspace/org/lib"

# Option 2: Clear UV cache first
amplifier-shadow exec xxx "rm -rf /tmp/uv-cache && uv tool install git+https://github.com/org/lib"

「PEP 668: 外部管理環境」：

解決策：必ず shadow 内で仮想環境を使用してください。

amplifier-shadow exec xxx "
  cd /workspace &&
  uv venv &&
  . .venv/bin/activate &&
  uv pip install ...
"

「コンテナイメージが見つからない」：

解決策：イメージをローカルでビルドしてください。

amplifier-shadow build

「/workspace のアクセスが拒否されました」：

解決策：代わりに $HOME または /tmp を使用してください。

amplifier-shadow exec xxx "cd $HOME && git clone ..."

レベル 3：高度なトピック [LEVEL 3]

カスタム Docker イメージ

追加のツールを含む独自の shadow イメージをビルドします。

FROM ghcr.io/microsoft/amplifier-shadow:latest

# Add your tools
RUN apt-get update && apt-get install -y \
    postgresql-client \
    redis-tools

# Add custom scripts
COPY my-test-script.sh /usr/local/bin/

ビルドして使用します。

docker build -t my-shadow:latest .
amplifier-shadow create --image my-shadow:latest --local ~/repos/lib:org/lib

シェルスクリプト（DIY Shadow セットアップ）

Amplifier にアクセスできないエージェントは、以下のスタンドアロンスクリプトを使用してください。

スクリプト 1：Git Bundle の作成（scripts/create-bundle.sh）：

#!/bin/bash
# Create git bundle snapshot of working tree

REPO_PATH=$1
OUTPUT_PATH=$2

cd "$REPO_PATH"

# Fetch all refs to ensure complete history
git fetch --all --tags --quiet 2>/dev/null || true

# Check for uncommitted changes
if [[ -n $(git status --porcelain) ]]; then
    # Create temp clone and commit changes
    TEMP_DIR=$(mktemp -d)
    git clone --quiet "$REPO_PATH" "$TEMP_DIR"

    # Sync working tree (including deletions)
    rsync -a --delete --exclude='.git' "$REPO_PATH/" "$TEMP_DIR/"

    cd "$TEMP_DIR"
    git add -A
    git commit --allow-empty -m "Shadow snapshot" --author="Shadow <shadow@localhost>"

    # Create bundle
    git bundle create "$OUTPUT_PATH" --all

    cd /
    rm -rf "$TEMP_DIR"
else
    # Clean repo - just bundle it
    git bundle create "$OUTPUT_PATH" --all
fi

echo "Bundle created: $OUTPUT_PATH"

スクリプト 2：Shadow コンテナのセットアップ（scripts/setup-shadow.sh）：

#!/bin/bash
# Start container with Gitea and configure git URL rewriting

CONTAINER_NAME=$1
BUNDLE_PATH=$2
ORG=$3
REPO=$4

# Start container
docker run -d \
    --name "$CONTAINER_NAME" \
    -v "$BUNDLE_PATH:/snapshots/bundle.git:ro" \
    ghcr.io/microsoft/amplifier-shadow:latest

# Wait for Gitea
echo "Waiting for Gitea to start..."
until docker exec "$CONTAINER_NAME" curl -sf http://localhost:3000/api/v1/version > /dev/null; do
    sleep 1
done

# Create org and repo in Gitea
docker exec "$CONTAINER_NAME" bash -c "
    curl -s -u shadow:shadow \
        -H 'Content-Type: application/json' \
        -d '{\"username\":\"$ORG\"}' \
        http://localhost:3000/api/v1/orgs

    curl -s -u shadow:shadow \
        -H 'Content-Type: application/json' \
        -d '{\"name\":\"$REPO\",\"private\":false}' \
        http://localhost:3000/api/v1/orgs/$ORG/repos
"

# Push bundle to Gitea
docker exec "$CONTAINER_NAME" bash -c "
    cd /tmp &&
    git init --bare repo.git &&
    cd repo.git &&
    git fetch /snapshots/bundle.git refs/heads/*:refs/heads/* &&
    git remote add origin http://shadow:shadow@localhost:3000/$ORG/$REPO.git &&
    git push origin --all --force
"

# Configure git URL rewriting
docker exec "$CONTAINER_NAME" bash -c "
    git config --global url.'http://shadow:shadow@localhost:3000/$ORG/$REPO.git'.insteadOf 'https://github.com/$ORG/$REPO.git'
"

echo "Shadow container ready: $CONTAINER_NAME"
echo "Local source: $ORG/$REPO"

使用方法：

# Create bundle from your repo
./scripts/create-bundle.sh ~/repos/my-lib /tmp/my-lib.bundle

# Setup shadow container
./scripts/setup-shadow.sh shadow-test /tmp/my-lib.bundle myorg my-lib

# Test
docker exec shadow-test bash -c "
    git clone https://github.com/myorg/my-lib /tmp/test &&
    cd /tmp/test &&
    git log -1 --oneline
"

Docker Compose の例

例 1：単一リポジトリ（docker-compose/single-repo.yml）：

version: "3.8"

services:
  shadow:
    image: ghcr.io/microsoft/amplifier-shadow:latest
    container_name: shadow-single
    volumes:
      - ./snapshots:/snapshots:ro
      - ./workspace:/workspace
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    command: >
      bash -c "
        /usr/local/bin/gitea-init.sh &&
        tail -f /dev/null
      "

例 2：複数リポジトリのテスト（docker-compose/multi-repo.yml）：

version: "3.8"

services:
  shadow-multi:
    image: ghcr.io/microsoft/amplifier-shadow:latest
    container_name: shadow-multi
    volumes:
      # Mount multiple bundles
      - ./snapshots/core-lib.bundle:/snapshots/org/core-lib.bundle:ro
      - ./snapshots/cli-tool.bundle:/snapshots/org/cli-tool.bundle:ro
      - ./workspace:/workspace
    environment:
      # Pass API keys from host
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      # UV cache isolation
      - UV_CACHE_DIR=/tmp/uv-cache
    command: >
      bash -c "
        /usr/local/bin/gitea-init.sh &&
        /usr/local/bin/setup-repos.sh org/core-lib org/cli-tool &&
        tail -f /dev/null
      "

使用方法：

# Create bundles for your repos
git -C ~/repos/core-lib bundle create snapshots/core-lib.bundle --all
git -C ~/repos/cli-tool bundle create snapshots/cli-tool.bundle --all

# Start shadow
docker-compose -f docker-compose/multi-repo.yml up -d

# Run tests
docker-compose exec shadow-multi bash -c "
    cd /workspace &&
    git clone https://github.com/org/cli-tool &&
    cd cli-tool &&
    uv pip install -e .
    pytest
"

# Cleanup
docker-compose down

例 3：CI 統合（docker-compose/ci-shadow.yml）：

version: "3.8"

services:
  ci-shadow:
    image: ghcr.io/microsoft/amplifier-shadow:latest
    container_name: ci-shadow
    volumes:
      - ./snapshots:/snapshots:ro
      - ./test-results:/test-results
    environment:
      - CI=true
      - GITHUB_ACTIONS=true
    command: >
      bash -c "
        /usr/local/bin/gitea-init.sh &&
        /usr/local/bin/run-ci-tests.sh > /test-results/output.log 2>&1
      "

GitHub Actions との統合：

# .github/workflows/shadow-test.yml
name: Shadow Test

on: [push, pull_request]

jobs:
  shadow-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Create git bundle
        run: git bundle create snapshot.bundle --all

      - name: Run shadow tests
        run: |
          docker run --rm \
            -v $PWD/snapshot.bundle:/snapshots/bundle.git:ro \
            ghcr.io/microsoft/amplifier-shadow:latest \
            /usr/local/bin/test-in-shadow.sh org/repo

Outside-In テストとの統合

shadow 環境とエージェント型 Outside-In テストを組み合わせます。

# Create shadow with local changes
amplifier-shadow create --local ~/repos/lib:org/lib --name test

# Run outside-in test scenarios inside shadow
amplifier-shadow exec test "gadugi-agentic-test run test-scenario.yaml"

# Extract evidence
amplifier-shadow extract test /evidence ./test-evidence

完全な統合例については、qa-team スキルを参照してください（outside-in-testing はエイリアスとして引き続き使用できます）。

ベストプラクティス [LEVEL 2]

1. ソースが使用されていることを必ず確認する

決めつけずに、shadow が実際にローカルコードを使用していることを確認してください。

# Check snapshot commits
amplifier-shadow status shadow-xxx | grep snapshot_commit

# Verify install resolves to that commit
amplifier-shadow exec shadow-xxx "pip install git+https://github.com/org/lib" | grep "org/lib @"

2. 事前にクローンされたワークスペースを使用する

ローカルソースは自動的に /workspace/{org}/{repo} に配置されます。

# ✅ FAST: Use pre-cloned repo
amplifier-shadow exec xxx "pip install -e /workspace/org/lib"

# ❌ SLOWER: Clone again
amplifier-shadow exec xxx "git clone https://github.com/org/lib && pip install -e lib"

3. パッケージマネージャーのキャッシュを分離する

shadow 環境では、古いパッケージを防ぐためにキャッシュが自動的に分離されます。

• Python UV：/tmp/uv-cache
• Python pip：/tmp/pip-cache
• Node npm：/tmp/npm-cache
• Rust cargo：/tmp/cargo-home
• Go モジュール：/tmp/go-mod-cache

これらは自動的に設定されるため、操作は不要です。

4. 必要な環境変数を渡す

# Amplifier (automatic for common API keys)
shadow.create(local_sources=["~/repos/lib:org/lib"])

# CLI (explicit)
amplifier-shadow create \
    --local ~/repos/lib:org/lib \
    --env ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
    --env CUSTOM_VAR=value

5. テスト後にクリーンアップする

# Always destroy shadows when done
amplifier-shadow destroy shadow-xxx

# Or destroy all
amplifier-shadow destroy-all

6. わかりやすさのために名前付き shadow を使用する

# ✅ GOOD: Descriptive name
amplifier-shadow create --local ~/repos/lib:org/lib --name test-breaking-change

# ❌ BAD: Auto-generated
amplifier-shadow create --local ~/repos/lib:org/lib
# Creates shadow-a3f2b8c1 (hard to remember)

統合パターン [LEVEL 3]

パターン：Shadow + Outside-In テスト

shadow による分離と宣言型のテストシナリオを組み合わせます。

# test-scenario.yaml
scenario:
  name: "Library Integration Test"
  type: cli

  steps:
    - action: launch
      target: "/workspace/org/lib/cli.py"

    - action: verify_output
      contains: "Success"

shadow 内で実行します。

amplifier-shadow create --local ~/repos/lib:org/lib --name test
amplifier-shadow exec test "gadugi-agentic-test run test-scenario.yaml"

パターン：Shadow + pytest

amplifier-shadow create --local ~/repos/lib:org/lib --name pytest-run

amplifier-shadow exec pytest-run "
  cd /workspace/org/lib &&
  uv venv && . .venv/bin/activate &&
  pip install -e '.[dev]' &&
  pytest --cov=src --cov-report=html
"

# Extract coverage report
amplifier-shadow extract pytest-run /workspace/org/lib/htmlcov ./coverage-report

パターン：Shadow + npm test

amplifier-shadow create --local ~/repos/pkg:org/pkg --name npm-test

amplifier-shadow exec npm-test "
  cd /workspace/org/pkg &&
  npm install &&
  npm test
"

パターン：Shadow + cargo test

amplifier-shadow create --local ~/repos/crate:org/crate --name cargo-test

amplifier-shadow exec cargo-test "
  cd /workspace/org/crate &&
  cargo build &&
  cargo test
"

哲学との整合性 [LEVEL 2]

このスキルは、amplihack の中核原則に従っています。

徹底したシンプルさ

• 最小限の抽象化：Shadow = コンテナ + gitea + URL の書き換え
• フレームワークなし：Docker、git、シェルスクリプトのみ
• 必要なものだけ：必要なものだけを取得します（ファイルシステム全体ではなく git bundle）

モジュール設計（Bricks & Studs）

• 自己完結型：各 shadow は独立しています
• 明確な契約：Git URL を入力し、ローカルソースを出力します
• 組み合わせ可能：他のテストツールと組み合わせられます

BS を排した実装

• スタブなし：すべてのスクリプトが完全に動作します
• 動作するデフォルト設定：すべての操作に妥当なデフォルト設定を用意しています
• 明確なエラー：トラブルシューティングにつながる、実行可能なエラーメッセージを表示します

Outside-In の考え方

• ユーザーの視点：ユーザーに見えるものをテストします
• 実装に依存しない：コードの内部動作は問いません
• 振る舞いを重視：結果に焦点を当てます

CLI リファレンス [LEVEL 3]

コマンド

# Create shadow environment
amplifier-shadow create [OPTIONS]
  --local, -l TEXT    Local source mapping: /path/to/repo:org/name (repeatable)
  --name, -n TEXT     Name for environment (auto-generated if not provided)
  --image, -i TEXT    Container image (default: amplifier-shadow:local)
  --env, -e TEXT      Environment variable: KEY=VALUE or KEY to inherit (repeatable)
  --env-file FILE     File with environment variables (one per line)
  --pass-api-keys     Auto-pass common API key env vars (default: enabled)

# Execute command in shadow
amplifier-shadow exec SHADOW_ID COMMAND
  --timeout INTEGER   Timeout in seconds (default: 300)

# Show changed files
amplifier-shadow diff SHADOW_ID [PATH]

# Extract file from shadow
amplifier-shadow extract SHADOW_ID CONTAINER_PATH HOST_PATH

# Inject file into shadow
amplifier-shadow inject SHADOW_ID HOST_PATH CONTAINER_PATH

# List all shadows
amplifier-shadow list

# Show shadow status
amplifier-shadow status SHADOW_ID

# Destroy shadow
amplifier-shadow destroy SHADOW_ID
  --force             Force destruction even on errors

# Destroy all shadows
amplifier-shadow destroy-all
  --force             Force destruction even on errors

# Build shadow image locally
amplifier-shadow build

# Open interactive shell
amplifier-shadow shell SHADOW_ID

クイックリファレンスカード [LEVEL 1]

# Typical workflow
amplifier-shadow create --local ~/repos/lib:org/lib --name test
amplifier-shadow exec test "pytest"
amplifier-shadow destroy test

# Multi-repo
amplifier-shadow create \
  --local ~/repos/lib1:org/lib1 \
  --local ~/repos/lib2:org/lib2 \
  --name multi

# With environment variables
amplifier-shadow create \
  --local ~/repos/lib:org/lib \
  --env API_KEY=$API_KEY \
  --name test

# Interactive shell
amplifier-shadow shell test

# Extract results
amplifier-shadow extract test /workspace/results ./local-results

関連スキル [LEVEL 1]

• qa-team：シャドウ環境でエージェントテストを実行します（旧名称：outside-in-testing）
• test-gap-analyzer：未テストのコードパスを特定します（シャドウテストを補完）
• philosophy-guardian：シャドウスクリプトが徹底したシンプルさに従っていることを確認します

トラブルシューティングのチェックリスト [LEVEL 2]

シャドウテストが失敗した場合：

• ローカルソースが使用されていることを確認します（スナップショットのコミットを確認）
• クローン済みリポジトリが /workspace/{org}/{repo} に存在することを確認します
• 環境変数が渡されていることを確認します（シャドウ環境内で env を実行）
• 古い場合はパッケージマネージャーのキャッシュをクリアします
• Git URL の書き換えが設定されていることを確認します（git config --list）
• Gitea にアクセスできることを確認します（curl http://localhost:3000/api/v1/version）
• 仮想環境を使用します（PEP 668 エラーを回避）
• コンテナが実行中であることを確認します（amplifier-shadow status）

変更履歴 [LEVEL 3]

バージョン 1.0.0（2026-01-29）

• スキルの初回リリース
• Amplifier、Claude Code、GitHub Copilot、手動での DIY をサポート
• 単独で使用するためのシェルスクリプト
• CI 統合用の Docker Compose の例
• CLI リファレンスとトラブルシューティングガイドの全項目
• qa-team / outside-in-testing エイリアスとの統合パターン
• 徹底したシンプルさを重視する哲学との整合性

---

覚えておいてください：シャドウ環境を使うと、CI を再現したクリーンで隔離された環境で、マシン上にある内容（未コミットの変更を含む）をそのままテストできます。問題を早期に発見するため、大きな変更をプッシュする前には必ず使用してください。