Chaos and Order

💡 왼쪽 원문을 읽으면서 오른쪽에 따라 써보세요. Tab 키로 힌트를 받을 수 있습니다.

왜 글 잘 쓰는 엔지니어가 10배 이긴다고 말하는가

한 엔지니어가 뛰어난 기술적 아이디어를 낸다. 팀에서 발표 못하고 문서도 없으면 그 아이디어는 한 사람 머리에서 끝난다. 같은 아이디어를 잘 정리된 RFC로 쓰면 팀 전체가 판단할 수 있다. 더 잘 쓰면 조직 전체가 본다. 엔지니어링 블로그에 내보내면 산업 전체의 기준이 바뀌기도 한다. AWS Nitro 하이퍼바이저, Google Borg, Netflix Chaos Monkey, Airbnb BinaryAlert — 모두 기술 자체만큼이나 그걸 글로 풀어낸 사람의 능력이 파급력을 만들었다.

2025년은 특히 글쓰기가 엔지니어 가치의 축이 되는 해다. 이유 3가지.

원격/하이브리드 근무가 고착되면서 비동기 문서가 동기 회의를 대체
AI 동료(Cursor·Claude Code·Copilot)와 AGENTS.md·CLAUDE.md 같은 메타 문서가 코드베이스의 일급 시민이 됨
LLM에게 맥락을 잘 주는 능력이 곧 생산성 (좋은 프롬프트 = 잘 쓴 요구사항)

이 글은 RFC·ADR·Design Doc·6-pager·엔지니어링 블로그·Slack/Email·AI 시대의 글쓰기까지 — 기술 글쓰기 모든 면을 다룬다.

이 글은 앞선 코드 리뷰 가이드의 자연스러운 동반자다. 코드를 잘 쓰는 법을 다뤘다면, 이제는 그 코드에 대해 설득력 있게 쓰는 법.

1부. 엔지니어링 글쓰기의 기본 원칙

1.1 Writing is Thinking

머릿속에 있는 아이디어가 글로 쓸 때 처음 검증된다
"왜 이 방안을 택했나"를 쓰다가 이유가 없음을 발견 → 방안 폐기
제프 베조스가 Amazon 파워포인트 금지, 6-pager narrative를 강제한 이유

1.2 독자 모델

초보자가 읽는가, 동료 전문가가 읽는가
상사 1명 vs 팀 전체 vs 사외 독자 — 각기 어휘·깊이·맥락 수준이 다름
잘 쓴 문서는 **"첫 3분"**에 독자에게 "이 글이 당신에게 중요한 이유"를 준다

1.3 BLUF — Bottom Line Up Front

군·컨설팅·임원 소통 관행. 결론을 맨 위에. 수평 구조 조직일수록 중요. 밑에서 소개·맥락부터 깔면 바쁜 리더는 스킵.

1.4 Plain English·명확성·동사 우위

수동태보다 능동태
단어 utilize → use, in order to → to, due to the fact that → because
짧은 문장이 좋지만 리듬이 죽지 않게 변주
원어민이 아닌 독자도 고려 (글로벌 팀)

1.5 Show, Don't Tell

"시스템이 느립니다"가 아니라 "p99 latency 2.3s → SLO 500ms 초과"
데이터·숫자·다이어그램·실제 코드 스니펫

2부. RFC — Request for Comments

2.1 RFC의 기원과 현대

IETF(인터넷 표준)의 RFC 프로세스가 원형(1969~)
Rust RFC, Ember RFC, Python PEP, Go Design Docs이 소프트웨어 오픈소스로 이식
사내 RFC — Shopify, GitLab, Coinbase, Stripe가 공개한 사례

2.2 RFC 템플릿 (사내용)

# RFC: [제목]
- Author: 이름
- Status: Draft / Review / Accepted / Rejected / Superseded
- Date: 2026-04-15
- Target release: v3.2 (optional)

## 요약 (TL;DR)
3문장 이내

## 문제 (Problem)
지금 무엇이 아픈가. 측정 가능한 고통.

## 목표 / Non-goals
- 이 제안이 해결하는 것
- 일부러 포함 안 한 것

## 제안 (Proposal)
구체적 설계 — API, 데이터 모델, 시퀀스, 에러 핸들링

## 대안 (Alternatives)
고려했지만 기각한 옵션 + 기각 이유

## 영향 (Impact)
- Backward compatibility
- Migration plan
- Performance
- Security

## 오픈 질문 (Open Questions)
아직 답이 없는 것

## 참고 자료

2.3 RFC 프로세스

Draft — 저자가 초안, 팀 공유
Comment Period — 1~2주, 서로 질문/반론
Decision Meeting (비동기 투표로도 가능)
Accepted/Rejected/Deferred
Implementation — 머지 전 최종 검토

2.4 좋은 RFC의 특징

대안을 3개 이상 나열 — 진지하게 고민했다는 신호
Non-goals 섹션 — 범위 명시로 무한 논쟁 방지
오픈 질문을 숨기지 않기 — 모르는 걸 인정
측정 가능한 성공 기준 — "배포 후 p99 30% 감소" 같은

2.5 RFC가 실패하는 이유

너무 긺 (50페이지) → 아무도 안 읽음
너무 짧음 → 대안 분석 없음 → 첫 회의에서 박살
의사결정자가 명시 안 됨 → 표류
기각 이유가 공유 안 되어 같은 논의 반복

3부. ADR — Architecture Decision Record

3.1 왜 ADR이 별도 개념인가

RFC는 제안 — 앞으로 할 일
ADR은 기록 — 이미 내린 결정을 이력으로 저장

"왜 Postgres가 아니라 MongoDB인가", "왜 gRPC가 아니라 GraphQL인가" — 6개월 뒤 신규 엔지니어가 물을 때 답할 수 있어야 한다.

3.2 Michael Nygard 템플릿 (2011 원조)

# ADR-042: Use PostgreSQL for User Service

## Status
Accepted (2026-03-15)

## Context
[배경·제약·고려사항]

## Decision
[무엇을 결정했나]

## Consequences
[결정의 결과 — 좋은 것, 나쁜 것, 중립적인 것]

3.3 구조

레포 안 docs/adr/ 폴더에 adr-NNNN-제목.md 형식
파일명·번호 순서대로 시간 이력
상태 전이: Proposed → Accepted → Deprecated → Superseded
Superseded는 "어떤 ADR이 대신함" 링크

3.4 도구

adr-tools (Jeff Nickoloff) — 커맨드라인 생성기
Log4brains — ADR 웹 렌더링
Backstage TechDocs — ADR을 포털에 자동 인덱싱

3.5 ADR이 만드는 문화

"회의에서 결정한 걸 녹음본으로 찾기" 지옥 종료
신규 엔지니어 온보딩이 ADR 5개 읽기로 해결
"그 결정 왜 그렇게 했어?" 질문이 사라짐

4부. Design Doc — 구글이 대중화한 형식

4.1 Design Doc vs RFC

대부분 조직에서 두 용어가 섞임
통상: Design Doc이 더 큼(시스템 전체), RFC가 더 좁음(API/프로토콜)
Google "Design Doc"이 유명 → 책 "Software Engineering at Google" 참조

4.2 좋은 Design Doc 구성

Context / Background
Goals / Non-goals
Overview — 다이어그램 1장
Detailed Design — 컴포넌트별
Data Model
APIs
Sequence Diagrams
Alternatives Considered
Security / Privacy / Compliance
Migration / Rollout Plan
Metrics / Success Criteria
Risks / Open Questions

4.3 도구 생태계

Google Docs — 코멘트 협업 강점, 버저닝 약함
Notion — 깔끔, 검색 약함
Confluence — 엔터프라이즈 표준, UX 낡음
Outline (OSS) — 가볍고 깔끔, 2024 급성장
GitBook — 기술 문서에 최적
Obsidian (개인) → 팀: Foam, Dendron
사내 팀의 Markdown in Git 운영 — 작성 문턱 낮고 이력 완전

4.4 다이어그램

Mermaid — 코드로 그리는 다이어그램, Markdown 기본 지원
Excalidraw — 손그림 느낌, 협업 가능, OSS
draw.io / diagrams.net — 복잡한 아키텍처
D2 (Terrastruct 2023 OSS) — 코드 기반 + 자동 레이아웃
Whimsical, FigJam — 팀 whiteboarding

5.1 규칙

미팅 시작하면 처음 20~30분은 전원 조용히 6-pager 읽기
모두 같은 맥락으로 참여
파워포인트 금지 (bullet 이상의 사고 강제)
저자는 반박을 받아 "답변본"을 만들기도

5.2 왜 효과적인가

파워포인트는 연사의 쇼, 6-pager는 내용의 검증
생각의 뼈대가 드러남 — 논리 구멍, 가정, 대안 평가
읽는 데 30분이지만, 회의 효율 2배

Opening (한 문단)
Background
Problem Statement
Options considered
Recommendation
FAQ (예상 반론 + 답)
Appendix (데이터, 상세)

5.4 팀에 도입하는 법

모든 회의를 바꿀 필요 없음 — 의사결정 회의만
저자는 최소 24시간 전 공유
"리더가 먼저 모범"을 보여야 문화가 됨

6부. 엔지니어링 블로그 — 외부 커뮤니케이션의 정점

6.1 왜 회사가 엔지니어링 블로그를 운영하는가

채용 브랜딩 — 최고의 채용 자석
기술 권위 — 고객 신뢰
내부 지식 정리 — 외부용으로 쓰면서 자체 정리
커뮤니티 기여 — OSS 조직 생태계

6.2 레퍼런스 블로그

Stripe — 단행본 수준 깊이, 디자인 훌륭
Shopify — Ruby/Rails 세계의 표준 사례
Uber — 대규모 인프라 사례
Airbnb — 데이터·ML 중심
Netflix TechBlog — Chaos Engineering, 스트리밍 인프라
Pinterest / Slack / Dropbox — 실전 중심
Cloudflare — 매일 포스팅, 깊이와 속도의 균형
GitHub Engineering, Meta Engineering
Vercel — Edge/Next.js 생태계

6.3 콘텐츠 유형

Incident Postmortem — 신뢰의 정점
Architecture Deep Dive — "우리는 이렇게 만들었다"
Tooling·Migration 스토리 — "Perl → Rust 전환기"
Open Source 소개
Performance Case Study
Research / Experiments

6.4 운영 체계

Editor 1명 전담 (엔지니어 겸직 많음)
월 2~4개 목표, 분기별 리뷰
작성자에 대한 시간 보상 — 20% time, 스프린트 편성
브랜딩 팀과 조율 (로고·SEO·소셜)
Syndication: Hacker News, Twitter/X, LinkedIn, Reddit r/programming

6.5 개인 엔지니어링 블로그

많은 엔지니어에게 커리어 최고 레버리지
Hacker News front page 1회 = LinkedIn 수천 팔로워
"1년에 12개, 매달 하나"가 현실적 목표
주제 발굴: 최근 트러블슈팅, 반복되는 설명, 논쟁 지점

7부. Changelog·Release Notes

7.1 Keep a Changelog 형식

# Changelog

## [Unreleased]
### Added
- new feature A

## [1.4.0] - 2026-04-15
### Added
- feature B
### Changed
- default timeout 30s → 60s
### Deprecated
- /v1/users (removed in v2.0)
### Fixed
- race condition in login
### Security
- CVE-2026-1234 mitigated

7.2 자동화

semantic-release — Conventional Commits → 버전·changelog 자동 생성
changeset (atlassian) — monorepo 친화
release-please (Google) — PR로 릴리스 관리

7.3 사용자 대상 Release Notes

Changelog는 기술적, Release Notes는 사용자용
스크린샷, 예제, 영향받는 사람은 누구인가 명시
Breaking change는 별도 강조 + 마이그레이션 가이드 링크

7.4 API Deprecation

공지 → 경고 기간(최소 6개월) → 제거
Deprecation header: Deprecation: true, Sunset: <date>
Stripe·GitHub API가 모범

8부. 비동기 커뮤니케이션 — Slack·Email·Linear·GitHub

8.1 동기 회의의 비용

8명 1시간 회의 = 8시간 인력. 연봉 $150K 기준 약$ 500
"이 회의 대신 5분 글로 끝낼 수 있는가?"

8.2 비동기 원칙

질문을 맥락과 함께 — "에러 나요" 금지, 로그·환경·시도한 것
Rubber Duck 먼저 — 질문 쓰다 답을 찾는 경우 많음
SLA 합의 — "24시간 내 응답" 같은
Thread 유지 — Slack 메인 채널 폭탄 금지

8.3 좋은 Slack 메시지 공식

[요약 1문장]

배경:
- 상황 X
- 원인 Y

질문:
1. ...
2. ...

시도:
- A → 실패 이유
- B → 결과

대기 중: @이름

8.4 Email의 복귀

Slack 피로 이후 "진지한 결정은 email로" 트렌드
Amazon PR/FAQ, 긴 업데이트
HEY·Superhuman 등 세련된 이메일 툴이 IDE 수준 경험

8.5 프로젝트 관리와 문서의 연결

Linear·Jira·Asana 이슈에 Design Doc·ADR·RFC 링크 필수
Notion database로 "프로젝트 → 관련 문서" 관계 유지

9부. AI 시대의 엔지니어링 글쓰기

9.1 AI를 도구로 쓰는 법

초안 뼈대 → AI에게 확장 시키기
긴 문서 → 요약 + 에디터 피드백
문법·어투 교정
다국어 번역 (특히 영어로 쓰는 한국·일본 엔지니어)

9.2 목소리는 인간이 지켜야 한다

AI 생성 문장은 "무해하지만 무미건조"
블로그 독자는 저자의 관점을 사러 온다
AI 결과물 그대로 게시는 신뢰 파괴
"AI 초안 → 저자가 재작성"이 안정적

9.3 AGENTS.md / CLAUDE.md / GEMINI.md 문화

2024 이후 표준 파일
AI 에이전트에게 코드베이스 맥락·규칙을 전달
사실상 "AI를 위한 기술 글쓰기"

9.4 프롬프트는 요구사항이다

좋은 프롬프트 = 잘 쓴 요구사항 명세
엔지니어링 글쓰기 훈련 = 프롬프트 실력 향상
애매한 요구를 쓰는 팀은 AI에게도 애매하게 지시 → 결과 나쁨

9.5 AI 검출과 학술 윤리

학회·컨퍼런스는 AI 보조 글쓰기 공시 의무
회사 블로그는 "편집 보조로 AI 사용" 공시 트렌드

10부. 글쓰기가 커리어에 미치는 기하급수 효과

10.1 내부 기하급수

RFC 1개 → 팀원 10명이 읽음
좋은 RFC → 조직 전체 (100명)
ADR 패턴 정착 → 모든 신규 엔지니어 영구 학습

10.2 외부 기하급수

블로그 1개 HN 1면 → 10만 읽음, 수백 채용 리드
컨퍼런스 톡 → 영상 YouTube 100만 뷰까지 가능
책 → 커리어를 바꾸는 사건 (Martin Kleppmann DDIA 사례)

10.3 개인 브랜드의 경제학

블로그 구독 1만 → 구직 역제안 월 수 건
기술 책 인세는 미미하지만 signal
스타트업 창업 시 초기 라운드에 결정적

10.4 반례 — "글만 쓰는 엔지니어"

코드 실제 출하 없이 글만 쓰면 신뢰 누적 실패
좋은 비율: 70% 빌드, 30% 쓰기

11부. 글쓰기 훈련 — 매일 할 수 있는 것

11.1 매일 습관

아침 5분: 오늘 할 일 3줄 공개 (Slack status)
끝에 5분: 오늘 배운 것 1줄 (팀 채널)
주 1회: 한 주 배운 것 요약 (개인 블로그 초안 후보)

11.2 월 1회

업무 중 발견한 트러블슈팅 1건 → internal 블로그 포스트
사외용으로 각색 가능한 것 → 공개 블로그

11.3 분기 1회

RFC 또는 Design Doc 1건 작성
발표·라이트닝 톡 1회

11.4 연 1~2회

외부 컨퍼런스 톡 제안
대형 기술 글 (5,000~10,000 단어)

12부. 글쓰기 도구 — 2025년의 필수

12.1 쓰기

Typora / iA Writer / Obsidian — Markdown 중심
Notion / Bear / Craft — 리치 노트
HackMD / Dillinger — 온라인 Markdown
Cursor / VS Code with AI assist
Vim/Neovim + plugins (개인 취향)

12.2 교정

Grammarly — 표준, AI 기능 확대
Vale — OSS, 스타일 가이드 커스터마이즈
LanguageTool — OSS, 다국어
Claude/Cursor — 스타일 변환·단순화

12.3 발행

Mintlify — 2024 SaaS docs 급성장 (OpenAI·Cursor 도입)
Docusaurus (Meta) — 오픈소스 문서 표준
MkDocs Material — Python 생태계
VitePress — Vue/Vite 생태계
Astro + Starlight — 2024 뜨는 조합
Next.js + Contentlayer — 이 블로그가 쓰는 스택

12.4 SEO·측정

Google Search Console
Ahrefs / SEMrush / Plausible / Fathom
Google Analytics 4 (복잡)
Twitter/X Analytics — 기술 글 영향력의 1차 지표

13부. 실패 패턴 — 쓰는 사람이 망하는 10가지

Wall of text — 섹션 없는 2,000단어
결론이 마지막에만 (BLUF 위반)
전문가 독자 가정 — 모든 글이 "고수용"
인용·레퍼런스 부재 — 출처 없음
AI 생성 그대로 게시
악마의 옹호(devil's advocate) 섹션 없음
시각 자료 부재
3개월 방치된 Changelog
RFC/ADR을 회의 끝나고 쓰지 않음
"왜"를 빼고 "무엇"만 기록

14부. 체크리스트 12 · 안티패턴 10

✅ 체크리스트 12

주요 결정에 RFC/ADR이 있는가?
새 기능 시작 전에 Design Doc이 리뷰됐는가?
ADR이 **레포 안 docs/adr/**에 파일로 남아 있는가?
Changelog가 semantic-release 등으로 자동 생성되는가?
엔지니어링 블로그가 월 2개 이상 게시되는가?
모든 PR 제목이 Conventional Commits 규칙을 따르는가?
사내 회의에 Agenda 문서가 붙는가?
비동기 질문 시 맥락 포함이 습관인가?
팀 Style Guide(Google/Microsoft 등 기반)가 있는가?
AI 사용이 편집 보조 수준에 머무르고 공시가 있는가?
신규 엔지니어 온보딩이 글 문서로 완료되는가?
AGENTS.md / CLAUDE.md가 최신인가?

⚠️ 안티패턴 10

"쓰기보다 말하기가 빠르다"로 문서화 회피
전원 동기 회의만 → 원격 팀 배제
Confluence·Notion·Google Docs 3개 중복
RFC를 형식만 맞추고 대안 분석 없음
AI 생성 블로그 그대로 게시해 신뢰 훼손
팀 위키 검색 불가 → 존재해도 못 찾음
엔지니어링 블로그 발행 멈춤 (6개월+)
Slack DM에만 결정 → 기록 휘발
사외 블로그에 숫자·결과 과장
Deprecation을 공지 없이 단행

다음 글 예고 — "테스트의 현대: 단위·통합·E2E·Playwright·Property-based·Mutation·Fault Injection·AI 생성 테스트" — 품질의 마지막 보루가 바뀌고 있다

글쓰기 다음은 테스트다. 2020년대 중반 테스트 판이 크게 달라지고 있다.

Testing Pyramid의 진화 — Trophy, Diamond
단위 테스트 — 진짜 필요한 것과 잉여
통합 테스트 — Testcontainers·Ephemeral Env
E2E 테스트 — Playwright의 독주, Cypress 쇠락
Property-based Testing — Hypothesis, fast-check, proptest
Snapshot Testing의 함정
Visual Regression — Chromatic·Percy·Lost Pixel
Contract Testing — Pact
Mutation Testing — Stryker, PIT
Fault Injection / Chaos — Gremlin, LitmusChaos
Fuzz Testing — AFL++, libFuzzer, Jazzer
AI로 테스트 자동 생성 — Qodo, Diffblue Cover
플래키 테스트 대응 — 업계의 10년 숙제

테스트는 엔지니어링의 운영 보험이다. 다음 편에서 2025년의 보험 상품 전부를 본다.