Jeric SkillsClaude Code 스킬 마켓플레이스
← 전체 스킬

dev-start

v1.0.0

티켓 단위 개발을 이슈 생성 → 기본 브랜치에서 브랜치 → 설계 승인 → 구현 → 검증 → Postman 컬렉션 → 변경 내역과 직접 할 일 정리까지 한 사이클로 진행

설치

호출 이름/dev-start:dev-start

dev-start

티켓 하나를 이슈 생성 → 기본 브랜치에서 브랜치 → 설계 승인 → 구현 → 검증 → Postman 컬렉션 → 마무리 정리까지 같은 순서, 같은 품질로 반복하게 만드는 스킬입니다.

뭘 하는지

1 이슈 → 2 브랜치 → 3 설계(승인 게이트) → 4 구현 → 5 검증 → 6 API 컬렉션 → 7 정리 보고
  • 3단계는 superpowers:brainstorming, 6단계는 postman-collection-from-code를 호출합니다. 이 스킬은 둘을 언제 부르는지를 정하는 오케스트레이터입니다.
  • 7단계 보고는 template.md 골격(변경 내역 / 검증 결과 / 직접 할 일 / 확인 필요 / 아직 안 한 것)으로 고정됩니다.
  • 커밋·푸시는 요청받았을 때만, 통합 브랜치 반영은 merge-safe로 넘깁니다.

왜 이렇게 설계했나

설계를 보여준 것 ≠ 구현한 것

실제로 있었던 일입니다. 필드를 추가하는 설계안을 제시하고 승인을 기다리는 사이, 사용자는 반영된 줄 알고 마이그레이션을 재실행했습니다. 결과는 새 컬럼이 없는 테이블이었습니다. 그래서 설계를 낸 응답에는 "아직 코드는 수정하지 않았습니다"를 반드시 적도록 했고, "했어?"라는 질문엔 기억이 아니라 git status로 답하게 했습니다.

마이그레이션은 파일로, 운영 전이면 합친다

콘솔에서 친 SQL은 다른 환경에서 재현되지 않습니다. 반대로 아직 운영에 안 나간 기능에 요구사항이 추가될 때마다 마이그레이션 파일을 늘리면 운영 배포 때 지저분한 이력이 남습니다. 운영 전이면 같은 파일에 합치되, 이미 실행한 DB는 메타 테이블 때문에 재실행되지 않으므로 undo → migrate 명령을 사용자 할 일에 넣습니다.

직접 할 일은 명령으로 준다

"CORS 설정을 추가하세요"는 할 일이 아니라 숙제입니다. 복붙 가능한 명령, 명령으로 안 되는 건 어느 화면에서 뭘 바꾸는지, 그리고 롤백 방법까지 적습니다.

실행 안 한 검증은 "미실행"

타입 체크를 돌렸는지, 런타임 호출을 해봤는지를 보고서에서 분리합니다. npx가 로컬이 아닌 동명의 패키지를 받아와 exit 0으로 통과해버리는 경우가 있어서, 로컬 바이너리를 직접 호출하도록 했습니다.

쓰는 법

이 기능 개발 시작하자. 이슈부터 만들어줘
<ISSUE-KEY>로 브랜치 따서 진행해줘
다 끝났으면 정리하고 내가 해야 할 거 알려줘

안 쓰는 경우

  • 티켓 없이 끝나는 한 줄 수정
  • 장애 원인 추적이 먼저인 디버깅 작업

에이전트가 읽는 절차 — SKILL.md

설치하면 Claude가 실행 중에 참조하는 실제 문서다. 아래 내용이 그대로 동작을 결정한다.

dev-start

Overview

티켓 하나를 이슈 → 브랜치 → 설계 승인 → 구현 → 검증 → API 문서 → 마무리 정리까지 한 사이클로 끝낸다. 각 단계는 앞 단계의 산출물이 있어야 넘어간다.

핵심 원칙: 설계를 보여준 것과 구현한 것은 다른 상태다. 두 상태를 사용자가 헷갈리지 않게 매 응답에서 분명히 한다.

When to Use

  • 새 기능·API·스키마 변경을 이슈 트래커 티켓 단위로 시작할 때
  • 개발이 끝나서 변경 내역과 사용자가 직접 해야 할 일을 정리할 때 (5~7단계만 수행)

Not for: 오타 수정 같은 티켓 없는 한 줄 변경, 장애 대응(→ systematic-debugging 계열).

사이클

1 이슈 → 2 브랜치 → 3 설계(승인 게이트) → 4 구현 → 5 검증 → 6 API 컬렉션 → 7 정리 보고
                                                          └→ (요청 시) 커밋·푸시 → 통합 브랜치 반영

1. 이슈를 만든다

  • 이슈 트래커 MCP(Jira 등)가 연결돼 있으면 그걸로 생성하고, 없으면 사용자에게 이슈 키를 받는다.
  • 제목은 결과물 기준 한 줄 ("주문 내역 엑셀 다운로드 API 개발"), 설명엔 배경·범위·제외 범위.
  • 생성은 외부 쓰기다. 제목·프로젝트를 보여주고 승인받은 뒤 만든다.

2. 기본 브랜치에서 브랜치를 딴다

git fetch origin
git switch -c <ISSUE-KEY>-<짧은-요약> origin/<master|main>
  • 로컬 master가 아니라 origin/<기본브랜치> 에서 딴다. 로컬이 뒤처져 있으면 머지 때 엉뚱한 diff가 딸려온다.
  • 작업트리가 더러우면 멈추고 알린다. 남의 변경을 새 브랜치로 끌고 가지 않는다.

3. 설계하고 승인받는다

  • superpowers:brainstorming을 호출해 spike / bounded / architectural로 분류한다.
  • 결과물이 갈리는 것만 AskUserQuestion으로 묻는다. 이런 류가 전형적이다:
    • 데이터 소유 범위 (전역 / 조직별 / 사용자별)
    • 권한 (누가 쓰고 누가 읽나)
    • 필수 여부, 이미 실행된 마이그레이션을 어떻게 처리할지
  • 설계는 "파일별로 뭘 바꾸는지 + 사용자가 수동으로 할 인프라 작업"까지 포함한다.
  • 설계를 제시한 응답에는 아직 코드는 수정하지 않았습니다를 명시하고 멈춘다. 승인 전 구현 금지.
  • spec/plan md 문서는 로컬에만 둔다. 커밋하지 않는다 (사용자 규칙이 다르면 그걸 따른다).

4. 구현한다

  • 레포의 가장 비슷한 기존 기능을 먼저 찾아 그 구조(model / repository / service / controller, 권한 맵, 라우트 등록 위치)를 그대로 따른다. 새 패턴을 만들지 않는다.
  • 스키마 변경은 마이그레이션 파일로 만든다. 콘솔에서 치는 SQL로 넘기지 않는다.
  • 요구사항이 중간에 바뀌었고 그 마이그레이션이 아직 운영에 안 나갔으면 새 파일을 추가하지 말고 같은 파일에 합친다. 이때 이미 실행된 DB가 있는지 사용자에게 확인하고, 있으면 7단계에 undo → migrate 재실행을 적는다.
  • 사용자가 "했어?"라고 물으면 기억이 아니라 git status/git diff로 확인하고 답한다.

5. 검증한다

  • 타입 체크·린트·빌드 중 레포가 쓰는 것을 실제로 실행하고 exit code를 본다. 출력이 비었다고 통과로 보지 않는다.
  • npx <tool>이 로컬 패키지가 아닌 걸 받아올 수 있으니 node node_modules/<pkg>/bin/<bin> 형태를 우선한다.
  • 마이그레이션 JS는 최소 node -e "require('./<file>')"로 문법을 확인한다.
  • 실행하지 못한 검증은 "미실행"으로 적는다. 런타임 호출을 안 했으면 안 했다고 쓴다.

6. API 컬렉션을 만든다

  • 엔드포인트가 생기거나 바뀌었으면 postman-collection-from-code 스킬을 호출한다.
  • 필드가 추가되면 컬렉션 변수·요청 body·응답 예시·에러 설명을 같이 고친다. 코드만 바뀌고 컬렉션이 낡는 게 가장 흔한 누락이다.

7. 정리 보고를 낸다

template.md 골격대로 쓴다. 섹션을 빼지 말고, 해당 없으면 "없음"이라고 적는다.

사용자가 직접 해야 할 일은 복붙 가능한 명령으로 준다. 클라우드 콘솔 작업처럼 명령으로 줄 수 없는 것은 어느 화면에서 무엇을 바꾸는지 적는다. 운영 리소스·클라우드 쓰기는 직접 실행하지 않는다.

(요청 시) 커밋·푸시와 통합 브랜치 반영

  • 커밋·푸시는 사용자가 요청했을 때만 한다. 커밋 대상 파일을 명시적으로 git add <path>하고, spec/plan 문서·.env는 제외한다.
  • test/dev 같은 통합 브랜치에 넣어야 하면 merge-safe 스킬로 넘긴다.
  • 푸시 후 보안 리뷰 같은 자동 경고가 오면, 이번 변경에서 나온 건지 통합 브랜치에 원래 있던 코드인지 구분해 보고한다.

Common Mistakes

실수 결과
설계안을 제시하면서 "수정 안 했음"을 안 적음 사용자가 반영된 줄 알고 DB를 재생성 → 새 컬럼 없는 테이블
로컬 master에서 브랜치 생성 오래된 기준점, 머지 때 무관한 diff
이미 실행된 마이그레이션 파일만 고침 메타 테이블에 기록돼 있어 재실행 안 됨 — undo 안내 필요
필드 추가 후 API 컬렉션 미갱신 프론트가 400을 받고 원인 문의
검증 안 하고 "완료" 첫 배포에서 타입 에러
"내가 할 일"을 설명문으로만 줌 사용자가 명령을 다시 조립하다 실수
GitHub에서 소스 보기 →