roadmap

name	roadmap
description	학습 로드맵 스펙 파일(`<CAT>_SPEC.md`) 작성. 새로운 docs 서브카테고리의 학습 커리큘럼을 GRADLE_SPEC.md / ELK_SPEC.md와 동일한 5 Layer 구조로 설계할 때 호출. '학습 로드맵', '커리큘럼', '과정 파일', '스펙 파일', '문서 계획', '학습 계획' 키워드 또는 기존 `*_SPEC.md` 참조하며 새 카테고리 동일 형식 작성 요청 시 반드시 사용. 단순 문서 1개 추가는 `/add` 사용.

/roadmap - 학습 로드맵 스펙 파일 작성

Triggers

• /roadmap 호출 시
• "학습 로드맵", "커리큘럼", "과정 파일", "스펙 파일", "문서 계획", "학습 계획" 등 키워드 언급 시
• 기존 GRADLE_SPEC.md / ELK_SPEC.md 등을 참조하며 새 카테고리용 동일 형식 파일 작성 요청 시
• 새 docs 서브카테고리에 어떤 문서를 어떤 순서로 작성할지 큰 그림 설계가 필요한 시점

단일 문서 추가는 /add, 기존 문서 보강은 /enhance. 본 스킬은 여러 문서로 구성된 카테고리 전체의 학습 경로를 설계할 때만 사용.

Arguments

$ARGUMENTS — 대상 기술·주제명 (예: "Kafka Streams", "PostgreSQL", "OpenTelemetry"). 생략 시 사용자에게 질문.

---

산출물

프로젝트 루트에 <CAT>_SPEC.md 파일 1개.

• 파일명: 영문 대문자 + 언더스코어, _SPEC.md 접미사 (예: KAFKA_STREAMS_SPEC.md, POSTGRESQL_SPEC.md)
• 위치: 프로젝트 루트 (기존 GRADLE_SPEC.md, ELK_SPEC.md와 동일 위치)
• 형식: 4섹션 고정 구조 (Intro → 디렉토리 위계 → 문서별 명세 → Style Guide)

---

작성 5단계

Step 1. Topic Scoping (인터뷰)

다음 항목을 사용자와 확정. 대화 맥락에 이미 답이 있으면 그대로 활용하고, 빠진 부분만 질문.

항목	설명	기본값
대상 기술·주제	한 단어~짧은 구로 명확히	(사용자 입력)
학습자 관점	누가 읽을지	"백엔드(Spring Boot) 개발자"
핵심 사용 시나리오	실무에서 가장 자주 마주치는 활용 1~2개	토픽별로 다름
의도적 배제 영역	다루지 않을 깊은 영역	토픽별로 다름
학습 깊이	입문 / 중급 / 심화	중급
기존 문서 존재 여부	이미 작성된 파일 목록	없음 (새 카테고리)

배제 영역 명확화의 중요성

배제 영역 명시는 인트로의 핵심. 무한 확장을 막아 스펙의 응집도를 유지함.

예시:

• GRADLE_SPEC: "복잡한 커스텀 플러그인 개발이나 내부 튜닝은 배제하고, 의존성 관리·멀티 모듈 구성·CI/CD 연동·성능 최적화 등 꼭 필요한 수준"
• ELK_SPEC: "대규모 클러스터 운영, 노드 단위 튜닝, 복잡한 확장 토폴로지는 배제하고, 인덱싱/검색 내부 동작·로그 수집 파이프라인·Kibana 시각화·기본 운영"

Bundle vs Split 판단

대상이 여러 컴포넌트로 구성된 경우 (예: ELK = Elasticsearch + Logstash + Kibana):

• 함께 쓰이는 맥락이 강하고 초기 학습 단계라면 Bundle (단일 SPEC + 단일 서브카테고리)
• 컴포넌트마다 독립 가치가 크고 학습 깊이가 다르면 Split (별도 SPEC + 별도 서브카테고리)
• 판단 애매하면 Bundle로 시작 → 분량 폭증 시 Split

Step 2. Layer Architecture Design

표준 5-Layer 의미 축을 토픽 특성에 맞춰 변형.

표준 5-Layer 의미 축

Layer	학습 단계	다루는 것	토픽별 예시
L1 Foundations	정적 이해	개념·아키텍처·데이터 모델	"Cluster·Node·Shard 분산 모델"
L2 Core Mechanics	동적 이해	핵심 동작 원리·기본 사용법	"Mapping, Analyzer, Query DSL"
L3 Advanced Patterns	응용	심화 기능·튜닝·트레이드오프	"Scoring, Aggregations"
L4 실무 통합	실전	Spring Boot/도메인 통합	"Filebeat + Logback 연동"
L5 Operations	운영	시각화·배포·모니터링·라이프사이클	"Kibana, ILM, Health"

토픽 특성별 변형 가이드

토픽 유형	L4 / L5 적용 패턴
검색 엔진·DB	L4: 클라이언트 통합, L5: ILM·Health·백업
메시징·스트리밍	L4: Producer/Consumer 통합, L5: 모니터링·운영
빌드·배포 도구	L4: 멀티 모듈·품질, L5: CI/CD·Docker 통합
프레임워크	L4: 도메인 통합 패턴, L5: 테스트·배포
관측성 도구	L4: 애플리케이션 계측, L5: 대시보드·알림

두 갈래 토픽

ELK처럼 토픽이 두 갈래(검색 엔진 + 로그 파이프라인)면 한 갈래는 L2/L3, 다른 갈래는 L4에 배치하여 한 SPEC에 공존시킴.

분량 가이드

• 총 문서 수: 10~15 (index.mdx 제외) — GRADLE_SPEC 11개, ELK_SPEC 13개
• Layer당 2~3 문서 권장
• Layer당 1개는 분할 부족 신호, 4개 이상은 통합 검토
• 5 Layer 미만으로 줄일 때는 인트로에 사유 명시

Step 3. Document Enumeration

각 문서를 다음 3요소로 명세.

**번호. Title (영문)**
- 내용: 다룰 주제 1~3개를 명사형으로 나열
- 핵심: 학습 후 얻는 능력·판단 기준 1줄

규칙

• 파일명: kebab-case 영문 .md (예: analyzer-and-inverted-index.md)
• 제목: 영문 — CLAUDE.md 제목 컨벤션 준수, 약어는 풀네임 괄호 (AOP (Aspect-Oriented Programming))
• 내용·핵심 모두 명사형 종결 ('~함', '~임')
• 마침표 사용

"내용" vs "핵심" 층위 구분

두 줄은 다른 층위. 혼동하면 가치 떨어짐.

구분	답하는 질문	표현
내용	"이 문서에서 무엇을 다루는가?"	토픽·개념·기능을 나열
핵심	"이 문서를 학습하면 무엇이 가능해지는가?"	능력·판단 기준·실무 응용

예시 (Mapping and Data Types):

• 내용: "Dynamic Mapping과 Explicit Mapping의 차이, text vs keyword의 결정적 구분, date·numeric·object·nested 타입의 사용처와 함정."
• 핵심: "잘못된 매핑 한 줄이 검색 품질과 성능 전체를 좌우하므로 인덱스를 만들기 전에 반드시 Explicit Mapping을 설계하는 습관을 정립."

Step 4. Spec Writing

아래 템플릿을 그대로 채움. 자리표시자(<...>)를 모두 치환.

# <대상 기술> 학습 및 실무 활용 문서화 명세서 (Roadmap)

이 문서는 <학습자 관점>가 실무에서 마주치는 <핵심 시나리오 1~2개>를 중심으로 **<대상 기술>의 핵심 동작 원리와 필수 활용법**을 정리한 가이드라인이다. <의도적 배제 영역>은 배제하고, <포함 영역 요약>까지 5개의 Layer로 구성하였다.

*(참고: <기존 문서 작성 상태 — "현재 모든 문서는 미작성 상태이며, Layer 1부터 순차 작성한다." 또는 작성 완료된 파일 명시>)*

## 1. 디렉토리 구조 및 위계

모든 콘텐츠는 `src/content/docs/docs/<key>/` 경로에 위치하며, 총 N개의 핵심 문서로 구성된다.

```text
src/content/docs/docs/<key>/
├── index.mdx                              # 섹션 랜딩 페이지
├── <slug-1>.md                            # L1: <한줄 설명>
├── <slug-2>.md                            # L1: <한줄 설명>
├── <slug-3>.md                            # L2: <한줄 설명>
...
```

---

## 2. 문서별 상세 명세

### Layer 1: <영문 라벨> (<한글 부연>)

**01. <Title>**
- 내용: <명사형 1~3 토픽>.
- 핵심: <학습 후 능력 1줄>.

**02. <Title>**
- 내용: ...
- 핵심: ...

(Layer마다 반복)

### Layer 2: ...

(반복)

---

## 3. 작성 원칙 (Style Guide)

1. 볼드(`**`) 금지: 강조는 문맥과 구조로 수행하며 본문 내 볼드 처리를 절대 하지 않음.
2. 명사형 종결: 리스트 항목이나 설명은 '~함', '~임' 등으로 간결하게 종결. (경어체 금지)
3. 영문 제목: 파일명과 주요 기술 객체명은 영문을 원칙으로 함. <대상 기술> 공식 용어는 그대로 유지.
4. 실무 중심: 이론적 깊이보다는 "이 설정을 어디에 어떻게 써야 하는가"와 "어떤 문제가 해결되는가"를 중심으로 간결하게 서술.
5. 예시 기반: 추상 설명은 배제하고, <대상 기술의 대표 코드 형식 — 예: ES Query DSL JSON, Logstash YAML, build.gradle 등> 실제 동작 가능한 코드 스니펫을 포함하여 설명.

템플릿 채우기 시 주의

• 인트로 1단락에 <학습자 관점>, <핵심 시나리오>, <의도적 배제 영역>, <포함 영역> 4가지가 모두 들어가야 함
• 인트로의 **bold** 사용은 강조점 1군데만 허용 (대상 기술의 핵심 가치를 표현). Style Guide의 "본문 내 볼드 금지" 원칙과 모순처럼 보이지만, 인트로의 1회 강조는 기존 SPEC에서도 허용되는 관용
• Section 2의 Layer 라벨은 영문(한글 부연) 형식 — 예: "Foundations (스택 개요와 아키텍처)"
• 디렉토리 트리는 text 코드블록, 주석으로 Layer 표시
• Style Guide 5번의 "예시 기반" 항목은 대상 기술의 대표 코드 형식으로 구체화 (Gradle이면 build.gradle, ELK면 Query DSL JSON, Spring이면 Java 클래스 등)

Step 5. Quality Checks

작성 후 아래 체크리스트로 자가 검증.

항목	체크
인트로에 audience·핵심 시나리오·배제 영역·포함 영역 4요소 모두 명시	✅
Layer 5개 구성 (변형 시 인트로에 사유)	✅
Layer당 문서 2~3개 (1개·4개+ 회피)	✅
총 문서 수 10~15 범위	✅
Layer가 점진적 진행 (정적→동적→응용→실전→운영)	✅
모든 문서에 내용·핵심 두 줄 모두 존재	✅
"내용"과 "핵심"이 다른 층위로 작성됨 (토픽 vs 능력)	✅
모든 제목 영문, 약어는 풀네임 괄호 처리	✅
명사형 종결 일관성 (경어체·반말체 혼재 없음)	✅
본문 내 볼드(**) 없음 (인트로 1회 외)	✅
Style Guide 5개 항목 그대로 포함 (5번만 토픽별 예시 구체화)	✅
디렉토리 트리에 모든 파일 + Layer 주석	✅

---

후속 작업 안내

스펙 작성 후 사용자에게 다음 단계 안내:

1. 서브카테고리 디렉토리 + index.mdx 생성 (없으면)

   • src/content/docs/docs/<key>/index.mdx
   • DocsTree 가시성은 index.mdx 존재로 판단됨 (콘텐츠 0개여도 표시)
   • 형식: /add skill 또는 기존 카테고리 index.mdx 참조

2. docsGroups.ts 등록 (없으면)

   • src/data/docsGroups.ts의 적절한 그룹 items에 { key: '<key>', label: '<표시명>' } 추가
   • 적합한 그룹 없으면 새 그룹 신설 검토 (사용자 확인 필요)

3. astro.config.mjs sidebar 등록 (없으면)

   • sidebar 배열에 { label, collapsed: true, autogenerate: { directory: 'docs/<key>', collapsed: true } } 추가

4. 첫 문서 작성: Layer 1부터 순차 진행

   • /add docs/<key> 또는 /writing 컨벤션으로 작성
   • 문서가 추가될 때마다 docsSections.ts에 슬러그 추가하여 SubcategoryPage에 정렬 반영

---

Behavioral Flow

1. $ARGUMENTS 또는 사용자 메시지에서 대상 기술 추출
2. Step 1 (Topic Scoping) — 대화 맥락에 이미 있는 정보 활용, 빠진 부분만 질문
3. Step 2 (Layer Architecture) — 5-Layer 초안 + 토픽 특성 반영 변형 사유 제시
4. Step 3 (Document Enumeration) — Layer별 문서 목록 + 내용·핵심 초안
5. 사용자에게 Step 2~3 초안 확인 요청 (의도 일치, 분량 적정성, 누락 영역)
6. 피드백 반영 후 Step 4 (Spec Writing) — 템플릿대로 파일 작성
7. Step 5 (Quality Checks) 자가 검증 후 통과 항목 보고
8. 후속 작업 안내 출력

Output Format

## <대상 기술> 학습 로드맵 스펙 작성 완료

생성 파일: <CAT>_SPEC.md
구성: 5 Layer / N 문서 (index.mdx 제외)

Layer 요약:
- L1 <라벨>: 문서 X개 — <한 줄 요지>
- L2 <라벨>: 문서 Y개 — <한 줄 요지>
- L3 <라벨>: 문서 Z개 — <한 줄 요지>
- L4 <라벨>: 문서 W개 — <한 줄 요지>
- L5 <라벨>: 문서 V개 — <한 줄 요지>

의도적 배제 영역:
- <배제 영역 1>
- <배제 영역 2>

다음 단계:
- [ ] 서브카테고리 디렉토리 + index.mdx 생성 (필요 시)
- [ ] docsGroups.ts 등록
- [ ] astro.config.mjs sidebar 등록
- [ ] Layer 1부터 순차 작성 시작 (`/add docs/<key>` 또는 `/writing` 컨벤션)

---

참고 — 기존 SPEC 파일

• GRADLE_SPEC.md — 빌드·배포 도구 패턴 (L4: 멀티 모듈·품질, L5: CI/CD·Docker)
• ELK_SPEC.md — 두 갈래 토픽 패턴 (L2/L3 검색 엔진 + L4 로그 파이프라인)

새 SPEC 작성 시 위 두 파일을 참조 사례로 활용.