블로그 포스트 작성 스킬

기술 블로그 포스트를 작성할 때 사용한다. 사용자와의 대화를 통해 주제와 관점을 명확히 한 후, 프로젝트의 기존 스타일에 맞는 MDX 파일을 생성한다.

워크플로우

1단계: 주제 및 관점 파악

포스트 작성 전 반드시 사용자에게 확인할 것:

1. •무엇을 배웠는가? - 핵심 학습 내용
2. •왜 이걸 찾아보게 되었는가? - 동기/문제 상황
3. •누구의 관점인가? - 학습자? API 제공자? 사용자?
4. •어떤 질문에 답하는 글인가? - 독자가 가질 질문들

예시 질문:

• •"이 글을 통해 독자가 알게 되었으면 하는 핵심이 뭔가요?"
• •"어떤 상황에서 이 내용을 찾아보게 되었나요?"
• •"글의 관점은 뭔가요? (예: 학습자의 삽질기, API 설계자의 가이드 등)"

2단계: 프로젝트 스타일 파악

기존 포스트의 스타일을 확인한다:

# 디렉토리 구조 확인
ls apps/web/content/

# 최근 포스트 읽기
cat apps/web/content/2026/01/*.mdx | head -100

확인할 항목:

• •Frontmatter 형식 (title, date, description, tags, draft)
• •섹션 구조 (도입부, 본문, 마무리)
• •코드 블록 스타일 (주석 위치, 언어 표기)
• •어조 (격식체/비격식체, 존댓말/반말)

3단계: 구조 설계

포스트 구조를 먼저 설계하고 사용자에게 확인받는다:

## 제안 구조

1. 도입부 - [질문/문제 제시]
2. 본문
   - 질문 1: [...]
   - 질문 2: [...]
   - 질문 3: [...]
3. 전체 코드 - [종합 예제]
4. 정리 - [핵심 요약 테이블]

4단계: MDX 파일 작성

파일 경로: apps/web/content/{year}/{month}/{slug}.mdx

Frontmatter 템플릿:

---
title: "제목"
date: "YYYY-MM-DD"
description: "설명 (1-2문장)"
tags: ["태그1", "태그2"]
draft: true
---

작성 원칙:

• •문제 → 해결 구조: 각 섹션은 질문/문제로 시작하고 해결책으로 끝낸다
• •코드 예제 필수: 모든 개념에는 실행 가능한 코드 예제를 포함한다
• •에러 메시지 포함: 잘못된 경우의 에러 메시지도 보여준다
• •한글 친화적: 에러 메시지나 주석은 가능하면 한글로 작성한다

5단계: 피드백 반영

사용자 피드백에 따라 수정할 수 있는 항목:

• •관점 변경: 전체 구조와 어조 수정
• •섹션 추가/삭제: 구조 변경
• •예제 수정: 코드 블록 업데이트
• •제목/태그 변경: Frontmatter 수정

작성 스타일 가이드

좋은 제목 패턴

• •질문형: "NestJS에서 API 사용자에게 친절한 에러 메시지 보내기"
• •How-to형: "TypeScript에서 타입 안전한 API 클라이언트 만들기"
• •적응기/삽질기: "Go 개발자의 NestJS 적응기"

섹션 제목 패턴

• •질문형: "질문 1: URL 파라미터를 숫자로 받으려면?"
• •문제-해결형: "문제: 모든 것이 문자열이다"
• •단계형: "1단계: 스키마 정의"

코드 블록 규칙

// 파일 경로를 주석으로 표시
// posts.controller.ts

// 중요한 부분에 주석 추가
@Get(':id')
async findOne(@Param('id', ParseIntPipe) id: number) {
  // id는 이제 진짜 number
  return this.postsService.findOne(id);
}

요약 테이블 활용

마지막에 핵심 내용을 테이블로 정리:

참고 자료

상세 스타일 가이드라인은 references/style-guide.md 참조.