リポジトリ環境セットアップ＆CI/CD自動化スキル

ユニバーサルリポジトリセットアップ＆環境スキル (setup-repository)

このスキルは、あらゆるソフトウェアリポジトリに対して、標準的な開発環境のセットアップ、構成、検証を行います。プロジェクトメタデータの自動検出、Git の品質管理、codebase-memory-mcp によるコードインテリジェンス（ワークスペースおよび Google Antigravity / AGY のみ のグローバル設定）、Husky & Commitlint によるコミット標準化、本番環境向け Docker コンテナ化、そして自動化された Release Please & マルチアーキテクチャ GHCR CI/CD デプロイを処理します。

---

ワークフロー概要

flowchart TD
    A["1. 自動検出 & ゼロ中断スキャン"] --> B["2. プロジェクトメタデータの真実（docs/project.json）"]
    B --> C["3. Codebase Memory MCP セットアップ（ワークスペース & AGY グローバル）"]
    C --> D["4. Git Hooks & Commitlint 構成"]
    D --> E["5. 本番用 Docker & Compose スタック"]
    E --> F["6. Release Please & マルチアーキテクチャ GHCR CI/CD"]
    F --> G["7. 環境健全性確認"]
    G --> H["8. 標準化された実行レポート & Git ガイダンス"]

---

ステップ 1: 自動検出 & リポジトリスキャン（ゼロ中断ルール）

[!IMPORTANT] リポジトリファイルに情報が存在する場合は、ユーザーにプロンプトを表示しないでください。 最初にリポジトリファイル、設定、および docs/ 内のドキュメントをスキャンします。ランタイム、ツール、規約を自動的に推定します。設定が不明確または不足している場合にのみ、ユーザーに質問してください。

1.1. 自動検査（ゼロ中断ルール）

1. フレームワークとランタイムの検出:
   • パッケージマニフェストを検査: package.json (Node/Bun)、pyproject.toml / requirements.txt (Python)、Cargo.toml (Rust)、go.mod (Go) など。
   • ロックファイルからパッケージマネージャーを検出:
     • pnpm-lock.yaml → pnpm
     • bun.lockb / bun.lock → bun
     • yarn.lock → yarn
     • package-lock.json → npm
2. 既存ドキュメントのスキャン:
   • CONTEXT.md、docs/plan.md、docs/adr/*.md、README.md を読み込み、アーキテクチャ標準、テストスイート、言語規約を抽出します。
3. Git ワーキングツリーの確認:
   • Git のステータスとブランチを確認します。すべての検査およびコマンドステップは、単一の操作として個別に実行し、チェーンにしてはいけません。

1.2. 対話型明確化（AI 支援型スキャフォールディング）

既存ファイルから重要なパラメータが不足、曖昧、または決定できない場合は、明確な選択肢を用いてユーザーに質問を投げかけます:

### 📋 リポジトリセットアップ & CI/CD 構成

このリポジトリの標準 CI/CD ワークフローを構成するために、以下を確認または指定してください:

1. **主要言語 & ランタイム**: (例: Node.js / TypeScript, Python, Go, Rust, Java, C++)
2. **テストコマンド**: (例: `pnpm test`, `pytest`, `cargo test`, `go test ./...`)
3. **ビルドコマンド**: (例: `pnpm run build`, `cargo build --release`, `go build`, `なし`)
4. **リリース / 公開ターゲット**:
   - [ ] Docker コンテナイメージ (GHCR / Docker Hub)
   - [ ] パッケージレジストリ (npm, PyPI, Crates.io, Maven)
   - [ ] バイナリリリース成果物 (GitHub Releases)
   - [ ] 静的サイト / ドキュメント (GitHub Pages)
   - [ ] なし (CI テスト & SemVer Git タグのみ)

---

ステップ 2: プロジェクトメタデータの真実 (docs/project.json)

中央で機械可読な設定ファイル docs/project.json を維持し、すべての AI エージェントと専門スキルが同一のコンテキストを共有できるようにします。

標準 docs/project.json テンプレート:

{
  "project_context_and_metadata": {
    "project_name": "my-project",
    "runtime": "node",
    "package_manager": "pnpm",
    "source_dir": "src",
    "test_command": "pnpm test",
    "build_command": "pnpm run build",
    "testing_library": ["jest", "playwright"],
    "containerization": "docker-standalone",
    "ci_cd_provider": "github-actions",
    "release_automation": "release-please",
    "publish_target": "container"
  }
}

1. docs/ ディレクトリが存在することを確認します。
2. 検出または確認された構成値で docs/project.json を書き込むか更新します。

---

ステップ 3: codebase-memory-mcp コードインテリジェンスサーバーのセットアップ

リポジトリに codebase-memory-mcp 永続的知識グラフサーバー（162言語、Tree-sitter AST、ハイブリッド LSP セマンティック型解決、100% ローカルベクトル検索）を装備します。

3.1. バイナリのインストール

プラットフォームに応じた方法を選択:

• Windows (PowerShell) :

  Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1
  Unblock-File .\install.ps1
  .\install.ps1
  Remove-Item .\install.ps1
  

• macOS / Linux (Bash) :

  curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
  

• グローバル npm パッケージの代替:

  npm install -g codebase-memory-mcp@latest
  

3.2. MCP サーバーの登録（ワークスペース & AGY グローバル限定）

[!IMPORTANT] グローバル MCP 登録は Antigravity (AGY) のみ対象です。 Antigravity はホストシステムにグローバルに設定された MCP サーバーを検出してロードします。他のコーディングエージェント（例: Claude Desktop、Cursor、VS Code、Cline）に対して MCP サーバーをグローバルに設定または登録しないでください。 以下の場所に MCP サーバーを登録します:

1. ワークスペースルート mcp.json:

   {
     "mcpServers": {
       "codebase-memory": {
         "command": "codebase-memory-mcp",
         "args": []
       }
     }
   }
   

2. ワークスペースエージェント設定 (.agents/mcp_config.json) (リポジトリが .agents/ を使用する場合):

   {
     "mcpServers": {
       "codebase-memory": {
         "command": "codebase-memory-mcp",
         "args": []
       }
     }
   }
   

3. グローバルホスト設定（Google Antigravity / AGY のみ）: AGY ホスト設定に厳密に codebase-memory を追加:
   • ~/.gemini/antigravity/mcp_config.json
   • ~/.gemini/config/mcp_config.json (Claude Desktop、Cursor、または他のコーディングエージェントには登録しないでください):

   {
     "mcpServers": {
       "codebase-memory": {
         "command": "codebase-memory-mcp",
         "args": []
       }
     }
   }
   

3.3. .cbmignore 除外設定の構成（エディタのスタッターと検出チャーンを防止）

• ローカル限定（デフォルト）: .codebase-memory/ を .gitignore に追加。

[!IMPORTANT] スタッター防止 & 高チャーン除外 (.cbmignore): codebase-memory-mcp は、リポジトリルート (<repo>/.cbmignore) に厳密に配置された .cbmignore ファイルを .gitignore 構文で読み取ります。.cbmignore がない場合、非コードファイル（計画ドキュメント、エージェントメモリ、テスト成果物、ビルドキャッシュなど）が編集されるたびに、継続的な AST 検出、型解決、ディスク書き込みがトリガーされます。 常にリポジトリルートに <repo>/.cbmignore を生成してください:

# codebase-memory-mcp 無視ルール (.cbmignore)
# 非コードおよび高チャーンファイルがグラフインデックスをトリガーしたり、AST グラフを肥大化させるのを防ぎます。

# エージェントログ、メタデータ、計画ドキュメント（アクティブセッション中は高チャーン）
.agents/
docs/
*.md

# ビルド成果物 & コンパイルキャッシュ
dist/
build/
out/
.next/
.swc/

# テスト、レポート、カバレッジ
coverage/
test-results/
playwright-report/
blob-report/
.playwright-mcp/
storybook-static/
*storybook.log

# Codebase Memory ローカル成果物（自己トリガーループを防止）
.codebase-memory/

# システムとログ
*.log
*.tsbuildinfo
.DS_Store

# 静的アセットとメディア（コードシンボルはゼロ）
public/
assets/
*.png
*.jpg
*.jpeg
*.gif
*.svg
*.ico
*.webp
*.mp4
*.mp3
*.pdf

# 環境変数 & ロックファイル
.env*
*.pem
*.lock
pnpm-lock.yaml
package-lock.json
yarn.lock
bun.lockb

3.4. 自動セッションファイル監視の無効化 (auto_watch = false)

[!CAUTION] システムスタッターの防止: デフォルトでは、codebase-memory-mcp は接続されたプロジェクトをバックグラウンド Git ウォッチャー (auto_watch = true) に自動登録します。Windows およびマルチタスクシステムでは、ウォッチャーがファイル保存を検出し、index.supervisor ワーカープロセスを起動し、キーストローク/保存のたびに zstd で .codebase-memory/graph.db.zst を圧縮するため、エディタ UI とウィンドウマネージャーに深刻なマイクロスタッターが発生します。 常にグローバルで自動セッション監視を無効にしてください:

codebase-memory-mcp config set auto_watch false

無効にすると、セッションはバックグラウンドウォッチャーに登録されず、エディタのフリーズが完全に解消されます。グラフは MCP ツールを介してクエリされ、オンデマンドで明示的にリフレッシュされます。

3.5. Git 品質管理 & 永続性

• ローカル限定（デフォルト）: .codebase-memory/ を .gitignore に追加します。バイナリ成果物を保存のたびにコミットしないでください。
• チームスナップショット共有: プリインデックスされたグラフスナップショットをチームでコミットする場合は、ルートの .gitattributes で Git LFS を使用して .codebase-memory/graph.db.zst を追跡します:

  .codebase-memory/graph.db.zst filter=lfs diff=lfs merge=lfs -text
  

3.6. 初期オンデマンドインデックス作成 & 定期的スクリプト

1. オンデマンドで初期インデックス作成を実行します（重いセマンティック埋め込み計算をスキップするために moderate または fast モードを使用）:

   codebase-memory-mcp cli index_repository --repo-path "<canonical-repo-path>"
   codebase-memory-mcp cli index_repository --repo-path "<canonical-repo-path>" --mode moderate
   

2. 主要なマイルストーン/コミットでインデックスをリフレッシュするための定期的スクリプトを package.json に追加します:

   {
     "scripts": {
       "cbm:update": "codebase-memory-mcp cli index_repository --repo-path . --mode moderate --persistence true"
     }
   }
   

---

ステップ 4: Husky & Commitlint を使用した Git Hooks のセットアップ

Conventional Commits を強制し、コードをリモートブランチにプッシュする前にテストスイートが確実に実行されるようにします。

1. 開発依存関係のインストール:

   pnpm add -D husky @commitlint/cli @commitlint/config-conventional
   

2. commitlint.config.mjs の構成:

   export default {
     extends: ["@commitlint/config-conventional"],
   };
   

3. Husky の初期化:

   pnpm exec husky init
   

4. commit-msg フックの構成:

   echo "pnpm exec commitlint --edit \$1" > .husky/commit-msg
   

5. pre-push フックの構成: 任意の git push の前にテストスイートの実行を強制:

   echo "pnpm run test:all" > .husky/pre-push
   

   [!NOTE] package.json のテストスクリプトに --passWithNoTests などのグレースフルフラグが含まれていることを確認し、テストファイルがないリポジトリでも終了コード 0 でプッシュが中断されないようにします。ワークスペースにサンプル/ダミーのテストファイルを作成しないでください。

---

ステップ 5: マルチステージ本番用 Docker コンテナ化のセットアップ

本番ビルドとデプロイ専用にコンテナ化を構成します。ローカル開発は、プロジェクトのネイティブパッケージマネージャーを使用してホストマシン上で実行します。

5.1. .dockerignore の構成

ローカル成果物、Git 履歴、シークレットを除外:

node_modules/
.pnp/
.pnpm-store/
dist/
build/
coverage/
test-results/
.env*
*.log
.git/
.dockerignore
Dockerfile*
docker-compose*.yml
.codebase-memory/

5.2. マルチステージ Dockerfile

セキュアな非 root ユーザーで実行される 3 ステージのマルチステージビルド (dependencies → builder → runner) を作成:

ARG NODE_VERSION=22-slim

FROM node:${NODE_VERSION} AS dependencies
WORKDIR /app
ENV CI=true
COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
RUN --mount=type=cache,target=/root/.local/share/pnpm/store \
  if [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm install --frozen-lockfile; \
  elif [ -f package-lock.json ]; then npm ci; \
  else yarn install --frozen-lockfile; fi

FROM node:${NODE_VERSION} AS builder
WORKDIR /app
COPY --from=dependencies /app/node_modules ./node_modules
COPY . .
ENV NODE_ENV=production
RUN if [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; else npm run build; fi

FROM node:${NODE_VERSION} AS runner
WORKDIR /app
ENV NODE_ENV=production
ARG PORT=3000
ENV PORT=${PORT}
ENV HOSTNAME="0.0.0.0"
COPY --from=builder --chown=node:node /app/dist ./dist
USER node
EXPOSE ${PORT}
CMD ["node", "dist/index.js"]

5.3. Docker Compose スタック

1. ローカルビルド & テスト (docker-compose.yml):

   services:
     app:
       build:
         context: .
         dockerfile: Dockerfile
       container_name: app-production
       restart: unless-stopped
       ports:
         - "${PORT:-3000}:${PORT:-3000}"
       environment:
         - NODE_ENV=production
   

2. 本番プレビルドスタック (docker-compose.prod.yml): ソースコードなしで GHCR から直接プレビルドされたマルチアーキテクチャイメージをプル:

   services:
     app:
       image: ghcr.io/<lowercase-owner>/<lowercase-repo>:${IMAGE_TAG:-latest}
       container_name: app-production
       restart: always
       ports:
         - "${PORT:-3000}:${PORT:-3000}"
       environment:
         - NODE_ENV=production
   

---

ステップ 6: クレジット最適化 CI/CD & Release Please 自動化のセットアップ

.github/workflows/release-please.yml を介して、セマンティックリリース、チェンジログ、およびマルチアーキテクチャ（AMD64 & ARM64）GitHub Container Registry への公開を自動化します:

コア DevOps 設計ルール:

1. 自動テストゲート: プルリクエストと main ブランチへのコミットでプロジェクトテストを実行します。
2. Release Please 自動化: バージョンアップ、チェンジログ、リリース PR を自動化します。
3. concurrency.cancel-in-progress: false: 進行中のリリースワークフローやメインブランチへのデプロイをキャンセルしないでください。
4. 2 ステージマルチアーキテクチャマトリックスビルダー: QEMU エミュレーションなしで、ネイティブランナーマシン（ubuntu-latest および ubuntu-24.04-arm）上で AMD64 および ARM64 をビルドします。イメージをダイジェストでプッシュします。
5. ダイジェストマニフェストマージ: 下流の merge-manifest ジョブが AMD64 と ARM64 のダイジェストを統合し、統一されたマルチアーキテクチャタグを作成します。
6. 小文字のリポジトリ名: github.repository を常に小文字に変換します。

ワークフローの作成

.github/workflows/release-please.yml を作成します:

name: Release Please & Multi-Arch GHCR

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: false

permissions:
  contents: write
  packages: write
  pull-requests: write
  id-token: write

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [22]
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
        with:
          version: 9
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm run test:all

  release-please:
    runs-on: ubuntu-latest
    needs: test
    if: github.ref == 'refs/heads/main'
    outputs:
      release_created: ${{ steps.release.outputs.release_created }}
      tag_name: ${{ steps.release.outputs.tag_name }}
    steps:
      - uses: googleapis/release-please-action@v4
        id: release
        with:
          release-type: node
          target-branch: main

  build-amd64:
    runs-on: ubuntu-latest
    needs: release-please
    if: needs.release-please.outputs.release_created == 'true'
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        id: push-amd64
        with:
          context: .
          file: Dockerfile
          platforms: linux/amd64
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ needs.release-please.outputs.tag_name }}-amd64
          labels: |
            org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
            org.opencontainers.image.version=${{ needs.release-please.outputs.tag_name }}
    outputs:
      amd64-digest: ${{ steps.push-amd64.outputs.digest }}

  build-arm64:
    runs-on: ubuntu-24.04-arm
    needs: release-please
    if: needs.release-please.outputs.release_created == 'true'
    steps:
      - uses: actions/checkout@v4
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        id: push-arm64
        with:
          context: .
          file: Dockerfile
          platforms: linux/arm64
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ needs.release-please.outputs.tag_name }}-arm64
          labels: |
            org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
            org.opencontainers.image.version=${{ needs.release-please.outputs.tag_name }}
    outputs:
      arm64-digest: ${{ steps.push-arm64.outputs.digest }}

  merge-manifest:
    runs-on: ubuntu-latest
    needs: [release-please, build-amd64, build-arm64]
    if: needs.release-please.outputs.release_created == 'true'
    steps:
      - uses: docker/setup-buildx-action@v3
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Create multi-arch manifest
        run: |
          REPO_LC=$(echo "${{ github.repository }}" | tr '[:upper:]' '[:lower:]')
          docker buildx imagetools create \
            -t ghcr.io/${REPO_LC}:${{ needs.release-please.outputs.tag_name }} \
            ghcr.io/${REPO_LC}:${{ needs.release-please.outputs.tag_name }}-amd64@${{ needs.build-amd64.outputs.amd64-digest }} \
            ghcr.io/${REPO_LC}:${{ needs.release-please.outputs.tag_name }}-arm64@${{ needs.build-arm64.outputs.arm64-digest }}
      - name: Tag latest
        run: |
          REPO_LC=$(echo "${{ github.repository }}" | tr '[:upper:]' '[:lower:]')
          docker buildx imagetools create \
            -t ghcr.io/${REPO_LC}:latest \
            ghcr.io/${REPO_LC}:${{ needs.release-please.outputs.tag_name }}

---

ステップ 7: 環境健全性確認

以下を確認して、セットアップが完全で機能することを確認します:

• プロジェクトメタデータ (docs/project.json) が存在し、正確である。
• codebase-memory-mcp バイナリがインストールされ、アクセス可能である。
• MCP サーバー構成が、ワークスペース mcp.json および該当する場合は AGY グローバルホスト設定に存在する。
• .cbmignore がリポジトリルートに存在する。
• Husky フック (commit-msg、pre-push) が機能している。
• commitlint.config.mjs が正しく構成されている。
• Dockerfile がビルド可能である (docker build --no-cache -t test-build .)。
• docker-compose.yml がサービスを開始できる (docker compose up -d)。
• GHCR ワークフローの GitHub Actions シークレットが構成されている。
• テストスクリプトが正常に実行される (既存のテストがパスするか、--passWithNoTests で終了コード 0 を返す)。

[!TIP] ワークフローが GHCR からプルできることを検証するには: docker compose -f docker-compose.prod.yml up -d

---

ステップ 8: 標準化実行レポート & Git ガイダンス

セットアップが完了したら、次の構造で標準化されたレポートを提供します:

## ✅ リポジトリセットアップ完了

### プロジェクトメタデータ
- **プロジェクト名**: `<name>`
- **ランタイム**: `<runtime>`
- **パッケージマネージャー**: `<package-manager>`
- **テストコマンド**: `<test-command>`
- **ビルドコマンド**: `<build-command>`
- **公開ターゲット**: `<publish-target>`

### コードインテリジェンス
- `codebase-memory-mcp`: ワークスペース `mcp.json` に登録済み (AGY グローバルのみ)
- 初期インデックス作成: `<completed|pending>`
- `.cbmignore`: 構成済み (高チャーン非コードファイルを除外)
- 自動監視: 無効 (エディタスタッター防止)

### Git Hooks
- Husky + Commitlint: 有効
- `pre-push` フック: プッシュ前に `<test-command>` を実行

### コンテナ化
- Dockerfile: マルチステージ (dependencies &rarr; builder &rarr; runner)
- Docker Compose: 利用可能 (ローカル & 本番スタック)

### CI/CD
- ワークフロー: `.github/workflows/release-please.yml`
- マルチアーキテクチャ: AMD64 + ARM64 (QEMU なし)
- GHCR 公開: 有効

### 次のステップ
1. 変更をコミット: `git add . && git commit -m "chore: setup development environment"`
2. リモートにプッシュ: `git push origin main`
3. リリース PR を監視 (Release Please によって自動生成されます)

---

トラブルシューティング & 注意事項

• commit-msg フックが壊れている: npx husky add .husky/commit-msg "pnpm exec commitlint --edit \$1" を実行して再初期化します。
• ビルドが Docker で失敗する: docker build --no-cache --progress=plain . を使用して詳細な出力を確認します。
• GHCR プッシュ権限エラー: ワークフローに packages: write 権限があることを確認し、リポジトリシークレットが設定されていることを確認します。
• codebase-memory-mcp インデックス作成エラー: バイナリが $PATH にあることを確認するか、npx codebase-memory-mcp を使用します。
• Husky フックがスキップされる: --no-verify フラグはプリプッシュフックをバイパスすることに注意してください。このフラグは慎重に使用してください。
• macOS Homebrew での ARM64 Docker: Dockerfile で FROM --platform=$BUILDPLATFORM を使用してクロスビルドの問題を解決します。