영어 테크니컬 라이팅 실전 가이드: RFC, ADR, Design Doc 작성법과 템플릿

[변경의 범위가 넓은가?]
├── Yes: 여러 팀에 영향 → RFC 작성
│         └── RFC 승인 후 → Design Doc 작성
│               └── 주요 결정마다 → ADR 작성
└── No: 단일 팀 내부
      ├── 아키텍처 결정인가?
      │     └── Yes → ADR 작성
      └── 구현 계획이 필요한가?
            └── Yes → Design Doc (경량 버전) 작성

# RFC-0042: Migrate User Service to Event-Driven Architecture

| Field         | Value                         |
| ------------- | ----------------------------- |
| **Status**    | In Review                     |
| **Authors**   | Jane Kim (jane@example.com)   |
| **Created**   | 2026-03-01                    |
| **Updated**   | 2026-03-05                    |
| **Reviewers** | @backend-team, @platform-team |

## Summary

A one-paragraph summary of the proposal. This should be concise enough
that someone can understand the core idea in 30 seconds.

> We propose migrating the User Service from a synchronous REST-based
> architecture to an event-driven architecture using Apache Kafka.
> This change aims to reduce inter-service coupling, improve fault
> tolerance, and enable real-time data propagation to downstream
> consumers.

## Motivation

Why are we doing this? What problem does it solve? Include data
and metrics wherever possible.

- Current synchronous calls between User Service and 7 downstream
  services create cascading failures. In Q4 2025, we experienced
  12 incidents directly caused by this coupling.
- Average response time for user profile updates is 1,200ms due
  to synchronous fan-out to notification, analytics, and billing
  services.
- The current architecture cannot support the projected 10x growth
  in user events expected by Q3 2026.

## Proposed Solution

### High-Level Design

Describe the proposed solution in enough detail for reviewers to
understand the approach without reading the implementation details.

### Detailed Design

Include diagrams, API contracts, data models, and workflow
descriptions as needed.

## Alternatives Considered

### Alternative 1: Async HTTP with Retry Queue

Description of the alternative and why it was not chosen.

**Pros:**

- Minimal code changes required
- Team is already familiar with HTTP-based patterns

**Cons:**

- Does not fundamentally solve the coupling problem
- Retry storms can overwhelm downstream services

### Alternative 2: gRPC Streaming

Description and trade-off analysis.

## Migration Plan

How will we roll this out? Include phases, timelines, and rollback
procedures.

1. **Phase 1 (Week 1-2):** Set up Kafka cluster and deploy
   to staging environment.
2. **Phase 2 (Week 3-4):** Dual-write to both REST and Kafka
   for the notification service.
3. **Phase 3 (Week 5-6):** Migrate remaining consumers one
   by one with feature flags.
4. **Phase 4 (Week 7-8):** Remove synchronous endpoints after
   validation period.

### Rollback Plan

If critical issues are detected, we can revert to synchronous
calls by disabling the feature flag. Kafka messages will be
retained for 7 days, allowing replay after fix deployment.

## Risks and Mitigations

| Risk                       | Impact | Likelihood | Mitigation                                    |
| -------------------------- | ------ | ---------- | --------------------------------------------- |
| Message ordering issues    | High   | Medium     | Use partition keys based on user ID           |
| Consumer lag during peak   | Medium | High       | Auto-scaling consumer groups + alerting       |
| Data loss during migration | High   | Low        | Dual-write validation with reconciliation job |

## Open Questions

- Should we use Kafka Connect or custom consumers for the
  analytics pipeline?
- What is the acceptable message delivery latency SLA?

## References

- [Event-Driven Architecture at Uber](https://example.com)
- [Kafka Best Practices](https://example.com)

# ADR-0015: Use PostgreSQL as the Primary Database

| Field         | Value                          |
| ------------- | ------------------------------ |
| **Status**    | Accepted                       |
| **Date**      | 2026-03-04                     |
| **Deciders**  | Jane Kim, Alex Park, Sarah Lee |
| **Consulted** | Database Team, Security Team   |

## Context

We need to select a primary database for the new Order Management
Service. The service will handle approximately 50,000 orders per
day initially, with projected growth to 500,000 orders per day
within 18 months.

Key requirements:

- ACID transactions for order state management
- Complex queries for reporting and analytics
- JSON support for flexible product metadata
- Strong ecosystem for monitoring and tooling

The team has production experience with both PostgreSQL and MongoDB.
Our existing infrastructure runs PostgreSQL 15 for three other
services.

## Decision

We will use **PostgreSQL 17** as the primary database for the
Order Management Service.

## Rationale

1. **ACID compliance**: Order processing requires strict
   transactional guarantees. PostgreSQL's MVCC provides
   this without application-level workarounds.
2. **Operational familiarity**: The team already operates
   three PostgreSQL instances. Adding MongoDB would
   increase operational overhead and require new runbooks.
3. **JSON support**: PostgreSQL's JSONB type with GIN
   indexing satisfies the flexible metadata requirement
   without sacrificing query performance.
4. **Cost**: Our existing database infrastructure and
   tooling (pgBouncer, pg_stat_statements, Patroni)
   can be reused.

## Alternatives Considered

### MongoDB

- **Pros:** Native JSON document model, flexible schema,
  horizontal scaling with sharding
- **Cons:** Eventual consistency by default requires careful
  configuration for order processing, additional operational
  overhead, separate monitoring stack needed
- **Rejected because:** The operational cost of maintaining
  two database ecosystems outweighs the benefits of native
  document storage.

### Amazon DynamoDB

- **Pros:** Fully managed, auto-scaling, single-digit
  millisecond latency
- **Cons:** Limited query flexibility, complex data modeling
  for relational data, vendor lock-in
- **Rejected because:** The reporting requirements demand
  complex JOINs and aggregations that DynamoDB does not
  natively support.

## Consequences

### Positive

- Consistent operational practices across all services
- Reduced time-to-production due to existing expertise
- Full SQL support for future analytics requirements

### Negative

- Vertical scaling limits may require sharding strategy
  if growth exceeds projections
- JSONB queries are less intuitive than MongoDB's query
  language for deeply nested documents

### Risks

- If order volume exceeds 500K/day significantly ahead
  of schedule, we may need to implement read replicas
  or table partitioning earlier than planned.

## Related Decisions

- ADR-0012: Event sourcing for order state transitions
- ADR-0014: Use Patroni for PostgreSQL HA

# Design Doc: Real-Time Notification Pipeline

| Field            | Value                                          |
| ---------------- | ---------------------------------------------- |
| **Authors**      | Jane Kim, Alex Park                            |
| **Status**       | Approved                                       |
| **Last Updated** | 2026-03-05                                     |
| **Approvers**    | Sarah Lee (Tech Lead), Mike Chen (Staff Eng.)  |
| **Related RFCs** | RFC-0042 (Event-Driven Architecture Migration) |

## 1. Overview

### 1.1 Objective

Build a real-time notification pipeline that delivers push
notifications, emails, and in-app messages within 5 seconds
of trigger events, supporting 100K notifications per minute
at peak load.

### 1.2 Background

Following the approval of RFC-0042, we are migrating from
synchronous notification delivery to an event-driven model.
Currently, notifications are sent synchronously during API
request processing, adding 200-800ms to response times and
creating tight coupling between the User Service and the
Notification Service.

### 1.3 Goals and Non-Goals

**Goals:**

- Deliver notifications within 5 seconds of trigger events
- Support push, email, and in-app notification channels
- Handle 100K notifications/min at peak without degradation
- Provide per-user notification preferences and opt-out

**Non-Goals:**

- SMS delivery (planned for Phase 2)
- Marketing campaign notifications (separate system)
- Real-time chat functionality

## 2. High-Level Design

[Architecture diagram description]

The pipeline consists of four main components:

1. **Event Ingestion Layer**: Consumes events from Kafka
   topics published by upstream services.
2. **Routing Engine**: Determines which channels to use
   based on event type and user preferences.
3. **Channel Adapters**: Deliver notifications via push
   (FCM/APNs), email (SES), and in-app (WebSocket).
4. **Feedback Loop**: Tracks delivery status and handles
   retries for failed deliveries.

## 3. Detailed Design

### 3.1 Data Model

[Detailed schema definitions, API contracts, and
sequence diagrams go here]

### 3.2 API Contracts

[Endpoint specifications with request/response examples]

### 3.3 Error Handling and Retry Strategy

- Transient failures: Exponential backoff with jitter,
  max 3 retries
- Permanent failures: Dead letter queue with alerting
- Channel-specific: FCM token refresh on
  InvalidRegistration errors

## 4. Scalability and Performance

### 4.1 Load Estimates

| Metric                   | Current | Target (6 months) |
| ------------------------ | ------- | ----------------- |
| Notifications/min (avg)  | 10K     | 50K               |
| Notifications/min (peak) | 30K     | 100K              |
| End-to-end latency (p99) | 3s      | 5s                |

### 4.2 Scaling Strategy

- Kafka consumer groups with auto-scaling based on
  consumer lag metric
- Horizontal pod autoscaler targeting 70% CPU utilization
- Email sending rate limiter to stay within SES quotas

## 5. Security and Privacy

- All notification content encrypted at rest (AES-256)
- PII fields (email, device tokens) stored in separate
  encrypted columns
- GDPR compliance: user data deletion propagated within
  72 hours

## 6. Testing Strategy

- Unit tests for routing logic (target: 90% coverage)
- Integration tests with embedded Kafka
- Load test simulating 150K notifications/min
- Chaos testing: Kafka broker failure, SES outage

## 7. Rollout Plan

| Phase | Timeline | Scope                | Rollback Trigger  |
| ----- | -------- | -------------------- | ----------------- |
| 1     | Week 1-2 | Internal dogfooding  | Any P0 bug        |
| 2     | Week 3   | 5% of users (canary) | Error rate > 0.5% |
| 3     | Week 4   | 50% of users         | Error rate > 0.1% |
| 4     | Week 5   | 100% of users        | Error rate > 0.1% |

## 8. Open Questions and Risks

- How should we handle notification deduplication across
  channels?
- What is the retention policy for notification history?

## 9. Appendix

- Link to prototype: [URL]
- Performance benchmark results: [URL]
- Related ADRs: ADR-0015, ADR-0017

"As our user base has grown from 1M to 10M monthly active users,
the current architecture has shown signs of strain, particularly
in [specific area]."

"Over the past quarter, we observed [metric] degradation,
which correlates with [root cause]."

"We chose X over Y primarily because [reason 1]. Additionally,
[reason 2] and [reason 3] supported this decision."

"While Y offers [advantage], the operational complexity
it introduces outweighs the benefits for our current scale."

"The primary risk of this approach is [risk]. We plan to
mitigate this by [mitigation strategy]."

"If [condition] occurs, we will [fallback plan]."

[1단계: Self-Review]
   작성자가 체크리스트로 자가 점검 (1일)
       |
[2단계: Peer Review]
   같은 팀 동료 1~2명이 리뷰 (2~3일)
       |
[3단계: Stakeholder Review]
   영향받는 팀의 Tech Lead가 리뷰 (3~5일)
       |
[4단계: Final Approval]
   승인권자(Staff/Principal Engineer)가 최종 판단 (1~2일)
       |
[5단계: Archive]
   최종 상태 업데이트 후 저장소에 보관

## Summary

This PR introduces RFC-0042 proposing the migration of User
Service to an event-driven architecture.

## Type of Document

- [x] RFC (Request for Comments)
- [ ] ADR (Architecture Decision Record)
- [ ] Design Doc

## Key Decisions Requested

1. Should we use Kafka or Pulsar for the event bus?
2. Is the proposed 8-week migration timeline realistic?
3. Are there additional risks we have not considered?

## Reviewers

- @backend-team: Technical feasibility
- @platform-team: Infrastructure implications
- @security-team: Security review of event payload design

## Review Deadline

Please provide feedback by **2026-03-10**. If no objections are
raised by the deadline, this RFC will be considered accepted.

## How to Review

- Focus on the **Alternatives Considered** section first.
- Check if the **Risks and Mitigations** are comprehensive.
- Comment inline on specific sections if possible.

[질문할 때]
"Have we considered the impact on [X]?"
"What happens if [edge case]?"
"Could you clarify the rationale for choosing X over Y?"

[개선 제안할 때]
"Consider adding a section on [topic] to address [concern]."
"It might be worth including metrics from [source] to
 strengthen the motivation."
"Suggestion (non-blocking): Mentioning the rollback SLA
 would help on-call engineers."

[동의를 표현할 때]
"LGTM - the trade-off analysis is thorough."
"+1 on the proposed approach. The phased rollout plan
 is well-structured."

[우려를 표현할 때]
"I have concerns about [specific aspect]. Specifically, [detail]."
"Blocking: The security implications of [X] need to be
 addressed before we proceed."

[반대 의견을 낼 때 - 한국어 직역은 피하기]

피하기: "I disagree."
       (너무 직접적이어서 갈등으로 읽힐 수 있음)

피하기: "That might not be the best approach, maybe..."
       (너무 간접적이어서 의견이 무시될 수 있음)

권장: "I see the merit of this approach. However, I have
      a concern about [specific issue]. Have we considered
      [alternative]?"

[동의하면서 보충할 때]
권장: "Building on Alex's point, I think we should also
      consider [additional factor]."

[확신이 없을 때]
권장: "I'm not fully sure about this, but my initial
      read is that [opinion]. I'd appreciate others'
      input on this."

## Decision Matrix: Message Queue Selection

Scoring: 1 (Poor) to 5 (Excellent)
Weight: Importance multiplier

| Criteria               | Weight | Kafka  | RabbitMQ | Amazon SQS |
| ---------------------- | ------ | ------ | -------- | ---------- |
| Throughput             | 5      | 5 (25) | 3 (15)   | 4 (20)     |
| Operational complexity | 4      | 2 (8)  | 3 (12)   | 5 (20)     |
| Team familiarity       | 3      | 4 (12) | 2 (6)    | 3 (9)      |
| Cost at scale          | 3      | 4 (12) | 4 (12)   | 2 (6)      |
| Ecosystem/tooling      | 2      | 5 (10) | 3 (6)    | 4 (8)      |
| **Total**              |        | **67** | **51**   | **63**     |

**Recommendation:** Kafka scores highest due to superior
throughput and strong ecosystem support, despite higher
operational complexity. The team's existing Kafka experience
(score: 4) mitigates the operational overhead.

Wrong: "Need to migrate the database before deployment."
Right: "The team needs to migrate the database before deployment."
Right: "We need to migrate the database before deployment."

Wrong: "System sends notification to user."
Right: "The system sends a notification to the user."

Wrong: "We propose using cache to reduce latency."
Right: "We propose using a cache to reduce latency."

Passive: "The configuration is loaded by the service at startup."
Active:  "The service loads the configuration at startup."

Passive: "It was decided that Kafka would be used."
Active:  "The team decided to use Kafka."

Vague:  "When the service calls the API, it returns an error."
        (it이 service인지 API인지 불명확)
Clear:  "When the service calls the API, the API returns an error."

Vague:  "The system handles errors, retries, etc."
Clear:  "The system handles errors, retries, and circuit breaking."

[ ] Summary가 3문장 이내인가
[ ] Motivation에 정량적 데이터가 포함되어 있는가
[ ] 최소 2개 이상의 대안이 분석되어 있는가
[ ] 각 대안에 Pros/Cons가 명시되어 있는가
[ ] Migration/Rollout plan이 단계별로 작성되어 있는가
[ ] Rollback plan이 포함되어 있는가
[ ] Risks and Mitigations 섹션이 있는가
[ ] Open Questions가 정리되어 있는가
[ ] 리뷰어가 명시되어 있고 리뷰 마감일이 설정되어 있는가
[ ] 문법과 스펠링 체크를 완료했는가 (Grammarly 등 활용)

[ ] 하나의 ADR에 하나의 결정만 담았는가
[ ] Context가 결정 당시의 제약 조건을 충분히 설명하는가
[ ] Decision이 한 문장으로 명확하게 서술되어 있는가
[ ] 고려한 대안과 각각의 기각 사유가 기록되어 있는가
[ ] Consequences에 긍정적/부정적 결과가 모두 포함되어 있는가
[ ] 상태(Proposed/Accepted/Deprecated/Superseded)가 정확한가
[ ] 관련된 다른 ADR이 참조되어 있는가
[ ] 번호 체계가 기존 ADR과 일관되는가

[ ] Goals와 Non-Goals가 명확히 구분되어 있는가
[ ] 성능 목표가 구체적 수치로 제시되어 있는가
[ ] High-Level Design에 아키텍처 다이어그램이 포함되어 있는가
[ ] API 계약(Contract)이 정의되어 있는가
[ ] Error handling 전략이 기술되어 있는가
[ ] Security/Privacy 고려사항이 포함되어 있는가
[ ] Testing 전략이 구체적인가
[ ] Rollout plan에 단계별 롤백 트리거가 명시되어 있는가
[ ] 관련 RFC와 ADR이 참조되어 있는가
[ ] 승인자가 명시되어 있는가

[ ] 문서가 Git 저장소에 버전 관리되고 있는가
[ ] 파일 네이밍 규칙이 일관되는가 (예: RFC-NNNN, ADR-NNNN)
[ ] 문서 색인(index) 또는 카탈로그가 유지되고 있는가
[ ] 더 이상 유효하지 않은 문서에 Deprecated 표시가 되어 있는가
[ ] 정기적인 문서 리뷰 일정이 잡혀 있는가 (분기별 권장)

> WARNING: This design doc was written in March 2026 and has
> not been updated since. The actual implementation may differ
> significantly. Refer to the codebase and ADR-0023 for the
> current architecture.