| name | jira-ingest |
| description | jira-ingest — Karpathy LLM Wiki 패턴으로 docs/ 디렉토리에 영구 지식 wiki 를 구축·갱신합니다. dev-guide 가 생성/완료될 때마다 docs/INDEX.md (전체 카탈로그) + docs/LOG.md (이벤트 로그) + ADR/sprint cross-reference 를 점진적으로 자동 갱신합니다. 사용자가 'wiki 등록', 'INDEX 갱신', 'docs 인덱스', 'wiki 만들어줘', 'wiki 처음 설정', '이슈 카탈로그화', 'dev-guide ingest', '문서 인덱싱', 'docs/INDEX.md 갱신', 'cross-reference 보강', '문서 정합성 동기화' 등을 요청하거나, /jira-plan / /jira-complete 가 자동 chain 으로 호출할 때 트리거됩니다. 또한 사용자가 새 프로젝트에 합류해서 'wiki 시작하자', 'Karpathy 패턴 적용', 'LLM 위키 셋업' 같은 의도를 보이면 첫 실행 onboarding 모드로 진입합니다. 이 스킬은 어느 프로젝트에서나 작동 (user-scope) — docs/INDEX-SCHEMA.md 가 프로젝트별 정책을 보유합니다. |
jira-ingest — Wiki Index/Log/Cross-ref 점진 갱신
Karpathy LLM Wiki 패턴 — synthesis 를 query-time 이 아니라 build-time 에 누적.
dev-guide 가 생성/완료될 때마다 INDEX·LOG·cross-ref 를 멱등하게 점진 갱신.
SSoT: ~/.claude/skills/_wiki-schema.md (정책·schema·규칙 전부 그곳).
Usage
/jira-ingest <ISSUE-KEY> # 기본 (의도는 자연어로 전달 또는 컨텍스트 추론)
/jira-ingest <ISSUE-KEY> --subtasks # 부모 + 슬라이스 일괄 (유일한 명시 플래그)
/jira-ingest # 인자 없이 — corpus 수준 의도 (bootstrap / backfill 등) 자연어로
호출 모드는 사용자 자연어에서 추론한다. 플래그 explosion 회피.
유일한 예외: --subtasks — _subtasks-convention.md 와 mechanical 일관성 필요.
⛔ Guard — Wiki 자산 존재 확인 (최우선)
스킬 시작 직후 다음 3 항목 점검. 결과에 따라 분기:
| 점검 | 부재 시 행동 |
|---|
docs/ 디렉토리 | 사용자에게 "docs/ 디렉토리 만들까요? 다른 경로 (예: documentation/) 사용하시나요?" 확인 |
docs/INDEX-SCHEMA.md | First-run onboarding flow (§ 1) 진입 |
docs/INDEX.md | Bootstrap flow (§ 2) 진입 (schema 는 있음 = onboarding 끝남) |
세 가지 모두 정상이면 → § 3 (정상 ingest) 로.
§ 1. First-run Onboarding — 새 프로젝트에서 처음 호출됐을 때
docs/INDEX-SCHEMA.md 가 없으면 wiki 자체가 미설정 상태. 사용자에게 안내 후 schema 부트스트랩.
1-1. ISSUE_PREFIX 추론
프로젝트 Jira 키 prefix 자동 감지 (예: STD, SURINP, SCRUM):
CLAUDE.md / README.md 에서 \b[A-Z]+-\d+\b 패턴 가장 빈도 높은 prefix- 추론 실패 시
mcp__atlassian__getVisibleJiraProjects → 사용자에게 어느 프로젝트인지 확인
- 위 둘 다 실패 시 사용자에게 직접 질문 ("Jira 이슈 키 prefix 는? 예: STD")
1-2. 사용자 확인 + Schema 작성
_wiki-schema.md § 2 의 default schema 를 보여주고 (ISSUE_PREFIX 만 치환), 다음 확인:
🆕 첫 실행 감지 — 이 프로젝트는 아직 wiki 가 설정되지 않았습니다.
다음 자산을 생성합니다:
📁 docs/INDEX-SCHEMA.md (프로젝트 schema, git tracked)
📁 docs/INDEX.md (LLM-maintained 카탈로그)
📁 docs/LOG.md (이벤트 로그, append-only)
추론된 설정:
ISSUE_PREFIX = <STD>
카테고리 = foundational / decisions / issue_guides / sprint / setup (5종)
bounded_writes.forbidden = PRD / DB schema / 코드 파일 일체
진행할까요? (yes / 카테고리 조정 / 취소)
사용자 승인 시:
docs/INDEX-SCHEMA.md 작성 (default schema, ISSUE_PREFIX 치환)docs/INDEX.md 빈 골격 작성 (헤더 + ingest-managed 마커)docs/LOG.md 헤더 1줄 + BOOTSTRAP 라인
이어서 § 1-3 (CLAUDE.md 보강 안내) → § 2 bootstrap 으로 자동 진행.
1-3. CLAUDE.md 보강 안내 — wiki 자산 가시화
_wiki-schema.md § 15 의 claude_md_integration 정책 적용 (default auto-patch).
왜 필요한가: 미래 LLM 세션은 CLAUDE.md 만 자동 로드 → 이 안내가 없으면 INDEX.md / LOG.md 의 존재를 모르고 dev-guide 작업 중 wiki 활용 안 함.
탐지:
CLAUDE.md grep "docs/INDEX.md"
매칭 있음 → 이미 안내됨, 생략
매칭 없음 → 보강 진행
announce 모드 (CLAUDE.md 무수정 — schema 에서 명시적으로 선택 시):
📌 권장: CLAUDE.md 에 wiki 자산 안내를 추가하세요
(jira-ingest 는 CLAUDE.md 를 자동 수정하지 않습니다 — 사용자가 직접 commit)
"Planning Docs" 또는 "Reference Docs" 표 끝에 다음 3 row:
| Wiki Index | dev-guide 카탈로그·상태 조회 | docs/INDEX.md |
| Wiki Log | ingest 이벤트 로그 (append-only) | docs/LOG.md |
| Wiki Schema | 카테고리·정책 (사용자 편집) | docs/INDEX-SCHEMA.md |
또는 "Key Rules" 에 1줄 추가:
- **ALWAYS** 새 dev-guide 작성 후 자동으로 INDEX/LOG 갱신
(jira-plan / jira-complete chain. 누락 시 `/jira-ingest <KEY>` 수동 호출)
auto-patch 모드 (default):
- "Planning Docs 표 끝에 3 row 를 자동 추가할까요? [y/n]" 1회 confirm
- y → Edit 툴로 target_section 헤더 직후 표 끝 anchor 찾아 append
- 표 헤더 매칭 실패 시 → announce 폴백
skip 모드: 안내 자체 생략 (실험적 셋업 또는 wiki 가 일시적).
§ 2. Bootstrap — 기존 dev-guide 일제 카탈로그화
docs/INDEX-SCHEMA.md 는 있는데 docs/INDEX.md 가 없거나 비어있으면, 또는 사용자가 "bootstrap" / "처음 카탈로그화" 의도를 보이면.
2-1. 5+1 Pass 알고리즘
Pass 1: Inventory (glob 만, ~1분)
glob: docs/**/*.md, sprint/**, setup/**, ops/**, qa/**, external/**, data/**
match → INDEX-SCHEMA.categories
read 안 함 — 카테고리 분류만
Pass 2: Metadata extraction (batch, ~10분)
파일 read + _wiki-schema.md § 4 의 6단계 fallback chain 적용.
100+ 파일은 10개씩 batch (context window 보호).
Pass 3: Cross-ref graph 구축
- parent / siblings / related_adrs 그래프 양방향 검증
- 비대칭 검출 시 LOG 에 warning, 자동 수정 X (wiki-lint L07 영역)
Pass 4: Render INDEX.md
- 카테고리별 표 생성
- 정렬: week 역순 + key 내림차순 (이슈 가이드)
- 빈 cell =
-
- ingest-managed 마커 전체 둘러쌈
Pass 5: LOG.md 백필
- entry 별
git log --diff-filter=A --reverse --format=%cI -- <file> → created
git log -1 --format=%cI -- <file> → last_activity- status 추론: archive 디렉토리 / closed_date / Jira 상태 (선택)
- 시간순 INGEST 라인 append
Pass 6 (옵션): Type 휴리스틱 confirm
multi-issue 파일명 (STD-10-STD-81-dev-guide.md) 처리. _wiki-schema.md § 5 휴리스틱 적용 후 ⚠️ 표시된 항목을 사용자에게 일괄 confirm:
⚠️ 다음 dev-guide 의 type 판정이 모호합니다 — 검토해주세요:
STD-10-STD-81-dev-guide.md → composite 추정 (STD-10/STD-81 둘 다 단독 guide 존재)
STD-194-68-dev-guide.md → slice 추정 (부모 STD-194 단독 존재, sub STD-68 단독 없음)
STD-24-STD-107-dev-guide.md → composite 추정
수정할 항목이 있으면 알려주세요. 없으면 'OK' 로 진행.
2-2. Bootstrap 출력
📋 Wiki Bootstrap 완료
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ INDEX.md : 94개 entry (foundational 15 / decisions 1 / issue_guides 74 / sprint 4)
✓ LOG.md : 102 lines (git log 백필 포함)
⚠ Parse warnings : 3개 (frontmatter 없는 신규 dev-guide — L08 lint 권고)
⚠ Type 휴리스틱 : 5개 항목 사용자 확인 완료
다음 단계:
wiki-lint --full # baseline health score 측정 (자동 chain 권장)
Bootstrap 종료 후 자동 chain:
- § 1-3 CLAUDE.md 보강 안내 — wiki 자산 row 가 CLAUDE.md 에 없으면 출력 (announce/auto-patch/skip 정책에 따라)
- wiki-lint 자동 호출 — baseline health score 측정 (사용자 명시 거부 없으면)
§ 3. 정상 Ingest — forecast / closure / refresh
호출자 의도를 자연어 컨텍스트에서 추론.
3-1. 의도 추론 우선순위
| 시그널 | 추론 |
|---|
| harness-workflow / jira-plan 가 직접 호출 + 인자에 "forecast" | forecast |
| harness-workflow / jira-complete 가 직접 호출 + "closure" | closure |
사용자가 <KEY> 만 주고 dev-guide 존재 + Jira 상태 = Open/In Progress | forecast |
사용자가 <KEY> 만 주고 Jira 상태 = QA/Done | closure |
| 사용자가 "다시 갱신" / "refresh" 의도 표명 | refresh (특정 이슈만 재계산) |
| 사용자가 "누락 채워줘" / "backfill" 의도 | backfill (INDEX 만 보충, LOG 변경 X) |
| 사용자가 "cross-ref 다시" 의도 | rebuild-cross-refs (그래프 재구축) |
추론이 모호하면 사용자에게 1회 확인.
3-2. Forecast 모드
/jira-plan 직후 호출됨. dev-guide 가 막 생성된 상태.
절차:
docs/<KEY>-dev-guide.md 존재 확인 (없으면 오류)_wiki-schema.md § 4 fallback chain 으로 메타 파싱INDEX.md 의 issue_guides 표에서 같은 key 검색
- 존재 → row 교체 (status 는 기존 유지, 다른 필드 갱신)
- 없음 → 표 끝에 row 추가 (status=planned)
LOG.md append:
[<timestamp> KST INGEST <KEY> forecast] guide=<path> parent=<parent or '-'> adrs=<csv> siblings=<csv>
- dev-guide 에 YAML frontmatter 없으면 best-effort 추가 제안 (사용자 확인)
- forecast 모드는 ADR / sprint cross-ref 갱신 안 함 — dev-guide 가 확정 전이라 위험
3-3. Closure 모드
/jira-complete 가 호출. 검증 무시 + 신뢰 (책임은 호출자).
절차:
INDEX.md row 찾아서 status=closed, closed=<today>, related_adrs/siblings 갱신LOG.md append:
[<timestamp> KST INGEST <KEY> closure] index_row=updated touched=<csv>
- Conditional writes 실행 (
_wiki-schema.md § 10 bounded_writes):
08-decision-log.md 의 각 related_adr 섹션에 ingest-managed 블록 upsert (referenced-by entry 추가)- dev-guide.week 있으면
sprint/weeks/<w>.md 의 ingest-managed 블록에 closure 라인 append
- dev-guide.track 있으면
sprint/tracks/<n>-<track>.md 의 ingest-managed 블록에 closure 라인 append
forbidden 파일은 절대 touch X — _wiki-schema.md § 10- 각 conditional write 는 dry-run 가능 (사용자가 "preview" 요청 시)
3-4. Refresh 모드 (특정 이슈)
사용자가 dev-guide 를 손으로 수정한 후 INDEX 갱신 원할 때.
절차:
- 해당 key 의
INDEX.md row 만 재계산
LOG.md append: REFRESH <KEY>- cross-ref 갱신 안 함 (해당 dev-guide 의 ADR/siblings 변경됐어도 closure 처럼 다루지 않음)
3-5. Backfill 모드 (INDEX 보충)
새 카테고리 추가 / wiki-lint 가 orphan 검출 후.
절차:
- glob docs/**/*.md → INDEX 에 없는 항목 식별
- 각 항목 메타 파싱 + INDEX 에 row 추가 (기존 row 보존)
- LOG 변경 안 함 (bulk operation 이라 noise)
3-6. Rebuild-cross-refs 모드
schema 의 cross_refs 패턴 변경 후 그래프 재구축.
절차:
- 모든 dev-guide 의 ADR/issue ref 재추출
- INDEX 의 related_adrs/siblings 컬럼 일괄 재계산
08-decision-log.md 의 모든 ingest-managed 블록 재생성- dev-guide 본문은 손대지 않음
§ 4. ingest-managed Block — 안전 갱신 메커니즘
_wiki-schema.md § 8 참조. 핵심 규칙:
- HTML 주석 마커
<!-- ingest-managed:begin <attr=val> --> ~ :end 사이만 rewrite
- 마커 부재 시 적절한 위치에 자동 삽입
- 본문 절대 touch X — git blame 보존
- 마커 attribute 로 식별 (
adr=ADR-070, file=INDEX.md, week=w5, track=qa)
ADR 본문에 마커 첫 삽입 시 위치:
- ADR 섹션의 모든 본문 뒤
- 다음 ADR 섹션 직전
\n\n<!-- ingest-managed:begin adr=ADR-N -->\n### Referenced by ...\n<!-- ingest-managed:end adr=ADR-N -->\n 삽입
§ 5. 멱등성 보장
같은 이슈를 두 번 ingest 해도 동일 결과:
| Layer | Mechanism |
|---|
| Row | issue_key (composite/slice 포함) 가 unique → upsert |
| File | ingest-managed 블록 전체 rewrite (부분 갱신 X) |
| LOG | append-only, timestamp millisecond 정밀 |
충돌 대응:
- 표 row 사이 빈 줄 1개 → diff 가 row 단위로 잘림 → merge 자연 해결
- INDEX.md 손상 감지 시
.bak 자동 백업 후 사용자에게 bootstrap 권고
§ 6. Error Handling
- 각 단계 try-catch — 한 단계 실패해도 다음 단계 계속 (jira-complete §4.5 archive 패턴)
- conditional write 실패 시 경고만, ingest 자체 PASS
forbidden 파일 접근 시도 검출되면 즉시 abort + 사용자에게 보고- Jira API 실패 → status 추론은 archive 디렉토리 / 사용자 확인으로 fallback
§ 7. 출력 포맷
Forecast / Closure / Refresh 공통
📋 Ingest 완료 — <KEY> (<mode>)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✓ INDEX.md : row <upserted | created | refreshed>
✓ LOG.md : append 1 line
✓ Conditional : <ADR-X 3개, sprint/weeks/w5.md 1줄 | none>
✗ Forbidden : <0 — clean | 위반 N건>
💡 CLAUDE.md : <bootstrap/onboarding 직후 1회 보강 안내 | 일반 ingest = 생략>
Wiki status:
total entries : 95
planned : 8 (stale ≥7d: 2 — L03)
closed : 87
다음 단계 권장:
wiki-lint --summary --severity high # high 위반 빠른 점검
Bootstrap (위 § 2-2)
First-run (위 § 1-2)
§ 8. Notes
- README.md 손대지 않음 — 사람용 changelog 보존. INDEX.md 가 LLM-maintained 카탈로그.
- Skill 호출당 context cost: forecast ~10K token / closure ~25K token (LOG 는 read 안 함, append 만)
- 모든 정책은
_wiki-schema.md SSoT 에서 관리 — 본 SKILL.md 가 SSoT 의 절차적 진입점
- harness-workflow 가 Phase 3, 7 에서 자연어 chain 으로 호출 — 본 스킬이 그 호출에 응답
§ 9. --subtasks Mode
사용자가 /jira-ingest <KEY> --subtasks 로 호출하고 부모 이슈에 하위 작업이 있으면:
- 부모 처리 (forecast 또는 closure)
- 각 슬라이스 dev-guide (
docs/<KEY>-<sub>-dev-guide.md) 별로 INDEX entry 추가 (key 형식 <PARENT>::<SUB>)
- LOG 에 슬라이스마다 별도 라인 (
INGEST <PARENT>::<SUB> forecast/closure)
- 슬라이스도 부모와 같은 conditional write (closure 모드)
- 출력에 부모 + 슬라이스별 결과 표 포함
자세한 정책: ~/.claude/skills/_subtasks-convention.md § 3 매트릭스 (jira-ingest 행).
