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 훅 및 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)

모든 AI 에이전트와 전문 스킬이 동일한 컨텍스트를 공유할 수 있도록 중앙 기계 판독 가능 구성 파일을 docs/project.json에 유지 관리합니다.

표준 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 제외 규칙 구성 (편집기 지연 및 발견 변동 방지)

• 로컬 전용 (기본값) : .gitignore에 .codebase-memory/를 추가합니다.

[!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 위생 및 지속성

• 로컬 전용 (기본값) : .gitignore에 .codebase-memory/를 추가합니다. 저장할 때마다 바이너리 아티팩트를 커밋하지 마십시오.
• 팀 스냅샷 공유: 팀을 위해 사전 인덱싱된 그래프 스냅샷을 커밋하는 경우 루트 .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>" --mode moderate
   

2. 주요 마일스톤/커밋 시 인덱스를 새로 고치기 위해 package.json에 케이던스 스크립트를 추가합니다:

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

---

4단계: Husky 및 Commitlint로 Git 훅 설정

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의 테스트 스크립트에 테스트 파일이 없는 저장소가 푸시를 중단하는 대신 종료 코드 0을 반환하도록 --passWithNoTests와 같은 적절한 플래그가 포함되어 있는지 확인하십시오. 작업 공간에 샘플/더미 테스트 파일을 생성하지 마십시오.

---

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단계: 크레딧 최적화 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의 소문자 변환을 항상 사용합니다.

CI/CD 워크플로우 템플릿 (.github/workflows/release-please.yml)

name: Release Please & Multi-Arch GHCR Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

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

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  test:
    name: Test Suite
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: corepack enable pnpm
      - run: pnpm install --frozen-lockfile
      - run: pnpm test

  release-please:
    name: Release Please
    needs: [test]
    runs-on: ubuntu-latest
    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

  docker-build:
    name: Docker Build & Push (${{ matrix.arch }})
    needs: [release-please]
    if: needs.release-please.outputs.release_created == 'true'
    runs-on: ${{ matrix.runner }}
    strategy:
      matrix:
        include:
          - arch: amd64
            runner: ubuntu-latest
          - arch: arm64
            runner: ubuntu-24.04-arm
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Build and push by digest
        id: build
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.release-please.outputs.tag_name }}-${{ matrix.arch }}
          labels: |
            org.opencontainers.image.source=${{ github.server_url }}/${{ github.repository }}
            org.opencontainers.image.version=${{ needs.release-please.outputs.tag_name }}
      - name: Export digest
        run: |
          mkdir -p /tmp/digests
          digests="${{ steps.build.outputs.digest }}"
          echo "$digests" > /tmp/digests/digest-${{ matrix.arch }}.txt
      - name: Upload digest
        uses: actions/upload-artifact@v4
        with:
          name: digests-${{ matrix.arch }}
          path: /tmp/digests/

  merge-manifest:
    name: Merge Multi-Arch Manifest
    needs: [docker-build]
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - name: Download digests
        uses: actions/download-artifact@v4
        with:
          pattern: digests-*
          merge-multiple: true
      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3
      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - name: Create multi-arch manifest
        run: |
          docker buildx imagetools create \
            -t ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.docker-build.outputs.tag_name }} \
            $(cat /tmp/digests/digest-amd64.txt) \
            $(cat /tmp/digests/digest-arm64.txt)

---

7단계: 환경 정합성 검증

모든 구성 요소가 올바르게 설치되고 예상대로 작동하는지 확인합니다.

7.1. 런타임 및 패키지 매니저 확인

node --version
pnpm --version

7.2. Git 훅 확인

git config --local --list | grep core.hooksPath
# 예상 출력: core.hooksPath=.husky

7.3. MCP 서버 확인

codebase-memory-mcp --version

7.4. Docker 및 Docker Compose 확인

docker --version
docker compose version

---

8단계: 실행 보고서 및 Git 안내

예시 보고서 형식:

## ✅ 저장소 설정 완료: `my-project`

**저장소**: `owner/my-project`
**기본 브랜치**: `main`
**런타임**: Node.js 22 (패키지 매니저: pnpm)

### 설정된 구성 요소

| 구성 요소 | 상태 | 위치 |
|---|---|---|
| `docs/project.json` | ✅ 작성됨 | `docs/project.json` |
| codebase-memory-mcp | ✅ 설치됨 | 작업 공간 `mcp.json` |
| Husky + Commitlint | ✅ 구성됨 | `.husky/` |
| Dockerfile | ✅ 생성됨 | `Dockerfile` |
| Docker Compose | ✅ 생성됨 | `docker-compose.yml` |
| CI/CD 워크플로우 | ✅ 생성됨 | `.github/workflows/release-please.yml` |

### 다음 단계 (Git 안내)

1. **커밋 메시지**는 Conventional Commits 형식을 따라야 합니다:
   - `feat: 새 기능 추가`
   - `fix: 버그 수정`
   - `chore: 유지 보수 작업`
2. **CI/CD**는 `main` 브랜치에 대한 모든 푸시에서 실행됩니다.
3. **릴리스 워크플로우**가 트리거되면 GHCR에서 제공되는 멀티 아키텍처 Docker 이미지를 확인하십시오.