Community생산성 & 협업github.com

실행

로컬 사이트나 앱을 시작하고 실제 브라우저에서 확인합니다. package.json, 설정 파일 또는 단순한 index.html에서 스택을 감지하고, 빈 포트를 선택한 후 dev 서버 또는 정적 서버를 시작하며, 실제로 응답할 때까지 기다렸다가 스크린샷을 찍거나 브라우저를 열고, 하나의 플래그로 다시 중지합니다. 사용자가 프로젝트를 로컬에서 실행, 서빙, 미리보기, 시작 또는 열어달라고 하거나, 브라우저에서 페이지를 확인하거나, 사이트 스크린샷을 찍거나, 빌드 결과를 확인해야 할 때 사용하세요.

실행란 무엇인가요?

이 스킬은 로컬 프로젝트를 실행하고 브라우저에서 결과를 확인하는 가장 짧은 경로를 제공합니다. package.json, index.html 또는 빌드된 출력 디렉토리를 자동으로 감지하여 적절한 dev 서버나 정적 서버를 시작하고, Playwright를 사용해 페이지를 스크린샷으로 캡처하거나 브라우저를 열 수 있습니다. Claude Code, Cursor, Codex 등 모든 AI 에이전트 플랫폼에서 사용 가능하며, npm 스크립트, Python HTTP 서버, 정적 파일 서버 등 다양한 스택을 지원합니다. 실행 후에는 `.run/state.json`과 `.run/server.log`에 프로세스 정보를 기록하여 시작과 중지 간의 핸드오버를 가능하게 하며, 서버를 실행 중인 상태로 두지 않도록 주의해야 합니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/itsdanylol/claude-sitecraft/tree/HEAD/skills/run

Installed? Explore more 생산성 & 협업 skills: steipete/gemini, steipete/gh-issues, steipete/skill-creator · View all 6 →

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

실행은(는) 무엇을 하나요?

사이트는 실제로 실행되었을 때 비로소 완성됩니다. 소스 코드는 의도를 알려주지만, 브라우저는 사용자가 실제로 얻는 결과를 보여줍니다. 이 스킬은 폴더에서 렌더링된 페이지까지의 가장 짧은 경로입니다.

실행하기

node <skill folder>/scripts/serve.mjs <dir> [--port 4173] [--open] [--shot out.png] [--stop] [--detect]
  • --detect는 감지된 내용을 출력하고 아무것도 시작하지 않습니다. 폴더가 낯설 때 먼저 이 옵션을 사용하세요.
  • --port는 해당 포트에서 시작하여 다음 빈 포트를 사용하므로 두 프로젝트를 동시에 실행할 수 있습니다.
  • --open은 기본 브라우저를 엽니다.
  • --shot out.png는 Playwright를 통해 1440px 너비, 전체 높이로 페이지를 렌더링합니다.
  • --stop은 .run/state.json에서 프로세스 트리를 종료합니다.

프로젝트 옆에 .run/state.json(pid, port, url, command)과 .run/server.log를 작성합니다. 이 두 파일이 시작과 중지 간의 전체 핸드오버입니다.

감지하는 내용

찾은 항목실행 방식
dev, start, serve 또는 preview 스크립트가 있는 package.json빈 포트에서 npm run <해당 스크립트> 실행, PORT 설정
루트에 index.html해당 폴더에서 python -m http.server 실행
public/index.html, dist/index.html, build/index.html빌드된 출력을 루트로 하는 정적 서버 실행
설정 파일이 있지만 스크립트가 없는 경우보고하고 중지: 프로젝트 자체 명령어가 필요함
go.mod, Cargo.toml, pubspec.yaml보고하고 중지: 프로젝트 자체 실행 명령어 사용

프레임워크별 세부 사항, 포트 기본값 및 알아야 할 실패 모드: references/stacks.md

결과 읽기

이 스크립트는 세 가지만 증명합니다: 프로세스가 시작되었음, 포트가 응답했음, 페이지가 렌더링되었음. 알 수 없는 것은:

  • 375, 768, 1440px에서 레이아웃이 올바른지 (이를 위해서는 sitecraft/scripts/verify.mjs 사용)
  • 콘솔이 깨끗한지 (여기서는 캡처되지 않음; verify.mjs가 캡처)
  • 스크린샷이 사용자가 의도한 페이지인지 (URL이 요청한 경로와 일치하는지 확인)

따라서 루프는 다음과 같습니다: serve.mjs --shot 실행, 직접 이미지 확인, 수정, 다시 스크린샷. 한 번의 패스에서 최대 3번의 렌더링; 그 이상이면 문제는 CSS가 아니라 계획에 있습니다.

규칙

  • 서버를 실행 중인 상태로 두지 마십시오. 확인이 끝나면 중지하거나, 여전히 실행 중이며 어떤 포트인지 명확히 알리십시오. 사용자 머신에 방치된 dev 서버는 사용자가 정리해야 할 혼란입니다.
  • 중지할 수 없는 것은 시작하지 마십시오. 프로젝트에 Docker, 데이터베이스 또는 유료 API 키가 필요하다면, 실행 전에 반드시 알리십시오.
  • 실제 URL을 보고하십시오. "앱"이 아닌 localhost:4173로 알리십시오. 4173이 사용 중이어서 포트가 변경되었다면 새 포트를 알리십시오.
  • 로그를 읽기 전에 추측하지 마십시오. 실패한 시작은 거의 항상 누락된 종속성, 누락된 환경 변수 또는 이미 사용 중인 포트 때문입니다. .run/server.log에 답이 있으며, 실제 오류를 인용하는 것이 이론보다 낫습니다.
  • 설치를 알리지 않고 진행하지 마십시오. node_modules가 누락된 경우 npm install이 일반적으로 올바르며, 이는 프로젝트를 변경하는 작업입니다. 실행한 후 실행했다고 알리거나, 설치가 큰 경우 한 번 물어보십시오.
  • 프레임워크보다 정적 서버를 우선하십시오. 빌드된 출력이 존재하고 최신 상태라면, dist/를 서빙하는 것이 dev 서버보다 빠르고 정확합니다.

시작되지 않는 경우

  1. .run/server.log를 읽고 마지막 줄이 아닌 첫 번째 실제 오류를 인용하십시오.
  2. 누락된 종속성: 프로젝트에서 npm install 실행 후 재시도.
  3. 누락된 환경 변수: .env.example을 찾아 필요한 것을 명시하고, 값이 비밀이고 누락된 경우 중지.
  4. 이미 사용 중인 포트: 스크립트는 이미 다음 빈 포트로 넘어가지만, 프레임워크 설정에 하드코딩된 포트가 원인인 경우가 일반적입니다.
  5. 빌드 단계 필요: 먼저 npm run build를 실행한 후 dist/를 서빙하십시오.
  6. 네이티브 또는 컨테이너화된 환경: 프로젝트 문서에 있는 명령어를 안내하십시오. 모든 스택이 스크립트로 처리되는 것은 아닙니다.

체크리스트

  • 스택을 가정하지 않고 감지했음
  • 시작 후 실제 HTTP 응답을 확인했음 (단순히 프로세스를 실행한 것만이 아님)
  • 정확한 URL과 포트를 보고했음
  • 로그뿐만 아니라 스크린샷도 확인했음
  • 경로가 의도한 페이지와 일치하는지 확인했음
  • 중지했거나, 여전히 실행 중이며 어디인지 알렸음
  • 실패 시 실제 오류를 인용했음

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

관련 스킬