---
name: ko-tech-blog
description: This skill should be used when writing Korean tech blog posts in Toss style. Guides through 7-step process from empathy → problem definition → step-by-step solution → results → learnings, using conversational Korean tone with philosophical insights.
---

# 한국어 기술 블로그 작성 스킬

## 스킬 개요

토스 기술블로그 스타일의 한국어 기술 블로그 글을 작성하는 스킬입니다. 문제 해결 경험을 공감 유도 → 문제 정의 → 단계적 해결 → 결과 → 배움 구조로 작성하며, 반말체 톤과 철학적 여운을 남깁니다.

## 실행 조건

다음 키워드나 상황에서 이 스킬이 트리거됩니다:

### 트리거 키워드
- "블로그 글", "기술 블로그", "포스팅"
- "경험 공유", "회고", "문제 해결 경험"
- "토스 스타일", "토스처럼", "토스 기술블로그"
- "/blog", "/tech-blog"

### 실행 상황
- 프로젝트 완료 후 회고 글 작성 요청
- 기존 초안을 토스 스타일로 다듬는 요청
- 특정 기술 경험을 블로그 글로 정리 요청

## 7단계 프로세스

### Step 1: 글감 파악

사용자에게 다음 질문을 통해 글감을 파악합니다:

1. **어떤 문제를 해결했나요?**
   - 구체적인 문제 상황과 발생 배경

2. **왜 이 문제가 중요했나요?**
   - 비즈니스/사용자에게 미친 영향
   - 해결하지 않으면 어떤 일이 일어났을까?

3. **어떤 시도들을 했나요?**
   - 첫 번째 시도와 그 결과
   - 개선 과정과 시행착오
   - 최종 해결책에 도달하기까지의 여정

4. **최종 해결책은 무엇인가요?**
   - 구체적인 구현 방법
   - 핵심 기술/패턴

5. **결과와 배움은 무엇인가요?**
   - 정성적/정량적 변화
   - 인사이트와 깨달음

**추가 확인:**
- 프로젝트 코드베이스 유무
- Git 이력 접근 가능 여부
- 기존 초안 존재 여부

### Step 2: 글 유형 선택

수집한 정보를 바탕으로 가장 적합한 템플릿을 선택합니다:

#### 1. 문제 해결형 (주력 템플릿)
- 명확한 문제와 해결 과정이 있을 때
- Phase별 시도와 개선이 있을 때
- `templates/problem-solving-template.md` 사용

#### 2. 개념 설명형
- 새로운 기술/개념을 소개할 때
- WHY와 HOW를 설명할 때
- `templates/concept-explaining-template.md` 사용

#### 3. 기본형
- 간단한 경험 공유나 팁 공유
- `templates/basic-template.md` 사용

**사용자에게 선택한 유형과 이유를 설명하고 확인받습니다.**

### Step 3: 구조화 및 초안 작성

선택한 템플릿을 기반으로 초안을 작성합니다:

#### 구조 (문제 해결형 기준)
1. **제목**: 숫자형/질문형/대비형 중 선택
2. **서론**: 공감 유도 (일상적 질문/경험)
3. **문제 정의**: 구체적 상황 + 영향 + 핵심 질문
4. **해결 과정**:
   - Phase 1: 첫 번째 시도 + 문제점
   - Phase 2: 개선 + 결과
   - Phase 3: 최종 해결책 + 구현
5. **결과**: 정성적 변화 + 정량적 수치
6. **배운 점**: 핵심 인사이트 + 철학적 전환

#### 참고 자료
- `references/article-structure.md`: 섹션별 상세 가이드
- `references/examples/good-intro.md`: 좋은 서론 예시
- `references/examples/good-problem.md`: 좋은 문제 정의 예시
- `references/examples/good-conclusion.md`: 좋은 결론 예시

**초안을 작성한 후 사용자에게 공유하고 피드백을 받습니다.**

### Step 4: 토스 스타일 적용

`references/toss-style-guide.md`의 규칙을 적용하여 초안을 다듬습니다:

#### 핵심 원칙 5가지 적용
1. **공감 먼저, 기술은 나중에**
   - 서론에서 독자의 공통 경험 환기
   - 문제의 중요성을 먼저 설명

2. **문제를 먼저 정의하라**
   - 해결책 제시 전에 문제를 명확히
   - 왜 이 문제가 중요한지 설명

3. **단계적 발전 보여주기**
   - Phase 1/2/3 구조로 시도와 개선 과정 보여주기
   - 실패와 배움의 과정 투명하게 공유

4. **정량보다 정성, 하지만 숫자는 강력하다**
   - 사용자 경험의 질적 변화 강조
   - 핵심 지표는 숫자로 강조 (예: "응답 속도 3배 개선")

5. **기술 용어를 일상 언어로 번역하라**
   - 전문 용어는 설명 추가
   - 비유와 예시 활용

#### 스타일 적용
- **반말체 혼용**: 현장 대사나 생각을 직접 인용할 때 반말 사용
- **문단 리듬**: 짧은 문단(1-3줄) + 긴 문단(5-7줄) 교대 배치
- **질문형 소제목**: 독자 호기심 유발 (H3 레벨)
- **블록 인용(>)**: 핵심 질문이나 깨달음 강조
- **강조 기법**:
  - 굵은 텍스트(**): 중요 개념
  - 인라인 코드(`): 기술 용어
  - 숫자 활용: "3가지", "10배", "0.3초"

**스타일을 적용한 버전을 사용자에게 공유하고 비교합니다.**

### Step 5: 코드 블록 및 이미지 위치 제안

#### 코드 블록 추가
프로젝트 코드베이스가 있는 경우:
1. 관련 파일 검색 (`grep`, `glob` 활용)
2. Git 이력에서 변경사항 추출 (`git log`, `git diff`)
3. Before/After 형태로 정리
4. 주석으로 핵심 강조

**코드 블록 작성 원칙:**
- 설명 먼저, 코드는 나중에
- Before/After 패턴 활용
- 너무 길면 핵심 부분만 발췌
- 주석으로 변경점 명확히 표시

#### 이미지 위치 제안
다음 위치에 이미지 가이드 코멘트 삽입:

1. **서론 직후**: 문제 상황 시각화
   ```markdown
   <!-- 💡 이미지 추천: 문제 상황을 보여주는 스크린샷 또는 다이어그램 -->
   ```

2. **Phase별 끝**: Before/After 비교
   ```markdown
   <!-- 💡 이미지 추천: Phase 1 결과 스크린샷 -->
   ```

3. **결과 섹션**: 최종 결과물/지표
   ```markdown
   <!-- 💡 이미지 추천: 개선 전후 비교 차트 또는 최종 결과 스크린샷 -->
   ```

**코드와 이미지 위치를 추가한 버전을 사용자에게 공유합니다.**

### Step 6: 검토 및 피드백

다음 체크리스트를 기준으로 검토하고 구체적인 개선점을 제시합니다:

#### 체크리스트
- [ ] **제목이 호기심을 유발하는가?**
  - 숫자형/질문형/대비형 중 하나인가?
  - 구체적이고 명확한가?

- [ ] **서론이 공감을 유도하는가?**
  - 일상적 질문이나 경험으로 시작하는가?
  - 독자가 "나도 그래"라고 생각할 만한가?

- [ ] **문제가 명확히 정의되었는가?**
  - 구체적인 상황이 제시되었는가?
  - 비즈니스/사용자 영향이 설명되었는가?
  - 핵심 질문(>)이 있는가?

- [ ] **Phase별로 구조화되었는가?**
  - 시도 → 실패 → 개선 → 최종 흐름이 명확한가?
  - 각 Phase의 목적이 명확한가?

- [ ] **코드 예시가 충분한가?**
  - Before/After 패턴이 있는가?
  - 주석으로 핵심이 강조되었는가?
  - 설명이 코드보다 먼저 나오는가?

- [ ] **토스 스타일이 적용되었는가?**
  - 반말체가 적절히 사용되었는가?
  - 짧은/긴 문단이 교대로 배치되었는가?
  - 질문형 소제목이 있는가?
  - 블록 인용(>)으로 핵심을 강조했는가?
  - 기술 용어가 일상 언어로 번역되었는가?

- [ ] **결론이 여운을 남기는가?**
  - 핵심 인사이트가 명확한가?
  - 철학적 전환이나 확장된 사고를 제시하는가?

#### 개선점 제시
체크리스트 항목별로 구체적인 개선점을 제시합니다:

```markdown
## 검토 결과

### 잘된 점
- [구체적인 칭찬]

### 개선 필요
1. **서론**: [현재 상태] → [개선 방향]
2. **문제 정의**: [현재 상태] → [개선 방향]
...

### 제안
- [추가 제안]
```

**검토 결과를 사용자에게 공유하고 수정 여부를 확인합니다.**

### Step 7: 메타데이터 및 마무리

#### YAML Frontmatter 추가
글 상단에 메타데이터를 추가합니다:

```yaml
---
title: "글 제목"
date: YYYY-MM-DD
category: [카테고리]
tags: [태그1, 태그2, 태그3]
description: "글 요약 (1-2문장)"
author: "작성자"
---
```

**카테고리 예시:**
- 개발 경험
- 성능 최적화
- 문제 해결
- 새로운 기술
- 아키텍처

**태그 예시:**
- 기술: Next.js, TypeScript, React
- 주제: 성능, 최적화, 리팩토링
- 방법론: TDD, DDD, 클린 아키텍처

#### 파일 저장
기본 저장 경로: `/posts/YYYY-MM-DD-제목.md`

사용자가 다른 경로를 원하면 해당 경로에 저장합니다.

#### 마무리 체크
- [ ] YAML frontmatter 추가 완료
- [ ] 파일 저장 완료
- [ ] 사용자에게 최종 경로 안내
- [ ] 다음 단계 제안 (이미지 추가, SEO 최적화 등)

## 주의사항

### 반드시 지켜야 할 것
1. **한국어로 작성** (기술 용어는 영어 그대로 + 설명 추가)
2. **허위 경험 작성 금지** (사용자가 제공한 정보만 사용)
3. **WHY 없이 WHAT만 쓰지 않기** (문제의 중요성 설명 필수)
4. **독자 고려** (전문 용어 남발 금지, 설명 추가)
5. **단계별 확인** (초안 → 스타일 → 코드 → 검토 → 마무리 각 단계마다 사용자 확인)

### 피해야 할 것
1. **기술 나열만 하기** (스토리와 배움이 있어야 함)
2. **결론 없이 끝내기** (반드시 인사이트와 여운 남기기)
3. **코드만 보여주기** (설명이 코드보다 먼저)
4. **추상적인 표현** (구체적인 상황과 숫자 활용)
5. **일방적인 진행** (각 단계마다 사용자 피드백 받기)

## 참고 자료

### 스타일 가이드
- `references/toss-style-guide.md`: 토스 스타일 핵심 규칙과 패턴
- `references/article-structure.md`: 섹션별 작성 가이드

### 템플릿
- `templates/problem-solving-template.md`: 문제 해결형 (주력)
- `templates/concept-explaining-template.md`: 개념 설명형
- `templates/basic-template.md`: 기본형

### 예시
- `references/examples/good-intro.md`: 좋은 서론 예시
- `references/examples/good-problem.md`: 좋은 문제 정의 예시
- `references/examples/good-conclusion.md`: 좋은 결론 예시

## 추가 기능

### 자동 코드 추출
- Git 이력에서 변경사항 추출
- 관련 파일 검색
- Before/After 형태로 정리

### 이미지 위치 제안
- 서론 직후: 문제 상황 시각화
- Phase별 끝: Before/After 비교
- 결과 섹션: 최종 결과물/지표

### 제목 자동 생성
- 숫자형: "[숫자] + [동사] + [명사]" (예: "3가지 방법으로 Next.js 빌드 속도 10배 개선하기")
- 질문형: "[질문]" (예: "왜 우리는 TypeScript를 선택했을까?")
- 대비형: "[Before] → [After]" (예: "느린 API → 0.3초 응답")

### SEO 메타데이터 생성
- title, description, keywords 자동 생성
- og:image 위치 제안