blog-post

Overview

개발하면서 겪은 것 중 글로 남길 만한 것은 따로 있다. 기능을 하나 추가한 건 글이 안 되고, "예상과 달랐던 것"이 있어야 글이 된다. 이 스킬은 레포에서 그 신호를 찾아 후보를 제안하고, 고른 주제로 초안을 만든다.

3개 스킬을 엮는다. 이 스킬이 뭘 쓸지 정하고 사실을 모으고 초안을 만들고, claude-in-chrome이 화면을 캡처하고, humanize-korean이 AI 티를 벗긴다.

문체와 흐름은 style.md가 기준이다. 합니다체를 쓰고, 번호 섹션으로 "기획 의도 → 기능 → 기술 → 느낀 점 → 개선 → 마무리" 순서로 나아가는 친절한 개발기다.

쓰지 않는 경우: README·API 문서(서사가 아니라 레퍼런스), 커밋 메시지, 단순 기능 추가만 있는 작업.

핵심 원칙

1. 없는 사실은 만들지 않는다. 글감을 키우다 보면 구체적인 숫자가 아쉬워진다. 원문·코드·로그에 근거가 없는 수치·기간·리전명·에러 메시지·비용은 절대 쓰지 않는다. "이틀은 아꼈다", "응답 속도가 3배" 같은 문장은 근거 파일을 인용할 수 있을 때만 쓴다. 없으면 > ⚠️ [확인 필요: ...] 블록으로 남기고 사용자에게 명시적으로 넘긴다.

2. AI 티를 벗기다가 가독성을 죽이지 않는다. 이모지·굵게·표·이미지를 전부 걷어내면 문체는 자연스러워져도 읽히지 않는 글이 된다. 문제는 이것들이 남발된 거지 존재한 게 아니다. §6 가독성 게이트를 반드시 통과시킨다.

3. 플레이스홀더를 남긴 채 끝내지 않는다. [여기 채우기]가 발행본에 그대로 나가는 사고가 실제로 난다. 초안을 쓰는 동안 [이미지 제안: ...] 같은 마커를 박아두는 건 좋다 — 어디에 무엇이 필요한지 보이니까. 다만 끝낼 때 하나도 안 남아야 한다. 실제로 캡처했으면 이미지로 바꾸고, 못 했으면 본문에서 빼서 §8 "직접 채울 것" 목록으로 옮긴다.

절차

1. 범위 확인

cwd가 git 레포인지 먼저 본다. 아니면 어떤 레포/디렉터리를 볼지 사용자에게 묻는다.

어디까지를 "이번 작업"으로 볼지 정한다 — 기본은 기본 브랜치와의 차이. 사용자가 기간이나 브랜치를 말하면 그걸 따른다.

BASE=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|origin/||' || echo main)
git log --oneline "$BASE"..HEAD
git log --oneline --since="3 weeks ago"          # 브랜치가 이미 머지됐을 때

2. 글감 신호 수집

기능 목록이 아니라 마찰의 흔적을 찾는다. 아래가 실제로 글이 되는 신호다.

신호	찾는 법
삽질 — 같은 걸 여러 번 고침	git log --oneline --all | grep -iE "fix|retry|again|revert|temp|wip"
방향 전환 — 접근을 통째로 바꿈	git log --diff-filter=D --name-only (파일·의존성 삭제), git log -p -- package.json | grep '^-'
자주 손댄 곳 — 어렵다는 뜻	git log --format= --name-only | sort | uniq -c | sort -rn | head -20
외부 제약에 부딪힘	코드 주석·이슈에서 grep -rn "때문에|어쩔 수 없|우회|workaround|안 되" --include="*.md"
수치가 있는 개선	비용·용량·응답시간을 다룬 커밋, 벤치마크 파일
처음 써본 기술	새로 추가된 의존성 (git log -p -- package.json | grep '^+ ')

이슈·PR이 있으면 같이 본다: gh issue list --state all --limit 20, gh pr list --state all --limit 20.

현재 세션의 대화도 1급 소재다. 이미 컨텍스트에 있는 내용 — 무엇이 막혔고 왜 그 방향을 접었는지 — 은 git에 안 남는다. 트랜스크립트 파일을 다시 읽지 말고 지금 맥락에서 가져온다.

3. 후보 제안 (필수)

3~4개를 AskUserQuestion으로 제안한다. multiSelect: true — 여러 개를 고를 수 있다.

각 후보는 세 가지를 담는다:

• 제목안 — 실제로 클릭할 만한 문장
• 어떤 이야기인지 — "무엇이 예상과 달랐고, 어떻게 풀었는가" 한두 줄
• 근거 — 어떤 커밋·파일·대화에서 나왔는지

후보는 두 종류다.

• 프로젝트 개발기 — 레포가 하나의 서비스로 완성됐을 때. 왜 만들었고 무엇을 어떻게 만들었는지가 글이 된다. 마찰 소재가 있으면 4장 "부딪힌 문제"에 넣는다.
• 트러블슈팅 단편 — 기존 서비스에 작업 하나를 더한 경우. 마찰이 없으면 후보가 아니다.

글이 안 될 것 같은 후보는 넣지 않는다. 쓸 만한 게 하나도 없으면 없다고 말한다 — 억지로 4개를 채우지 않는다.

3.5. 후보가 다 아니라고 하면 — 인터뷰로 전환

사용자가 후보를 전부 거절하는 일이 실제로 있다. 이유는 대개 하나다. §2가 찾는 건 git에 남은 마찰인데, 사용자가 쓰고 싶은 건 왜 이걸 만들었고 무엇을 느꼈는가일 때다. 회고·프로젝트 소개·"AI 시대에 개발자는" 같은 글이 여기 해당한다.

이때 후보를 다시 4개 만들어 던지지 않는다. 근거가 git에 없으니 몇 번을 다시 뽑아도 같은 성격의 후보가 나온다. 인터뷰로 바꾼다.

전환 신호:

• 후보를 전부 거절하고 "~한 느낌으로 쓰고 싶다"처럼 방향만 말할 때
• 트러블슈팅이 아니라 소개·회고를 원할 때
• 사용자가 "물어보면서 해도 된다"고 할 때

넘겨짚지 않는다. 이런 글의 알맹이는 사용자의 판단과 감상이고, 그건 레포에 없다. 지어내면 "그럴듯한데 내 생각이 아닌 글"이 나온다. 그래서 묻고 받아쓴다.

먼저 AskUserQuestion으로 두 가지를 못 박는다.

물을 것	왜
독자	"AI 도구를 쓰는 동료 개발자"와 "채용 담당자"는 완전히 다른 글이 된다
결론 한 문장	글이 끝났을 때 독자에게 남길 것. 이게 정해져야 소재를 고를 수 있다

그다음 한 번에 서너 개씩 묶어 질문한다. 한 문항씩 주고받으면 사용자가 지친다. 좋은 질문은 의견이 아니라 장면을 부른다.

• ❌ 이 프로젝트의 의의는 무엇인가요
• ✅ 이걸 쓰기 전에는 그 작업을 어떻게 하셨나요
• ✅ 만들고 나서 실제로 달라진 순간이 있었나요
• ✅ AI에 맡겼다가 안 됐던 건 뭐였나요
• ✅ 남들은 잘 모르는데 본인은 자주 쓰는 방법이 있나요

답변은 요약하지 말고 소재로 쓴다. 사용자가 든 구체적인 예(도구 이름, 그때 한 말, 반복하던 요청)가 글에서 제일 값어치 있는 부분이다. 매끄럽게 다듬다가 그 예를 통째로 날리면 인터뷰한 의미가 없다.

인터뷰가 끝나면 §4로 간다. 인터뷰 내용도 사실 확인 대상이다 — 사용자가 언급한 스킬·파일·수치는 실제로 있는지 확인하고, 없으면 본문에서 뺀다.

4. 사실 수집

고른 주제에 대해 실제 코드·커밋·설정·로그를 읽는다. 기억이나 추측으로 채우지 않는다.

읽으면서 두 개의 목록을 만든다.

• 확인된 사실 — 파일과 줄 번호를 붙인다. 본문에 쓸 수 있다.
• 확인 못 한 것 — 에러 메시지 원문, 실제 수치, 리전명, 소요 시간처럼 사용자만 아는 것. 본문에 추정치를 넣지 말고 §8 목록으로 뺀다.

5. 스크린샷 (claude-in-chrome)

레포 README에 넣을 캡처라면 readme-screenshots 스킬을 쓴다. 그쪽이 목록 합의·뷰포트 고정·파일명 안정성까지 다룬다. 여기서 찍는 건 블로그 본문용 — 실패 화면, 에러 메시지, 중간 과정처럼 README에는 안 들어갈 것들이다.

거기서 두 가지는 그대로 가져온다. 앱이 안 뜨면 거기서 멈춘다 — 목업을 만들거나 옛 캡처를 재활용하지 않고 왜 못 띄웠는지 보고한다. 그리고 로딩 스피너나 에러 난 화면을 찍지 않는다 — 실제 콘텐츠가 뜬 걸 확인하고 찍는다 (의도적으로 에러 화면을 보여주는 경우는 예외).

글에 들어갈 화면이 있으면 실제로 캡처한다. 먼저 필요한 도구를 한 번의 ToolSearch로 로드한다.

ToolSearch: "select:mcp__claude-in-chrome__tabs_context_mcp,mcp__claude-in-chrome__tabs_create_mcp,mcp__claude-in-chrome__navigate,mcp__claude-in-chrome__computer,mcp__claude-in-chrome__resize_window,mcp__claude-in-chrome__gif_creator,mcp__claude-in-chrome__tabs_close_mcp"

동작 자체를 보여줘야 하는 화면(경로 탐색, 폼 제출, 로딩 후 결과)은 정지 샷보다 GIF가 낫다. gif_creator로 녹화하되 동작 전후로 프레임을 여유 있게 잡고, 파일명은 나중에 알아볼 수 있게 짓는다 (route-search.gif).

절차:

1. tabs_context_mcp로 현재 탭 상황을 본다. 기존 탭을 재사용하지 않는다 — tabs_create_mcp로 새 탭을 연다.
2. 로컬 앱이면 dev 서버가 떠 있는지 확인하고, 안 떠 있으면 사용자에게 띄워달라고 한다. 배포본이면 그 URL로 간다.
3. 캡처 전에 resize_window로 폭을 고정한다 — 데스크톱 1280, 모바일 화면이면 390. 샷마다 크기가 다르면 글이 지저분해진다.
4. computer의 screenshot으로 찍고 레포 밖(스크래치패드)에 저장한다. 사용자가 넣을 위치를 정하기 전까지 레포를 건드리지 않는다.
5. 끝나면 열었던 탭을 닫는다.

캡처 전 확인할 것 — 화면에 이게 찍히면 안 된다. 실명·이메일·전화번호, 토큰·API 키(주소창 쿼리스트링 포함), 사번·계좌·주소, 고객사 이름, 사내 도메인. 하나라도 보이면 찍기 전에 테스트 계정으로 바꾸거나, 찍은 뒤 사용자에게 가려달라고 말한다. 직접 모자이크 처리했다고 말하지 않는다 — 안 했으면 안 했다고 한다.

확인 다이얼로그(confirm/alert)를 띄울 버튼은 누르지 않는다. 브라우저 모달이 뜨면 이후 도구 호출이 전부 멈춘다.

6. 초안 작성

쓰기 전에 style.md를 읽는다. 어투와 문형, 고쳐 쓴 예가 거기 있다. 그다음 template.md의 골격을 채운다.

글의 성격은 친절한 프로젝트 개발기다. 독자를 놀라게 하려는 글이 아니라, 왜 만들었고 무엇을 어떻게 만들었는지 차분하게 안내하는 글이다.

어투는 합니다체로 통일한다. 해요체, "ㅋㅋ", 말줄임("..")은 쓰지 않는다. 문단은 1~2문장으로 쓰고, 문단 안에서도 문장마다 줄을 바꾼다.

도입부는 이 순서로 쓴다.

순서	하는 일	예
1. 인용	독자나 예전의 내가 했을 법한 말을 > 인용으로	"SQL 공부는 하고 싶은데, DB 설치부터 너무 막막해요…"
2. 경험	그게 언제 내가 느낀 벽이었는지	"대학 시절 SQL을 처음 배울 때 제가 느꼈던 가장 큰 벽이었습니다."
3. 구체화	되는 것 → 하지만 막히는 것 → 결국 어떻게 타협했나	2~4개 짧은 문단
4. 연결	정해진 문장으로 넘어간다	"그래서 만들게 된 프로젝트가 바로 X입니다."
5. 목표	굵은 따옴표 한 문장 + "이 목표로 프로젝트를 시작했습니다."	"설치 없이 ~을 만들자."

본문은 번호 섹션으로 쓰고 순서를 지킨다.

1. 기획 의도: 왜 만들었을까? — 대상 독자의 불편을 불릿으로
2. 주요 기능 및 스크린샷 — 2-1, 2-2 소제목. 기능마다 이미지
3. 기술 스택 및 구조 — 영역별 기술, 핵심 선택의 이유(불릿), ASCII 구조도
4. 개발하며 부딪힌 문제 — 선택. 삽질·방향 전환 소재를 골랐을 때만 넣는다
5. 개발하며 느낀 점 — "특히 다음 부분에서 많은 것을 배웠습니다." + 불릿
6. 아쉬웠던 점과 앞으로 개선하고 싶은 점
7. 서비스 링크
8. 마무리 — 도입부의 불편으로 되돌아와 닫는다

섹션마다 리듬이 같다. 한두 문장으로 상황을 설명하고, "다음과 같습니다"로 불릿을 나열한 뒤, 의도 한 문장으로 닫는다. 독자는 이 반복 덕분에 어디까지 읽었는지 놓치지 않는다.

4장을 넣을 때는 이 순서를 합니다체로 쓴다.

증상 → 범위 좁히기 (되는 경우와 안 되는 경우의 차이) → 확인한 것 → 원인 → 판단 (왜 그 방법을 골랐나)

원인만 쓰면 매뉴얼이 된다. 판단까지 써야 글이 된다.

기술 깊이는 얕게 잡는다. 기술마다 "무엇을 썼고, 그게 뭐고, 그래서 뭐가 가능했는지" 세 문장이면 된다. 공식, 상수 튜닝, 파일 경로는 기본으로 뺀다. 꼭 필요하면 4장에 하나만 넣는다.

제목은 "{서비스가 해주는 일}, {서비스명} 개발기" 형식으로 쓴다.

• ✅ 설치 없이 SQL을 연습할 수 있는 웹 서비스, NULL지마 개발기
• ✅ 출발점만 넣으면 돌아오는 러닝 코스를 찾아주는 웹앱, 루프런 개발기

가독성 게이트 — 쓰면서 지킨다.

• 이미지는 기능 섹션마다 1장. 대표 화면이 있으면 도입부 끝에도 넣는다
• 문단은 1~2문장. 문장마다 줄을 바꾼다
• 큰 섹션 사이와 기능 소제목 사이에 ---를 넣는다
• 섹션 제목에는 번호를 붙이고(## 1., ### 2-1.) 이모지는 붙이지 않는다. 이모지는 서비스 링크 줄(🌐 🐙)에만 쓴다
• 굵게는 섹션의 핵심 한 구절에만 쓴다. 섹션당 1~2회
• 불릿 항목은 짧게 쓴다. 불릿 안에서 굵게+콜론 조합은 쓰지 않는다
• 코드블록은 구조도 위주로 넣는다. 구현 코드는 4장에만, 15줄 이내로
• 앞 문장에서 무슨 화면인지 말하지 않았다면 이미지 아래에 캡션을 한 줄 단다

쓰다가 "여기 뭔가 들어가야 하는데 아직 없다" 싶으면 [이미지 제안: 배포 실패 화면]처럼 자리를 표시해두고 계속 쓴다. §5로 돌아가 캡처하거나 §8 목록으로 넘길 수 있도록, 마커는 대괄호 한 줄로 통일한다.

7. humanize-korean 통과

초안을 humanize-korean 스킬에 넘겨 AI 티를 벗긴다.

주의할 점:

• humanize-korean은 내용을 안 바꾼다. 문체·리듬만 고친다. 그러니 초안 단계에서 내용은 완성해둔다.
• cwd에 _workspace/를 만든다. 레포 안에서 돌리지 않는다 — 스크래치패드에서 돌리거나, 돌렸으면 _workspace/가 커밋에 안 들어갔는지 확인한다.
• 결과는 final.md. 본문 끝의 <!-- HUMANIZE-SUMMARY --> 주석 블록은 발행 전에 지운다.

넘길 때 문체 보존 지시를 같이 준다. 아래 요소는 AI 티처럼 보여도 style.md가 의도한 문체다. 걷어내지 말라고 명시한다.

• 합니다체 (해요체로 바꾸지 않는다)
• "다음과 같습니다" 뒤에 이어지는 짧은 불릿
• 번호 섹션 제목과 --- 구분선
• 문장마다 줄을 바꾼 짧은 문단
• "그래서 만들게 된 프로젝트가 바로 X입니다", "단순히 ~가 아니라 ~할 수 있도록" 같은 반복 문형

윤문 후 §6 게이트를 다시 확인한다. 이미지, 불릿, 줄바꿈이 깎였거나 어미가 해요체로 바뀌었으면 되돌린다.

8. 마무리 점검과 인계

기계적으로 센다. 눈으로 넘겨짚지 않는다.

F=<초안 경로>
grep -c '^!\[' "$F"                    # 이미지 — 1 이상
grep -nE '^#{2,3} ' "$F"              # 번호 섹션 순서 확인, 제목에 이모지 없는지
grep -nE '(요|죠|네요)[.!?]?$|ㅋㅋ|\.\.$' "$F"   # 해요체·구어체 잔존 — 0건
grep -nE '확인 필요|여기 채우기|TODO|이미지 제안|시각자료|\[\[|HUMANIZE-SUMMARY' "$F"   # 잔존물 — 0건

그리고 사용자에게 직접 채울 것을 목록으로 넘긴다. 본문에 추정치로 때우지 않고 여기 모은다.

• §4에서 확인 못 한 항목 (에러 원문, 실제 수치, 리전명 등)
• 캡처에서 가려야 할 부분
• 이미지를 넣을 위치 (파일 경로와 함께)

발행한 뒤에는 실제 페이지를 한 번 스크롤해보라고 사용자에게 말한다. 에디터 화면과 발행본의 단 폭이 달라서, 원고에선 괜찮던 구간이 글자 벽으로 보이는 일이 흔하다.

초안은 로컬 .md 파일로만 남긴다. 커밋하지 않는다 — 사용자가 요청할 때만 한다.

9. 글 소개문 (150자 이내)

본문을 넘기고 끝내지 않는다. 목록·공유 화면에 뜰 소개문 하나를 같이 만든다. velog의 글 소개, 티스토리의 메타 설명, 링크를 붙였을 때 뜨는 미리보기가 전부 이 문장을 쓴다.

항목	기준
길이	150자 이내. 넘기면 잘린다
앞 80자	목록 카드에서 보이는 건 사실상 여기까지. 문제를 여기서 끝낸다
구조	본문 도입부와 같은 흐름 — 불편 한 문장 → 그래서 만든 것 → 핵심 방식 한 줄
인칭·문체	본문과 같은 합니다체
저장	초안 옆에 summary.txt

쓰는 법은 간단하다. 본문 도입부 세 문단을 압축한다. 새로 쓰지 않는다 — 요약이 본문과 다른 약속을 하면 들어온 독자가 바로 나간다.

• ❌ Claude Code 스킬을 만들어 개발 생산성을 높인 경험을 공유합니다 (무슨 문제인지 없음)
• ❌ 이 글에서는 스킬 시스템의 구조와 활용법을 살펴봅니다 (목차 안내)
• ✅ 집 근처에 강도 공원도 없어 매번 어디로 뛸지 고민했습니다. 그래서 출발점과 거리만 넣으면 돌아오는 러닝 코스 3개를 골라주는 웹앱, 루프런을 만들었습니다. TMAP 경유지로 루프를 그리고 경사·횡단보도를 따져 추천합니다. 운영비는 월 0원입니다

넘기기 전에 글자수를 실제로 센다. 눈대중하지 않는다.

python3 -c "s='''<소개문>'''; print(len(s))"

흔한 실수

• 해요체·"ㅋㅋ"·".."로 쓰기, 또는 윤문을 거치면서 해요체로 바뀐 걸 놓치기
• 문단 하나에 34문장을 붙여 쓰기 — 12문장으로 쓰고 문장마다 줄을 바꾼다
• 공식·상수·파일 경로를 기능 소개에 섞기 — 기술 디테일은 3장 "선택 이유"나 4장으로
• 느낀 점·아쉬운 점 섹션을 빼고 링크로 끝내기
• 트러블슈팅 단편에 마찰 없이 기능 목록만 늘어놓기
• 후보를 전부 거절당했는데 같은 성격의 후보를 다시 4개 뽑기 — §3.5 인터뷰로 전환할 자리다
• 인터뷰 답변을 매끄럽게 요약하다가 사용자가 든 구체적인 예를 날리기 — 그게 제일 값어치 있는 부분이다
• 회고·소개 글에서 사용자의 생각을 넘겨짚어 지어내기 — 레포에 없는 건 물어봐야 안다
• 본문만 넘기고 150자 소개문을 빼먹기 — 목록에서 클릭될지가 여기서 갈린다
• AskUserQuestion 건너뛰고 혼자 주제를 정하기
• 구체성이 아쉬워서 없는 수치를 지어내기 — 근거 없으면 §8 목록으로
• AI 티를 벗기다가 이미지·표·굵게까지 전부 걷어내 텍스트 벽 만들기
• 플레이스홀더를 본문에 남긴 채 "완성됐습니다"라고 말하기
• 스크린샷에 실계정·토큰이 찍힌 걸 확인 안 하고 넘기기, 또는 안 가리고 가렸다고 말하기
• 레포 안에서 humanize-korean을 돌려 _workspace/를 커밋에 섞기
• 기존 크롬 탭을 재사용해서 사용자 작업을 건드리기
• 도입부를 인용 → 경험 → "그래서 만들게 된 프로젝트가 바로 X" → 목표 문장 순서 없이 바로 기능 설명으로 들어가기
• 원고 에디터 기준으로 가독성을 판단하기 — 발행본은 단이 좁아서 다르게 보인다
• [이미지 제안: ...] 마커를 본문에 남긴 채 넘기기 — 캡처하든 목록으로 빼든 둘 중 하나