akbun 스타일 글쓰기

글 끝에 "더 공부할 것", "아직 분석하지 않았지만", "다음에 시도해볼 것" 같은 섹션을 두는 걸 두려워하지 않는다. 모르는 것을 모른다고 쓰면 독자가 글을 더 신뢰한다.

6. 재현할 수 있어야 한다

실습이 포함된 글에서 코드가 돌아가지 않으면 글 전체가 무너진다. 재현 가능성은 스타일이 아니라 품질이다. 검증되지 않은 명령어를 넣지 않는다.

나쁜 글의 기준 (안티패턴)

아래에 해당하면 akbun 스타일이 아니다. 쓸 때와 검토할 때 모두 이 기준으로 걸러낸다.

• 문서 번역 — 공식 문서를 번역하듯 옮겨놓은 것
• 기능 나열 — 체험 없이 "~할 수 있다"로 끝나는 기능 소개
• 설명 없는 코드 — 앞에 산문 설명 없이 코드 블록만 나오는 것
• 체험 없는 이론 — 구체적 사건이나 핸즈온 경험에 기반하지 않고 원리만 나열한 것
• 꾸며낸 경험 — 저자가 겪지 않은 것을 겪은 것처럼 쓴 것
• 감정 없는 조립 — 개인 반응과 실패담이 전혀 없는 기술 조립만 있는 글

목소리와 톤

실무자의 목소리로 쓴다. 존댓말(~습니다/~입니다)을 기반으로 하되, 교과서처럼 딱딱하지 않고 자연스럽게 풀어낸다. 구어체와는 다르다 — 존댓말이면서 편안한 톤이 목표다.

1인칭을 아끼지 않는다

"저는", "제가", "저의"를 문단 단위로 자주 쓴다. akbun 글의 거의 모든 문단에는 1인칭 표지가 어떤 식으로든 등장한다.

감정 표현을 허용한다

"식은땀", "운이 좋게", "ㅜ.ㅜ", "😭", "재밌는", "아쉽게도" 같은 감정 표현을 자연스럽게 섞는다. 격식 있는 기술 문서라면 걷어낼 단어들이지만, akbun 스타일에서는 자산이다. 이런 표현이 글을 인간적으로 만들고 독자와 거리를 좁힌다.

질문-답변 구조로 문단을 연결한다

"왜 ~했을까요?" → 답 → "그런데 ~한다면 어떻게 될까요?" → 답. 이렇게 질문을 던지고 답하는 리듬이 문단을 자연스럽게 연결한다. 독자가 "그래서?"라고 묻기 전에 먼저 묻고 답한다.

시간과 숫자를 구체적으로 드러낸다

"2025년 1월", "3시간 동안 삽질", "5분 타임아웃", "4년차", "추석이 끝나고"처럼 구체적인 시간과 숫자를 아끼지 않는다. 추상적인 "예전에"보다 구체적인 "2024년 추석이 끝나고"가 훨씬 생생하다.

사람 맥락을 지우지 않는다

"개발자님", "팀원", "Y님, K님", "사수", "10년차 아키텍터", "고객사 담당자" — 기술적 의사결정의 배경에 있는 사람을 구체적으로 남긴다. 개인정보는 주의해서 이니셜 처리한다. 사람이 빠지면 결정의 이유가 사라진다.

문장과 문단

• 기본은 13 문장 문단이다. 하지만 그렇다 해서라도 문단이 너무 짧으면 안된다. 읽는 흐름을 끊지 않는 선에서, 하나의 생각이 완결되도록 문단을 구성한다. 45 문장도 괜찮다. 중요한 건 문장 수가 아니라 한 문단이 하나의 생각을 다루는가이다.
• 개념 정의나 결론 문단은 4~5 문장도 괜찮다. 중요한 건 문장 수가 아니라 한 문단이 하나의 생각을 다루는가이다.
• 긴 복합 문장은 두세 개로 쪼갠다. 접속사가 여러 개 이어지면 읽는 사람이 따라오기 힘들다.
• 굵은 글씨는 섹션당 2~4개까지 자유롭게 쓴다. 개념 정의, 핵심 결론, 중요한 용어, 명령어에 집중한다. 남용하면 강조가 강조의 기능을 잃는다.

한국어/영어 사용 기준

본문은 전부 한국어로 작성한다. 독자가 실무에서 영어로 검색하고 영어로 명령어를 입력하기 때문에, 기술 용어·서비스명·약어·코드·명령어·URL은 영어를 쓴다.

• 이미 굳어진 기술 용어는 영어 그대로 표기한다 (TCP, IPsec, eBPF, IKE, AMI, nvidia-smi, k6, LM studio, obsidian)
• 약어가 처음 등장할 때 영어 약어(Full English Name) 형식을 사용한다: mTLS(mutual TLS), SNI(Server Name Indication), VPN(Virtual Private Network)

구조와 포맷

첫 섹션: 독자를 현장으로 데려온다

첫 섹션은 다음 중 하나로 시작한다. 무엇이든 첫 문단에서 "이 사람이 직접 겪었구나"를 독자가 느낄 수 있어야 한다.

• # 개요 또는 # 들어가며 헤더 + 배경 설명
• 구체적 사건으로 시작 — 시간, 장소, 인물 ("아침 7시 40분쯤 메신저에서 긴급이라는 메시지가 보였습니다")
• 질문으로 시작 ("쿠버네티스 node가 not ready일 때, 내부적으로 어떤 일이 일어날까요?")
• 사례 관찰 ("최근 운영 중에 이런 사례를 봤습니다", "서비스를 운영하면서 이런 경우를 만났습니다")

마지막 섹션: # 참고자료

거의 모든 글은 # 참고자료 섹션으로 끝난다. 이유는 두 가지다.

1. 재현하려는 독자에게 진입점을 남긴다.

공식 문서, 블로그, github, youtube 링크를 bullet으로 정리한다.

코드 블록은 3단 구조

모든 코드 블록은 앞에 한 줄 설명이 있고, 뒤에 결과 해석 또는 스크린샷 참조가 붙는다.

1. 앞 설명 — "저는 homebrew로 pandoc을 설치했습니다"
2. 코드 블록 — 언어 태그 반드시 포함 (sh,yaml, hcl,json)
3. 뒤 해석 — "설치가 끝나면 pandoc --version으로 확인할 수 있습니다"

이 구조가 독자에게 "왜 이 명령어인가"와 "무엇이 나와야 하는가"를 동시에 전달한다.

헤더 레벨: H1부터 시작

글은 최상단 제목(H1)으로 시작하고, 이후 모든 섹션은 H2부터 쓴다. 한 문서 안에서 레벨을 건너뛰지 않는다 — H1 → H3처럼 점프하면 독자의 구조 인식이 흔들린다. 과거 Obsidian에서 블로그로 옮긴 일부 글이 H1만 반복되거나 H2부터 시작하는 경우가 있는데, 그건 변환 과정에서 생긴 아티팩트이지 의도한 구조가 아니다. 본 프로젝트의 markdown 규칙(최상단만 H1, 이후 H2)과 동일하다.

목록과 표

• 순서가 있는 단계나 순위에는 번호 목록
• 순서 없는 항목에는 bullet 목록
• 비교에는 표

자기 검토 체크리스트

쓴 글을 돌려볼 때 아래 질문으로 훑는다.

• 첫 문단에서 "저는/제가" 또는 구체적 사건이 나오는가?
• 시간의 경과(언제, 얼마나 걸렸는지)가 어딘가에 드러나는가?
• 코드 블록은 앞/뒤 설명과 함께 가는가?
• 마지막에 # 참고자료 섹션이 있는가?
• "~할 수 있다" 기능 나열이 반복되지는 않는가?

서너 개가 "아니오"라면 글을 한 번 더 다듬는다. 이 체크리스트가 akbun-style-reviewer agent의 체크리스트와 거의 겹친다 — reviewer를 부르면 같은 기준으로 진단을 받을 수 있다.

관련 skill

• akbun-hands-on — 실습 문서 뼈대 생성 (이 skill의 1단계). github에 올릴 짧고 단답형 뼈대를 먼저 만들고, 이 skill로 살을 붙여 블로그 글로 확장한다.
• akbun-blog-post-template — 블로그 글 구조(목차, 공부 배경, 결론, 참고자료)를 정의하는 템플릿 skill.
• akbun-style-reviewer (agent) — 쓴 글이 실제로 akbun 스타일을 따르는지 검토하는 리뷰어.