| 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 주석 | ✅ |
후속 작업 안내
스펙 작성 후 사용자에게 다음 단계 안내:
-
서브카테고리 디렉토리 + index.mdx 생성 (없으면)
src/content/docs/docs/<key>/index.mdx- DocsTree 가시성은
index.mdx 존재로 판단됨 (콘텐츠 0개여도 표시)
- 형식:
/add skill 또는 기존 카테고리 index.mdx 참조
-
docsGroups.ts 등록 (없으면)
src/data/docsGroups.ts의 적절한 그룹 items에 { key: '<key>', label: '<표시명>' } 추가- 적합한 그룹 없으면 새 그룹 신설 검토 (사용자 확인 필요)
-
astro.config.mjs sidebar 등록 (없으면)
sidebar 배열에 { label, collapsed: true, autogenerate: { directory: 'docs/<key>', collapsed: true } } 추가
-
첫 문서 작성: Layer 1부터 순차 진행
/add docs/<key> 또는 /writing 컨벤션으로 작성- 문서가 추가될 때마다
docsSections.ts에 슬러그 추가하여 SubcategoryPage에 정렬 반영
Behavioral Flow
$ARGUMENTS 또는 사용자 메시지에서 대상 기술 추출- Step 1 (Topic Scoping) — 대화 맥락에 이미 있는 정보 활용, 빠진 부분만 질문
- Step 2 (Layer Architecture) — 5-Layer 초안 + 토픽 특성 반영 변형 사유 제시
- Step 3 (Document Enumeration) — Layer별 문서 목록 + 내용·핵심 초안
- 사용자에게 Step 2~3 초안 확인 요청 (의도 일치, 분량 적정성, 누락 영역)
- 피드백 반영 후 Step 4 (Spec Writing) — 템플릿대로 파일 작성
- Step 5 (Quality Checks) 자가 검증 후 통과 항목 보고
- 후속 작업 안내 출력
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 작성 시 위 두 파일을 참조 사례로 활용.
