---
name: AGENT_GUIDE
type: router
version: 8.0
last_updated: 2026-04-13
changelog: "v8.0 (2026-04-13): tutoring_topic_picker.py 도입 — sql-topics.md·algo-topics.md 기반 uniform random 주제 선정. 유형 직접 지정 시에도 스크립트로 토픽 선정. /writing 라우팅 수정(weakness→{이름}, rubric→lv{N}). random 트리거 설명에 tutor/track 인수 명시. 커맨드별 로드 비교에 Mode B sub-guide 및 /writing 예시 추가."
description: >
  슬래시 커맨드 라우터. 사용자가 명령어를 입력하면 해당 태스크에 필요한 가이드만 로드한다.
  공통 규칙은 guides/AGENT_GUIDE_CORE.md에 있다 — 모든 태스크에서 반드시 먼저 로드한다.
scope: global
---

# AGENT_GUIDE.md — Copilot CLI 진입점

> **Copilot CLI 전용 래퍼.** 모든 공통 규칙은 `guides/AGENT_GUIDE_CORE.md`에 있다.
> 작업 시작 전 반드시 `guides/AGENT_GUIDE_CORE.md`를 먼저 읽어라.
>
> Claude Code 사용자는 `CLAUDE.md`를 참조한다.

---

## 로드 원칙


모든 태스크에서 **반드시 `conda activate blog` & `guides/AGENT_GUIDE_CORE.md` 를 가장 먼저 로드**한다.  
그 후 아래 슬래시 커맨드에 매핑된 가이드만 추가로 로드한다.

```
사용자 입력
    ↓
conda activate blog
    ↓    
guides/AGENT_GUIDE_CORE.md 로드 (항상)
    ↓
슬래시 커맨드 파싱 → 매핑 테이블 조회
    ↓
해당 skill 가이드 + category GUIDE만 로드
    ↓
실행
```

**슬래시 커맨드가 없으면**: 자연어로 태스크 유형을 추론하여 아래 표의 가장 적합한 행을 선택한다.

---

## 슬래시 커맨드 정의

| 명령어 | 태스크 | 로드할 가이드 (CORE 제외) |
|--------|--------|--------------------------|
| `/write [category] [topic]` | **새 포스트 작성** — 3-Layer 탐색 → 중복 판단 → .qmd 신규 작성 → index.qmd 링크 추가 → 렌더링 → 배포 | `guides/info-search.md` + `guides/write-post.md` + `docs/blog/posts/{category}/GUIDE.md` |
| `/fix [file-path]` | **기존 포스트 교정** — 지정 파일의 YAML·한다체·수식·구조를 현행 규칙에 맞게 직접 수정 (내용 삭제 금지) | `guides/retrofit-post.md` + `docs/blog/posts/{category}/GUIDE.md` |
| `/qa [question]` | **질문 답변** — 블로그→교재→사전지식 3-Layer 탐색 후 통합 답변 (파일 변경 없음) | `guides/info-search.md` + `guides/answer-question.md` |
| `/convert [category]` | **TBD 메모→정식 포스트 전환** — TBD.qmd의 임시 메모를 정식 .qmd로 분리·재작성 → index 업데이트. Essay형 글(포트폴리오·단상·전략)은 `Data_Science/Essay/`로 이동 | `guides/info-search.md` + `guides/convert-tbd.md` + `docs/blog/posts/{category}/GUIDE.md` + (Essay면) `docs/blog/posts/Data_Science/Essay/GUIDE.md` |
| `/series [category]` | **시리즈 재구성** — 카테고리 내 기존 .qmd 파일들의 중복·누락·순서 진단 → 파일 병합/분할/번호 재배치 → index.qmd 반영 | `guides/info-search.md` + `guides/organize-series.md` + `docs/blog/posts/{category}/GUIDE.md` |
| `/audit [file-path]` | **품질 감사 (읽기 전용)** — 지정 파일의 추상적 서술·누락 섹션·규칙 위반을 진단·보고만 함 (파일 수정 안 함) | `guides/audit.md` + `docs/blog/posts/{category}/GUIDE.md` |
| `/log` | **변경 이력 요약** — git 히스토리에서 .qmd 생성/수정/삭제 이력을 기간별로 조회·보고 (파일 변경 없음) | `guides/changelog-summary.md` |
| `/reindex [category]` | **index.qmd 재편성** — 카테고리 내 모든 .qmd 메타데이터를 읽고 논리적 그룹핑·순서로 index.qmd를 재작성 | `guides/reorganize-index.md` + `docs/blog/posts/{category}/GUIDE.md` |
| `/algo [track] [problem]` | **Python 알고리즘 튜터** — AIE/DS 트랙 Level 1~5 문제를 대화식으로 풀이 → 세션을 .qmd 포스트로 저장 | `guides/algo-tutor.md` + `docs/blog/posts/Code_Test/GUIDE.md` |
| `/sql [problem]` | **SQL 코딩 테스트 튜터** — Programmers Level 1~5 문제를 평가·교정·해설 → 세션을 .qmd 포스트로 저장 | `guides/sql-tutor.md` + `docs/blog/posts/Code_Test/GUIDE.md` |
| `/writing [level] [lang] [topic]` | **논리적 글쓰기 튜터** — Lv.1~7 × 한국어/영어 글쓰기 채점·피드백 → 세션을 .qmd 포스트로 저장 | `guides/writing-tutor.md` + `guides/writing-rubric-lv{N}.md` (레벨 확인 후) + `guides/writing-weakness-{이름}.md` (사용자 확인 후) + `docs/blog/posts/Writing/GUIDE.md` |
| `/publish` | **배포** — 변경된 .qmd를 HTML 렌더링 → git add (.qmd + _site/ + _freeze/) → commit → push → 충돌 해결 | `guides/publish.md` |

### 커맨드별 사용 예시

| 명령어 | 예시 |
|--------|------|
| `/write` | `/write Statistics continuous distributions` |
| `/fix` | `/fix Statistics/101-maximum-likelihood-estimators.qmd` |
| `/qa` | `/qa 포아송과 음이항의 차이는?` |
| `/convert` | `/convert Statistics` |
| `/series` | `/series Statistics` |
| `/audit` | `/audit Statistics/56-common-families-discrete.qmd` |
| `/log` | `/log` |
| `/reindex` | `/reindex Statistics` |
| `/algo` (Mode B 바로 출제) | `/algo DS Lv1 문자열 random go` |
| `/algo` (Mode B 유형 지정) | `/algo AIE Lv3 DFS go` |
| `/algo` (Mode A 실전) | `/algo AIE Lv2 Programmers 완주하지못한선수` |
| `/algo` (Mode C 개념) | `/algo 공통 Hash concept` |
| `/writing` (Mode A 글 제출) | `/writing Lv3 ko` |
| `/writing` (Mode B 주제 출제) | `/writing Lv5 en random go` |
| `/writing` (Mode C 개념) | `/writing concept R4` |
| `/sql` (Mode B 바로 출제) | `/sql DS Lv1 random go` |
| `/sql` (Mode B 유형 지정) | `/sql Lv2 JOIN go` |
| `/sql` (Mode A 실전) | `/sql Programmers 조건에맞는회원수구하기` |
| `/sql` (Mode C 개념) | `/sql WindowFunction concept` |
| `/publish` | `/publish` |

### `/algo` · `/sql` 바로 출제 단축 문법

튜터가 설정 질문(트랙·모드·주제·푸시 타이밍 확인)을 **건너뛰고 즉시 Step 1(문제 제시)부터 시작**하도록 하려면 아래 트리거 키워드를 명령어에 포함한다.

| 트리거 | 효과 |
|--------|------|
| `random` | 그룹·토픽 모두 random. algo: `--tutor algo --track {T} --level N`, sql: `--tutor sql --level N`, writing: `--tutor writing --level N` 으로 호출 |
| `go` 또는 `!` | 모든 확인 단계 건너뛰고 Step 1부터 시작. Self-Check·푸시 확인은 세션 종료 시 일괄 처리 |
| 유형명 직접 지정 | `문자열`, `Hash`, `DFS`, `JOIN`, `NULL처리` 등 — **그룹을 고정하고** 스크립트 `--group {키워드}` 로 토픽 random 선정 |
| `Programmers {문제명}` / URL | Mode A 실전 문제 튜터링 |
| `concept` 또는 `concept:{주제}` | Mode C 개념 설명 |

**최소 필수 정보 조합** (이 조합이면 바로 출제됨):

```
/algo <track> <level> (<type>|random) go
/sql  [track] <level> (<type>|random) go
```

- `track`: DS / AIE / 공통 (sql은 생략 시 DS 가정)
- `level`: Lv1~Lv5 (또는 Level 1~5)
- `type`: 유형명 또는 `random`
- `go`: 확인 스킵 플래그

**예시 비교**:

| 입력 | 스크립트 호출 | 동작 |
|------|--------------|------|
| `/algo DS Lv1 문자열` | `--track DS --level 1 --group string` | 확인 단계 유지 후 진행 |
| `/algo DS Lv1 문자열 go` | `--track DS --level 1 --group string` | 문자열 그룹 내 토픽 random → 즉시 출제 |
| `/algo DS Lv1 random go` | `--track DS --level 1` | DS Lv.1 전체 random → 즉시 출제 |
| `/sql Lv2 JOIN` | `--level 2 --group join` | 확인 단계 유지 후 진행 |
| `/sql Lv2 JOIN go` | `--level 2 --group join` | JOIN 그룹 내 토픽 random → 즉시 출제 |
| `/sql Lv1 random go` | `--level 1` | Lv.1 전체 random → 즉시 출제 |

**주의**: `go` 트리거는 **Mode B·C에서만** 유효하다. Mode A(실전 문제)는 앵커 문제가 명확히 지정되어 있어야 하므로 `go` 없이도 바로 진행한다.

### `/fix` vs `/audit` 차이

| | `/fix` | `/audit` |
|---|---|---|
| 동작 | 형식·구조·내용을 **직접 수정** | 문제점을 **진단·보고만** |
| 파일 변경 | O | X (사용자가 결정) |
| 언제 쓰나 | 수정이 필요한 게 확실할 때 | 먼저 뭐가 문제인지 파악하고 싶을 때 |

### 커맨드별 로드 비교

```
/write Statistics discrete distributions
  → CORE + info-search + write-post + Statistics/GUIDE.md
  → 로드 안 함: retrofit, audit, changelog, organize-series, ...

/qa 포아송 분포란?
  → CORE + info-search + answer-question
  → 로드 안 함: write-post, retrofit, audit, category GUIDE, ...

/fix Statistics/101-maximum-likelihood-estimators.qmd
  → CORE + retrofit-post + Statistics/GUIDE.md
  → 로드 안 함: info-search(전체), write-post, changelog, ...

/log
  → CORE + changelog-summary
  → 로드 안 함: 모든 skill/category 가이드

/algo AIE Level 3 DFS
  → CORE + algo-tutor + Code_Test/GUIDE.md
  → Mode B (출제) 시 추가: algo-flow-b-rules.md
  → 로드 안 함: write-post, info-search, sql-tutor, ...

/sql Programmers JOIN Level 2
  → CORE + sql-tutor + Code_Test/GUIDE.md
  → Mode B (출제) 시 추가: sql-flow-b-rules.md
  → 로드 안 함: write-post, info-search, algo-tutor, ...

/writing Lv5 en random go
  → CORE + writing-tutor + writing-rubric-lv5.md + writing-weakness-{이름}.md + Writing/GUIDE.md
  → 로드 안 함: write-post, info-search, algo-tutor, sql-tutor, ...

/publish
  → CORE + publish.md
  → 로드 안 함: 모든 content/category 가이드
```

**슬래시 커맨드가 없으면**: 슬래시 커맨드가 없는 입력은 일반 질문(General Inquiry)으로 간주한다. 이 경우 `AGENT_GUIDE.md` 및 하위 가이드(CORE 포함)의 제약 없이 에이전트의 자율적 판단에 따라 답변한다. 다만, 사용자가 명시적으로 분석, 수정, 작성을 요청하는 경우는 기존 태스크 가이드를 따른다.

---

## 카테고리 목록

`{category}` 자리에 아래 폴더명을 사용한다.

| 폴더명 | 주제 |
|--------|------|
| `Statistics` | 분포, 검정, 회귀, 종단분석, FDA |
| `Math` | 선형대수, 미적분, 최적화 |
| `Machine_Learning` | 분류, 회귀, 앙상블, 비지도학습 |
| `Deep_Learning` | CNN, RNN, Transformer, NLP |
| `Experimentation` | A/B Test, 인과추론, MAB |
| `Engineering` | DevOps, Python, Infra |
| `Agent` | RAG, LangChain, LangGraph |
| `Data_Science` | CRISP-DM, EDA, Feature Engineering |
| `Data_Science/Essay` | 포트폴리오 전략, 역량 전이, 산업 적용 단상 — **모두 draft:true** |
| `Governance` | 데이터 거버넌스, 품질 |
| `Strategy_Frameworks` | 비즈니스 분석, 전략 |
| `Code_Test` | 알고리즘, SQL |
| `Writing` | 논리적 글쓰기, 비판적 사고, Lv.1~7 |
| `Surveilance` | 의료기기 규제, FDA/EMA |

---

## 규칙 우선순위

```
카테고리 GUIDE.md  >  guides/AGENT_GUIDE_CORE.md  >  에이전트 자체 판단
```

---

## Project Info

- **Site**: https://kk3225.netlify.app
- **Author**: Kwangmin Kim
- **Stack**: Quarto → Netlify
- **Commands**: `quarto preview` / `quarto render`
- **Key Files**: `_quarto.yml`, `docs/blog/posts/_metadata.yml`

---

## Essay 규칙

`Data_Science/Essay/` 는 **draft:true 전용** 하위 카테고리다 (`_metadata.yml`로 자동 적용).

### 어떤 글이 Essay로 가는가

| 글 유형 | 목적지 |
|---|---|
| 특정 기술 주제의 정식 설명 | 해당 카테고리 (Statistics, Data_Science 등) |
| 포트폴리오 전략·커리어 단상 | `Data_Science/Essay/` |
| 역량 전이·산업 적용 분석 | `Data_Science/Essay/` |
| 방법론 비교·선택 근거 | `Data_Science/Essay/` |
| 임시 메모 (아직 미정리) | `docs/blog/posts/TBD.qmd` (inbox) |

### TBD → Essay 전환 흐름

```
TBD.qmd (inbox, 단편 메모)
  ↓  /convert essay  또는  /write Data_Science/Essay [topic]
Data_Science/Essay/{slug}.qmd  (draft:true, 정리된 에세이)
  ↓  발행 준비되면 draft:true 제거
블로그 발행
```

### Essay 하위 도메인 폴더

주제가 많아지면 `Essay/` 아래에 **도메인 폴더**를 생성할 수 있다.

```
Data_Science/Essay/
├── _metadata.yml          ← draft:true 전체 적용 (하위 폴더 포함)
├── index.qmd
├── pcr/                   ← PCR 진단 관련 essay
├── logistics/             ← 물류·리테일 관련 essay
├── ecommerce/             ← e-커머스 관련 essay
└── {새 도메인}/           ← 필요 시 추가
```

**폴더 생성 기준**: TBD 내용을 변환하거나 새 Essay를 작성할 때, 같은 도메인의 글이 **2개 이상** 예상되면 하위 폴더를 만든다. 단일 글이면 `Essay/` 바로 아래에 둔다.

**`_metadata.yml` 상속**: 루트의 `Essay/_metadata.yml`(`draft: true`)은 모든 하위 폴더에 자동 적용된다. 하위 폴더에 별도 `_metadata.yml`을 만들 필요 없다.

### Essay 파일 명명 규칙

- 형식: `{주제}-{키워드}.qmd` (예: `pcr-portfolio-career-strategy.qmd`)
- 도메인 폴더 내 배치: `Essay/pcr/`, `Essay/logistics/`, `Essay/ecommerce/` 등
- 수동 번호 금지 (`number-sections: true` 자동 적용)
- 반드시 `categories: [Data Science, Essay]` 포함