LabHub

블로그

엔지니어링 글쓰기의 시대 — RFC·ADR·Design Doc·Amazon 6-pager·Eng Blog·Changelog·Slack·LLM 시대 글쓰기 심층 가이드 (2025)

2026-04-15 · 22 분 읽기 · #technical-writing#rfc#adr#design-doc#engineering-blog#changelog#communication#slack#ai-writing

왜 글 잘 쓰는 엔지니어가 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

1.2 독자 모델

1.3 BLUF — Bottom Line Up Front

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

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

1.5 Show, Don't Tell

2부. RFC — Request for Comments

2.1 RFC의 기원과 현대

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의 특징

2.5 RFC가 실패하는 이유

3부. ADR — Architecture Decision Record

3.1 왜 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 구조

3.4 도구

3.5 ADR이 만드는 문화

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

4.1 Design Doc vs RFC

4.2 좋은 Design Doc 구성

4.3 도구 생태계

4.4 다이어그램

5부. Amazon 6-pager — 회의 시작 20분의 침묵

5.1 규칙

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

5.2 왜 효과적인가

5.3 6-pager 구조

  1. Opening (한 문단)
  2. Background
  3. Problem Statement
  4. Options considered
  5. Recommendation
  6. FAQ (예상 반론 + 답)
  7. Appendix (데이터, 상세)

5.4 팀에 도입하는 법

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

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

6.2 레퍼런스 블로그

6.3 콘텐츠 유형

6.4 운영 체계

6.5 개인 엔지니어링 블로그

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 자동화

7.3 사용자 대상 Release Notes

7.4 API Deprecation

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

8.1 동기 회의의 비용

8.2 비동기 원칙

8.3 좋은 Slack 메시지 공식

[요약 1문장]

배경:
- 상황 X
- 원인 Y

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

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

대기 중: @이름

8.4 Email의 복귀

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

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

9.1 AI를 도구로 쓰는 법

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

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

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

9.5 AI 검출과 학술 윤리

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

10.1 내부 기하급수

10.2 외부 기하급수

10.3 개인 브랜드의 경제학

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

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

11.1 매일 습관

11.2 월 1회

11.3 분기 1회

11.4 연 1~2회

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

12.1 쓰기

12.2 교정

12.3 발행

12.4 SEO·측정

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년대 중반 테스트 판이 크게 달라지고 있다.

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

원문 보기: https://www.youngju.dev/blog/culture/2026-04-15-engineering-writing-rfc-adr-design-doc-6-pager-eng-blog-changelog-slack-ai-writing-deep-dive-guide-2025

댓글

아직 댓글이 없습니다.

로그인하면 댓글을 쓸 수 있습니다