개발자를 위한 테크니컬 라이팅 가이드: RFC, ADR, 기술 블로그, API 문서 작성법

독자 분석 체크리스트:
- 독자의 기술 수준은? (주니어/시니어/비개발자)
- 독자가 이미 아는 것은 무엇인가?
- 독자가 이 문서를 읽고 할 수 있어야 하는 것은?
- 독자가 이 문서를 어떤 상황에서 읽는가? (학습/참조/문제해결)

# RFC-001: 사용자 알림 시스템 재설계

## 메타데이터
- 작성자: 홍길동
- 상태: Draft / In Review / Accepted / Rejected / Superseded
- 작성일: 2025-03-15
- 리뷰어: 김철수, 이영희, 박지민
- 관련 RFC: RFC-042 (이벤트 시스템)

## 요약 (Summary)
현재 폴링 기반 알림 시스템을 WebSocket 기반 실시간 알림 시스템으로
교체하여 지연 시간을 30초에서 1초 이내로 단축합니다.

## 동기 (Motivation)
- 현재 시스템은 30초마다 폴링하여 알림을 확인 (높은 지연)
- 폴링으로 인한 불필요한 API 호출이 전체 트래픽의 15% 차지
- 사용자 만족도 조사에서 "알림이 느리다" 불만 42%

## 제안 (Proposal)
### 기술 설계
WebSocket 서버를 도입하고, 이벤트 기반 알림 파이프라인을 구축합니다.

### 대안 검토 (Alternatives Considered)
1. SSE (Server-Sent Events): 단방향만 가능, 양방향 통신 불가
2. 폴링 간격 축소 (5초): 서버 부하 6배 증가
3. Long Polling: 커넥션 관리 복잡도 증가

### 마이그레이션 전략
1. Phase 1: WebSocket 서버 구축 및 내부 테스트 (2주)
2. Phase 2: 10% 카나리 배포 (1주)
3. Phase 3: 전체 배포 및 폴링 제거 (1주)

## 리스크 및 우려 사항
- WebSocket 연결 유지 비용
- 방화벽/프록시 환경에서의 WebSocket 제한
- 모바일 환경에서의 배터리 소모

## 오픈 질문 (Open Questions)
- Redis Pub/Sub vs Kafka를 메시지 브로커로 사용할지?
- 오프라인 사용자 알림 큐잉 전략은?

## 참고 자료
- Slack의 실시간 메시징 아키텍처
- Discord의 WebSocket 구현 사례

┌─────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  Draft   │ -> │ In Review│ -> │ Decision │ -> │ Accepted │
│ (작성)   │    │ (리뷰)   │    │ (회의)    │    │ (승인)   │
└─────────┘    └──────────┘    └──────────┘    └──────────┘
                    │                              │
                    v                              v
              ┌──────────┐                  ┌───────────┐
              │ Revision │                  │ Superseded│
              │ (수정)   │                  │ (대체됨)   │
              └──────────┘                  └───────────┘

## RFC 리뷰 포인트
- [ ] 문제가 명확하게 정의되었는가?
- [ ] 제안이 문제를 실제로 해결하는가?
- [ ] 대안이 충분히 검토되었는가?
- [ ] 마이그레이션 전략이 현실적인가?
- [ ] 리스크가 식별되고 완화 방안이 있는가?
- [ ] 성공/실패 측정 기준이 있는가?
- [ ] 롤백 계획이 있는가?

# ADR-007: PostgreSQL을 주 데이터베이스로 선택

## 상태 (Status)
Accepted (2025-02-20)

## 맥락 (Context)
새 프로젝트의 주 데이터베이스를 선택해야 합니다. 주요 요구사항:
- ACID 트랜잭션 지원
- JSON 데이터 타입 네이티브 지원
- 전문 검색(Full-text search) 기능
- 팀의 기존 경험 활용

후보: PostgreSQL, MySQL 8.0, MongoDB, CockroachDB

## 결정 (Decision)
PostgreSQL 16을 주 데이터베이스로 사용합니다.

이유:
1. JSONB 타입으로 반정형 데이터를 효율적으로 처리 가능
2. pg_trgm, ts_vector로 전문 검색 가능 (별도 Elasticsearch 불필요)
3. 팀원 5명 중 4명이 PostgreSQL 경험 보유
4. MVCC 기반 동시성 제어가 우리 워크로드에 적합

## 결과 (Consequences)
긍정적:
- 단일 데이터베이스로 관계형 + JSON + 검색 처리
- 운영 복잡도 감소 (Elasticsearch 불필요)
- 팀 학습 비용 최소화

부정적:
- 수평 확장(horizontal scaling)이 MySQL보다 복잡
- Write-heavy 워크로드에서 MVCC 오버헤드 가능성
- Citus 등 확장 시 추가 비용 발생

## 대체 검토 (Alternatives)
- MySQL 8.0: JSON 지원이 PostgreSQL JSONB보다 제한적
- MongoDB: ACID 트랜잭션 지원이 4.0부터이나, 복잡한 조인 불가
- CockroachDB: 분산 SQL이나 팀 경험 부족, 운영 비용 높음

docs/
└── adr/
    ├── 0001-use-react-for-frontend.md
    ├── 0002-adopt-typescript.md
    ├── 0003-choose-postgresql.md
    ├── 0004-implement-event-sourcing.md
    ├── 0005-migrate-to-kubernetes.md
    ├── 0006-adopt-graphql.md        # Status: Superseded by 0010
    ├── 0007-choose-postgresql.md
    ├── 0008-use-redis-for-caching.md
    ├── 0009-adopt-trunk-based-dev.md
    ├── 0010-rest-api-over-graphql.md # Supersedes 0006
    └── template.md

# adr-tools 설치 및 사용
brew install adr-tools

# 새 ADR 생성
adr new "Use React for Frontend"
# -> docs/adr/0001-use-react-for-frontend.md 생성

# ADR 대체
adr new -s 6 "REST API over GraphQL"
# -> 0006의 상태를 Superseded로 변경

# 목차 생성
adr generate toc

openapi: 3.1.0
info:
  title: User Management API
  description: 사용자 관리를 위한 RESTful API
  version: 2.1.0
  contact:
    name: Platform Team
    email: platform@example.com

servers:
  - url: https://api.example.com/v2
    description: Production
  - url: https://staging-api.example.com/v2
    description: Staging

paths:
  /users:
    get:
      summary: List all users
      description: |
        페이지네이션을 지원하는 사용자 목록 조회 API입니다.
        기본적으로 활성(active) 사용자만 반환합니다.
      operationId: listUsers
      tags:
        - Users
      parameters:
        - name: page
          in: query
          description: 페이지 번호 (1부터 시작)
          schema:
            type: integer
            minimum: 1
            default: 1
        - name: limit
          in: query
          description: 페이지당 항목 수
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: status
          in: query
          description: 사용자 상태 필터
          schema:
            type: string
            enum: [active, inactive, suspended]
            default: active
      responses:
        '200':
          description: 성공
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/User'
                  pagination:
                    $ref: '#/components/schemas/Pagination'
              example:
                data:
                  - id: "usr_abc123"
                    name: "Alice Kim"
                    email: "alice@example.com"
                    role: "admin"
                    createdAt: "2025-01-15T09:00:00Z"
                pagination:
                  page: 1
                  limit: 20
                  totalItems: 150
                  totalPages: 8
        '401':
          description: 인증 실패
        '429':
          description: 요청 제한 초과

    post:
      summary: Create a new user
      operationId: createUser
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
            example:
              name: "Bob Lee"
              email: "bob@example.com"
              role: "member"
      responses:
        '201':
          description: 사용자 생성 성공
        '400':
          description: 유효성 검증 실패
        '409':
          description: 이메일 중복

components:
  schemas:
    User:
      type: object
      required: [id, name, email, role, createdAt]
      properties:
        id:
          type: string
          description: 사용자 고유 ID (usr_ 접두사)
          example: "usr_abc123"
        name:
          type: string
          description: 사용자 이름
          example: "Alice Kim"
        email:
          type: string
          format: email
          description: 이메일 주소
        role:
          type: string
          enum: [admin, member, viewer]
        createdAt:
          type: string
          format: date-time

    CreateUserRequest:
      type: object
      required: [name, email, role]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        email:
          type: string
          format: email
        role:
          type: string
          enum: [admin, member, viewer]

    Pagination:
      type: object
      properties:
        page:
          type: integer
        limit:
          type: integer
        totalItems:
          type: integer
        totalPages:
          type: integer

  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

security:
  - BearerAuth: []

## API 문서 품질 체크리스트
- [ ] 모든 엔드포인트에 설명이 있는가?
- [ ] 요청/응답 예제가 있는가?
- [ ] 에러 응답과 에러 코드가 문서화되었는가?
- [ ] 인증 방법이 명시되었는가?
- [ ] Rate limit 정보가 포함되었는가?
- [ ] 페이지네이션 방법이 설명되었는가?
- [ ] SDK/코드 예제가 제공되는가?
- [ ] 변경 이력(changelog)이 관리되고 있는가?

# 프로젝트 이름

간결한 한 줄 설명: 이 프로젝트가 무엇이고 왜 사용하는지

![Build Status](https://img.shields.io/badge/build-passing-green)
![License](https://img.shields.io/badge/license-MIT-blue)
![Version](https://img.shields.io/badge/version-2.1.0-orange)

## 주요 기능 (Features)
- 기능 1: 간결한 설명
- 기능 2: 간결한 설명
- 기능 3: 간결한 설명

## 빠른 시작 (Quick Start)
설치부터 첫 실행까지 3단계 이내로 설명합니다.

## 설치 (Installation)
다양한 설치 방법을 운영체제별로 안내합니다.

## 사용법 (Usage)
가장 일반적인 사용 예제를 코드와 함께 제공합니다.

## 설정 (Configuration)
환경 변수, 설정 파일 등을 표로 정리합니다.

## API 참조 (API Reference)
주요 API의 사용법을 간략히 안내합니다.

## 기여 방법 (Contributing)
PR 프로세스, 코드 스타일, 테스트 요구사항을 설명합니다.

## 라이선스 (License)
MIT, Apache 2.0 등 라이선스를 명시합니다.

# my-project
Install and run.

# FastCache

Redis 호환 인메모리 캐시 서버. Go로 작성되어 Redis 대비 40% 낮은 메모리 사용량.

## 왜 FastCache인가?
- Redis 프로토콜 100% 호환 — 기존 클라이언트 그대로 사용
- 메모리 사용량 40% 절감 (벤치마크 결과 포함)
- 단일 바이너리, 제로 디펜던시

## 30초 시작
(3줄의 설치/실행 코드)

# Changelog

이 프로젝트의 모든 주요 변경사항을 기록합니다.
[Keep a Changelog](https://keepachangelog.com/) 형식을 따릅니다.

## [Unreleased]

### Added
- 다크 모드 지원 (#234)
- 사용자 프로필 이미지 업로드 기능 (#256)

### Changed
- 로그인 페이지 UI를 새 디자인 시스템으로 마이그레이션 (#278)

## [2.1.0] - 2025-03-01

### Added
- WebSocket 기반 실시간 알림 시스템 (#189)
- 관리자 대시보드 분석 차트 (#201)
- API 요청 제한(rate limiting) 기능 (#215)

### Changed
- JWT 토큰 만료 시간을 24시간에서 12시간으로 변경
- 데이터베이스 커넥션 풀 크기를 10에서 20으로 증가

### Fixed
- 동시 로그인 시 세션 충돌 버그 수정 (#220)
- 프로필 수정 시 이메일 검증 우회 가능한 보안 취약점 수정 (#225)

### Deprecated
- /api/v1 엔드포인트 (v3.0에서 제거 예정)

### Removed
- Legacy XML 응답 형식 지원 제거

### Security
- 의존성 업데이트: lodash 4.17.21 (CVE-2021-23337)

## [2.0.0] - 2025-01-15

### Breaking Changes
- 인증 방식이 API Key에서 JWT로 변경
- 응답 형식 변경: snake_case에서 camelCase로 통일

MAJOR.MINOR.PATCH

MAJOR: 호환되지 않는 API 변경 (Breaking Change)
MINOR: 이전 버전과 호환되는 새 기능 추가
PATCH: 이전 버전과 호환되는 버그 수정

예시:
1.0.0 -> 1.0.1  (버그 수정)
1.0.1 -> 1.1.0  (새 기능 추가)
1.1.0 -> 2.0.0  (Breaking Change)

# conventional-changelog 사용
npx conventional-changelog -p angular -i CHANGELOG.md -s

# standard-version 사용
npx standard-version

# release-please (GitHub Action)
# .github/workflows/release.yml

# .github/workflows/release.yml
name: Release
on:
  push:
    branches: [main]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: google-github-actions/release-please-action@v4
        with:
          release-type: node

1. 제목 (Title)
   - 구체적이고 검색 가능한 키워드 포함
   - Bad: "내가 배운 것들"
   - Good: "PostgreSQL에서 100만 행 쿼리를 2초에서 50ms로 최적화한 방법"

2. 도입부 (Introduction)
   - 문제 정의: 독자가 공감할 수 있는 상황
   - 결과 미리보기: "이 글을 읽으면 X를 할 수 있습니다"

3. 본문 (Body)
   - 문제 -> 시도 -> 실패 -> 해결의 스토리 구조
   - 코드 예제는 실행 가능한 형태로
   - 다이어그램으로 복잡한 개념 시각화

4. 결론 (Conclusion)
   - 핵심 교훈 요약 (3줄 이내)
   - 다음 단계 제안

5. 참고 자료 (References)

## SEO 체크리스트
- [ ] 제목에 핵심 키워드 포함 (50~60자)
- [ ] 메타 설명(description) 작성 (150~160자)
- [ ] H2/H3 헤딩에 관련 키워드 포함
- [ ] 이미지에 alt 태그 추가
- [ ] 내부/외부 링크 포함
- [ ] URL이 깔끔하고 키워드 포함
- [ ] 코드 블록에 syntax highlighting 적용

"우리 팀은 매일 3시에 서버가 다운되는 문제를 겪었다." (문제)
"처음에는 메모리 누수라고 생각했다." (가설)
"하지만 프로파일링 결과, 문제는 GC가 아니라 커넥션 풀 고갈이었다." (발견)
"커넥션 풀 설정을 변경하고 모니터링을 추가한 결과..." (해결)
"이 경험에서 배운 3가지 교훈:" (교훈)

sequenceDiagram
    participant Client
    participant API Gateway
    participant Auth Service
    participant User Service
    participant Database

    Client->>API Gateway: POST /login
    API Gateway->>Auth Service: Validate credentials
    Auth Service->>Database: Query user
    Database-->>Auth Service: User data
    Auth Service-->>API Gateway: JWT token
    API Gateway-->>Client: 200 OK + token

graph TD
    A[Client] --> B[Load Balancer]
    B --> C[API Server 1]
    B --> D[API Server 2]
    C --> E[Redis Cache]
    D --> E
    C --> F[PostgreSQL Primary]
    D --> F
    F --> G[PostgreSQL Replica]
    C --> H[Message Queue]
    D --> H
    H --> I[Worker 1]
    H --> J[Worker 2]

stateDiagram-v2
    [*] --> Draft
    Draft --> InReview: Submit for review
    InReview --> Approved: All reviewers approve
    InReview --> Draft: Changes requested
    Approved --> Published: Deploy
    Published --> Archived: Deprecate
    Archived --> [*]

@startuml
!theme plain

package "Frontend" {
  [React App] as react
  [Next.js SSR] as nextjs
}

package "Backend" {
  [API Gateway] as gateway
  [User Service] as user
  [Order Service] as order
  [Notification Service] as notif
}

package "Data" {
  database "PostgreSQL" as pg
  database "Redis" as redis
  queue "Kafka" as kafka
}

react --> gateway
nextjs --> gateway
gateway --> user
gateway --> order
user --> pg
order --> pg
user --> redis
order --> kafka
kafka --> notif

@enduml

# .github/workflows/docs-lint.yml
name: Docs Lint
on: [pull_request]

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: markdownlint
        uses: DavidAnson/markdownlint-cli2-action@v18
        with:
          globs: 'docs/**/*.md'

      - name: vale (prose linter)
        uses: errata-ai/vale-action@v2
        with:
          files: docs/
          vale_flags: "--config=.vale.ini"

# .vale.ini
StylesPath = .vale/styles
MinAlertLevel = suggestion

[*.md]
BasedOnStyles = Vale, Google
Google.Passive = warning
Google.We = warning
Google.Will = error
Vale.Terms = error

// TypeDoc으로 TypeScript API 문서 자동 생성
// tsconfig.json에 아래 추가:
// "plugins": [{ "name": "typedoc" }]

/**
 * 사용자 서비스
 *
 * @remarks
 * 사용자 CRUD 작업을 처리합니다.
 *
 * @example
 * ```typescript
 * const service = new UserService(repository);
 * const user = await service.getUser('usr_123');
 * ```
 */
export class UserService {
  /** 사용자 조회 */
  async getUser(id: string): Promise<User> {
    // ...
  }
}

1단계: README 표준화 (1~2주)
  - 모든 저장소에 README 템플릿 적용
  - PR 체크리스트에 "문서 업데이트" 항목 추가

2단계: ADR 도입 (2~4주)
  - ADR 템플릿 및 디렉토리 구조 설정
  - 주요 아키텍처 결정에 ADR 작성 의무화

3단계: RFC 프로세스 도입 (1~2개월)
  - RFC 템플릿 및 리뷰 프로세스 수립
  - 영향도 높은 변경에 RFC 필수

4단계: Docs-as-Code (2~3개월)
  - 문서 사이트 구축 (Docusaurus/MkDocs)
  - CI/CD 파이프라인에 문서 빌드/배포 통합
  - 린팅(markdownlint, Vale) 자동화

5단계: 문화 정착 (지속)
  - 좋은 문서에 대한 인정과 보상
  - 글쓰기 워크숍 정기 진행
  - 신입 온보딩에 문서 작성 연습 포함