claude-dev-skill

claude-dev-skill이란?

claude-dev-skill은 Claude Code용 커스텀 스킬로, Claude를 여러 AI 워커 에이전트를 활용한 소프트웨어 빌드 “tech lead” 프로세스로 전환합니다. 이 스킬은 격리된 worktree에서 병렬 워커 작업을 조율하는 구조화된 다단계 워크플로를 제공하며, PR과 리뷰를 통해 변경 사항을 라우팅하여 컨텍스트 손실과 병합 충돌을 줄입니다.

핵심 목적은 단일 스레드 코드 생성을 넘어서는 것입니다: 요구사항 정렬(PRD), 아키텍처 결정, 작업 분해, 병렬 구현, 정적 QA 검사, 구조화된 PR 리뷰/병합 단계를 안내합니다.

주요 기능

• /dev 명령 워크플로 (다단계 SOP): 요청 분류로 시작해 PRD 정렬, 아키텍처 및 이슈 생성, 워커 구현, QA 검증, PR 병합 조율까지 진행합니다.
• Tech-lead 라우팅 규칙: 메인 대화는 코디네이터로 취급되며 “코드 직접 작성 안 함”, Worker Agent → PR → 리뷰 프로세스를 요구합니다.
• Worktree를 통한 병렬 워커 에이전트: 기능의 다른 부분(예: auth, API, frontend)을 지원하기 위해 격리된 worktree에서 병렬 개발하는 여러 워커 에이전트를 생성합니다.
• 코딩 전 충돌 스캔: 작업 시작 전에 워커 에이전트가 다른 열린 이슈를 파일 중복으로 스캔해 잠재 충돌을 조기 발견합니다.
• 병합 후 PR 조율: 병합 후 열린 PR을 스캔하고 리베이스 필요한 브랜치를 알립니다.
• 리뷰 전 보안 게이트: 리뷰 단계 전에 보안 도구 실행(bandit + pip-audit for Python, 또는 npm audit for Node)을 필수로 강제합니다.
• 거부 조건 포함 구조화된 PR 리뷰 체크리스트: 7개 항목 체크리스트로 코드 리뷰를 진행하며 필수 거부 조건이 있습니다.
• 테스트 커버리지용 반례 자체 검사: Null/Empty/Boundary/External failure/Concurrency/Malicious 입력 시나리오를 워커가 고려하도록 6개 카테고리 자체 검사를 포함합니다.

claude-dev-skill 사용 방법

1. 스킬 파일을 Claude Code의 commands 디렉토리에 설치 (macOS/Linux/Windows용 스크립트 설치 또는 디렉토리 구조 유지하며 수동 복사).
2. Claude Code (Anthropic 공식 CLI) 로그인 확인.
3. 인증 세션으로 GitHub CLI (gh) 사용 (gh auth login 먼저 실행).
4. Claude Code에서 /dev [선택적 설명] 실행. 스킬이 요청을 분류(예: 신규 프로젝트, 신규 기능, 버그 픽스, 핫픽스, 아키텍처 변경, 리팩토링)하고 적합한 흐름으로 진입합니다.

일반 실행은 리포지토리에서 보여준 단계대로 진행: PRD 정렬(2라운드), 아키텍처 및 GitHub 이슈 작업 분해, 병렬 worktree 워커 실행, QA 정적 검증, 체크리스트 기반 PR 리뷰 및 병합.

사용 사례

• 기존 PRD로 소형~중형 웹 백엔드 기능 빌드: /dev로 기존 제품 요구사항 문서를 아키텍처 결정, GitHub 이슈, 병렬 워커 구현으로 변환.
• 병합 충돌 최소화하며 여러 모듈 동시 구현: 별도 워커 에이전트가 다른 컴포넌트(예: 인증 vs. 작업 CRUD API vs. 프론트엔드)를 처리하고, 코딩 전 충돌 스캔 및 병합 후 리베이스 조율에 의존.
• 조율된 버그 픽스 또는 핫픽스 작업: 버그 픽스나 긴급 핫픽스의 경우 요청 유형 분류 후 아키텍처 리뷰, 워커 변경, QA 검증, 구조화된 PR 병합으로 라우팅.
• 구조화된 리뷰를 통한 체계적 리팩토링: 리팩토링 시 SOP의 반례 자체 검사와 병합 전 보안 게이트가 엣지 케이스 고려와 필수 감사 도구 실행을 보장.
• 코딩 전 정렬 필요한 아키텍처 변경 작업: Phase 1 PRD 정렬과 Phase 2 아키텍처 결정을 통해 워커 구현 전에 팀 계획을 명확히 합니다.

자주 묻는 질문

• 이 스킬 워크플로에서 “tech lead”는 무엇을 의미하나요? 메인 대화가 코디네이터 역할을 합니다: PRD를 정렬하고, 아키텍처 방향을 결정하며, 워커 에이전트를 생성하고, 코드 변경이 채팅에서 직접 편집되지 않고 Worker Agent PR과 리뷰를 거치도록 강제합니다.

• claude-dev-skill은 메인 대화에서 직접 코드를 작성하나요? 아닙니다. 워크플로에는 “철칙”이 포함되어 메인 대화가 직접 코드를 작성하지 않으며, 변경 사항은 Worker Agent를 거쳐 PR 리뷰로 진행됩니다.

• 병렬 개발 중 충돌은 어떻게 처리되나요? 스킬에는 코딩 전 충돌 스캔(워커 에이전트가 시작 전에 오픈 이슈에서 파일 중복 확인)과 병합 후 단계(오픈 PR을 스캔해 리베이스 필요한 브랜치를 식별)가 포함됩니다.

• 어떤 보안 검사가 강제되나요? 리뷰 단계 전에 bandit 플러스 pip-audit(Python용) 또는 npm audit(Node용) 같은 보안 도구 실행을 의무화하며, 이는 리포지토리의 Security gate 설명에 따릅니다.

• 프로덕션 배포 작업에 적합한가요? 리포지토리 범위 설명에 따르면 DevOps/배포 기능이 없으므로 프로덕션 배포가 필요한 프로젝트에는 적합하지 않습니다.

대안

• 단일 에이전트 코드 어시스턴트(자동완성/채팅 스타일): 프롬프트에서 직접 코드를 작성하는 데 초점을 맞추지만, 다중 에이전트 PRD-to-PR 워크플로와 강제 리뷰 게이트를 제공하지 않습니다.
• 일반적인 다단계 프롬프팅 + 수동 PR 워크플로: 직접 Claude에게 태스크 분해를 요청하고 워커를 수동 실행할 수 있지만, 내장 SOP 구조(분류, 충돌 스캔, QA 및 체크리스트 리뷰 조율)를 잃습니다.
• 표준 GitHub 기반 팀 워크플로(Issues/PRs without AI SOP): GitHub Issues와 PR 리뷰로 흐름 일부를 재현할 수 있지만, “워커 에이전트” 병렬화와 자동 단계 라우팅은 동일하게 제공되지 않습니다.
• 기획이나 테스트에 초점을 맞춘 다른 Claude Code 커스텀 스킬: 병렬 워커 에이전트를 엔드투엔드 조율하는 대신 워크플로 일부(예: 테스트 생성)만 타겟으로 하여 통합과 병합 조율을 사용자에게 맡깁니다.