Post Writing Rules

1. 게시글 파일 형식

게시글 파일은 content/posts 디렉터리에 .md 또는 .mdx 확장자로 작성한다. 파일 이름에서 확장자를 제거한 값이 URL slug가 된다.

예를 들어 content/posts/store-facade.md 파일은 /posts/store-facade 경로로 연결된다.

파일 이름은 kebab-case를 사용한다. 이 규칙은 현재 코드에서 강제하지 않지만 URL 가독성과 일관성을 위해 지킨다.

2. Frontmatter 규칙

모든 게시글은 파일 맨 위에 YAML frontmatter를 작성한다. 현재 코드가 검증하는 필드는 title, date, tags, draft다.

---
title: 'Store와 Facade를 분리한 이유'
date: '2026-07-02'
tags: ['architecture', 'store', 'facade']
draft: false
---

title은 비어 있지 않은 문자열이어야 한다. 시리즈 글은 [Part N.] 제목 형식을 사용한다.

date는 YYYY-MM-DD 형식의 유효한 날짜여야 한다.

tags는 하나 이상의 문자열을 담은 배열이어야 한다. 각 태그는 비어 있으면 안 되고 / 문자를 포함하면 안 된다.

draft는 boolean 값이다. true이면 공개 글 목록과 상세 페이지에서 제외된다.

3. 본문 구조

글은 배경과 동기에서 시작하고, 고민 과정과 선택지를 거쳐, 결론과 인사이트로 수렴한다.

섹션 제목은 1., 2., 3. 형식을 사용한다. 하위 섹션이 필요하면 3-1., 3-2. 형식을 사용한다.

각 섹션은 먼저 왜 이 주제가 필요한지 설명하고, 그다음 어떻게 해결했는지 설명한다.

## 1. 왜 Store와 Facade를 분리했는가

문제 상황과 기존 구조의 한계를 설명한다.

## 2. 어떻게 책임을 나누었는가

선택한 구조와 코드 예시를 설명한다.

## 3. 무엇을 배웠는가

결론, 트레이드오프, 다음 개선 방향을 정리한다.

4. 문장과 어조

한국어를 기본으로 쓰되, Store, Facade, Session, Single Source of Truth 같은 영어 기술 용어는 그대로 사용할 수 있다.

기술 용어를 처음 사용할 때는 간단히 정의한다. 예를 들어 Facade는 "복잡한 내부 구현 앞에 두는 단순한 호출 표면"처럼 이 글에서 사용하는 의미를 먼저 고정한다.

친근하되 전문적인 1인칭 서술체를 사용한다. 시행착오가 있었다면 숨기지 말고 어떤 판단이 틀렸는지와 그 판단을 수정한 이유를 함께 쓴다.

기능 목록만 나열하지 않는다. 각 기능이나 구조가 독자에게 어떤 문제를 줄여 주는지 설명한다.

5. 예시와 코드

개념 설명만으로 끝내지 말고 실행 가능한 코드 예시를 포함한다. 코드 예시는 독자가 복사해서 실행하거나 프로젝트 안에서 위치를 확인할 수 있어야 한다.

예시는 쉬운 사례에서 시작해 점진적으로 복잡도를 높인다.

interface StoreState {
  selectedTrackId: string | null;
}

function selectTrack(state: StoreState, trackId: string): StoreState {
  return {
    ...state,
    selectedTrackId: trackId,
  };
}

코드 예시 뒤에는 코드가 어떤 문제를 해결하는지와 어떤 한계가 남는지 설명한다.

6. 주장과 근거

측정한 수치가 없으면 정량적 효과를 주장하지 않는다. 예를 들어 "성능이 크게 좋아졌다" 대신 "불필요한 재계산 가능성을 줄였다"처럼 관찰 가능한 변화만 쓴다.

원인과 증상을 구분한다. 로그, 에러 메시지, 재현 조건이 있으면 먼저 제시하고, 그다음 가능한 원인을 좁혀 간다.

확실하지 않은 내용은 추정이라고 밝힌다. 근거가 부분적이면 "원인이다"가 아니라 "원인과 일치한다", "가능성을 좁힌다"처럼 쓴다.

7. 문제 해결 글 규칙

문제 해결 글은 문제 정의, 전제 조건, 해결 방법, 검증 방법 순서로 작성한다.

# [문제 해결 제목]

## Problem Definition

어떤 환경에서 어떤 증상이 발생하는지 설명한다.

## Prerequisites

필요한 실행 환경, 패키지 버전, 설정을 적는다.

## Solution

바로 적용 가능한 명령어, 코드, 설정을 제시한다.

## Verification

문제가 해결되었는지 확인하는 방법을 적는다.

환경 차이가 결과에 영향을 줄 수 있으면 운영체제, Node.js 버전, 패키지 매니저, 브라우저 차이를 별도로 적는다.

8. 학습형 글 규칙

학습형 글은 목표, 사전 준비, 단계별 가이드, 최종 검증 순서로 작성한다.

# [튜토리얼 제목]

## Goal

독자가 글을 따라 한 뒤 무엇을 할 수 있는지 설명한다.

## Prerequisites

필요한 지식, 도구, API key, 패키지를 적는다.

## Step-by-Step Guide

### 1. 첫 번째 단계

가장 작은 실행 가능한 예시부터 시작한다.

### 2. 두 번째 단계

앞 단계의 결과 위에 다음 개념을 추가한다.

## Verify Final Result

최종 결과와 확인 방법을 설명한다.

FAQ가 있으면 글 말미에 추가한다. 핵심 요약이나 긴 보충 설명은 <details>와 <summary>를 사용할 수 있다.

9. 금지 규칙

문서, 코드 주석, 커밋 메시지, PR 본문에 에이전트 이름, 도구 이름, 생성 서명 문구를 남기지 않는다.

근거 없는 정량 지표를 쓰지 않는다. 측정하지 않은 수치는 사례처럼 표현하지 않는다.

결론 없이 열거만 하는 구성을 피한다. 글의 마지막은 반드시 배운 점, 설계 판단, 다음 개선 방향 중 하나로 수렴시킨다.

10. 작성 후 확인

새 글을 작성한 뒤에는 frontmatter 형식과 렌더링 여부를 확인한다.

pnpm typecheck
pnpm lint
pnpm build

형식만 수정한 경우에도 공개 글이면 빌드 결과에서 목록 페이지와 상세 페이지가 정상적으로 생성되는지 확인한다.