start-local-dev

name	start-local-dev
description	로컬 개발 서버를 시작하거나 포트 충돌, stale process, 환경변수/서비스 연결 문제를 진단할 때 사용. 특정 회사/레포의 포트·명령·서비스 의존성은 project/private overlay 스킬을 우선 따른다.

Start Local Dev

로컬 개발 서버를 진단 가능하게 시작하기 위한 범용 절차다.

특정 레포 전용 명령과 고정 포트가 있으면 해당 project/private skill을 사용한다.

원칙

• 실행 전 포트 충돌을 확인한다.
• dev server가 fallback port로 떠서 앱 연결이 깨지는지 확인한다.
• 기존 프로세스를 죽일 때는 사용자 의도를 확인한다.
• 서비스 간 의존성이 있으면 한쪽만 local이고 다른 쪽은 remote/dev인 상태를 의식적으로 선택한다.
• 로그 파일과 health endpoint로 readiness를 검증한다.

Workflow

1. 요구 범위 확인

• frontend만인지, backend/API도 필요한지
• local dependency를 모두 띄울지, remote/dev backend를 볼지
• 특정 role/account/feature flag가 필요한지

2. 포트 점검

프로젝트의 고정 포트 목록이 있으면 먼저 확인한다.

lsof -nP -iTCP:<port> -sTCP:LISTEN

충돌 시 사용자에게 선택지를 제시한다.

• 기존 프로세스 유지
• 기존 프로세스 종료 후 새로 실행
• 중단 후 사용자가 수동 정리

3. 공식 start command 사용

레포 README/AGENTS/package scripts의 공식 명령을 우선한다. 개별 dev command를 직접 실행해 fallback port가 생기는 패턴은 피한다.

4. readiness 확인

• stdout/stderr 로그
• health check
• 브라우저 첫 화면/API ping
• 콘솔/네트워크 에러

5. 문제 발생 시

• stale lock/cache/process 정리
• env backup/restore 여부 확인
• service-to-service host가 local/dev 중 어디를 보는지 확인
• dependency install 상태 확인

Output

완료 보고에는 다음을 포함한다.

• 실행 명령
• 떠 있는 URL/포트
• local/dev 연결 선택
• 확인한 로그/health evidence
• 남은 문제와 다음 진단 명령