コンテンツにスキップ

開発環境

automedia の運用者・開発者が手元で git / aws CLI / tofu (OpenTofu) / Claude Code / Node を回すための環境方針。

OS 選択

OS 推奨度 補足
macOS ◎ 標準。チームの主流
Linux（Ubuntu 等） ◎ CI と同じ環境で再現性高い
Windows + WSL2 ◎ Windows 運用者は WSL2 を使う（後述）
Windows native（PowerShell / Git Bash） ✕ 非推奨。動作はするが安定運用に不向き

automedia の ドキュメント・スクリプト・OpenTofu 設定は全て Unix（bash + Linux パス）前提で書かれているため、Windows 運用者は WSL2 を使ってチームの他メンバーと同じ環境を共有する。

Windows 運用者向け: WSL2 セットアップ

推奨スタック

  • Windows 11 + WSL2 + Ubuntu 22.04 / 24.04 LTS
  • VS Code（Windows 側）+ WSL 拡張（VS Code から WSL に attach する形）
  • リポは WSL2 のホーム配下に clone（~/Projects/spin/...）。/mnt/c/... 配下は I/O が遅く git / npm で体感差が出る

必須ツールのインストール（WSL2 側）

# 基本
sudo apt update && sudo apt install -y git python3 python3-pip jq curl unzip

# gh CLI
(type -p wget >/dev/null || sudo apt-get install -y wget) \
  && sudo mkdir -p -m 755 /etc/apt/keyrings \
  && wget -nv -O- https://cli.github.com/packages/githubcli-archive-keyring.gpg \
     | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
  && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
     | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
  && sudo apt update && sudo apt install gh -y

# AWS CLI v2
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip && sudo ./aws/install

# OpenTofu
curl -fsSL https://get.opentofu.org/install-opentofu.sh | sh -s -- --install-method standalone

# Node 20+ (nvm 経由推奨)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
. ~/.nvm/nvm.sh && nvm install 20

# Claude Code (推奨)
# https://docs.claude.com/en/docs/claude-code/ を参照

AWS 認証 (spindd profile)

aws configure --profile spindd
# Access Key / Secret Access Key を入力
# region: ap-northeast-1
# output: json

~/.aws/credentials に [spindd] プロファイルが作成される。日常作業では AWS_PROFILE=spindd を export しておくと楽。

Backlog API Key

~/.zshrc (or ~/.bashrc) に追加:

export BACKLOG_API_KEY='<your-backlog-api-key>'

gh / git の認証

  • WSL2 側で gh auth login を実行（GitHub.com / SSH or HTTPS）
  • Windows Credential Manager 連携は 使わない（WSL2 と native の認証が混ざってトラブル源になる）
  • 個人の SSH 鍵は WSL2 ホームの ~/.ssh/ に置く

よくあるハマりどころ

症状 原因 対処
pre-commit hook が落ちる CRLF 改行混入 git config --global core.autocrlf input
npm install が極端に遅い リポを /mnt/c/ に置いている WSL ホーム ~/ 配下に移動
tofu apply で AWS API エラー profile / region が未設定 AWS_PROFILE=spindd + region=ap-northeast-1 を確認
ファイル監視（mkdocs serve）が効かない /mnt/c/ でのファイル変更検知の制約 WSL ホーム配下で起動

native Windows でやってよいこと

automedia のコードや secrets に 触れない 作業は Windows 側で問題ない:

  • ドキュメント閲覧（mkdocs / ブラウザ）
  • HubSpot / Backlog / LINE Official Account Manager の管理画面操作
  • AWS Console
  • Slack / Notion / Office 等のクライアントアプリ

Claude Code の 2 つの起動経路

automedia テーマリポでは claude の起動経路が 2 種類用意されており、運営者が用途に応じて opt-in で選ぶ:

起動方法 認証経路 用途
claude (直接) /login (Anthropic Console アカウント) 個人 Claude Code アカウントでの通常作業
./.automedia/bin/claude Claude Platform on AWS (AWS IAM) API キー不要・AWS 集約課金・CloudTrail 監査を伴う運営作業

両経路とも CLI 機能・skill 動作は同一で、認証と請求経路だけが異なる。

.automedia/bin/claude の動き

bin/automedia.mjs init で配布される launcher。実行すると:

  1. .automedia/project.json の aws.profile / aws.region / claude.workspaceId を読む
  2. aws sts get-caller-identity --profile <profile> で SSO 有効性を確認
  3. 期限切れなら aws sso login --profile <profile> を対話起動
  4. 以下 4 つを env に設定して claude を exec:
    • CLAUDE_CODE_USE_ANTHROPIC_AWS=1
    • CLAUDE_AWS_BASE_URL=https://aws-external-anthropic.<region>.api.aws
    • ANTHROPIC_AWS_WORKSPACE_ID=<workspace-id>
    • AWS_PROFILE / AWS_REGION

claude.workspaceId は spin-dd の Anthropic workspace ID。.automedia/project.json に未指定時は launcher 内のハードコード値 (wrkspc_01Jo...) を使う。将来テナント別 workspace を持つ場合のみ project.json で override する。

経路ごとの位置づけ

  • 個人アカウント (claude 直接) — Anthropic Console で課金。運営者個人の MAX プランや会社契約リソースを自由に使える
  • Claude Platform on AWS (./.automedia/bin/claude) — AWS 請求書に集約、CloudTrail に呼び出しが残る、IAM ロール経由で aws-external-anthropic:CreateInference 権限ベースに認可。組織として運営作業の監査・予算管理を一本化したいケース向け。Lambda 側 (Deliver Lambda) と同じ Claude Platform on AWS 経路をデスクトップから利用する形

既知の制約

  • claude が PATH に必要: launcher は exec claude するため、運営者 PC に Claude Code CLI 本体がインストールされていること
  • AWS CLI v2 が必要: SSO 検証に aws sts get-caller-identity / aws sso login を使う
  • tofu apply 必要: TenantOperator-<tenant> Permission Set に aws-external-anthropic:* + sts:GetWebIdentityToken の Statement が含まれている前提 (22-credentials.md §per-tenant Permission Set の権限例)。既存運営者の SSO セッションには反映されないため、Permission Set 変更後は aws sso logout && aws sso login で短期 STS を取り直す必要がある

CI との関係

CI は Ubuntu runner（GH Actions ubuntu-latest）で動く。WSL2 + Ubuntu はこの環境と最も近いため、ローカルで動けば CI でも動く 確度が高い。Windows native だと CI との差で再現困難なバグが出やすい。

関連