프로젝트 2: 기술 블로그 작성 Skill 만들기
기술 블로그 글쓰기는 겉으로 보면 단순한 문서 작업처럼 보인다. 하지만 실제로는 세 가지 일이 동시에 일어난다. 먼저 코드를 읽어야 한다. 다음으로 문서와 변경 맥락을 이해해야 한다. 마지막으로 그것을 개발자 독자가 읽고 납득할 수 있는 설명으로 바꿔야 한다. 이 셋 중 하나라도 흔들리면 글은 금방 이상해진다. 코드는 맞는데 설명이 홍보문처럼 흐르거나, 문장은 유려한데 정작 구현 사실과 어긋나거나, 기술적으로는 맞지만 독자 수준을 전혀 고려하지 못하는 식이다.
그래서 기술 블로그 작성은 Agent Skill 프로젝트로 아주 좋은 과제다. 입력 자료가 다양하고, 절차가 분명하며, 결과물의 품질 기준도 비교적 선명하기 때문이다. 좋은 기술 블로그 작성 Skill은 "대충 읽고 그럴듯한 글을 뽑는 도구"가 아니다. 코드와 문서를 근거로 메시지를 추출하고, 주장과 사실을 분리하고, 독자 수준에 맞게 난이도를 조정하고, 마지막에 검증 가능한 초안으로 정리하는 생산 시스템이다.
이 장에서는 바로 그 시스템을 만든다. 목표는 간단하다. 저장소의 코드, 릴리스 노트, 설계 문서, PR 설명 같은 재료가 주어졌을 때, 에이전트가 개발자 대상 블로그 글을 안정적으로 생산하도록 만드는 것이다.
왜 기술 블로그는 별도의 Skill이 필요한가
많은 팀이 기술 블로그를 하나의 긴 프롬프트로 처리하려 한다. "이 코드를 읽고 블로그 글 써줘." 처음 한두 번은 괜찮아 보인다. 하지만 조금만 복잡해지면 바로 문제가 생긴다. 에이전트가 README만 읽고 핵심 구현을 놓치거나, 코드를 읽긴 했는데 왜 이 변경이 중요해졌는지를 설명하지 못하거나, 반대로 실제 코드에 없는 효용을 과하게 부풀리는 일이 생긴다.
기술 글쓰기는 특히 순서가 중요하다. 먼저 무엇이 바뀌었는지 파악해야 하고, 그다음 왜 바뀌었는지 이해해야 하며, 마지막으로 누구에게 어떤 의미가 있는지를 해석해야 한다. 그런데 이 순서를 고정하지 않으면 에이전트는 가장 눈에 잘 띄는 문장부터 집어 들고 글을 시작해버린다. 그 결과는 대개 비슷하다. 제목은 멋있고 문단도 그럴듯한데, 읽고 나면 남는 정보가 없다.
Skill로 만들면 이 문제를 줄일 수 있다. 에이전트는 먼저 자료 종류를 구분하고, 코드 읽기 순서에 따라 핵심 포인트를 추출하며, 기술적 사실과 해석을 구분한 뒤, 정해진 템플릿에 맞춰 글을 작성한다. 글이 잘 써지는 것보다 더 중요한 것은, 같은 기준으로 반복해서 써진다는 점이다. 그래야 팀 블로그가 사람마다 다른 목소리로 흔들리지 않고, 한 번 잘 작동한 절차를 계속 재사용할 수 있다.
이 Skill의 책임 범위부터 정하자
프로젝트를 시작할 때 가장 먼저 할 일은 에이전트가 어디까지 책임질지를 정하는 것이다. 기술 블로그 작성 Skill은 보통 다음 범위를 책임진다. 소스 코드와 문서를 읽고, 변경 사항을 구조화하고, 개발자 독자 기준으로 설명 수준을 맞추고, 필요한 예시 코드와 다이어그램 제안을 포함해 블로그 초안을 작성하는 것까지다.
반대로 이 Skill이 책임지지 않는 일도 있다. 실제 배포 여부 판단, 내부 비공개 정보 공개 승인, 성능 수치의 법무 검토, 제품 마케팅 문구 최종 승인, 이미지의 최종 디자인 작업은 이 Skill 바깥에 두는 편이 안전하다. 기술 블로그는 기술 설명과 대외 커뮤니케이션의 경계에 놓여 있기 때문에, 마지막 승인 단계는 사람이 가져가는 구조가 좋다.
핵심은 이것이다. 이 Skill은 글을 자동으로 발행하는 기계가 아니라, 근거 있는 초안을 빠르고 일관되게 만드는 시스템이어야 한다.
입력 계약을 먼저 고정하라
기술 블로그 작성 Skill이 흔들리는 가장 큰 이유는 입력이 너무 모호하기 때문이다. "이번 기능 블로그 써줘"라는 요청만으로도 글은 나올 수 있다. 하지만 어떤 자료를 봤는지, 어느 독자를 상정하는지, 공개 가능한 범위가 어디까지인지 정해지지 않으면 결과물은 쉽게 어긋난다.
그래서 이 Skill도 입력 계약이 필요하다. 최소한 다음 질문에는 답이 있어야 한다.
글의 주제 또는 다루는 변경 사항은 무엇인가
입력 자료는 무엇인가: 저장소 경로, PR 설명, 설계 문서, 릴리스 노트, 이슈 링크 등
예상 독자는 누구인가: 프레임워크 사용자, 사내 개발자, 오픈소스 기여자, 프론트엔드 엔지니어 등
독자가 이미 알고 있다고 가정하는 배경지식 수준은 어느 정도인가
글의 목적은 무엇인가: 소개, 튜토리얼, 변경 요약, 마이그레이션 안내, 성능 개선 설명 등
꼭 포함해야 할 내용과 공개하면 안 되는 내용은 무엇인가
글의 길이와 출력 형식은 어떤가: 짧은 릴리스 글, 심층 기술 해설, 단계별 튜토리얼 등
이 입력 계약의 장점은 아주 실용적이다. 에이전트가 시작부터 "무슨 말을 해야 하는 글인지"를 추측으로 채우지 않게 된다. 예를 들어 글의 목적이 단순 소개인지, 기존 사용자를 위한 마이그레이션 가이드인지에 따라 구성 자체가 달라진다. 같은 코드 변경이라도 개발자 독자를 위한 설명은 전혀 달라진다.
입력이 빈약할 때는 바로 글을 쓰지 말고 부족한 슬롯만 질문하도록 설계하면 된다. 좋은 Skill은 빈칸을 상상으로 메우지 않는다. 모르면 묻고, 불확실하면 표시한다.
기술 블로그 Skill의 폴더 구조
작은 개인용 Skill이라면 SKILL.md 하나로 시작해도 된다. 하지만 실제로 몇 번만 써보면 금방 자료가 늘어난다. 코드 읽기 체크리스트, 글 구조 템플릿, 다이어그램 규칙, 사실 검증 체크리스트, SEO 제목 규칙이 한 파일에 다 들어가면 관리가 힘들어진다. 그래서 프로젝트 단위로는 폴더를 나누는 편이 좋다.
예를 들면 이런 구성이 실전적이다.
tech-blog-writer/
├── SKILL.md
├── references/
│ ├── code-reading-checklist.md
│ ├── audience-levels.md
│ ├── diagram-guidelines.md
│ ├── fact-vs-marketing-rules.md
│ └── final-review-checklist.md
├── assets/
│ ├── intake-form.md
│ ├── post-outline-template.md
│ ├── tutorial-template.md
│ ├── release-note-template.md
│ └── seo-title-patterns.md
└── scripts/
├── diff_summary.py
└── extract_code_blocks.py이 구조의 핵심은 역할 분리다. SKILL.md는 전체 작업 순서를 지휘한다. 긴 체크리스트는 references에 두고, 실제 출력 양식은 assets에 둔다. 코드 비교나 코드 블록 추출처럼 반복 계산이 필요한 일은 scripts로 분리한다. 이렇게 하면 Skill이 커져도 유지보수가 쉬워진다.
핵심 설계 원리: 코드 먼저, 문서 다음, 메시지는 마지막
기술 블로그 작성 Skill의 심장은 읽기 순서다. 이 순서가 뒤집히면 글은 금방 표면적인 소개문이 된다. 특히 릴리스 노트나 제품 소개 문구를 먼저 읽으면 에이전트는 이미 정리된 문장에 끌려가고, 실제 구현의 중요 포인트를 놓치기 쉽다.
좋은 기본 순서는 다음과 같다.
먼저 코드와 변경 범위를 본다.
다음으로 설계 문서, PR 설명, 이슈 맥락을 읽는다.
그다음 공식 문서나 README에서 사용자 관점을 확인한다.
마지막으로 이 정보를 바탕으로 핵심 메시지를 정리한다.
이 순서는 단순하지만 강력하다. 코드는 실제로 무엇이 바뀌었는지 알려주고, 문서는 왜 바뀌었는지 알려주며, README와 릴리스 노트는 사용자가 무엇을 체감하는지 알려준다. 이 세 층이 합쳐져야 제대로 된 기술 블로그가 나온다.
소스 코드와 문서를 읽는 순서
이 프로젝트에서 가장 중요한 부분을 좀 더 구체적으로 보자. 기술 블로그 Skill은 코드를 닥치는 대로 읽으면 안 된다. 먼저 범위를 좁히고, 그다음 변화의 중심을 찾아야 한다.
추천하는 읽기 순서는 이렇다.
변경 범위 파악
처음에는 전체 저장소를 이해하려 하지 말고, 이번 글의 대상이 되는 변경 범위를 확인한다. 어떤 디렉터리가 바뀌었는지, 어떤 파일이 핵심인지, 새로 추가된 모듈인지 기존 모듈 수정인지부터 파악한다. 기술 블로그는 대개 "모든 것을 설명하는 글"이 아니라 "이번 변화의 의미를 설명하는 글"이기 때문이다.
이 단계에서 에이전트가 뽑아야 할 질문은 단순하다. 무엇이 추가되었는가. 무엇이 바뀌었는가. 무엇이 제거되었는가. 그리고 이 변화가 어디에서 시작되어 어디에 영향을 주는가.
진입점 확인
다음으로는 진입점을 본다. 웹 애플리케이션이라면 라우트, 컴포넌트 진입 파일, API 핸들러가 될 수 있고, 라이브러리라면 공개 API, export 지점, 대표 함수가 될 수 있다. 이 진입점을 먼저 읽어야 기능의 표면을 이해할 수 있다. 겉으로 드러나는 사용법을 모른 채 내부 구현부터 파고들면 글이 지나치게 낮은 수준의 설명으로 가라앉는다.
핵심 로직 추적
진입점을 봤다면 이제 내부 구현으로 들어간다. 여기서 필요한 것은 모든 줄을 설명하는 일이 아니라, "이 변화가 기존과 어떻게 다른지"를 드러내는 핵심 로직을 찾는 것이다. 조건 분기, 데이터 흐름, 상태 변경, 캐시 전략, 오류 처리, 성능 최적화 포인트처럼 실제 의미가 있는 부분을 집어야 한다.
기술 블로그는 코드 독해 보고서가 아니다. 독자가 알고 싶어 하는 것은 구현 전체가 아니라, 무엇이 달라졌고 왜 좋아졌는지다.
문서와 설계 의도 확인
코드만으로는 놓치는 것이 있다. 왜 이런 선택을 했는가, 대안은 무엇이었는가, 어떤 문제를 해결하려 했는가 같은 맥락이다. 그래서 PR 설명, 설계 문서, 이슈 토론, 커밋 메시지를 이어서 읽어야 한다. 이때 중요한 것은 문서의 주장과 코드의 실제 구현이 일치하는지 확인하는 일이다.
문서는 야심차고 코드는 현실적일 때가 많다. Skill은 언제나 코드를 최종 근거로 삼아야 한다.
사용자 관점으로 다시 정리
마지막으로 README, 가이드 문서, 예제 사용법을 읽으면서 사용자 입장에서 어떤 변화가 체감되는지 정리한다. 설치가 쉬워졌는지, API가 간결해졌는지, 설정이 줄었는지, 성능이 개선되었는지, 디버깅이 나아졌는지 같은 변화가 여기에 속한다.
이 순서를 거치면 에이전트는 기술적 사실, 설계 의도, 사용자 효용을 한꺼번에 갖게 된다. 좋은 기술 블로그는 늘 이 세 요소를 함께 담는다.
핵심 포인트 추출 규칙
읽기만 잘해서는 부족하다. 읽은 내용을 어떤 형식으로 압축할지도 정해야 한다. 그렇지 않으면 에이전트는 자료를 많이 읽고도 산만한 글을 쓴다.
가장 실용적인 방법은 핵심 포인트를 다섯 칸으로 정리하는 것이다.
바뀐 것: 실제 변경 사항
이유: 왜 이 변경이 필요했는가
독자 영향: 사용자는 무엇을 얻게 되는가
주의점: 호환성, 제약, 예외는 무엇인가
증거: 어떤 코드, 문서, 테스트가 이를 뒷받침하는가
이 다섯 칸만 제대로 채워도 글의 절반은 끝난다. 예를 들어 "캐시 레이어가 추가되었다"는 바뀐 것이다. "중복 요청으로 인한 지연을 줄이기 위해"는 이유다. "반복 조회 시 응답 시간이 줄어든다"는 독자 영향이다. "실시간 일관성이 중요한 경로에는 사용하지 말아야 한다"는 주의점이다. "특정 함수와 테스트 케이스, 벤치마크 결과"는 증거다.
이 구조가 중요한 이유는, 기술 글쓰기가 원래 주장과 증거를 번갈아 놓는 작업이기 때문이다. 포인트만 뽑고 근거를 남기지 않으면 글은 쉽게 홍보문이 된다.
기술적 사실과 홍보성 표현을 분리하는 규칙
기술 블로그에서 가장 자주 생기는 실패는 사실과 해석이 섞이는 것이다. 예를 들어 "이제 완벽하게 확장 가능한 구조가 되었다" 같은 문장은 멋있어 보이지만, 실제로는 무엇이 바뀌었다는 뜻인지 모호하다. 개발자 독자는 이런 문장을 좋아하지 않는다. 근거 없는 확신은 오히려 신뢰를 깎는다.
그래서 Skill 안에는 반드시 사실과 홍보 표현을 분리하는 규칙이 있어야 한다.
먼저 기술적 사실은 코드나 문서로 확인 가능한 문장이어야 한다. 예를 들어 "설정 파일이 세 개에서 하나로 줄었다", "새 훅이 추가되었다", "동기 처리 경로가 비동기 큐로 바뀌었다", "타입 정의가 공개 API에 포함되었다" 같은 문장이다.
반대로 홍보성 표현은 해석과 감정을 담은 문장이다. "더 강력해졌다", "혁신적이다", "획기적으로 간단해졌다", "개발 경험이 극적으로 좋아졌다" 같은 표현이 그렇다. 이런 문장은 완전히 금지할 필요는 없지만, 항상 사실 뒤에 와야 하고, 가능하면 근거를 붙여야 한다.
이를 Skill 규칙으로 바꾸면 이렇게 된다.
기능 설명 문단은 확인 가능한 사실부터 쓴다.
효용 설명은 사실 다음에 쓴다.
성능, 안정성, 생산성 향상 같은 표현은 근거가 있을 때만 쓴다.
수치가 없으면 과장형 부사를 피한다.
"쉽다", "빠르다", "강력하다" 같은 형용사는 무엇이 어떻게 달라졌는지 뒤따르지 않으면 쓰지 않는다.
이 규칙 하나만 지켜도 글의 온도가 확 달라진다. 독자는 설명받는 느낌보다 이해하는 느낌을 받게 된다.
개발자 독자에 맞는 톤과 난이도 조정
기술 블로그는 같은 주제라도 독자에 따라 완전히 다른 글이 된다. 프레임워크를 처음 접하는 독자를 위한 글과, 이미 사용 중인 팀을 위한 마이그레이션 가이드는 구조부터 다르다. 그래서 Skill은 글쓰기 전에 반드시 독자 수준을 판정하게 해야 한다.
실전에서는 독자를 세 단계 정도로 나누면 충분하다.
입문자 중심
입문자용 글은 맥락 설명이 먼저다. 문제 상황을 설명하고, 왜 이 기능이 필요한지부터 보여줘야 한다. 용어를 쓸 때는 짧은 정의를 붙이고, 코드 예시는 최소 단위로 제공하는 편이 좋다. 한 문단 안에 너무 많은 개념을 넣지 않는 것도 중요하다.
실무자 중심
실무자용 글은 배경 설명을 줄이고, 바로 사용 시나리오와 제약 조건으로 들어가도 된다. 독자는 이미 기본 개념을 알고 있다고 가정하므로, 핵심 차이점, 설계 선택, 운영상 주의점이 더 중요해진다. 예시 코드도 장난감 예제보다 실제 환경에 가까운 형태가 좋다.
고급 사용자 또는 기여자 중심
이 수준의 글은 내부 구조와 트레이드오프를 적극적으로 다뤄야 한다. 왜 이런 아키텍처를 택했는지, 어떤 케이스를 의도적으로 포기했는지, 향후 변경 가능성이 어디 있는지를 설명해야 한다. 단순 사용법 소개만으로는 부족하다.
Skill에는 이런 식의 톤 조정 규칙을 넣어둘 수 있다.
입문자 글은 용어 정의와 문제 상황 설명을 먼저 둔다.
실무자 글은 사용 조건, 제한 사항, 마이그레이션 포인트를 앞에 둔다.
고급 사용자 글은 내부 구조와 의사결정 이유를 반드시 포함한다.
한 문장에 새로운 개념이 두 개 이상 들어가면 난이도를 다시 낮춘다.
독자 수준에 맞지 않는 비유나 과도한 생략을 피한다.
좋은 기술 블로그는 많이 아는 사람이 쓰는 글이 아니라, 독자가 어디에서 막힐지를 아는 사람이 쓰는 글이다. Skill은 바로 그 감각을 절차로 바꾸는 장치다.
출력 형식을 먼저 정하라
기술 블로그 작성 Skill은 글 구조를 자유롭게 두지 않는 편이 좋다. 완전히 자유롭게 두면 에이전트는 매번 다른 구조를 고르고, 팀 블로그의 일관성도 무너진다. 목적별 템플릿을 고정해두면 품질이 안정된다.
가장 많이 쓰이는 형식은 세 가지다.
기능 소개형: 무엇이 바뀌었는지, 왜 중요한지, 어떻게 쓰는지 설명하는 글
튜토리얼형: 특정 목표를 단계적으로 따라 하게 만드는 글
변경 안내형: 릴리스, 마이그레이션, 주의점 중심으로 정리하는 글
예를 들어 기능 소개형 템플릿은 이렇게 설계할 수 있다.
## 한 줄 요약
## 어떤 문제가 있었나
## 이번에 무엇이 바뀌었나
## 코드로 보면 어떻게 동작하나
## 실제로 어떻게 사용하나
## 주의할 점과 한계
## 누가 이 기능을 바로 써보면 좋은가반면 튜토리얼형은 독자의 실행 흐름이 중요하므로 준비물, 단계, 예상 결과, 실패 시 확인 포인트가 꼭 들어가야 한다. 변경 안내형은 이전 방식과 새 방식의 차이, 호환성 영향, 마이그레이션 절차를 먼저 보여주는 편이 좋다.
핵심은 글의 목적에 따라 템플릿을 바꾸되, 같은 목적의 글끼리는 늘 비슷한 구조를 유지하는 것이다.
다이어그램 지침을 Skill 안에 넣어라
기술 블로그에서 다이어그램은 장식이 아니다. 독자가 코드 전체를 읽지 않고도 구조를 파악하게 해주는 요약 장치다. 특히 아키텍처 변화, 데이터 흐름, 요청 처리 단계, 컴포넌트 관계를 설명할 때 매우 유용하다.
하지만 아무 다이어그램이나 넣으면 오히려 글이 복잡해진다. 그래서 Skill에는 다이어그램을 언제 쓰고, 언제 쓰지 말아야 하는지 기준이 있어야 한다.
가장 실용적인 규칙은 이렇다.
흐름이 3단계 이상 이어질 때는 다이어그램을 고려한다.
컴포넌트나 모듈 관계가 둘 이상 얽혀 있으면 다이어그램이 유리하다.
단일 함수 사용법처럼 짧은 설명은 다이어그램보다 코드 예시가 낫다.
다이어그램은 구현 세부보다 개념 구조를 보여줘야 한다.
박스 수가 너무 많아지면 한 장에 다 담지 말고 관점을 나눈다.
예를 들어 요청 처리 방식이 바뀐 기능을 설명한다면, 이전 흐름과 이후 흐름을 나란히 보여주는 단순한 박스 다이어그램이 훨씬 효과적이다. 반면 단일 API 옵션 몇 개를 소개하는 글에서는 다이어그램이 필요 없다. 오히려 예시 코드와 표가 더 낫다.
Skill에 넣을 수 있는 다이어그램 지침 문장은 이런 식이다.
- Show system relationships, not every implementation detail.
- Prefer one diagram per key concept.
- If the diagram needs long text in every box, rewrite the article instead.
- Use diagrams to explain flow, boundaries, ownership, or lifecycle.
- Do not create diagrams for trivial API examples.즉, 다이어그램은 복잡함을 줄일 때만 사용한다. 복잡함을 새로 만드는 다이어그램은 실패다.
예시 코드 삽입 기준
기술 글에서 예시 코드는 매우 강력하다. 하지만 코드가 많다고 좋은 글이 되는 것은 아니다. 오히려 너무 긴 코드는 독자의 시선을 빼앗고 핵심 메시지를 흐린다. 그래서 Skill에는 예시 코드를 넣는 기준도 분명해야 한다.
첫째, 예시 코드는 설명하려는 포인트가 코드로 더 빨리 전달될 때만 넣는다. 둘째, 예시 코드는 가능한 한 가장 작은 단위로 자른다. 셋째, 실제 공개 API와 일치하는 코드만 사용한다. 넷째, 코드가 들어가면 그 아래에 "무엇을 봐야 하는지"를 한두 문장으로 설명한다.
실전 기준으로는 다음 원칙이 좋다.
API 사용법, 설정 방식, 마이그레이션 전후 비교에는 코드 예시를 넣는다.
내부 구현 전체를 복사하지 말고 핵심 부분만 발췌한다.
한 코드 블록에는 하나의 메시지만 담는다.
코드만 보여주고 설명하지 않는 구성을 피한다.
실제와 다른 가짜 함수명, 존재하지 않는 옵션명은 사용하지 않는다.
예를 들어 "설정이 간단해졌다"는 말을 하고 싶다면, 이전 설정 코드와 이후 설정 코드를 짧게 나란히 보여주는 것이 가장 좋다. 개발자는 형용사보다 diff를 더 빨리 이해한다.
또한 예시 코드가 테스트되지 않았거나 실제 코드와 살짝 다른 경우에는 그것을 명시해야 한다. 기술 블로그에서 예시 코드는 설명 도구인 동시에 신뢰의 기준이기 때문이다.
SEO 제목 개선은 마지막 단계에서 하라
기술 블로그를 쓰다 보면 SEO 때문에 제목을 먼저 잡고 싶어진다. 하지만 너무 이르게 제목을 고정하면 글 전체가 검색어를 따라가고, 정작 핵심 메시지는 흐려질 수 있다. 그래서 SEO 제목 개선은 항상 마지막 단계에 두는 것이 좋다.
먼저 에이전트는 글의 실제 내용을 한 문장으로 요약해야 한다. 그다음 독자가 이 글을 어떤 문제로 검색할지 생각한다. 마지막으로 이 둘을 합쳐 검색성과 정확성을 함께 잡는 제목 후보를 만든다.
기술 블로그용 SEO 제목에서 중요한 것은 자극적인 문구가 아니라 정확한 약속이다. 개발자는 제목에서 기대한 내용을 본문에서 찾지 못하면 바로 이탈한다. 따라서 제목은 검색어를 담되, 본문이 실제로 설명하는 범위를 벗어나면 안 된다.
실전 패턴은 대개 이 정도면 충분하다.
무엇이 바뀌었는가 + 왜 중요한가
문제 상황 + 해결 방법
대상 기술명 + 구체적 작업
비교 대상 + 전환 포인트
예를 들면 이런 식이다.
React 서버 컴포넌트에서 데이터 로딩 구조를 단순화하는 방법
우리 팀이 배치 작업 큐를 도입한 이유와 구현 방식
Next.js 설정 중복을 줄인 새 아키텍처 소개
기존 캐시 전략에서 이벤트 기반 무효화로 전환한 과정
여기서 중요한 것은 제목에 없는 내용을 본문이 설명하지 않거나, 본문에 있는 중요한 내용을 제목이 숨기지 않게 하는 것이다. SEO는 포장을 잘하는 기술이 아니라, 독자가 찾는 질문과 글의 실제 답을 잘 맞추는 기술에 가깝다.
사실 검증 체크리스트를 마지막에 강제하라
기술 블로그 Skill의 마지막 단계에는 반드시 검증이 있어야 한다. 이 단계가 빠지면 글은 쉽게 번지르르해지고, 팀은 금방 AI 초안을 신뢰하지 않게 된다.
검증 체크리스트는 다음 질문을 포함해야 한다.
본문의 모든 핵심 주장이 코드, 문서, 테스트 중 하나와 연결되는가
존재하지 않는 API, 옵션, 함수명을 만들어내지 않았는가
성능 향상이나 안정성 개선을 말한다면 근거가 있는가
공개하면 안 되는 내부 정보가 포함되어 있지 않은가
예시 코드는 현재 인터페이스와 모순되지 않는가
제목이 본문 범위를 과장하지 않는가
독자 수준에 맞지 않는 전문 용어 남발이나 과도한 생략은 없는가
다이어그램 제안이 실제 설명에 도움이 되는가
마이그레이션이나 주의점이 있는데 빠뜨리지 않았는가
불확실한 내용은 가정 또는 추가 확인 필요로 표시했는가
이 체크리스트는 단순한 마무리 절차가 아니다. 기술 블로그 Skill의 신뢰성을 지키는 안전장치다. AI가 쓴 초안이 반복 사용되려면, 결국 팀이 "이 Skill은 마지막에 스스로 의심해본다"는 믿음을 가져야 한다.
SKILL.md 초안 예시
이제 이 프로젝트의 뼈대를 실제 문서 형태로 보자. 아래 예시는 시작점으로 쓰기에 충분한 단순화 버전이다.
---
name: tech-blog-writer
description: Write developer-facing blog posts from source code, PRs, docs, release notes, and design materials. Use when the user wants a technical article, release post, migration note, or tutorial grounded in real implementation details.
---
## Purpose
Turn code and documentation into accurate, readable technical blog drafts for developers.
## Activation
Use this skill when the task involves:
- explaining a new feature or architecture change
- writing a release or migration post
- converting code changes into a tutorial or technical article
- summarizing implementation details for developer audiences
## Workflow
1. Collect missing inputs using `assets/intake-form.md`.
2. Identify the change scope before drafting.
3. Read code first, starting from entry points and changed files.
4. Read PR descriptions, design docs, issues, and release notes after code.
5. Extract key points into: change, reason, user impact, caveats, evidence.
6. Separate technical facts from interpretation using `references/fact-vs-marketing-rules.md`.
7. Select tone and depth using `references/audience-levels.md`.
8. Choose the output template that matches the article type.
9. Add diagrams only if structure or flow is hard to explain with text alone.
10. Add code examples only when they clarify usage, migration, or behavior.
11. Improve the title for clarity and SEO after the draft is complete.
12. Run final checks using `references/final-review-checklist.md`.
## Rules
- Never claim behavior that is not supported by code or documentation.
- Do not invent APIs, benchmarks, or roadmap promises.
- State uncertainty clearly.
- Prefer precise language over promotional adjectives.
- When audience level is unclear, default to practical intermediate developers.
- Always include caveats if the feature has constraints or trade-offs.이 문서에서 중요한 것은 "좋은 문장을 써라"가 아니라 "무슨 순서로 진실에 가까워질 것인가"가 먼저 나온다는 점이다. 기술 블로그 Skill은 결국 글쓰기 Skill이면서 동시에 해석 Skill이다.
예시 템플릿: 기능 소개형 블로그 글
실제로 자주 쓰이는 템플릿 하나를 더 보자. 기능 소개형은 팀 블로그에서 가장 빈도가 높은 형식이다.
## 글 초안 구조
### 한 줄 요약
이 글이 설명하는 변화와 핵심 가치를 한 문장으로 정리한다.
### 배경
기존 방식의 문제나 불편을 설명한다.
### 무엇이 바뀌었나
새 기능, 변경 구조, 공개 API 변화를 요약한다.
### 왜 이렇게 설계했나
설계 의도와 선택 이유를 설명한다.
### 사용 예시
최소한의 예시 코드로 실제 사용 방법을 보여준다.
### 이전 방식과의 차이
필요하면 before/after 비교를 넣는다.
### 주의할 점
제약, 예외, 성능 조건, 마이그레이션 포인트를 쓴다.
### 마무리
누가 이 변경을 바로 활용할 수 있는지 정리한다.이 템플릿이 좋은 이유는 구조가 단순해서가 아니다. 코드에서 읽은 사실, 문서에서 읽은 맥락, 개발자 독자가 궁금해할 질문이 자연스럽게 만나는 구조이기 때문이다.
필요하면 스크립트도 붙여라
기술 블로그는 기본적으로 언어 작업이지만, 반복 변환은 스크립트가 더 잘한다. 예를 들어 긴 diff에서 변경 파일 목록을 요약하거나, 특정 디렉터리의 공개 API 시그니처만 추출하거나, 예시로 쓸 수 있는 코드 블록을 자동으로 모으는 일은 자연어보다 스크립트가 안정적이다.
예를 들면 diff_summary.py는 다음 역할을 맡을 수 있다.
변경 파일을 영역별로 묶기
추가, 수정, 삭제 패턴 요약하기
테스트 파일 변경 여부 표시하기
문서 변경과 코드 변경을 분리해서 보여주기
또 extract_code_blocks.py는 다음 일을 할 수 있다.
공개 API 예시 후보 추출
너무 긴 코드 블록 자르기
주석이나 비공개 정보 제거 후보 표시
before/after 비교를 위한 코드 조각 정리
이런 스크립트는 글을 대신 써주지 않는다. 대신 에이전트가 더 정확한 글을 쓰도록 돕는다. Skill과 스크립트의 관계가 바로 이런 것이다. 절차는 자연어로, 반복 계산은 코드로 분리한다.
실행 예시로 흐름을 보자
예를 들어 팀이 새로운 캐시 무효화 전략을 도입했다고 해보자. 사용자는 에이전트에게 "이번 아키텍처 변경을 설명하는 기술 블로그 초안을 써줘"라고 요청한다.
좋은 Skill은 곧바로 글을 쓰지 않는다. 먼저 입력을 확인한다. 이 글의 대상 독자가 내부 백엔드 개발자인지, 외부 오픈소스 사용자들인지 묻는다. 공개 가능한 범위를 확인하고, 관련 PR 설명과 설계 문서 위치를 받는다.
그다음 변경 범위를 본다. 캐시 모듈, 이벤트 처리기, API 핸들러, 테스트 파일이 함께 수정되었는지 확인한다. 이어서 진입점과 공개 API를 읽고, 내부 구현에서 캐시 무효화가 어느 조건에서 일어나는지 추적한다.
그 후 설계 문서와 PR 설명을 읽으며 왜 기존 시간 기반 만료 대신 이벤트 기반 무효화로 바꿨는지 파악한다. README와 사용 예시를 보며 사용자가 실제로 변경을 체감하는 부분을 정리한다.
이제 핵심 포인트를 다섯 칸으로 정리한다. 바뀐 것, 이유, 독자 영향, 주의점, 증거를 채운다. 그런 다음 독자를 실무자 중심으로 분류하고, 기능 소개형 템플릿을 선택해 글 초안을 쓴다. 이전 방식과 새 방식의 차이는 짧은 코드 예시와 간단한 흐름 다이어그램으로 보여준다. 마지막에는 제목을 "이벤트 기반 캐시 무효화로 전환한 이유와 구현 방식" 같은 식으로 다듬고, 검증 체크리스트를 통과했는지 확인한다.
이렇게 만들어진 글은 단순히 설명이 많은 글이 아니다. 코드와 맥락과 독자 수준이 맞물린 글이다.
이 프로젝트에서 자주 생기는 실패
첫 번째 실패는 README만 읽고 글을 쓰는 것이다. README는 이미 정리된 결과일 뿐, 이번 변경의 본질을 모두 담고 있지 않을 수 있다.
두 번째 실패는 코드만 읽고 글을 쓰는 것이다. 이렇게 하면 왜 이 선택을 했는지, 어떤 문제를 해결하려 했는지 빠지기 쉽다. 글은 정확하지만 무미건조해진다.
세 번째 실패는 독자를 정하지 않는 것이다. 그러면 입문자에게는 너무 어렵고, 실무자에게는 너무 얕은 글이 나온다.
네 번째 실패는 효용을 과장하는 것이다. 성능이 조금 개선되었을 뿐인데 "혁신적인 개선"처럼 쓰는 순간 기술 블로그는 신뢰를 잃는다.
다섯 번째 실패는 예시 코드가 본문 메시지와 연결되지 않는 것이다. 코드는 많은데 독자가 무엇을 봐야 하는지 모르면, 글은 오히려 더 읽기 어려워진다.
여섯 번째 실패는 제목을 너무 빨리 정하는 것이다. 제목이 글을 끌고 가기 시작하면 정작 코드가 말하는 핵심을 놓칠 수 있다.
팀 자산으로 확장하는 방법
기술 블로그 작성 Skill은 개인 생산성 도구로 시작해도 좋다. 하지만 진짜 힘은 팀 자산이 되었을 때 드러난다. 개발 조직이 공통 톤, 공통 템플릿, 공통 검증 기준을 갖게 되면, 블로그뿐 아니라 릴리스 노트, 변경 안내, 내부 기술 문서까지 훨씬 안정적으로 생산할 수 있다.
예를 들어 팀 저장소에는 다음 같은 표준을 함께 둘 수 있다.
블로그 글 목적별 템플릿
독자 수준 분류표
코드 예시 길이 제한 규칙
금지 표현 목록
공개 승인 전 체크리스트
이렇게 해두면 에이전트는 단지 글을 빠르게 쓰는 보조자가 아니라, 팀의 기술 커뮤니케이션 방식을 재현하는 실행 장치가 된다. 그리고 바로 이 지점이 Skill의 본질이다. 개인의 감각을 매번 되풀이하는 대신, 반복 가능한 절차와 기준으로 설치하는 것 말이다.
마무리
기술 블로그 작성 Skill의 핵심은 문장을 예쁘게 만드는 데 있지 않다. 코드와 문서와 독자 사이의 번역 절차를 고정하는 데 있다. 먼저 변경 범위를 파악하고, 코드에서 사실을 읽고, 문서에서 맥락을 확인하고, 개발자 독자에게 맞게 톤과 난이도를 조정한 뒤, 다이어그램과 예시 코드를 필요한 만큼만 넣고, 마지막에 제목과 사실 검증으로 마무리한다. 이 흐름이 한 번 Skill로 정리되면, 에이전트는 더 이상 말주변 좋은 초안 생성기가 아니다. 팀의 기술 지식을 안정적으로 전달하는 글쓰기 시스템이 된다.
다음 장에서는 이런 원리를 더 엄격한 업무 문맥으로 가져가 본다. 기술 블로그가 외부 독자를 향한 설명이라면, 사내 보고서는 의사결정을 위한 요약이다. 즉, 같은 글쓰기 Skill이라도 목표와 평가 기준이 달라질 때 무엇이 바뀌는지를 보게 될 것이다.
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.