til

name	til
description	Use when user mentions "TIL", "write TIL", "TIL 작성", "learning note", or /til command. Do NOT use for Obsidian notes (use obsidian-note) or blog posts (use tech-blog-writer).

TIL Writer

TIL 저장소에 "왜(Why)" 중심의 스토리텔링 기술 문서를 작성합니다.

사용법

/til "주제"     # 주제로 바로 문서 작성 시작
/til            # 대화형으로 주제/카테고리 선택

참고 자료

파일	내용
mermaid-style-guide.md	mermaid 다이어그램 스타일 규칙 (색상, sequenceDiagram, subgraph)
writing-style-guide.md	작성 철학, 스토리텔링, Bold, LaTeX, 출처
category-guide.md	카테고리별 작성 특성
til-template.md	TIL 문서 템플릿

Instructions

Step 1: 주제 확인

인자가 있는 경우 (/til "주제"):

• 주제를 파악하고 적절한 카테고리 제안
• 카테고리 선택 시 category-guide.md 참조
• 사용자 확인 후 작성 시작

인자가 없는 경우 (/til):

• 어떤 주제로 TIL을 작성할지 질문
• 카테고리 선택 (python, java, spring, nodejs, security, computer-science, ai 등)

Step 2: 리서치

작성 전 tavily_search 또는 WebSearch로 주제를 검색하여 최신 정보와 공식 문서 URL을 확보한다. 할루시네이션 방지와 정확한 출처 확보를 위해 항상 실행한다.

Step 3: 문서 구조 작성

til-template.md의 템플릿을 기반으로 작성.

필수 섹션:

• # 제목 (호기심 유발)
• ## 결론부터 말하면 (핵심 요약 2-3문장 + 다이어그램/코드 비교)
• ## 1. 왜 ...? (배경, 문제 상황)
• ## 2. 핵심 개념 설명
• ## 3. 실제 사례 / 코드 예시
• ## 4. 정리
• ## 출처

Step 4: 핵심 원칙 적용

writing-style-guide.md를 읽고 아래 원칙을 적용:

• "왜(Why)"를 반드시 설명 — 정의 나열이 아닌 문제 상황에서 출발
• 스토리텔링 패턴 사용 — 문제→의문→해답, 만약~라면?, 이상한 점 발견
• 빌드업으로 처음 보는 독자도 따라오게 — 핵심 용어를 정의 없이 사용 금지. 도구 정의 → 직관적 기대 → 직관이 무너지는 순간 → 해법 순서로 쌓을 것 (writing-style-guide.md §6)
• 연결어로 흐름 만들기 — 단락 간 자연스러운 전환
• 문단 단위로 설명 — 한 줄씩 끊지 말 것

Step 5: 시각화 규칙

mermaid-style-guide.md를 읽고 아래 규칙을 적용:

• ASCII 박스 금지 → 테이블 또는 mermaid 사용
• 어두운 배경 + 흰 글씨: style Node fill:#1565C0,color:#fff
• 줄바꿈은 <br> 사용 (\n 아님)
• subgraph에는 style 지정하지 않음
• sequenceDiagram은 style 대신 rect rgba() 사용
• 다이어그램 작성 즉시 mcp__claude_ai_Mermaid_Chart__validate_and_render_mermaid_diagram으로 검증

Step 6: 스타일 규칙

writing-style-guide.md의 스타일 규칙 섹션을 참조:

• Bold 닫는 ** 다음에 반드시 띄어쓰기
• 수식은 LaTeX ($...$, $$...$$)
• 출처는 ## 출처 섹션에 공식 문서 최상단 배치

Step 7: 파일 저장

파일명 = 제목에서 공백을 하이픈으로 변환:

제목	파일명
# Python의 f-string	Python의-f-string.md
# Node.js가 싱글스레드라는 미신	Node.js가-싱글스레드라는-미신.md
# 왜 Spring은 CGLIB을 선택했을까?	왜-Spring은-CGLIB을-선택했을까.md

특수문자 처리: /, ?, :, * 등은 제거 후 하이픈 변환

저장 위치: /Users/sskim/dev/TIL/{category}/

Step 8: Self-Check 실행

문서 작성 완료 후 아래 항목 점검:

필수 (MUST)

• "왜"를 설명했는가?
• 스토리텔링으로 풀어갔는가?
• 빌드업이 충분한가? — 검색으로 처음 들어온 독자가 첫 섹션에서 막히는 핵심 용어가 있는가? 모든 핵심 용어가 등장 시점에 정의되어 있는가?
• "결론부터 말하면" 섹션이 있는가?
• 파일명이 제목과 일치하는가?

권장 (SHOULD)

• Before/After 비교가 있는가?
• 복잡한 개념은 mermaid로 시각화했는가?
• ASCII 박스 대신 테이블/mermaid를 사용했는가?

시각화 (CHECK)

• mermaid에서 \n 대신 <br> 사용했는가?
• mermaid style에 color가 있는가?
• sequenceDiagram에서 rect rgba() 사용했는가?
• subgraph에 style을 지정하지 않았는가?
• mcp__claude_ai_Mermaid_Chart__validate_and_render_mermaid_diagram으로 렌더링 검증했는가?

스타일 (CHECK)

• Bold 닫는 ** 다음에 띄어쓰기가 있는가?
• 수식은 LaTeX로 작성했는가?
• 출처를 명시했는가?
• 문단 단위로 설명했는가?

Verification

• mermaid 작성 즉시 → mcp__claude_ai_Mermaid_Chart__validate_and_render_mermaid_diagram으로 렌더링 검증
• Self-Check 체크리스트 (Step 8) 통과 확인

Gotchas

• ❌ mermaid에서 \n 사용 → <br> 사용해야 함
• ❌ subgraph에 style 지정 → subgraph는 style 미지원
• ❌ sequenceDiagram에서 style 사용 → rect rgba() 사용
• ❌ README.md 수정 시도 → GitHub Actions 자동 생성이므로 절대 금지
• ❌ "~는 ~이다" 정의 나열 → Why 중심 스토리텔링으로
• ❌ 핵심 용어를 정의 없이 사용 → 등장 시점에 1줄이라도 정의를 깔거나 빌드업 4단계(도구 정의→직관→직관 붕괴→해법)로 쌓아라
• ❌ 리서치 없이 내부 지식만으로 작성 → 항상 tavily_search 먼저
• ❌ 파일명에 /, ?, : 특수문자 포함 → 제거 후 하이픈 변환
• ❌ git add/commit/push 자동 실행 → 사용자가 명시적으로 요청할 때만

Troubleshooting

문제	원인	해결
mermaid 렌더링 깨짐	\n 사용 또는 color 누락	<br> 사용, style에 color 명시
Bold 뒤 텍스트 붙음	** 뒤 띄어쓰기 누락	**텍스트** 뒤 형태로 수정
sequenceDiagram 스타일 무시됨	style 미지원	rect rgba() 사용
카테고리 미결정	주제가 여러 카테고리에 걸침	가장 핵심적인 기술 기준으로 선택
파일명 특수문자 에러	제목에 /, ?, : 등 포함	특수문자 제거 후 하이픈 변환