Split View: 기술 문서 영어 작성 가이드: RFC·ADR·Design Doc·Tech Spec 템플릿과 실전 표현

[문서 유형 선택 기준]

1. "팀의 의견을 넓게 구하고 싶다" --> RFC
   - 새로운 기술 도입, 프로세스 변경, 크로스팀 영향이 큰 변경

2. "아키텍처 결정의 배경과 근거를 남기고 싶다" --> ADR
   - 데이터베이스 선택, 프레임워크 전환, API 설계 방향

3. "시스템 설계를 상세하게 공유하고 합의하고 싶다" --> Design Doc
   - 새로운 서비스 설계, 대규모 리팩토링, 성능 최적화 프로젝트

4. "구현에 필요한 상세 사양을 정의하고 싶다" --> Tech Spec
   - API 엔드포인트 정의, 데이터 모델 설계, 배포 전략

[RFC 템플릿]

RFC-XXX: Title of the Proposal
Author: Your Name
Status: Draft | In Review | Accepted | Rejected | Superseded
Created: 2026-03-12
Last Updated: 2026-03-12

## Summary
One paragraph summarizing what this RFC proposes and why.

## Motivation
Why is this change needed? What problem does it solve?
Include data, metrics, or user feedback that supports the need.

## Detailed Design
The technical details of the proposal.
- Architecture diagrams
- API changes
- Data model changes
- Migration strategy

## Alternatives Considered
What other approaches were evaluated?
Why were they rejected?

## Risks and Mitigations
What could go wrong? How do we mitigate each risk?

## Success Metrics
How will we measure whether this change was successful?

## Open Questions
What decisions have not yet been made?
What feedback are you specifically looking for?

## References
Links to related documents, prior art, and research.

[Summary 섹션]

"This RFC proposes migrating our authentication service from a
session-based model to JWT-based authentication."
(이 RFC는 인증 서비스를 세션 기반 모델에서 JWT 기반 인증으로
마이그레이션하는 것을 제안합니다.)

"The goal of this proposal is to reduce deployment coupling
between the frontend and backend teams."
(이 제안의 목표는 프론트엔드와 백엔드 팀 간의
배포 결합도를 줄이는 것입니다.)

[Motivation 섹션]

"Our current system has reached its scalability limits,
with p99 latency exceeding 2 seconds during peak hours."
(현재 시스템이 확장성 한계에 도달했으며,
피크 시간에 p99 레이턴시가 2초를 초과합니다.)

"Over the past quarter, we have received 15 customer complaints
related to this limitation."
(지난 분기 동안 이 제한과 관련하여 15건의 고객 불만을 받았습니다.)

[Alternatives Considered 섹션]

"We evaluated three alternatives: (1) vertical scaling of the
existing database, (2) introducing a read replica, and
(3) migrating to a distributed database."
(세 가지 대안을 평가했습니다: (1) 기존 데이터베이스의 수직 확장,
(2) 읽기 복제본 도입, (3) 분산 데이터베이스로의 마이그레이션.)

"Alternative 1 was rejected because it only delays the problem
by an estimated 6 months without addressing the root cause."
(대안 1은 근본 원인을 해결하지 않고 문제를 약 6개월만
지연시킬 뿐이므로 기각했습니다.)

[RFC 상태 전환 표현]

"This RFC is currently in Draft status and open for initial feedback."
(이 RFC는 현재 초안 상태이며 초기 피드백을 받고 있습니다.)

"The review period for this RFC closes on March 20, 2026."
(이 RFC의 검토 기간은 2026년 3월 20일에 마감됩니다.)

"Based on the feedback received, we are updating this RFC
to address the concerns raised about data consistency."
(받은 피드백을 바탕으로, 데이터 일관성에 대해 제기된
우려를 해결하기 위해 이 RFC를 업데이트하고 있습니다.)

"This RFC has been accepted and will be implemented in Q2 2026."
(이 RFC는 승인되었으며 2026년 2분기에 구현될 예정입니다.)

"This RFC is superseded by RFC-087, which takes a different
approach to solving the same problem."
(이 RFC는 같은 문제를 다른 접근 방식으로 해결하는
RFC-087로 대체되었습니다.)

[ADR 템플릿 - Michael Nygard 형식]

# ADR-XXX: Title of Decision

## Status
Proposed | Accepted | Deprecated | Superseded by ADR-YYY

## Context
What is the issue that we are seeing that is motivating
this decision or change?

## Decision
What is the change that we are proposing and/or doing?

## Consequences
What becomes easier or more difficult to do because
of this change?

[ADR 확장 작성 예시]

# ADR-012: Use PostgreSQL as the Primary Database

## Status
Accepted (2026-03-10)

## Context
Our application currently uses MongoDB for all data storage.
As the product has evolved, we have encountered increasing
challenges with:
- Complex queries requiring multiple aggregation pipelines
- Data consistency issues in transactions spanning
  multiple collections
- Difficulty enforcing referential integrity at the
  database level

The team has spent approximately 20 percent of each sprint
addressing data consistency bugs over the past three months.

## Decision
We will migrate our primary data store from MongoDB to
PostgreSQL for all transactional data. MongoDB will be
retained for the audit log service where its document
model is a natural fit.

## Consequences

### Positive
- ACID transactions will eliminate the consistency bugs
  we have been experiencing
- The team has stronger expertise in relational databases
- Joins will simplify our current multi-query patterns

### Negative
- Migration will require approximately 4 weeks of
  engineering effort
- We will need to maintain two database technologies
  during the transition period
- Some document-oriented patterns will require
  schema redesign

### Risks
- Data migration downtime: mitigated by using a
  dual-write strategy during transition
- Performance regression: mitigated by load testing
  the new schema before cutover

[Context 작성 표현]

"The current architecture does not support horizontal scaling
beyond 3 nodes without significant operational overhead."
(현재 아키텍처는 상당한 운영 오버헤드 없이는
3노드 이상의 수평 확장을 지원하지 않습니다.)

"We need to decide on an approach before the Q3 feature
freeze deadline."
(Q3 기능 동결 마감일 전에 접근 방식을 결정해야 합니다.)

[Decision 작성 표현]

"We will adopt a strangler fig pattern to incrementally
migrate from the legacy system."
(레거시 시스템에서 점진적으로 마이그레이션하기 위해
strangler fig 패턴을 채택합니다.)

"We will use Protocol Buffers instead of JSON for
inter-service communication."
(서비스 간 통신에 JSON 대신 Protocol Buffers를 사용합니다.)

[Consequences 작성 표현]

"This decision will increase deployment complexity but
significantly improve runtime performance."
(이 결정은 배포 복잡성을 증가시키지만 런타임 성능을
크게 향상시킵니다.)

"Teams will need to invest in learning the new technology,
estimated at 2 weeks of ramp-up time per engineer."
(팀은 새 기술 학습에 투자해야 하며,
엔지니어당 약 2주의 적응 시간이 필요합니다.)

[Design Doc 템플릿 - Google Style]

Title: [Project Name] Design Document
Author(s): Name (email)
Reviewers: Names
Status: Draft | In Review | Approved
Last Updated: 2026-03-12

## 1. Overview
A brief description of the project, its goals,
and why it matters.

## 2. Background
Relevant context that the reader needs to understand
the rest of the document. Prior art and existing systems.

## 3. Goals and Non-Goals
What this project will and will not accomplish.

## 4. Detailed Design
### 4.1 System Architecture
### 4.2 API Design
### 4.3 Data Model
### 4.4 Algorithms

## 5. Alternatives Considered
Other approaches and why they were rejected.

## 6. Cross-Cutting Concerns
### 6.1 Security
### 6.2 Privacy
### 6.3 Observability

## 7. Migration Strategy
How to get from the current state to the proposed state.

## 8. Open Questions
Unresolved decisions that need input from reviewers.

## 9. Timeline and Milestones
Estimated effort and key milestones.

[Goals and Non-Goals 작성 예시]

## Goals
- Reduce API response time for the product search endpoint
  from 800ms (p95) to under 200ms (p95)
- Support real-time indexing of product catalog updates
  with a maximum delay of 30 seconds
- Maintain backward compatibility with existing API clients

## Non-Goals
- This project will NOT address the image search feature
  (tracked separately in Project Atlas)
- Optimizing the recommendation engine is out of scope
  for this design
- We are NOT planning to migrate the entire search
  infrastructure; only the product search endpoint
  is in scope

[Non-Goals 작성 시 유용한 표현]

"This is explicitly out of scope for this project."
(이것은 이 프로젝트의 범위에서 명시적으로 제외됩니다.)

"While important, this concern will be addressed in
a follow-up project."
(중요한 문제이지만, 후속 프로젝트에서 다룰 예정입니다.)

"We acknowledge this limitation but consider it acceptable
given the timeline constraints."
(이 제한을 인지하고 있지만 일정 제약을 고려할 때
수용 가능하다고 판단합니다.)

[시스템 아키텍처 설명 표현]

"The system consists of three main components:
an API gateway, a processing pipeline, and a storage layer."
(시스템은 세 가지 주요 구성 요소로 이루어집니다:
API 게이트웨이, 처리 파이프라인, 스토리지 레이어.)

"Requests flow from the client through the load balancer
to one of N stateless application servers."
(요청은 클라이언트에서 로드 밸런서를 거쳐
N개의 상태 비저장(stateless) 애플리케이션 서버 중 하나로 흐릅니다.)

"This component is responsible for validating incoming requests
and enriching them with user context before forwarding
to the downstream service."
(이 컴포넌트는 들어오는 요청을 검증하고, 다운스트림 서비스로
전달하기 전에 사용자 컨텍스트를 추가하는 역할을 합니다.)

[API 설계 설명 표현]

"The API follows RESTful conventions with the following
endpoints..."
(API는 RESTful 규칙을 따르며 다음 엔드포인트를
포함합니다...)

"We chose gRPC over REST for this internal service
because of its lower serialization overhead and
built-in streaming support."
(이 내부 서비스에 REST 대신 gRPC를 선택한 이유는
직렬화 오버헤드가 낮고 스트리밍 지원이
내장되어 있기 때문입니다.)

[Tech Spec 템플릿]

Title: [Feature Name] Technical Specification
Author: Name
Approvers: Names
Status: Draft | Approved | Implemented
Sprint/Quarter: Sprint 24 / Q1 2026

## Executive Summary
What are we building and why? (2-3 sentences)

## Technical Requirements
### Functional Requirements
### Non-Functional Requirements
  - Performance targets
  - Availability requirements
  - Security requirements

## System Design
### Architecture Overview
### Component Design
### Data Model / Schema Changes
### API Contracts

## Implementation Plan
### Phase 1: [Description] (Week 1-2)
### Phase 2: [Description] (Week 3-4)

## Testing Strategy
### Unit Tests
### Integration Tests
### Load Tests
### Rollback Plan

## Dependencies
External services, libraries, or teams we depend on.

## Risks and Mitigations
What could go wrong and how we plan to handle it.

## Success Metrics
How we will measure the success of this implementation.

## Appendix
Additional technical details, diagrams, or references.

[Technical Requirements 표현]

"The system must handle at least 10,000 concurrent connections
with a p99 latency below 100 milliseconds."
(시스템은 p99 레이턴시 100밀리초 미만으로
최소 10,000개의 동시 연결을 처리해야 합니다.)

"Data at rest must be encrypted using AES-256,
and data in transit must use TLS 1.3."
(저장 데이터는 AES-256으로 암호화해야 하며,
전송 중 데이터는 TLS 1.3을 사용해야 합니다.)

[Implementation Plan 표현]

"In Phase 1, we will implement the core data pipeline
and validate it against the existing system using
shadow traffic."
(1단계에서 핵심 데이터 파이프라인을 구현하고
섀도 트래픽을 사용하여 기존 시스템 대비 검증합니다.)

"Phase 2 is gated on the successful completion of
Phase 1 load testing."
(2단계는 1단계 부하 테스트의 성공적인 완료를
전제로 합니다.)

[Testing Strategy 표현]

"We will achieve at least 80 percent code coverage
with unit tests for all new modules."
(모든 새로운 모듈에 대해 단위 테스트로 최소
80퍼센트 코드 커버리지를 달성합니다.)

"The rollback plan involves reverting the feature flag
and restoring the previous database schema via
the automated migration tool."
(롤백 계획은 기능 플래그를 되돌리고 자동화된
마이그레이션 도구를 통해 이전 데이터베이스
스키마를 복원하는 것입니다.)

[피드백 심각도별 표현]

[Blocker - 반드시 해결해야 함]
"Blocker: This approach has a potential data loss scenario
that must be addressed before we can approve."
(블로커: 이 접근 방식에 잠재적인 데이터 손실 시나리오가 있어
승인 전에 반드시 해결해야 합니다.)

[Major - 중요한 변경 필요]
"Major: The proposed caching strategy does not account for
cache invalidation in a multi-region setup."
(주요: 제안된 캐싱 전략은 멀티 리전 환경에서의
캐시 무효화를 고려하지 않았습니다.)

[Minor - 개선 권장]
"Minor: Consider adding a sequence diagram to illustrate
the authentication flow."
(소소한 의견: 인증 흐름을 설명하기 위한
시퀀스 다이어그램 추가를 고려해 보세요.)

[Nit - 사소한 제안]
"Nit: Typo in the API endpoint name on page 3."
(사소한 점: 3페이지 API 엔드포인트 이름에 오타가 있습니다.)

[Question - 이해를 위한 질문]
"Question: What happens if the downstream service is
unavailable for more than 5 minutes?"
(질문: 다운스트림 서비스가 5분 이상 불가용할 경우
어떻게 되나요?)

[리뷰에서 긍정적 피드백 주기]

"This is a well-thought-out design. I especially appreciate
the detailed migration strategy."
(잘 고민된 설계입니다. 특히 상세한 마이그레이션 전략이 좋습니다.)

"The trade-off analysis in the Alternatives section is
very thorough."
(대안 섹션의 트레이드오프 분석이 매우 철저합니다.)

"I like how you have explicitly called out the non-goals.
This helps set clear expectations."
(Non-Goals를 명시적으로 기술한 점이 좋습니다.
이것이 명확한 기대치 설정에 도움이 됩니다.)

"Strong proposal overall. I have a few minor suggestions below."
(전반적으로 강력한 제안입니다. 아래에 몇 가지 사소한
제안이 있습니다.)

[건설적으로 반대 의견 제시하기]

"I have a concern about the proposed approach.
Have we considered the impact on the billing service?"
(제안된 접근 방식에 우려가 있습니다.
결제 서비스에 미치는 영향을 검토했나요?)

"I think there might be a simpler approach here.
What if we used an event-driven architecture instead?"
(여기에 더 단순한 접근 방식이 있을 수 있다고 봅니다.
대신 이벤트 기반 아키텍처를 사용하면 어떨까요?)

"While I agree with the overall direction, I am not convinced
that the proposed timeline is realistic given our current
team capacity."
(전반적인 방향에는 동의하지만, 현재 팀 역량을 고려할 때
제안된 일정이 현실적인지 확신이 서지 않습니다.)

"Could you elaborate on how this handles the edge case
where the user session expires mid-transaction?"
(사용자 세션이 트랜잭션 도중에 만료되는 엣지 케이스를
어떻게 처리하는지 부연해 주시겠어요?)

[흔한 구조적 실수와 개선]

[실수 1: Problem Statement 없이 바로 해결책 제시]

Bad:  "We should use Redis for caching."
Good: "Our API response times have increased by 40 percent
      over the past month due to repeated database queries
      for frequently accessed data. We propose implementing
      a Redis caching layer to reduce database load and
      improve response times."

[실수 2: 대안 분석 생략]

Bad:  "We decided to use Kubernetes."
Good: "We evaluated three container orchestration options:
      Kubernetes, Docker Swarm, and Amazon ECS.
      We selected Kubernetes because..."

[실수 3: 정량적 근거 부재]

Bad:  "The system is slow."
Good: "The system currently has a p95 latency of 1.2 seconds,
      which exceeds our SLA target of 500 milliseconds."

[실수 4: Success Metrics 누락]

Bad:  "This change will improve performance."
Good: "Success will be measured by:
      - p95 latency reduction from 1.2s to under 500ms
      - Error rate below 0.1 percent
      - Zero data loss during migration"

[기술 문서에서 흔한 영어 실수]

[관사 (a/the) 오용]
Bad:  "System handles request and sends response."
Good: "The system handles a request and sends a response."

[시제 혼용]
Bad:  "The service received a request and processes it."
Good: "The service receives a request and processes it."
      (현재 시제로 통일 - 시스템 동작 설명 시)

[수동태 남용]
Bad:  "The data is being processed by the pipeline and
      is then stored by the database."
Good: "The pipeline processes the data and stores it
      in the database."

[장황한 표현]
Bad:  "In order to achieve the purpose of reducing latency..."
Good: "To reduce latency..."

[주어 생략 (일본어/한국어 습관)]
Bad:  "Should consider using connection pooling."
Good: "We should consider using connection pooling."

[기술 문서 작성 5단계 워크플로우]

Step 1: Outline First (개요 먼저)
- 템플릿의 섹션 헤딩만 먼저 채운다
- 각 섹션에 1-2 문장의 핵심 메시지를 적는다
- 이 단계에서 mentor나 tech lead에게 방향을 확인받는다

Step 2: Write the Core Sections (핵심 섹션 작성)
- Problem Statement / Context를 먼저 완성한다
- 그 다음 Proposed Solution / Decision을 작성한다
- 마지막으로 Alternatives와 Trade-offs를 작성한다

Step 3: Add Supporting Details (뒷받침 자료 추가)
- 다이어그램, 테이블, 코드 예시를 추가한다
- 정량적 데이터로 주장을 뒷받침한다

Step 4: Internal Review (내부 리뷰)
- 신뢰하는 동료 1-2명에게 먼저 리뷰를 받는다
- 영어 표현이 자연스러운지 확인을 요청한다

Step 5: Publish and Iterate (공개와 반복)
- 팀 전체에 공유하고 피드백을 수집한다
- 피드백 반영 후 상태를 업데이트한다

[RFC 체크리스트]
- [ ] Summary가 한 문단으로 제안 사항을 명확히 요약하는가?
- [ ] Motivation에 정량적 데이터나 구체적 사례가 있는가?
- [ ] Alternatives를 최소 2개 이상 검토했는가?
- [ ] Open Questions가 구체적인가?
- [ ] 리뷰 마감일이 명시되어 있는가?

[ADR 체크리스트]
- [ ] Context가 의사결정의 배경을 충분히 설명하는가?
- [ ] Decision이 명확하고 모호하지 않은가?
- [ ] Consequences에 긍정적/부정적 영향이 모두 있는가?
- [ ] 6개월 후 새로운 팀원이 읽어도 이해할 수 있는가?

[Design Doc 체크리스트]
- [ ] Non-Goals가 명시되어 있는가?
- [ ] 아키텍처 다이어그램이 포함되어 있는가?
- [ ] Security와 Privacy 고려사항이 있는가?
- [ ] Migration Strategy가 현실적인가?

[Tech Spec 체크리스트]
- [ ] 비기능 요구사항(성능, 보안, 가용성)이 정량적인가?
- [ ] Implementation Plan에 단계별 마일스톤이 있는가?
- [ ] Testing Strategy에 롤백 계획이 포함되어 있는가?
- [ ] Dependencies가 모두 나열되어 있는가?

[전환 표현 모음]

[배경 설명에서 제안으로]
"Given these constraints, we propose..."
(이러한 제약을 고려하여, 우리는 다음을 제안합니다...)

"To address this issue, the following approach is recommended."
(이 문제를 해결하기 위해 다음 접근 방식을 권장합니다.)

[장단점 비교]
"On the one hand... On the other hand..."
(한편으로는... 다른 한편으로는...)

"While this approach offers simplicity, it comes at the cost of flexibility."
(이 접근 방식은 단순성을 제공하지만, 유연성의 비용이 따릅니다.)

[결론 도출]
"Taking all factors into consideration, we recommend..."
(모든 요소를 고려하여, 우리는 다음을 권장합니다...)

"Based on the analysis above, the proposed solution
best balances performance and maintainability."
(위 분석에 기반하여, 제안된 솔루션이 성능과
유지보수성을 가장 잘 균형잡습니다.)

[범위 제한]
"This document focuses specifically on..."
(이 문서는 구체적으로 다음에 초점을 맞춥니다...)

"The following topics are covered in a separate document."
(다음 주제들은 별도의 문서에서 다룹니다.)