BIGboss248/nextjs-wordpress

通用倉庫設定與環境技能 (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) 等。
   • 從 lockfile 偵測套件管理器：
     • 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 Tags)

---

步驟 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）： 嚴格地將 codebase-memory 新增至 AGY 主機配置：

• ~/.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

# 環境與 Lockfile
.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。切勿在每次儲存時提交二進位工件。
• 團隊快照分享：如果要為團隊提交預索引的圖形快照，請使用 Git LFS 在根目錄 .gitattributes 中追蹤 .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>" --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 Hook：

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

5. 配置 pre-push Hook： 在允許任何 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

建立一個 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：設定 credit 優化的 CI/CD 與 Release Please 自動化

透過 .github/workflows/release-please.yml 自動化語意版本發布、變更日誌和多架構 (AMD64 & ARM64) GitHub Container Registry 發佈：

核心 DevOps 設計規則：

1. 自動化測試閘門：在 pull request 和提交到 main 分支時執行專案測試。
2. Release Please 自動化：自動化版本號提升、變更日誌和發布 PR。
3. concurrency.cancel-in-progress: false：絕不取消正在進行中的釋出工作流程或 main 分支部署。
4. 兩階段多架構矩陣建置器：在本機執行器機器（ubuntu-latest 和 ubuntu-24.04-arm）上建置 AMD64 和 ARM64，無需 QEMU 模擬。依摘要推送映像。
5. 摘要清單合併：下游的 merge-manifest 任務將 AMD64 和 ARM64 摘要合併為統一的 multi-arch 標籤。
6. 小寫倉庫名稱：透過 github.repository_owner 和 github.event.repository.name 將 github.repository 轉換為小寫，因為容器註冊表區分大小寫且規範為小寫。
7. 條件發佈：僅在 Release Please 建立 GitHub Release 時執行 GHCR 推送和標籤。

---

步驟 7：環境健全性驗證

執行最終檢查以確保所有元件正確運作：

1. 驗證 docs/project.json：確認檔案存在且格式正確。
2. 驗證 codebase-memory-mcp 安裝：

codebase-memory-mcp --version

3. 驗證 Git Hooks：檢查 .husky/ 目錄是否存在且包含正確的 hook 檔案。
4. 驗證 Docker 建置：執行 docker build -t test-validate . 以確保 Dockerfile 可建置。
5. 驗證 CI/CD 工作流程：確認 .github/workflows/ 中存在正確的工作流程檔案。

---

步驟 8：標準化執行報告

以可讀格式向使用者呈現結果摘要：

## ✅ 倉庫設定完成

已成功為 `<project-name>` 配置以下內容：

- **專案元資料**：`docs/project.json` ✓
- **Codebase Memory MCP**：安裝於工作區和 AGY 全域 ✓
- **Git Hooks**：Husky + Commitlint 已配置 ✓
- **Docker 容器化**：多階段 Dockerfile 已建立 ✓
- **CI/CD 自動化**：Release Please + GHCR 已配置 ✓

### 後續步驟

1. 檢閱 `docs/project.json` 以確認配置。
2. 執行 `pnpm run cbm:update` 以初始化程式碼圖形。
3. 進行變更並提交以觸發 CI/CD 管道。

**執行摘要**：
- 總花費時間：<duration>
- 設定的檔案：<file-list>

---

此技能旨在提供一致、可重複的開發環境設定，適用於任何軟體專案，遵循慣例優先於配置和 DevOps 最佳實踐。