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

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

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

1. **원격/하이브리드 근무**가 고착되면서 비동기 문서가 동기 회의를 대체

2. **AI 동료**(Cursor·Claude Code·Copilot)와 **AGENTS.md·CLAUDE.md** 같은 메타 문서가 코드베이스의 일급 시민이 됨

3. **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 프로세스

1. **Draft** — 저자가 초안, 팀 공유

2. **Comment Period** — 1~2주, 서로 질문/반론

3. **Decision Meeting** (비동기 투표로도 가능)

4. **Accepted/Rejected/Deferred**

5. **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부. Amazon 6-pager — 회의 시작 20분의 침묵

5.1 규칙

1. 미팅 시작하면 처음 20~30분은 **전원 조용히** 6-pager 읽기

2. 모두 같은 맥락으로 참여

3. 파워포인트 금지 (bullet 이상의 사고 강제)

4. 저자는 반박을 받아 "답변본"을 만들기도

5.2 왜 효과적인가

- 파워포인트는 **연사의 쇼**, 6-pager는 **내용의 검증**

- 생각의 뼈대가 드러남 — 논리 구멍, 가정, 대안 평가

- 읽는 데 30분이지만, 회의 효율 2배

5.3 6-pager 구조

1. Opening (한 문단)

2. Background

3. Problem Statement

4. Options considered

5. Recommendation

6. FAQ (예상 반론 + 답)

7. 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가지

1. Wall of text — 섹션 없는 2,000단어

2. 결론이 마지막에만 (BLUF 위반)

3. 전문가 독자 가정 — 모든 글이 "고수용"

4. 인용·레퍼런스 부재 — 출처 없음

5. AI 생성 그대로 게시

6. 악마의 옹호(devil's advocate) 섹션 없음

7. 시각 자료 부재

8. 3개월 방치된 Changelog

9. RFC/ADR을 회의 끝나고 쓰지 않음

10. "왜"를 빼고 "무엇"만 기록

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

✅ 체크리스트 12

1. 주요 결정에 **RFC/ADR**이 있는가?

2. 새 기능 시작 전에 **Design Doc**이 리뷰됐는가?

3. ADR이 **레포 안 `docs/adr/`**에 파일로 남아 있는가?

4. **Changelog**가 semantic-release 등으로 자동 생성되는가?

5. 엔지니어링 **블로그**가 월 2개 이상 게시되는가?

6. 모든 PR 제목이 **Conventional Commits** 규칙을 따르는가?

7. 사내 회의에 **Agenda 문서**가 붙는가?

8. 비동기 질문 시 **맥락 포함**이 습관인가?

9. 팀 **Style Guide**(Google/Microsoft 등 기반)가 있는가?

10. **AI 사용**이 편집 보조 수준에 머무르고 공시가 있는가?

11. 신규 엔지니어 온보딩이 **글 문서**로 완료되는가?

12. **AGENTS.md / CLAUDE.md**가 최신인가?

⚠️ 안티패턴 10

1. "쓰기보다 말하기가 빠르다"로 문서화 회피

2. 전원 동기 회의만 → 원격 팀 배제

3. Confluence·Notion·Google Docs 3개 중복

4. RFC를 형식만 맞추고 대안 분석 없음

5. AI 생성 블로그 그대로 게시해 신뢰 훼손

6. 팀 위키 검색 불가 → 존재해도 못 찾음

7. 엔지니어링 블로그 발행 멈춤 (6개월+)

8. Slack DM에만 결정 → 기록 휘발

9. 사외 블로그에 숫자·결과 과장

10. 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년의 보험 상품 전부를 본다.