> For the complete documentation index, see [llms.txt](https://seungyeon-kang.gitbook.io/yeons-frame/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://seungyeon-kang.gitbook.io/yeons-frame/engineering/readme.md).

# 엔지니어링

소프트웨어는 애플리케이션 코드만으로 동작하지 않는다. 요청 경계, 의존성 실패, 컨테이너 런타임, 배포, 확장과 관측이 함께 시스템 동작을 만든다.

## 기술 주제

* [서비스 아키텍처](/yeons-frame/engineering/service-architecture.md): 서비스 경계, 외부 연동과 게이트웨이 정책
* [클라우드 플랫폼](/yeons-frame/engineering/cloud-platform.md): ECS 런타임, 서비스 디스커버리, 프라이빗 네트워크와 롤아웃
* [신뢰성 엔지니어링](/yeons-frame/engineering/reliability.md): 부하 테스트, 관측, SLO, 배포와 자동 확장
* [분산 시스템](/yeons-frame/engineering/distributed-systems.md): Kafka, 재시도, 백프레셔와 서킷 브레이커
* [Kubernetes와 GitOps](/yeons-frame/engineering/kubernetes.md): ECS와 EKS 선택 기준, Argo CD, HPA와 Karpenter
* [AI 시스템](/yeons-frame/engineering/ai-systems.md): 비동기 LLM 처리, RAG, Structured Outputs와 MLOps
* [안전한 리팩터링](/yeons-frame/engineering/safe-refactoring.md): 특성화 테스트, 트래픽 동등성과 스트랭글러 마이그레이션

## 시스템을 하나의 흐름으로 보기

```mermaid
flowchart LR
    Client["클라이언트"] --> Gateway["게이트웨이"]
    Gateway --> Service["애플리케이션 서비스"]
    Service --> Store["데이터베이스 / 캐시"]
    Service --> Queue["Kafka / 작업 큐"]
    Queue --> Worker["워커"]
    Service --> External["외부 API"]
    Worker --> External
    Runtime["컨테이너 플랫폼"] --> Service
    Runtime --> Worker
    Observe["지표 / 로그 / 트레이스"] --> Runtime
    Observe --> Service
    Observe --> Worker
```

각 화살표는 단순한 연결이 아니라 타임아웃, 재시도, 소유권, 보안과 관측 기준이 필요한 경계다. 글은 이 경계를 독립적으로 설명하면서도 전체 요청 생명주기 안에서 연결한다.

## 문제에 따른 읽기 순서

| 문제                       | 시작할 글                                                                                         | 이어서 볼 글                                                                                                                                                                   |
| ------------------------ | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 서비스가 서로 강하게 결합됨          | [서비스 아키텍처](/yeons-frame/engineering/service-architecture/01-system-boundaries.md)             | [서킷 브레이커](/yeons-frame/engineering/distributed-systems/03-circuit-breaker.md), [스트랭글러 마이그레이션](/yeons-frame/engineering/safe-refactoring/03-strangler-migration.md)        |
| 외부 API 장애가 전체 요청으로 번짐    | [외부 연동 경계](/yeons-frame/engineering/service-architecture/02-external-integration-boundary.md) | [재시도와 백프레셔](/yeons-frame/engineering/distributed-systems/02-retry-and-backpressure.md), [SLO](/yeons-frame/engineering/reliability/04-slo-error-budget.md)                |
| 컨테이너는 실행되지만 요청이 실패함      | [ECS 런타임](/yeons-frame/engineering/cloud-platform/01-ecs-on-ec2-runtime.md)                   | [서비스 디스커버리](/yeons-frame/engineering/cloud-platform/02-service-discovery.md), [프라이빗 네트워크 라우팅](/yeons-frame/engineering/cloud-platform/03-private-network-routing.md)      |
| 부하에서 병목 위치가 불명확함         | [부하 테스트 전략](/yeons-frame/engineering/reliability/01-load-test-strategy.md)                    | [병목 진단](/yeons-frame/engineering/reliability/02-bottleneck-diagnosis.md), [JVM 관측](/yeons-frame/engineering/reliability/03-jvm-container-observability.md)                |
| 배포 직후 오류가 증가함            | [무중단 배포](/yeons-frame/engineering/reliability/05-zero-downtime-deployment.md)                 | [CI/CD 롤아웃](/yeons-frame/engineering/cloud-platform/04-cicd-and-rollout.md), [자동 확장 제어 루프](/yeons-frame/engineering/reliability/06-autoscaling-control-loop.md)           |
| 비동기 처리에서 유실과 중복이 걱정됨     | [Kafka 로그 파이프라인](/yeons-frame/engineering/distributed-systems/01-kafka-log-pipeline.md)       | [재시도와 백프레셔](/yeons-frame/engineering/distributed-systems/02-retry-and-backpressure.md)                                                                                    |
| Kubernetes 전환 기준이 모호함    | [ECS와 EKS 비교](/yeons-frame/engineering/kubernetes/01-ecs-vs-eks.md)                           | [Argo CD](/yeons-frame/engineering/kubernetes/02-argocd-gitops.md), [HPA와 Karpenter](/yeons-frame/engineering/kubernetes/03-hpa-and-karpenter.md)                         |
| LLM 출력을 애플리케이션이 신뢰하기 어려움 | [Structured Outputs 계약](/yeons-frame/engineering/ai-systems/03-structured-output-contract.md) | [비동기 LLM 파이프라인](/yeons-frame/engineering/ai-systems/01-async-llm-pipeline.md), [MLOps 피드백 루프](/yeons-frame/engineering/ai-systems/04-mlops-feedback-loop.md)              |
| 레거시 교체 범위가 너무 큼          | [특성화 테스트](/yeons-frame/engineering/safe-refactoring/01-characterization-tests.md)             | [트래픽 동등성](/yeons-frame/engineering/safe-refactoring/02-production-traffic-parity.md), [스트랭글러 마이그레이션](/yeons-frame/engineering/safe-refactoring/03-strangler-migration.md) |

## 공통 설계 원칙

### 경계를 먼저 정의한다

모듈 이름보다 입력, 출력, 소유자와 실패 계약을 먼저 정한다. 경계가 명확하면 구현과 인프라를 바꿔도 영향 범위를 설명할 수 있다.

### 실패를 정상 경로처럼 설계한다

타임아웃, 부분 실패, 중복과 오래된 데이터는 예외적인 사건이 아니다. 재시도 예산, 멱등성, 폴백과 운영자 복구 절차를 성공 경로와 함께 정의한다.

### 목표 상태와 실제 상태를 비교한다

배포, 자동 확장과 GitOps는 한 번 실행되는 명령이 아니라 반복되는 제어 루프다. 목표 상태, 관측 신호와 수렴 동작을 함께 본다.

### 평균보다 분포를 본다

지연 시간, 큐 대기 시간과 리소스 사용량의 평균은 꼬리 지연 특성과 포화도를 숨길 수 있다. 백분위수, 히스토그램, 오류 유형과 워크로드 형태를 함께 해석한다.

### 계약을 실행 가능하게 만든다

API 스키마, 특성화 테스트, 계약 테스트, 동등성 픽스처와 SLO는 문서만으로 남기지 않는다. 파이프라인과 런타임에서 자동으로 검증할 수 있어야 한다.

### 롤백을 변경 전에 설계한다

바이너리만 되돌리는 것으로 충분한지, 데이터와 이벤트도 이전 구현에서 읽을 수 있는지 확인한다. 되돌릴 수 없는 작업은 별도 마이그레이션과 전진 복구가 필요하다.

## 문서의 관점

각 글은 다음 질문을 반복한다.

* 어떤 경계와 상태를 다루는가?
* 정상 흐름과 실패 흐름은 어떻게 다른가?
* 어떤 지표로 동작을 관찰할 수 있는가?
* 자동화가 판단할 것과 운영자가 판단할 것은 무엇인가?
* 변경을 어떻게 검증하고 되돌릴 수 있는가?

기술 이름은 바뀌어도 이 질문은 남는다. 특정 도구의 설정값보다 시스템 동작을 설명할 수 있는 모델을 만드는 것이 목표다.