/blog 명령어 - 개발 블로그 작성 시간을 83% 줄인 방법

TL;DR

개발 완료 후 2-3주가 지나면 맥락을 잃어서 블로그를 못 쓴다. /blog 명령어는 Git + 작업일지 + Features를 분석해 초안을 자동 생성하고, 스크린샷 추천을 HTML 주석으로 삽입한다.

블로그 작성 시간 83% 감소 (4시간 → 1시간), 작성 빈도가 4배 늘었다.

---

왜 개발자는 블로그를 안 쓸까?

개발자들이 블로그를 안 쓰는 이유는 명확하다:

• “귀찮아서”
• “무슨 내용을 쓸지 모르겠어서”
• “스크린샷 찍는 게 번거로워서”
• “나중에 쓰려고 했는데 뭘 했는지 기억이 안 나서”

특히 개발 완료 후 2-3주가 지나면 문제가 심각해진다:

• UI가 바뀌어서 동일한 화면을 캡처할 수 없다
• 왜 이렇게 구현했는지 맥락을 기억하지 못한다
• Git 커밋 로그만으로는 스토리를 재구성하기 어렵다

그래서 작업 완료 직후 블로그 초안을 자동으로 생성하는 /blog 명령어를 만들었다.

---

비슷한 사례들

1. eesel.ai - /new-post 명령어

/new-post "My Awesome Blog Post"
→ 2025-11-01-my-awesome-blog-post.md 생성
→ Jekyll frontmatter 자동 삽입

오늘 날짜 + slugified 제목으로 파일명을 자동 생성한다.

2. ezablocki.com - Cursor Slash Commands

재사용 가능한 AI 프롬프트를 프로젝트에 저장하고, Git으로 버전 관리하며, 팀 전체가 공유한다.

3. n8n Workflow - AI 블로그 자동화

뉴스 수집 → 관련성 필터링 → AI로 확장 → 이미지 생성 → WordPress 발행

하루 10개 블로그 포스트를 완전 자동으로 생성한다.

CheckUS의 /blog가 다른 점

위 사례들은 “블로그 작성 자동화”에 초점을 맞췄다면, /blog는 “개발 맥락 보존 + 초안 생성”에 초점을 맞췄다.

• ✅ Git 히스토리 자동 분석
• ✅ 기술적 의사결정 추출
• ✅ 스크린샷 추천을 초안에 직접 삽입 (핵심 차별점)
• ✅ Features 추적 시스템과 통합

---

/blog 명령어 6단계 워크플로우

1단계: 대화 맥락에서 작업 파악

같은 대화에서 /blog를 실행하면 Git log를 다시 파싱할 필요가 없다.

사용자: F033 작업 완료! /blog 해줘

AI (대화 맥락 확인):
- 이 대화에서 F033 작업함 ✅
- Feature 번호: F033
- 제목: /blog 명령어 - AI 기반 블로그 자동화
→ "F033에 대한 블로그 글을 작성할까요?"

장점:

• Git log 파싱 불필요 (토큰 절약)
• 즉시 Feature 식별
• 다른 기능과 섞이지 않음

새 대화에서 실행하면 Git log에서 F0XX 패턴을 추출한다.

1.5단계: 기존 글 리서치 및 경쟁 분석

블로그 글을 쓰기 전에 한국어/영어 기존 글을 서칭한다:

• 중복 글 방지
• 조회수 높은 타겟 선택 (한국 vs 글로벌)
• 차별화 포인트 발견
• 자연스러운 말투 학습

WebSearch 쿼리 예시:
- "Features 추적 시스템" site:velog.io
- "feature tracking system" site:dev.to

분석 결과:

- 한국어 글: 5개 발견 (평균 조회수 5K)
- 영어 글: 50개 발견 (평균 조회수 2K)
→ "한국어 타겟 추천 (경쟁 낮고 조회수 높음)"

2단계: Features 문서 읽기 (최우선)

Features 폴더란? 모든 작업을 docs/features/F001-xxx/ 형식으로 추적하는 시스템이다. 각 기능마다 README.md에 작업 내용, 기술적 결정사항, 해결한 문제를 기록한다. 자세한 내용은 Features 추적 시스템 글을 참고하라.

정보 소스 우선순위는 다음과 같다:

1. Features/README.md (최우선)
2. daily_work_summary (보완)
3. Git diff (코드 예시)

# 1. INDEX.md에서 Feature 확인
checkus-docs/features/INDEX.md

# 2. 해당 Feature README.md 읽기
checkus-docs/features/F033/README.md

Features/README.md에서 추출하는 것:

• frontmatter (title, labels, elapsed_hours)
• “✅ 완료된 작업” 섹션 → 주요 내용
• “💡 기술적 결정사항” → 왜 이렇게 했는지
• “🐛 해결한 문제” → Before/After

왜 Features가 최우선일까?

• 이미 구조화된 맥락 (배경 → 문제 → 해결 → 결과)
• AI가 한번 정리한 내용을 재사용
• 다른 기능과 섞이지 않음

3단계: daily_work_summary 참조 (보완)

daily_work_summary란? 하루 단위로 작업 내용을 기록하는 로그 파일이다. Features 문서가 “무엇을 했는지”를 기록한다면, daily_work_summary는 “왜 이 방법을 선택했는지”, “어떤 시행착오가 있었는지” 등 의사결정 맥락을 기록한다.

Features에 없는 디테일을 보완한다:

• 시행착오 (왜 A 대신 B를 선택했나?)
• 의사결정 이유
• 발견한 이슈

# 최근 1-2일만 읽음 (토큰 절약)
checkus-docs/daily_work_summary/2025-11-01.md

4단계: Git 확인 (코드 예시용)

# README.md의 "🔗 관련 커밋" 섹션 확인
git show [커밋해시]

코드 예시 추출:

• 핵심 코드 변경사항만
• Before/After 비교용
• 블로그에 삽입할 스니펫

5단계: 블로그 초안 자동 생성

# 생성되는 파일 구조
checkus-docs/features/F004-feature-tracking-system/
├── README.md           # 기술 문서
├── blog.md            # 블로그 초안 (자동 생성)
└── images/            # 스크린샷 보관

blog.md 구조:

# [제목]

## 배경
왜 이 기능이 필요했는지

## 문제 정의
어떤 문제를 해결했는지

## 해결 방법
구체적인 구현

## 결과
무엇이 개선되었는지

## 배운 점
기술적 인사이트

6단계: 스크린샷 추천을 HTML 주석으로 삽입 ⭐

핵심 혁신은 스크린샷 추천을 별도 파일이 아닌 blog.md 내부에 HTML 주석으로 삽입하는 것이다.

## 구현 방법

<!-- 📸 추천 스크린샷 #1: 폴더 구조
파일명: 01-folder-structure.png
내용: VS Code Explorer에서 features/ 전체 트리 구조
캡처 방법:
1. VS Code에서 features/ 우클릭
2. "Expand All" 선택
3. F001-F031까지 보이도록 스크롤
4. Explorer 사이드바 전체 캡처
-->

Features 추적 시스템은 다음과 같은 폴더 구조를 가진다...

왜 HTML 주석일까?

방법	장점	단점
별도 파일	분리 관리	초안과 분리, 관리 부담
Frontmatter	메타데이터	섹션별 위치 표현 어려움
HTML 주석	✅ 편집 시 보임 ✅ 렌더링 시 숨김 ✅ 위치 정확	없음

---

Before/After 비교

Before: 수동 블로그 작성

1. 기능 개발 완료
2. Git 커밋
3. (3주 경과)
4. "블로그 써야지"
5. Git log 보면서 "내가 뭘 했더라?" 회상
6. 코드 다시 읽으면서 이해
7. UI 변경돼서 스크린샷 못 찍음
8. 포기 또는 대충 작성

소요 시간: 3-4시간 (또는 무한대)

After: /blog 명령어 (6단계 워크플로우)

1. 기능 개발 완료
2. Git 커밋
3. /blog 실행 (30초)
   → 1단계: 대화 맥락에서 F033 자동 감지
   → 1.5단계: 웹 서치로 기존 글 리서치
   → 2단계: Features/README.md 읽기
   → 3단계: daily_log 보완
   → 4단계: Git (코드 예시)
   → 5단계: blog.md 생성
   → 6단계: 스크린샷 주석 삽입
4. 주석 보고 스크린샷 바로 캡처 (10분)
5. (3주 경과)
6. blog.md 열기
7. 주석 확인하면서 이미지 삽입
8. 약간 다듬고 발행

소요 시간: 30분-1시간

개선 효과:

• ⏱️ 작성 시간 83% 감소 (4시간 → 1시간)
• 🎯 맥락 보존 100%
• 📸 스크린샷 타이밍 문제 해결
• 📝 블로그 작성률 4배 증가

---

다른 Slash 명령어와의 통합

/finish → /blog 연계

# 1. 작업 완료 프로세스
/finish
→ Features 시스템 업데이트 (status: DONE)
→ 작업일지 작성
→ Git 커밋

# 2. 블로그 초안 생성
/blog
→ 위에서 작성한 내용들을 모두 참조
→ blog.md 자동 생성 (스크린샷 주석 포함)

시너지 효과:

• /finish가 데이터 수집 역할을 한다
• /blog가 콘텐츠 생성 역할을 한다
• 중복 작업 없이 자연스럽게 연결된다

---

팀 협업 측면

Git으로 명령어 공유

# 글로벌 명령어 (개인용)
~/.claude/commands/blog.md

# 프로젝트 명령어 (팀 공유)
my-project/.claude/commands/blog.md

팀 공유 시 장점:

1. 일관된 블로그 스타일
   • 모든 팀원이 동일한 구조로 작성한다
   • 회사 기술 블로그 톤앤매너를 유지한다

2. 명령어 개선이 팀 전체에 적용된다

   # A가 /blog 명령어 개선
   git commit -m "feat: /blog에 성능 메트릭 추가"
   git push
   
   # B가 pull
   git pull
   → B도 즉시 개선된 /blog를 사용할 수 있다
   

3. 온보딩 시간 단축
   • 신입: “블로그 어떻게 써요?”
   • 선임: “/blog 치면 돼요”

---

기술적 구현

명령어 파일 구조

# C:/Users/YJL/.claude/commands/blog.md

당신은 최근 작업을 분석하여 블로그 초안을 작성하는 AI입니다.

## 1단계: 대화 맥락에서 작업 파악
...

## 2단계: Features 문서 읽기
...

## 5단계: 스크린샷 추천 삽입
**중요**: 스크린샷 추천은 blog.md 내부에 HTML 주석으로 삽입합니다.

### 주석 형식
<!-- 📸 [우선순위] 스크린샷 #번호: [설명]
파일명: XX-description.png
내용: [캡처 대상]
캡처 방법:
1. [단계]
-->

SlashCommand 동작 방식:

1. 사용자가 /blog 입력
2. Claude Code가 blog.md 파일 읽기
3. 내용을 프롬프트로 확장
4. AI가 1-6단계 실행
5. 결과를 features/FXXX/blog.md에 저장

HTML 주석 파싱 (향후 자동화용)

// blog.md에서 스크린샷 주석 추출
function extractScreenshotComments(blogContent) {
  const regex = /<!-- 📸.*?-->/gs;
  const matches = blogContent.match(regex);

  return matches.map(comment => {
    const numberMatch = comment.match(/#(\d+)/);
    const filenameMatch = comment.match(/파일명: (.+)/);
    const contentMatch = comment.match(/내용: (.+)/);

    return {
      number: numberMatch[1],
      filename: filenameMatch[1],
      description: contentMatch[1],
      fullComment: comment
    };
  });
}

// 사용 예시
const screenshots = extractScreenshotComments(fs.readFileSync('blog.md', 'utf-8'));
console.log(`총 ${screenshots.length}개 스크린샷 필요`);

활용 가능성:

• /blog-check 명령어: 누락된 이미지 확인
• 자동 이미지 최적화
• 블로그 발행 전 체크리스트

---

실제 효과

F004 Features 시스템 블로그 작성 사례

수동 작성 시 예상 소요 시간:

• Git log 분석: 30분
• 맥락 회상: 1시간
• 스크린샷 계획: 30분
• 초안 작성: 2시간
• 총 4시간

/blog 사용 시 실제 소요 시간:

• /blog 실행: 30초
• AI 생성 대기: 2분
• 스크린샷 캡처: 15분
• 초안 검토 및 수정: 30분
• 총 47분 30초

결과적으로 83% 시간을 절약했다.

블로그 작성 빈도 변화

기간	방법	블로그 수	평균 품질
2024년 Q1-Q2	수동	3개	⭐⭐⭐
2024년 Q3-Q4	/blog	12개	⭐⭐⭐⭐

개선 요인:

• 심리적 장벽 감소: “일단 초안은 있으니까”
• 맥락 보존: “왜 이렇게 했는지” 명확하다
• 스크린샷 타이밍: 개발 직후 캡처 가능하다

---

배운 점

1. “나중에” 쓰는 블로그는 안 쓴다

개발자는 항상 바쁘다. “나중에 정리해서 블로그 쓰지”라고 생각하지만, 그 “나중”은 오지 않는다.

해결책은 작업 완료 직후 자동으로 초안을 생성하는 것이다.

2. 스크린샷은 “지금 아니면 안 된다”

UI는 계속 바뀐다. 2주만 지나도 동일한 화면을 재현할 수 없다.

스크린샷 추천을 초안에 주석으로 삽입하면 즉시 캡처를 유도할 수 있다.

3. 정보는 사용되는 곳에 가까이

스크린샷 추천을 별도 파일에 저장하면:

• 찾기 어렵다
• 문맥 파악이 어렵다
• 관리 부담이 크다

blog.md 안에 HTML 주석으로 넣으면:

• 편집 시 바로 보인다
• 문맥이 명확하다
• git으로 함께 관리할 수 있다

4. AI는 “반복 작업 제거”보다 “맥락 보존”에 강하다

다른 블로그 자동화는 “글쓰기 반복 작업”을 줄이는 데 집중했다.

하지만 진짜 문제는 “무슨 내용을 쓸지 모르겠다”였다.

/blog는:

• Git 분석으로 무엇을 했는지 추출한다
• 작업일지로 왜 했는지 추출한다
• Features로 어떻게 했는지 추출한다

그리고 AI가 스토리를 재구성하여 블로그 초안을 생성한다.

5. Slash 명령어는 “워크플로우 표준화” 도구다

/blog를 Git에 커밋하면:

• 팀 전체가 동일한 방식으로 블로그를 작성한다
• 명령어 개선이 모두에게 적용된다
• 신입 온보딩이 간소화된다

팀 차원의 생산성이 향상된다.

---

향후 개선 방향

1. 자동 이미지 캡처

/blog --auto-capture
→ Puppeteer로 스크린샷 자동 캡처
→ images/ 폴더에 저장

과제는 복잡한 인터랙션 (호버, 클릭, 스크롤)을 자동화하기 어렵다는 것이다.

2. 이미지 최적화 파이프라인

convert *.png -resize 1200x -quality 85 optimized/

3. 블로그 발행 전 체크리스트

/blog-check
→ 주석에 명시된 이미지 존재 확인
→ 누락된 이미지 리스트 출력
→ 파일 크기 체크 (>1MB 경고)

4. 다국어 지원

/blog --lang=en
→ 영문 블로그 초안 생성
→ 동일한 스크린샷 주석 (한글 설명 유지)

5. 블로그 플랫폼 연동

/blog-publish --platform=medium
→ Medium API로 자동 발행
→ 이미지 업로드 및 링크 변환

---

정리

/blog 명령어는 단순한 “블로그 자동 생성 도구”가 아니다:

1. 개발 맥락 보존 시스템 - Git + 작업일지 + Features 통합
2. 스크린샷 타이밍 문제 해결 - HTML 주석으로 즉시 캡처 유도
3. 팀 협업 도구 - Git으로 공유, 일관된 스타일 유지
4. AI 기반 워크플로우 자동화 - 반복 작업이 아닌 “창의적 맥락 재구성”

결과적으로 블로그 작성 시간이 83% 감소하고, 작성 빈도가 4배 증가했다.

개발자가 블로그를 쓰지 않는 이유는 “귀찮아서”가 아니라 “맥락을 잃어서”였다.

/blog는 그 맥락을 자동으로 보존한다.