| name | jira-execute |
| description | jira-execute — docs/<ISSUE-KEY>-dev-guide.md를 읽고 스택 최고 개발자 페르소나로 실제 구현을 진행합니다. 병렬 작업은 dynamic Workflow 레인(모델 티어링)으로 수행합니다. 구현 단계에서, '구현해줘', '실행해줘', '코드 작성해줘', 'Phase 진행', 'dev-guide대로 개발', 'jira execute', '개발 시작' 등의 요청에 이 스킬을 사용하세요. /jira-plan 이후, harness-workflow gate 단계 이전에 사용합니다. |
jira-execute — 개발 가이드 기반 구현 실행
개발 가이드 MD 파일을 읽고, 스택 최고 개발자 페르소나로 실제 구현을 진행합니다.
병렬 작업이 필요하면 dynamic Workflow 레인으로 수행합니다 (Agent Teams 신규 사용 금지 — 2026-07-20 확정, 실측 결함 4건).
지라에 댓글이나 설명을 작성할 때에는 한글로 작성합니다.
Usage
/jira-execute <ISSUE-KEY>
ISSUE-KEY: Jira 이슈 키 (예: PROJ-156)docs/<ISSUE-KEY>-dev-guide.md 파일이 존재해야 함 (/jira-plan으로 생성)
Procedure
1. 개발 가이드 MD 로드 및 검증
1-1. MD 파일 읽기
docs/<ISSUE-KEY>-dev-guide.md
파일이 없으면:
❌ 개발 가이드를 찾을 수 없습니다.
먼저 /jira-plan <ISSUE-KEY> 를 실행하세요.
1-2. 가이드 구조 검증
필수 섹션 확인:
## 1. 요구사항 요약 — 인수조건 존재## 2. 영향 범위 분석 — 수정 대상 파일 목록 존재## 3. 구현 계획 — Phase가 1개 이상
누락된 섹션이 있으면 경고 후 진행 가능한 범위에서 실행.
2. 스택 감지 및 페르소나 활성화
작업 디렉토리에서 프로젝트 스택을 자동 감지하고 페르소나를 활성화합니다 — 감지 매핑 + 스택별 페르소나는 ~/.claude/skills/_stack-detection.md §1 + §2 참조.
3. 실행 모드 결정
IF dev-guide 에 "## 5. 병렬 작업 가이드" 존재 (BE/FE 2레인, disjoint slice 등):
→ § 4A 병렬 모드 (dynamic Workflow 레인)
ELSE:
→ § 4B 순차 실행 모드
구 Agent Teams / --subtasks slice fan-out / sub-agent 낱개 fan-out 은 전부 supersede (2026-07-20, harness v2 설계 §7 — 시퀀스 해석 결함·worker hang·모델 오버라이드 미적용 전원-fable 상속 실측 4건). dev-guide 에 "Agent Teams 구성" 표가 남아 있으면 각 행을 Workflow 레인 1개로 읽는다.
4A. 병렬 실행 모드 (dynamic Workflow) — 표준
병렬 모드 SSoT: ~/.claude/skills/harness-workflow/references/parallel-modes.md (단일이슈 2레인 / 다중부모 fan-out + 모델 티어링). 핵심 절차:
- Phase 0 scaffold — 공통 계약(DTO/interface/migration)은 레인 spawn 전에 메인이 직접 완료 (레인끼리 합의 불가).
- Workflow 스크립트 구성 — 레인별
agent() 호출. 모든 호출에 opts.model 명시 (BE 복잡 도메인=opus, FE·기계적 변환=sonnet — 미지정 = 메인 모델 상속 함정). meta.phases[].model 표기.
- 모델 스모크 프로브 1회 — 첫 agent 에게 자기 모델 식별을 보고시켜 오버라이드 실적용 확인 후 본 fan-out.
- 레인 프롬프트: dev-guide 경로 + 담당 파일(타 레인 파일 read-only) + 단위 테스트 GREEN + "통합 빌드/Codex 는 메인 책임 — 시도 금지" + 최종 메시지로 수정 파일 목록·테스트 결과 반환.
- 동시 쓰기 충돌 우려 시
isolation:'worktree' (머지 부담 발생 — disjoint 확실하면 단일 워킹트리).
- 크로스레인 seam(계약 정합)은 메인이 직접 대조·해소 — 레인에 재위임 금지.
- 통합 빌드는 § 7 에서 메인이 1회.
4B. 순차 실행 모드
MD의 Phase를 순서대로 실행합니다.
각 Phase 실행 프로세스:
FOR each Phase in 구현 계획:
1. Phase 목표 확인
2. 수정 대상 파일 읽기 (반드시 Read 먼저)
3. 변경 적용 (Edit/Write)
4. Phase 검증 (MD에 명시된 검증 방법 실행)
END FOR
# 모든 Phase 완료 후 1회만 수행:
- npm run lint (전체 lint)
- npm run build (전체 빌드)
빌드/린트 정책: Phase 단위로 lint/build를 매번 돌리지 않는다. 매 변경마다 검증하면
시간 낭비가 크고 컨텍스트가 무거워진다. 모든 Phase 구현이 끝난 후 단계 7에서 1회만
전체 검증을 수행한다. Phase 검증은 MD가 명시한 정적 확인(파일 존재, 라우트 등록 등)으로 충분.
사이드 이펙트 방지 규칙:
이 규칙들은 가이드에 없는 변경이 코드에 스며드는 것을 막기 위해 존재합니다. 가이드 외 변경이 쌓이면 리뷰 범위가 넓어지고, 의도하지 않은 동작 변경을 일으킬 수 있습니다.
- MD에 명시된 파일만 수정 — 영향 범위 분석에 없는 파일은 수정하지 않음
- MD에 명시된 변경만 적용 — 추가 리팩토링, 코드 정리, 주석 추가 금지
- 기존 코드 스타일 유지 — 수정 대상 파일의 기존 포맷팅/네이밍 따르기
- import 정리 외 포맷팅 변경 금지 — 새 import 추가는 허용, 기존 코드 재정렬 금지
- 빌드 깨뜨리지 않기 — Phase 단위 빌드는 생략. 모든 Phase 완료 후 단계 7(전체 완료 검증)에서 1회만 수행. 단, 명백히 빌드를 깰 변경(존재하지 않는 import, 신택스 에러)은 즉시 발견·수정.
예외: 빌드 에러나 컴파일 에러가 발생하면 해결에 필요한 최소 범위의 추가 수정은 허용. 이 경우 사용자에게 알림.
5. Phase별 진행 상황 출력
각 Phase(또는 레인) 완료 시:
✅ Phase <N>/<Total> 완료: <Phase명>
수정: <파일 목록>
검증: <통과/실패>
6. Codex 코드 리뷰 (필수 — Codex 설치 시)
구현이 완료되면 Codex adversarial review 로 git diff 기반 코드 리뷰를 반드시 수행합니다.
이 단계는 빌드 검증 전에 실행하여, 리뷰 피드백 반영과 빌드 검증을 한 사이클로 끝냅니다.
왜 필수인가: Codex 는 다른 모델 시각으로 working-tree diff 를 검토합니다. 같은 모델이 자기 코드를 리뷰하면 동일한 사각지대를 공유하지만, 외부 리뷰어는 페르소나가 놓친 패턴 (race condition, 누락된 edge case, 잘못된 가정)을 잡아냅니다. "선택" 으로 두면 루프 모드/시간 압박 시 가장 먼저 스킵되는데, 그게 정확히 외부 시각이 가장 필요한 시점입니다. 그래서 설치돼 있으면 무조건 실행.
실행 방법
Step 6-0. 프로젝트 표준 래퍼 우선 — 프로젝트에 scripts/codex-review.sh 가 있으면 반드시 래퍼 경유 (stdin 봉인·출력 파일화·이중 타임박스·호출 계측 — hang 원천 차단):
bash scripts/codex-review.sh <prompt-file>
- exit 42 → Claude adversarial workflow(opus skeptic 레인)로 자동 대체 + verdict 에
codex=fallback(<사유>) 기록. 파이프라인은 Codex 가용성과 분리.
- 래퍼가 없으면 Step 6-1 로.
Step 6-1. 설치 감지:
CODEX_SCRIPT=$(printf '%s\n' "$HOME"/.claude/plugins/cache/openai-codex/codex/*/scripts/codex-companion.mjs 2>/dev/null | sort -V | tail -1)
ls 대신 printf 글로브를 쓰는 이유: 일부 환경의 ls 는 실행 파일에 * suffix 를 붙여 후속 [ -f ] 검증을 깨뜨립니다.
$CODEX_SCRIPT 가 비어있으면 미설치 → "⚠️ Codex 미설치 — adversarial review 스킵" 명시 출력 후 진행- 있으면 Step 6-2 진행
Step 6-2. 실행 전 working-tree 정리 (EISDIR / ENOENT 회피)
Codex companion 은 git status 의 ??(untracked) 라인을 파일로 간주해 read 합니다. untracked 디렉토리, 또는 .gitignore 슬래시 mismatch 로 파일이 untracked 로 남으면 EISDIR/ENOENT 로 죽습니다. 호출 직전 git status --short | grep '^??' 점검 → 디렉토리는 git add 로 파일 단위 staging 후 호출. (메모리: codex-working-tree-eisdir)
Step 6-3. 실행 (스킵 금지):
node "$CODEX_SCRIPT" adversarial-review --wait --scope working-tree
| 실패 증상 | fix |
|---|
EISDIR ... read | untracked 디렉토리 → git add <dir> 또는 .gitignore 정리 (Step 6-2 재점검) |
ENOENT ... stat | 모노레포 sub-repo 안에서 호출 → root 에서 재호출 |
| hang(무출력 3분+) | kill 후 opus skeptic workflow 폴백 — codex=fallback(hang) 기록 |
리뷰 결과 처리
- 피드백 중 타당한 지적만 선별 반영 (전문적 판단으로 필터링 — 무비판 수용 금지)
- 수정 발생 시 해당 파일만 재수정 후 Step 7(빌드 검증)에서 함께 확인
- 요약 출력:
🔍 Codex 코드 리뷰 완료 — 피드백 <N>건 중 <M>건 반영
7. 전체 완료 검증
모든 Phase/레인 완료 후:
7-1. 빌드 검증 (CLAUDE.md 프로젝트 명령 우선)
./gradlew.bat build -x test
npm run build
flutter analyze
7-2. 인수조건 체크 — MD의 "인수조건"을 하나씩 확인 (수동 확인 필요 항목은 ⚠️ 로 명시).
7-3. 변경사항 요약 — git diff --stat
8. Jira 코멘트 및 결과 출력
Jira 코멘트
🔨 구현 완료 (<ISSUE-KEY>)
📊 변경사항: 수정 <N>·신규 <M>개 / +XXX / -XXX
✅ 인수조건 충족: <X>/<Total>
✅ 빌드: 성공
🔍 Codex 리뷰: <수행 — N건 반영 / fallback(<사유>) / 미설치 스킵>
실행 모드: <순차 / 병렬 (Workflow N레인)>
터미널 출력 — 위 코멘트와 동일 정보 + 스택·페르소나. 다음 단계: /harness-review → harness-workflow gate 단계 (테스트+DoD+커밋 — 구 /jira-test·/jira-commit 은 폐기, ~/.claude/skills/harness-workflow/references/gate.md).
Error Handling
- MD 파일 미존재 →
/jira-plan 실행 안내
- MD 구조 불완전 → 누락 섹션 경고 후 가능한 범위에서 진행
- 빌드 실패 → 해당 Phase에서 중단, 에러 내용 출력, 수정 시도
- 레인 간 파일 충돌 → 즉시 중단, 사용자에게 알림 (worktree 격리 재구성 검토)
- Phase 검증 실패 → 해당 Phase에서 중단, 원인 분석 출력
- MD에 없는 파일 수정 필요 발생 → 사용자에게 확인 후 진행
Notes
/jira-plan에서 생성된 MD를 소비하도록 설계됨. MD 직접 수정 후 실행도 정상 동작- 사이드 이펙트 방지가 핵심 원칙 — 가이드에 없는 변경은 하지 않음
- CLAUDE.md에 프로젝트별 빌드/린트 명령이 있으면 우선 사용
- Codex adversarial review (Step 6)는 Codex 설치 시 필수 — 어떤 모드에서도 스킵 금지. 단 hang/실패 시 opus skeptic 폴백은 정식 경로 (skip 이 아님)
- Agent Teams 신규 사용 금지 (2026-07-20) — 구 § 4A(teammate 협업)·4A-FB(sub-agent 낱개 fan-out)·
--subtasks slice fan-out 서술은 전부 dynamic Workflow 레인으로 supersede. Jira 하위이슈 댓글/전이는 부모와 함께 처리하되, 병렬 실행 단위는 § 4A 기준으로만 판단
