지라 기반 개발 자동화 하네스 구축기 — 이슈 키 하나에서 코드 검증까지

지라 이슈 키 입력
  │
  ├─ 1. 이슈 컨텍스트 수집 ─── 지라 API → context.json + report.md
  │
  ├─ 2. 스펙 생성 ──────────── 컨텍스트 + 코드 분석 → spec.md
  ├─ 3. 스펙 리뷰 ──────────── 팩트 체크 + 범위 검증 → APPROVED / REGENERATE
  │
  ├─ 4. BDD 시나리오 ────────── Given-When-Then 도출 (조건부)
  ├─ 5. 개발 계획 ──────────── 파일 단위 태스크 + 코드 스니펫 → dev-plan.md
  ├─ 6. 계획 리뷰 ──────────── 스펙 커버리지 + 경로 검증 → APPROVED / REGENERATE
  │
  ├─ 7. 격리 환경 구성 ─────── Git worktree + 의존성 설치
  ├─ 8. 자동 개발 ──────────── TDD 사이클, 태스크 단위 커밋
  │
  ├─ 9. 5단계 검증 ─────────── 기능 → 타입 → 보안 → 성능 → 품질
  ├─ 10. E2E 테스트 ─────────── 브라우저 자동화 (조건부)
  │
  └─ 11. 완료 보고서 ────────── 전체 산출물 종합 + HTML 시각화

스펙 생성 (Step 2) ──→ 스펙 리뷰 (Step 3)
                        │
                        ├─ APPROVED → 다음 단계로
                        ├─ REVISE → 리뷰어가 직접 수정
                        └─ REGENERATE → Step 2 재실행 (최대 2회)
 
개발 계획 (Step 5) ──→ 계획 리뷰 (Step 6)
                        └─ 동일한 판정 루프
 
자동 개발 (Step 8) ──→ 5단계 검증 (Step 9)
                        │
                        ├─ PASS → 다음 단계로
                        └─ FAIL → 수정 후 재검증 (최대 5회)

repos/                          ← 원본 (절대 수정하지 않음)
├── frontend/
├── backend/
└── ...
 
worktrees/                      ← 이슈별 독립 환경
├── PROJ-1234/
│   ├── reports/                ← 산출물 (스펙, 계획, 검증 결과)
│   ├── frontend/               ← git worktree (독립 브랜치)
│   └── backend/                ← git worktree (독립 브랜치)
└── PROJ-5678/
    └── ...

{
  "issue": {
    "key": "PROJ-1234",
    "summary": "주문 상세 페이지에 배송 추적 기능 추가",
    "description": "...",
    "type": "feature"
  },
  "comments": [
    { "author": "PM Kim", "body": "배송사 API 연동 필요", "created": "2026-03-28" }
  ],
  "attachments": [
    { "filename": "shipping-ui-design.html", "content": "..." }
  ],
  "linked_issues": [
    { "key": "PROJ-1100", "summary": "배송사 API 인증 구현", "relation": "is blocked by" }
  ],
  "changelog": [
    { "field": "description", "from": "...", "to": "...", "date": "2026-03-30" }
  ]
}

## PROJ-1234: 주문 상세 페이지에 배송 추적 기능 추가
 
### 이슈 요약
- 유형: feature
- 보고자: PM Kim
- 생성일: 2026-03-25
 
### 댓글 (3건)
1. PM Kim (03-28): 배송사 API 연동 필요
...
 
### 연결 이슈 (1건)
- PROJ-1100: 배송사 API 인증 구현 (is blocked by)

Feature: 주문 상세 페이지 배송 추적
 
  Scenario: 배송 중인 주문의 추적 정보 표시
    Given 주문 번호 "ORD-001"이 배송 중 상태이다
    When 사용자가 주문 상세 페이지를 연다
    Then 배송 추적 정보가 표시된다
    And 현재 배송 위치가 지도에 표시된다
 
  Scenario: 배송 전 주문은 추적 정보 없음
    Given 주문 번호 "ORD-002"가 결제 완료 상태이다
    When 사용자가 주문 상세 페이지를 연다
    Then "배송 준비 중" 메시지가 표시된다
    And 배송 추적 섹션은 비활성화된다

### Task 3: 배송 추적 API 엔드포인트 추가
 
**파일:**
- Create: `app/routers/shipping.py`
- Modify: `app/main.py` (라우터 등록)
- Test: `tests/routers/test_shipping.py`
 
**단계:**
1. Pydantic 스키마 정의
   - ShippingTrackingResponse: tracking_id, status, location, updated_at
2. 라우터 함수 구현
   - GET /api/orders/{order_id}/shipping
   - 배송사 API 호출 → 응답 변환 → 반환
3. main.py에 라우터 등록
4. 테스트 작성 및 실행

feat(shipping): 배송 추적 API 엔드포인트 추가
 
JIRA: PROJ-1234

.claude/
└── skills/
    ├── orchestrator/            # 마스터 스킬 (유일한 진입점)
    │   └── SKILL.md
    ├── jira-collector/          # 이슈 컨텍스트 수집
    │   ├── SKILL.md
    │   └── scripts/
    │       ├── collect.py       # 지라 API 수집 스크립트
    │       └── api_client.py    # HTTP 클라이언트
    ├── spec-generator/          # 스펙 생성
    │   └── SKILL.md
    ├── spec-reviewer/           # 스펙 리뷰
    │   └── SKILL.md
    ├── bdd-explorer/            # BDD 시나리오 (조건부)
    │   └── SKILL.md
    ├── dev-planner/             # 개발 계획
    │   └── SKILL.md
    ├── plan-reviewer/           # 계획 리뷰
    │   └── SKILL.md
    ├── worktree-creator/        # 격리 환경 구성
    │   ├── SKILL.md
    │   └── scripts/
    │       └── create-worktree.sh
    ├── developer/               # 자동 개발
    │   ├── SKILL.md
    │   └── references/          # 프로젝트별 코딩 가이드
    │       ├── backend.md
    │       └── frontend.md
    ├── verifier/                # 5단계 검증
    │   ├── SKILL.md
    │   └── references/
    │       ├── security-checklist.md
    │       └── quality-checklist.md
    ├── e2e-tester/              # E2E 테스트 (조건부)
    │   └── SKILL.md
    └── reporter/                # 보고서 생성
        └── SKILL.md

---
name: spec-generator
description: 수집된 컨텍스트를 기반으로 개발 명세서를 생성한다
---
 
## 입력
- `{REPORTS_DIR}/research/jira/context.json` — 지라 수집 데이터
- 소스 코드 — 에이전트가 직접 코드베이스를 읽어 분석
 
## 실행 절차
1. context.json을 읽고 이슈 유형을 분류한다 (feature/bug/enhancement/refactor)
2. 이슈 유형에 따라 TDD/BDD/E2E 플래그를 결정한다
3. 영향 범위에 해당하는 소스 코드를 읽어 현재 구조를 파악한다
4. 아래 템플릿에 맞춰 spec.md를 작성한다
 
## 출력
- `{REPORTS_DIR}/spec/spec.md`
 
## 출력 포맷
(마크다운 템플릿 정의)
 
## 에러 처리
- 소스 코드 경로를 찾을 수 없으면 즉시 중단하고 보고한다
- context.json이 비어있으면 이전 단계 실패로 판단하고 중단한다

Step 1:  /jira-collector      → context.json 생성
Step 2:  /spec-generator       → spec.md 생성
Step 3:  /spec-reviewer        → APPROVED?
         └─ NO → Step 2 재실행 (max 2)
Step 4:  if spec.BDD == true
         └─ /bdd-explorer      → bdd-scenarios.md
Step 5:  /dev-planner          → dev-plan.md
Step 6:  /plan-reviewer        → APPROVED?
         └─ NO → Step 5 재실행 (max 2)
Step 7:  /worktree-creator     → 격리 환경 준비
Step 8:  /developer            → 코드 작성 + 커밋
Step 9:  /verifier             → 5단계 검증
         └─ FAIL → 수정 후 재검증 (max 5)
Step 10: if spec.E2E == true
         └─ /e2e-tester        → 테스트 보고서
Step 11: /reporter             → 완료 보고서

import urllib.request
import json
import base64
 
class JiraClient:
    def __init__(self, server_url, username, password):
        self.server_url = server_url
        credentials = base64.b64encode(
            f"{username}:{password}".encode()
        ).decode()
        self.headers = {
            "Authorization": f"Basic {credentials}",
            "Content-Type": "application/json"
        }
 
    def get_issue(self, key, expand="renderedFields,changelog"):
        url = f"{self.server_url}/rest/api/2/issue/{key}?expand={expand}"
        req = urllib.request.Request(url, headers=self.headers)
        with urllib.request.urlopen(req) as resp:
            return json.loads(resp.read())
 
    def search_issues(self, jql, fields=None, max_results=50):
        url = f"{self.server_url}/rest/api/2/search"
        data = json.dumps({"jql": jql, "maxResults": max_results})
        req = urllib.request.Request(
            url, data=data.encode(), headers=self.headers
        )
        with urllib.request.urlopen(req) as resp:
            return json.loads(resp.read())

def collect(jira_key, config, output_dir):
    client = JiraClient(**config["jira"])
 
    # 1. 메인 이슈 수집
    issue = client.get_issue(jira_key)
 
    # 2. 댓글 추출
    comments = extract_comments(issue)
 
    # 3. 첨부파일 다운로드 + 텍스트 추출
    attachments = download_attachments(issue, output_dir)
 
    # 4. 연결 이슈 1-depth 수집
    linked = collect_linked_issues(client, issue)
 
    # 5. 변경 이력 추출
    changelog = extract_changelog(issue)
 
    # 6. 외부 URL 크롤링
    urls = extract_and_fetch_urls(issue, comments)
 
    # 7. context.json 저장
    context = {
        "issue": normalize_issue(issue),
        "comments": comments,
        "attachments": attachments,
        "linked_issues": linked,
        "changelog": changelog,
        "external_urls": urls
    }
    save_json(context, f"{output_dir}/context.json")
 
    # 8. report.md 생성
    generate_report(context, f"{output_dir}/report.md")

## 실행 절차
1. config.json에서 지라 서버 URL과 인증 정보를 읽는다
2. 다음 명령으로 수집 스크립트를 실행한다:
   `python scripts/collect.py --key {JIRA_KEY} --output {REPORTS_DIR}/research/jira`
3. 실행 결과를 확인한다:
   - context.json이 생성되었는지 확인
   - 이슈 본문이 비어있지 않은지 확인
4. 에러 시 즉시 중단하고 에러 메시지를 보고한다

## 이슈 분류
- 유형: {feature | bug | enhancement | refactor}
- TDD: {O | X}
- BDD: {O | X}
- E2E: {O | X}
 
## 요구사항
(context.json에서 추출한 기능 요구사항을 번호 목록으로)
 
## 수용 기준
(완료 조건을 체크리스트 형태로)
 
## 영향 범위
| 프로젝트 | 파일 | 변경 내용 |
|----------|------|-----------|
(에이전트가 코드 분석 후 채움)
 
## 기술 결정사항
(설계상 선택과 근거)

## 이슈 분류 기준
- **feature**: 새로운 기능 추가 (기존에 없던 화면, API, 로직)
- **bug**: 기존 기능의 오작동 수정
- **enhancement**: 기존 기능의 개선 (UI 변경, 성능 개선, UX 개선)
- **refactor**: 동작 변경 없이 코드 구조 개선
 
분류에 따른 플래그:
- feature → TDD: O, BDD: O, E2E: O
- bug → TDD: X, BDD: X, E2E: UI 관련이면 O
- enhancement → TDD: O, BDD: 사용자 시나리오 변경이 있으면 O, E2E: O
- refactor → TDD: O, BDD: X, E2E: X

### Stage 3: 보안 검증 (OWASP Top 10)
 
다음 체크리스트를 변경된 코드에 적용한다:
 
- [ ] SQL 쿼리에 파라미터 바인딩 사용 여부
- [ ] 사용자 입력의 XSS 이스케이핑 여부
- [ ] 인증/인가 게이트 존재 여부 (API 엔드포인트)
- [ ] CSRF 토큰 검증 여부 (상태 변경 요청)
- [ ] 민감 정보(비밀번호, 토큰) 로깅 여부
- [ ] 파일 업로드 검증 여부 (타입, 크기)
 
위반 항목이 있으면:
1. 위반 내용과 파일:라인 번호를 기록한다
2. 코드를 수정한다
3. FAIL로 판정한다 (전체 5단계 재실행 트리거)