github·2026년 8월 4일·4분 읽기큐레이션 요약

거대한 AI 생성 풀 리퀘스트 하나를 검토 가능한 스택으로 바꾸기

AI 코딩 에이전트는 짧은 시간에 대규모 기능을 구현하지만, 모든 변경을 하나의 거대한 PR에 담는 방식은 리뷰 품질과 병합 속도를 떨어뜨린다. 이 글은 기능을 데이터·API·애플리케이션 연결·UI처럼 논리적 계층으로 나누고, 각 계층을 작은 PR로 쌓는 “스택드 풀 리퀘스트(stacked pull requests)”를 대안으로 제시한다. 이를 통해 에이전트의 생산성은 유지하면서도 각 변경을 독립적으로 검토하고 관리할 수 있다. ## AI가 만든 대규모 PR의 문제 - 쇼핑 어시스턴트에 상품 검색 기능을 추가하면 다음 변경이 한 PR에 함께 들어가기 쉽다. - 새 데이터 모델과 시드 데이터 - API 라우트와 입력 검증 - 클라이언트 연결 - UI 및 빈 상태·오류 상태·대체 상태 - 결과적으로 1,000~1,700줄 이상의 큰 diff가 만들어질 수 있다. - 리뷰어는 변경 내용을 한 번에 이해하기 어렵고, PR 설명이 길지만 구체적이지 않으면 검토를 뒤로 미루게 된다. - 리뷰가 늦어지면서 문맥이 사라지고 피드백 품질이 낮아지며, 충돌과 수동 동기화가 늘어난다. - 결국 기능이 충분히 검토되지 않은 채 병합될 위험이 커진다. ## 스택드 풀 리퀘스트의 기본 원리 - 하나의 대형 PR 대신 기능을 논리적으로 분해해 여러 개의 작은 PR로 만든다. - 각 PR은 하나의 관심사만 다루며, 리뷰어가 한 번에 이해할 수 있는 크기로 제한한다. - PR은 의존성 순서에 따라 연결된다. - 하위 계층이 먼저 구현되고, 상위 계층은 그 변경을 기반으로 작업한다. - 이전 계층에서 얻은 문맥은 다음 계층으로 자연스럽게 이어지므로, 전체 기능을 매번 처음부터 읽을 필요가 없다. - 데이터 담당자, 백엔드 담당자, UI 담당자처럼 변경 영역에 맞는 리뷰어를 배정할 수 있다. ## 상품 검색 기능의 스택 구조 | 계층 | 브랜치 | 작업 내용 | 의존 대상 | |---|---|---|---| | L1 | `feat/catalog-data` | 타입이 지정된 카탈로그, 시드 데이터, 검증, 데이터 접근 모듈 | `main` | | L2 | `feat/search-api` | 검증을 포함한 `/api/products/search` 엔드포인트 | L1 | | L3 | `feat/chat-grounding` | 채팅이 API를 호출하고 실제 상품 데이터에 기반해 응답 | L2 | | L4 | `feat/grounded-ui` | 상품 인용 카드와 UI 상태 처리 | L3 | - 데이터, API, 애플리케이션 연결, UX가 각각 독립된 작업 단위가 된다. - 각 계층은 자체적으로 리뷰할 수 있지만, 전체 기능은 계층 간 의존성을 통해 완성된다. - 가장 기반이 되는 작업을 스택의 아래쪽에 배치하고, 그 위에 이를 사용하는 작업을 쌓는다. ## GitHub 도구와 초기 설정 - GitHub는 PR 화면뿐 아니라 터미널에서도 스택드 PR을 관리할 수 있다. - `gh-stack` CLI 확장 설치: ```bash gh extension install github/gh-stack ``` - 코딩 에이전트가 스택 구조를 이해하고 생성·관리하도록 관련 스킬을 설치할 수 있다. ```bash gh skill install github/gh-stack ``` 또는: ```bash npx skills add github/gh-stack ``` - 스택을 시작하기 전에 스택의 기준 브랜치(stack base)를 정해야 한다. - 일반적으로 `main`이 기준이 된다. - CI 검사와 병합 규칙이 전체 스택에서 이 기준을 바탕으로 평가된다. - 모든 계층에 CI가 존재하는지 확인해야 한다. - 각 PR 계층마다 CI 검사가 실행된다. - 따라서 작은 PR이라도 테스트와 규칙 검증을 통과해야 한다. ## 에이전트별 작업 분담 - 에이전트에게 전체 기능을 한 번에 맡기기보다, 계층별로 역할과 범위를 지정한다. - 예시 구성: - L1: 데이터 모델러 에이전트 - L2: 백엔드 에이전트 - L3: 프론트엔드 에이전트 - L4: 프론트엔드 에이전트 - 각 에이전트는 하나의 작업 스트림과 엄격한 범위를 따르도록 구성한다. - 이런 방식은 에이전트가 자동화 루프에서 작업하더라도 결과물이 지나치게 커지는 것을 방지한다. - 작업 순서는 데이터 기반을 먼저 만들고, API, 채팅 연결, UI 순으로 진행한다. ## 실용적인 적용 방법 - 기능을 시작할 때 먼저 데이터·도메인 모델·API·애플리케이션 연결·UI로 나눈다. - 각 PR이 단일 관심사만 포함하는지 확인한다. - 기반 브랜치를 먼저 만들고, 각 후속 브랜치를 바로 이전 계층에서 파생한다. - 계층별로 적절한 리뷰어를 배정하고, 각 PR에 해당 계층의 목적과 검증 방법을 명확히 작성한다. - AI 에이전트에는 “전체 기능 구현”이 아니라 특정 스택 계층과 변경 범위를 명시하는 것이 좋다. - 스택드 PR은 리뷰 부담을 줄이는 대신 브랜치 의존성을 관리해야 하므로, CLI와 자동화 도구를 함께 사용하는 것이 효과적이다.

원문 읽기(새 탭에서 열림)

API 설계CI/CDgithubcoding-agents+2

toss·2026년 8월 3일·4분 읽기큐레이션 요약

DS와 MLE가 함께 일하는 법

토스뱅크는 DS와 MLE 사이의 역할 경계를 사람이나 파일이 아닌 명시적인 인터페이스로 정의하면서 ML 모델 배포 협업을 개선했습니다. 노트북 전달 방식에서 `.py` 파일 공유를 거쳐, 전처리·추론·후처리를 구현한 모델 패키지를 `pip install`로 배포하는 구조로 발전했습니다. 여기에 모노레포, 공통 추상화, CI, AI 코딩 스타일 규칙을 결합해 배포 속도와 일관성을 높였습니다. ## 노트북 전달 방식의 한계 - Phase 0에서는 DS가 주피터 노트북에서 학습과 추론 코드를 모두 작성하고, MLE가 이를 바탕으로 서빙 코드를 처음부터 다시 작성했습니다. - 라이브러리, 설정 파일, 소스 코드가 흩어져 있어 실행 환경을 재현하기 어려웠습니다. - 노트북에서 동작하던 전처리나 설정을 MLE가 다르게 해석하는 문제가 발생했습니다. - 모델 수가 늘어날수록 파일 요청과 커뮤니케이션 비용이 크게 증가했습니다. - 역할의 경계가 코드가 아니라 사람 사이에 있었기 때문에 책임과 작업 범위가 불명확했습니다. ## `.py` 파일로 추론 로직 분리 - Phase 1에서는 DS가 노트북에서 핵심 추론 로직을 별도의 `.py` 파일로 분리했습니다. - 노트북은 학습과 실험에 집중하고, 실제 모델 로직은 코드 파일로 관리했습니다. - MLE 리뷰와 CI 검증을 거치도록 하면서 DS의 의도를 더 정확히 보존할 수 있었습니다. - 그러나 모델마다 함수 이름이 `predict()`, `run()`, `inference()` 등으로 달라 인터페이스가 통일되지 않았습니다. - 서빙 환경으로 코드를 옮길 때 환경 차이로 수정이 필요했고, 로깅·메트릭·에러 처리를 공통으로 적용하기도 어려웠습니다. - 노트북에서 전역 설정을 변경한 코드가 여러 모델이 실행되는 서빙 프로세스에 영향을 주는 문제도 있었습니다. ## 인터페이스를 통한 역할 분리 - Phase 2에서는 `commons-ml-model` 패키지에 모델의 표준 구조를 정의했습니다. - 추상화 클래스가 다음 세 가지 인터페이스를 제공합니다. - `pre_process`: 입력 데이터 전처리 - `inference`: 모델 추론 - `post_process`: 결과 후처리 - DS는 위 메서드의 구현체를 작성하고 모델을 하나의 패키지로 배포합니다. - MLE는 해당 패키지를 설치해 서비스에 연결하므로 코드를 직접 복사하거나 재작성하지 않습니다. - 추상화 클래스가 추론 전후에 공통으로 다음 기능을 처리합니다. - 요청 추적을 위한 `trace_id` - 추론 시작·완료 로그 - 실행 시간 측정 - 메트릭 기록 - 결과적으로 DS는 모델 동작에 집중하고, MLE는 서비스 인프라와 운영 기능을 담당하게 됐습니다. - 공통 관측 기능을 추상화 클래스 한 곳에서 수정하면 모든 모델에 일괄 적용할 수 있습니다. ## 모노레포와 `uv` 워크스페이스 - 여러 모델 패키지와 공통 추상화 패키지를 하나의 저장소에서 관리했습니다. - `uv` 워크스페이스를 사용해 DS와 MLE가 같은 코드베이스에서 작업하고 리뷰할 수 있도록 했습니다. - 공통 인터페이스 변경과 모델 패키지 수정이 하나의 PR에서 함께 이뤄졌습니다. - CI, 버전 관리, 배포 정책을 저장소 단위로 통일할 수 있었습니다. - 공통 패키지 변경이 모든 모델에 영향을 줄 수 있다는 위험도 존재합니다. - 모델과 패키지가 늘면서 빌드가 느려졌고, Poetry에서 `uv`로 전환해 빌드 속도를 약 3~5배 개선했습니다. ## AI 시대의 코드 스타일 통일 - AI가 코드를 작성하면서 같은 기능도 예외 처리, 네이밍, enum 사용 방식 등이 사람마다 달라지는 문제가 생겼습니다. - 인터페이스가 같더라도 코드의 세부적인 작성 방식이 달라 리뷰 비용이 증가했습니다. - 팀 규칙 모음인 `pfmls-stylepack`을 도입해 AI가 코드 작성 단계부터 팀 컨벤션을 따르도록 했습니다. - Hook을 활용해 네이밍, 예외 처리, 고정값과 enum 사용 기준 등을 자동 적용했습니다. - 규칙이 적용된 코드에는 그 이유를 표시해 리뷰어가 변경 의도를 쉽게 파악하도록 했습니다. - 협업 표준을 두 층위로 나눴습니다. - 구조 표준화: 인터페이스로 담당 범위와 코드 형태 통일 - 스타일 표준화: 컨벤션으로 구현 방식과 코드 결 통일 ## 도입 과정에서 얻은 교훈 - 인터페이스는 너무 엄격하면 DS의 모델별 커스터마이징을 막고, 너무 느슨하면 다시 구현 방식이 제각각이 될 수 있습니다. - 초기에는 가이드 문서를 제공하고 DS와 MLE가 첫 모델을 페어로 함께 만드는 방식이 효과적입니다. - 공통 라이브러리는 한 번의 수정으로 전체 모델에 개선을 적용할 수 있지만, 반대로 전체 모델에 장애를 전파할 수도 있습니다. - 기존 모델 패키지를 참고 코드로 제공하면 새로운 구성원의 러닝 커브를 줄일 수 있습니다. - AI 활용이 늘어날수록 기능의 책임뿐 아니라 코드 작성 방식까지 명시적으로 관리해야 합니다. 실무적으로는 모델 배포 과정에서 “누가 무엇을 한다”를 문서로만 정의하기보다, 추상화 클래스와 패키지 구조로 강제하는 것이 효과적입니다. 먼저 전처리·추론·후처리 같은 최소 인터페이스를 정하고, 공통 로깅·메트릭·CI를 그 바깥에 배치하는 방식부터 시작하는 것을 추천합니다.

원문 읽기(새 탭에서 열림)

API 설계머신러닝CI/CDPython+4

discord·2026년 6월 30일·3분 읽기큐레이션 요약

Discord API의 비용 귀속

Discord의 API는 1,700개 이상의 엔드포인트와 약 700개의 백그라운드 작업을 포함한 단일 Python 코드베이스로 운영되며, 수백 개의 Kubernetes 배포에 단계적으로 배포된다. 기존 모니터링은 지연 시간·처리량·오류율은 보여주지만, 메시지 전송이나 스트리밍 같은 제품 기능별 호스팅 비용은 충분히 설명하지 못했다. Discord는 배포 구조를 변경하지 않고 애플리케이션 프로파일링 도구를 확장해, 각 기능의 코드 실행 시간에 따라 배포 비용을 배분하는 방식을 도입했다. ### 대규모 단일 API 코드베이스의 운영 - Discord API는 하나의 Python 코드베이스로 구성되어 있다. - 1,700개 이상의 API 엔드포인트와 약 700개의 백그라운드 작업을 포함한다. - 엔지니어들은 매일 공통 코드에 변경을 가한다. - 변경 사항은 수백 개의 Kubernetes 배포 환경에 단계적 롤아웃 방식으로 지속 배포된다. - 규모가 크고 변경 빈도가 높기 때문에, 매일 발생하는 변화가 사용자나 시스템에 미치는 영향을 추적하기 어렵다. ### 기존 관측성의 범위 - Discord는 다음과 같은 운영 지표를 이미 수집하고 있었다. - 지연 시간 - 처리량 - 오류율 - 이러한 지표는 성능 저하나 오류 증가 같은 회귀(regression)를 감지하는 데 유용하다. - 그러나 특정 제품 기능이 전체 호스팅 비용에서 차지하는 비중은 파악하기 어려웠다. - 예를 들어 다음과 같은 질문에 답하기 어려웠다. - 메시지 송수신 API 운영 비용은 얼마인가? - 스트림 시작 기능에는 얼마가 드는가? - Nitro 선물 전송 비용은 얼마인가? - 특정 코드 변경이 팀의 호스팅 비용을 얼마나 변화시켰는가? ### Kubernetes 배포 단위만으로는 부족한 비용 추적 - 클라우드 제공업체는 일반적으로 Kubernetes 배포별 비용 분류를 제공한다. - 하지만 Discord의 모든 배포에는 동일한 API 코드베이스가 배포된다. - 각 배포는 특정 HTTP 트래픽이나 백그라운드 작업의 일부를 처리하지만, 제품 기능 단위로 깔끔하게 분리되어 있지는 않다. - 비용 추적을 위해 배포를 기능별로 더 세분화하면 운영 복잡성이 지나치게 커진다. - 따라서 기존 배포 토폴로지를 변경하지 않고 비용을 추적할 방법이 필요했다. ### 동시 실행 환경에서의 비용 배분 - 하나의 API 워커 프로세스는 여러 작업을 동시에 처리한다. - 같은 시점에 여러 제품 기능과 관련된 코드를 실행할 수 있다. - 일부 트래픽은 특정 배포로 격리되어 있지만, 기능별 비용 분석에 충분할 정도로 분리된 것은 아니다. - 따라서 단순히 배포 단위의 비용을 특정 기능에 모두 할당할 수 없다. - 정확한 비용 배분을 위해서는 각 배포가 특정 기능의 코드 실행에 얼마나 많은 시간을 사용했는지 측정해야 한다. ### 프로파일링을 활용한 해결책 - Discord는 기존 애플리케이션 프로파일링 도구를 확장했다. - 각 기능과 관련된 코드가 실행된 시간을 측정하고, 이를 기반으로 배포 비용을 배분한다. - 이를 통해 배포 구조를 바꾸지 않고도 다음 단위의 비용을 추정할 수 있다. - 개별 API 엔드포인트 - 여러 엔드포인트로 구성된 제품 기능 - 글에 제시되는 수치와 코드는 실제 운영값이 아닌 설명을 위한 예시다. ### 실용적인 결론 기능별 인프라 비용을 파악하려면 서비스를 물리적으로 기능별 배포로 나누기보다, 공통 실행 환경에서 각 기능이 소비한 컴퓨팅 시간과 리소스를 측정해 비용을 배분하는 방식이 효과적이다. 특히 대규모 단일 코드베이스에서는 기존 관측성에 비용 귀속 정보를 결합하는 것이 운영 구조를 복잡하게 만들지 않는 현실적인 접근이다.

원문 읽기(새 탭에서 열림)

API 설계쿠버네티스옵저버빌리티Python+2

cloudflare·2026년 4월 17일원문

기억하는 에이전트: 에이전트 메모리를 소개합니다 (새 탭에서 열림)

AI 에이전트가 방대한 컨텍스트 윈도우를 사용할 때 발생하는 정보 과부하와 품질 저하(Context Rot) 문제를 해결하기 위해, Cloudflare는 관리형 영구 기억 서비스인 'Agent Memory'를 출시했습니다. 이 서비스는 대화 내용에서 핵심 정보를 자동으로 추출하고 필요할 때만 검색하여 제공함으로써, 컨텍스트를 채우지 않고도 에이전트가 과거의 경험을 기억하고 시간이 지남에 따라 더 똑똑해지도록 돕습니다. 이를 통해 개발자는 긴 시간 동안 실행되는 복잡한 워크로드에서도 비용 효율적이고 고성능인 추론 환경을 구축할 수 있습니다. ### 기존 에이전트 메모리의 한계와 차별점 * **컨텍스트 부패(Context Rot) 해결**: 컨텍스트 윈도우가 100만 토큰 이상으로 커져도 정보를 모두 담으면 모델의 추론 품질이 떨어지고, 반대로 정보를 삭제하면 나중에 필요한 데이터를 잃게 되는 딜레마를 해결합니다. * **검색 기반 아키텍처**: 에이전트에게 파일 시스템에 대한 직접적인 접근 권한을 주는 대신, 최적화된 API를 통한 검색 기반 방식을 채택하여 보안과 성능을 높였습니다. * **복잡한 추론 지원**: 단순 저장을 넘어 시간 논리(temporal logic), 정보의 최신성 유지(supersession), 지시 사항 준수와 같은 운영 환경의 복잡한 요구사항을 처리할 수 있는 토대를 제공합니다. ### 주요 기능 및 API 동작 방식 * **프로필(Profile) 단위 관리**: 메모리는 '프로필'이라는 독립된 저장소에 이름별로 관리되며, 여러 세션이나 사용자, 에이전트 간에 공유될 수 있습니다. * **핵심 오퍼레이션**: * **Ingest**: 대화 이력을 분석하여 중요한 정보를 추출합니다. 보통 컨텍스트를 압축해야 하는 시점에 호출됩니다. * **Remember**: 에이전트가 도구 사용(Tool Use)을 통해 특정 사실을 즉시 명시적으로 저장합니다. * **Recall**: 전체 메모리 파이프라인을 실행하여 질문에 최적화된 합성된 답변(Synthesized answer)을 반환합니다. * **유연한 연결성**: Cloudflare Workers 내에서 직접 바인딩하여 사용하거나, REST API를 통해 외부 프레임워크(Claude Code, Anthropic Managed Agents 등)와 연동할 수 있습니다. ### 활용 가능한 에이전트 아키텍처 * **개별 및 자율 에이전트**: 코딩 에이전트나 백그라운드에서 실행되는 자율형 에이전트가 세션 재시작 후에도 이전 작업 내용을 기억하도록 구현할 수 있습니다. * **에이전트 간 지식 공유**: 팀 단위로 메모리 프로필을 공유하여, 한 엔지니어의 코딩 에이전트가 학습한 코딩 컨벤션이나 아키텍처 결정 사항을 팀 내 다른 에이전트와 도구가 즉시 활용하게 할 수 있습니다. * **비용 및 성능 최적화**: 모든 데이터를 컨텍스트에 넣는 대신 필요한 정보만 호출함으로써 추론당 비용을 낮추고 응답 속도를 향상시킵니다. Agent Memory는 단순한 데이터 저장을 넘어 에이전트가 장기적으로 학습하고 협업할 수 있는 기반을 제공합니다. 특히 긴 호흡의 프로젝트를 수행하거나 복잡한 운영 업무를 자동화하려는 개발자들에게 컨텍스트 관리 부담을 줄여주는 실용적인 해결책이 될 것입니다.

API 설계ReactTypeScriptCloudflare Workers+3

cloudflare·2026년 4월 14일원문

MCP 도입 확대: 더 단순하고 안전하며 비용 효율적인 기업용 MCP 배포를 위한 참조 아키텍처 (새 탭에서 열림)

Cloudflare는 기업 전반에 걸친 모델 컨텍스트 프로토콜(MCP) 도입을 안전하고 효율적으로 확장하기 위해, 자사의 보안 플랫폼(Cloudflare One)과 개발자 플랫폼을 결합한 참조 아키텍처를 구축했습니다. 이 아키텍처는 로컬 MCP 서버의 보안 취약성을 해결하기 위해 중앙 집중식 원격 MCP 서버 모델을 채택하고, 인증 및 데이터 유출 방지(DLP) 기능을 통합하여 거버넌스를 강화했습니다. 이를 통해 기업은 권한 확산이나 프롬프트 인젝션과 같은 위험을 관리하는 동시에, 토큰 비용을 절감하고 생산성을 높이는 에이전트 워크플로우를 구현할 수 있습니다. **원격 MCP 서버를 통한 가시성과 제어권 확보** - 로컬에서 호스팅되는 MCP 서버는 검증되지 않은 소프트웨어 사용과 공급망 공격의 위험이 크며, IT 관리자의 중앙 통제가 불가능하다는 단점이 있습니다. - Cloudflare는 사내 모노레포(Monorepo) 내에 중앙 관리형 MCP 플랫폼을 구축하여, 직원이 템플릿을 통해 승인된 인프라 위에서 원격 MCP 서버를 신속하게 배포할 수 있도록 지원합니다. - 모든 원격 MCP 서버는 Cloudflare의 글로벌 네트워크를 통해 배포되므로 전 세계 어디서든 낮은 지연 시간으로 접근이 가능하며, 관리자는 모든 사용 내역에 대한 가시성을 가집니다. **Cloudflare Access 기반의 강력한 인증** - 내부 자산에 접근하는 MCP 서버를 보호하기 위해 Cloudflare Access를 OAuth 제공자로 통합하여 권한이 부여된 직원만 접근할 수 있도록 제한합니다. - 단일 로그인(SSO), 다요소 인증(MFA)뿐만 아니라 IP 주소, 위치, 기기 인증서와 같은 컨텍스트 기반의 속성을 검증하여 보안 수준을 높입니다. - 공개된 리소스(문서, 레이더 등)와 내부 프라이빗 리소스에 대한 접근 권한을 명확히 분리하여 운영합니다. **MCP 서버 포털을 통한 중앙 집중식 거버넌스** - 직원이 사용 가능한 모든 MCP 서버를 쉽게 찾을 수 있도록 'MCP 서버 포털'을 제공하여 검색성(Discovery) 문제를 해결합니다. - 포털 내에서 중앙 집중식 로깅과 데이터 유출 방지(DLP) 규칙을 적용하여 개인정보(PII) 등의 민감 데이터가 외부로 유출되는 것을 차단합니다. - 사용자 역할에 따라 도구 노출 범위를 다르게 설정하는 정책을 시행할 수 있습니다. (예: 재무팀은 읽기 전용 도구만, 엔지니어링팀은 읽기/쓰기 도구 모두 노출) **비용 절감과 보안 감지 기술** - 모든 API 엔드포인트를 개별 도구로 정의할 때 발생하는 토큰 비용 문제를 해결하기 위해, 에이전트가 코드를 생성하여 API와 상호작용하는 '코드 모드(Code Mode)'를 도입하여 컨텍스트 창 최적화를 달성했습니다. - Cloudflare Gateway를 활용한 '섀도우 MCP(Shadow MCP)' 감지 기능을 통해 조직 내에서 승인되지 않은 원격 MCP 서버가 사용되는 것을 식별하고 통제합니다. - 포털, 원격 서버, 인증 시스템이 모두 Cloudflare의 동일한 물리적 네트워크 노드 내에서 작동하므로 보안 검사 과정에서 발생하는 네트워크 지연을 최소화합니다. 기업이 MCP를 성공적으로 도입하려면 개별 사용자의 로컬 실행에 의존하기보다는, 인증과 거버넌스가 결합된 중앙 관리형 원격 아키텍처를 구축하는 것이 필수적입니다. 이를 통해 보안 리스크를 관리하는 동시에 AI 에이전트 운영에 드는 비용 효율성까지 확보할 수 있습니다.

API 설계CI/CD모델 컨텍스트 프로토콜cloudflare+4

cloudflare·2026년 3월 24일원문

AI 에이전트 샌드박싱, 100배 더 빠르게 (새 탭에서 열림)

Cloudflare는 AI 에이전트가 생성한 코드를 안전하고 신속하게 실행할 수 있는 'Dynamic Worker Loader' API를 공개했습니다. 이 기술은 기존 컨테이너 방식보다 100배 빠른 실행 속도와 뛰어난 메모리 효율성을 제공하여, 수백만 명의 사용자를 대상으로 하는 대규모 AI 에이전트 서비스의 보안 및 성능 문제를 해결합니다. 개발자는 이를 통해 AI가 작성한 코드를 독립된 V8 Isolate 환경에서 즉시 실행하고, TypeScript 인터페이스를 통해 효율적으로 도구(Tool)를 연동할 수 있습니다. ### 기존 컨테이너 기반 샌드박스의 한계 * AI가 생성한 코드를 직접 실행(eval)하는 것은 보안상 매우 위험하므로 격리된 샌드박스 환경이 필수적입니다. * 기존의 리눅스 기반 컨테이너 샌드박스는 부팅에 수백 밀리초(ms)가 소요되고 수백 메가바이트(MB)의 메모리를 점유하여 비용이 많이 듭니다. * 지연 시간을 줄이기 위해 컨테이너를 미리 띄워두는 방식은 자원 낭비가 심하며, 컨테이너를 재사용할 경우 보안성이 취약해지는 딜레마가 있습니다. ### V8 Isolate 기반의 'Dynamic Worker Loader' * Cloudflare는 구글 크롬에서 사용하는 V8 엔진의 격리 기술인 'Isolate'를 활용해 런타임에 워커를 즉시 생성하는 API를 제공합니다. * Isolate 기술은 실행에 단 몇 밀리초만 소요되며 수 메가바이트의 메모리만 사용하므로, 컨테이너 대비 속도는 100배 빠르고 메모리 효율은 10~100배 더 뛰어납니다. * 모든 유료 워커 사용자는 이 API를 통해 요청마다 독립된 샌드박스를 생성하고, 실행이 끝나면 즉시 폐기하는 방식을 비용 효율적으로 구현할 수 있습니다. ### 무한한 확장성과 제로 레이턴시 * 동적 워커 로더는 전역 동시 실행 수나 생성 속도에 제한이 없어, 초당 수백만 건의 요청이 발생하는 대규모 트래픽도 안정적으로 처리할 수 있습니다. * 샌드박스가 코드를 호출한 워커와 동일한 머신 혹은 동일한 스레드 내에서 실행되므로, 전 세계 어느 지역에서든 네트워크 지연 없이 즉각적인 코드 실행이 가능합니다. * 특정 API에 대한 접근 권한을 부여하거나 외부 인터넷 접속을 차단하는 등 세밀한 보안 제어가 가능합니다. ### AI 친화적인 TypeScript 도구 정의 * AI 에이전트는 이미 자바스크립트와 타입스크립트에 능숙하며, 이러한 언어들은 태생적으로 웹 샌드박스 환경에 최적화되어 있습니다. * 장황한 OpenAPI 명세 대신 간결한 TypeScript 인터페이스를 사용하여 에이전트에게 API 도구를 설명함으로써 토큰 사용량을 80% 이상 절감할 수 있습니다. * `env.LOADER.load()` 함수를 통해 생성된 워커에 RPC(Remote Procedure Call) 스텁을 전달하여 에이전트가 안전하게 외부 기능을 호출하도록 설계되었습니다. 대규모 AI 에이전트 서비스를 구축하려는 개발자에게 Cloudflare의 Dynamic Worker Loader는 최적의 선택지입니다. 기존의 무거운 컨테이너 방식에서 벗어나 V8 Isolate 기반의 가벼운 샌드박스를 채택하고, 도구 정의를 TypeScript로 전환함으로써 성능 최적화와 비용 절감을 동시에 달성할 수 있습니다.

API 설계대규모 언어 모델TypeScriptJavaScript+4

line·2026년 3월 20일원문

기획서 없이 내재화하기: 검증 로직으로 동일함을 증명하다 (새 탭에서 열림)

사양서나 소스 코드를 참조할 수 없는 블랙박스 상태의 레거시 시스템을 내재화하기 위해, Kafka 생태계를 활용한 자동화된 검증 파이프라인을 구축하여 시스템의 동일성을 증명했습니다. 데이터 발생부터 분석까지 이어지는 검증 루프를 통해 불일치 건수를 0으로 수렴시키는 과정을 거쳤으며, 결과적으로 대규모 커머스 데이터를 안전하고 정밀하게 신규 시스템으로 이관할 수 있었습니다. **통합 커머스 검색의 도메인 구조** * **상품과 카탈로그**: 판매자가 등록한 개별 '상품'들을 동일 모델별로 묶어 최적의 정보를 제공하는 상위 객체인 '카탈로그'로 관리하며, 이는 최저가 산출 및 객단가 지표 제공의 핵심이 됩니다. * **수신 파이프라인**: 대규모 상품 데이터를 내부 표준 형식으로 변환하고 정합성을 검사하여 상품 및 카탈로그 정보에 반영하는 거대 파이프라인으로, 서비스 전체에 막대한 영향력을 미칩니다. **무중단 검증 루프의 설계** * **검증 파이프라인 아키텍처**: 트리거(DB 변경/이벤트) → 실행 및 비교(양쪽 시스템에 동일 입력 주입) → 가공 및 적재(불일치 데이터 저장) → 분석 및 개선(오류 패턴 수정)으로 이어지는 유기적인 루프를 생성했습니다. * **입력과 출력의 정의**: 동일한 ID나 스냅숏을 입력값으로 설정하고, API 응답이나 DB 업데이트 결과를 출력값으로 명확히 정의함으로써 내부 로직이 복잡하더라도 통계적으로 동일함을 증명할 수 있는 환경을 만들었습니다. **조회 로직 검증과 블랙박스 분석** * **CDC와 Kafka 기반 비교**: DB의 바이너리 로그를 실시간 스트리밍하는 CDC(Change Data Capture)를 트리거로 사용하고, Kafka를 통해 검증 로직을 물리적으로 격리하여 서비스 성능에 영향을 주지 않으면서 기존/신규 API 응답을 1:1로 대조했습니다. * **재귀적 필드 비교 및 정렬**: 100개가 넘는 API 응답 필드를 `Map<String, Object>` 구조로 변환해 재귀적으로 탐색했으며, 리스트 내 순서 차이로 인한 노이즈를 제거하기 위해 문자열 정렬 후 2차 비교를 수행하는 유연한 로직을 도입했습니다. * **가시성 확보 및 최적화**: ksqlDB를 활용해 실시간으로 이상 징후를 Slack으로 알리고 OpenSearch로 상세 로그를 분석했으며, 처리율 제한(Rate Limit)을 적용해 동일 패턴의 중복 오류가 분석을 방해하지 않도록 제어했습니다. **상태 변화를 다루는 업데이트 로직 검증** * **실시간 시뮬레이션**: 카탈로그 통계 업데이트 시 CDC 이벤트가 발생하면 검증 모듈이 신규 로직으로 예상 결과값을 즉시 산출하고, 이를 기존 로직이 업데이트한 DB의 실제값과 대조하는 시뮬레이션 방식을 채택했습니다. * **비동기 지연 및 트리거 누락 해결**: 비동기 환경의 시차 문제는 'N회차 재시도 큐' 전략으로 해결하고, 특정 필드 변경 시에만 검증이 작동하도록 필터링하여 리소스를 최적화했습니다. 또한 ETL 배치 검증을 병행하여 실시간 스트림에서 놓칠 수 있는 트리거 누락 결함까지 포착했습니다. **성공적인 시스템 전환을 위한 제언** 복잡한 시스템의 내재화는 단순히 코드를 옮기는 것이 아니라 '기존과 동일하게 작동함'을 객관적으로 입증하는 과정입니다. 데이터 스트림 기반의 자동화된 검증 체계를 구축하면 블랙박스 로직의 베일을 하나씩 벗겨낼 수 있을 뿐만 아니라, 실시간 트래픽 환경에서의 성능 비교 지표까지 확보하여 안정성과 성능이라는 두 마리 토끼를 모두 잡을 수 있습니다.

API 설계데이터베이스 설계PostgreSQLApache Kafka+4

line·2026년 3월 17일원문

LINE 앱의 다자간 대화 기능 통합 (새 탭에서 열림)

LINE은 서로 다른 용도로 운영되던 '여러 명과의 대화'와 '그룹' 기능을 '그룹 대화'라는 단일 모델로 통합하여 사용자 경험을 개선하고 시스템 리소스를 효율화했습니다. 기존의 이원화된 구조에서 발생하던 기능 제한과 중복 대화방 생성 문제를 해결하기 위해 통합 API 설계 및 점진적인 데이터 마이그레이션을 수행했습니다. 이를 통해 사용자는 생성 방식에 관계없이 모든 기능을 동일하게 사용할 수 있게 되었으며, 중복 방 생성 비율을 획기적으로 낮추는 기술적 성과를 거두었습니다. ### 이원화된 대화 모델의 한계 * **여러 명과의 대화(Room):** 별도의 승인 없이 즉시 대화가 가능하지만, 일시적 목적으로 설계되어 앨범이나 노트 같은 그룹 전용 기능을 사용할 수 없었습니다. * **그룹(Group):** 초대 승인 절차가 필요한 대신 장기적인 소통에 적합한 다양한 편의 기능을 제공했으나, 초기 진입 장벽이 존재했습니다. * **사용자 혼란 및 리소스 낭비:** 사용자들이 두 모델의 차이를 이해하지 못해 기능이 제한된 방을 잘못 만들거나, 동일한 구성원의 대화방을 중복으로 생성하여 서버와 클라이언트의 리소스가 불필요하게 소모되었습니다. ### 그룹 대화로의 기술적 마이그레이션 * **점진적 API 전환:** 새로운 그룹 대화 API를 설계한 후, '이중 읽기(Dual Read)' 방식을 도입하여 이전 API와의 호환성을 유지하며 단계적으로 전환을 진행했습니다. * **데이터 배치 처리:** 기존의 모든 그룹 데이터를 배치 처리를 통해 신규 모델로 이관하였으며, 안정성이 확인된 후 이중 읽기를 중단하고 그룹 대화 시스템으로 단일화했습니다. * **통합 모델 확립:** 그룹 모델의 아키텍처를 기반으로 여러 명과의 대화 모델을 흡수하여, 향후 추가될 모든 신규 기능이 모든 대화방에 동일하게 적용되도록 구조를 개선했습니다. ### 사용자 경험 최적화 및 운영 성과 * **초대 메커니즘 단일화:** 대화방 생성 UI를 통합하여 '즉시 참여'와 '수락 후 참여' 여부를 사용자가 상황에 맞게 직접 선택할 수 있도록 개선했습니다. * **중복 생성 방지 힌트:** 동일한 구성원으로 새로운 방을 만들려 할 때 기존 대화방을 안내하는 '힌트' 기능을 제공하여 불필요한 대화 목록 생성을 방지했습니다. * **정량적 성과:** 프로젝트 결과, 동일 구성원으로 중복 생성되는 대화방 비율이 기존 15%에서 0.78%로 급감하며 데이터 관리 효율성이 크게 향상되었습니다. 대규모 서비스에서 유사한 기능을 통합할 때는 사용자에게 갑작스러운 변화를 강요하기보다, 점진적인 API 전환과 기능적 일원화를 통해 자연스러운 이동을 유도하는 것이 중요합니다. 이번 통합 사례는 시스템의 복잡성을 줄이면서도 데이터 일관성과 사용자 편의성을 동시에 확보할 수 있는 구체적인 마이그레이션 전략을 보여줍니다.

API 설계사용자 경험real-time-communicationdata-migration+2

meta·2026년 3월 13일원문

패치 미 이프 유 캔: 기본부터 안전한 안드로이드 앱을 위한 AI 코드모드 (새 탭에서 열림)

Meta는 수백만 줄의 코드와 수천 명의 엔지니어가 얽혀 있는 대규모 환경에서 모바일 보안 취약점을 효율적으로 해결하기 위해 '기본 보안 기반(Secure-by-default)' 프레임워크와 생성형 AI를 결합한 전략을 채택했습니다. 잠재적으로 위험할 수 있는 Android OS API를 안전한 프레임워크로 감싸 개발자가 자연스럽게 보안 경로를 선택하게 유도하고, 기존의 방대한 레거시 코드는 AI를 통해 자동으로 마이그레이션하는 것이 핵심입니다. 이 시스템을 통해 Meta는 엔지니어의 개입을 최소화하면서도 수십억 명의 사용자를 보호할 수 있는 대규모 보안 패치를 성공적으로 수행하고 있습니다. ### 대규모 모바일 환경의 보안 한계와 과제 * 수백만 줄의 코드와 수천 명의 엔지니어가 협업하는 환경에서는 단순한 API 업데이트조차 막대한 리소스가 소요되는 작업이 됩니다. * 특히 모바일 보안의 경우, 특정 유형의 취약점이 수많은 앱 코드 곳곳에 반복적으로 나타나기 때문에 이를 수동으로 일일이 수정하는 것은 불가능에 가깝습니다. * 빌리언(Billion) 단위의 사용자를 보유한 다수의 앱을 운영하면서 일관된 보안 수준을 유지하는 것이 가장 큰 엔지니어링 도전 과제입니다. ### '기본 보안 기반(Secure-by-default)' 프레임워크 구축 * 취약할 가능성이 있는 Android OS API를 직접 사용하는 대신, 보안 기능이 내장된 래퍼(Wrapper) 프레임워크를 설계했습니다. * 개발자가 보안 지식이 부족하더라도 가장 쉽고 직관적으로 사용할 수 있는 구현 방식이 곧 가장 안전한 경로가 되도록 인터페이스를 최적화했습니다. * 프레임워크 수준에서 보안을 강제함으로써 개발 단계에서 발생할 수 있는 보안 실수를 원천적으로 차단합니다. ### 생성형 AI를 통한 대규모 코드 마이그레이션 자동화 * 새로운 보안 프레임워크를 도입하더라도 기존의 방대한 레거시 코드를 전환하는 데 따르는 비용을 절감하기 위해 생성형 AI 기술을 활용합니다. * AI가 기존 코드를 분석하여 보안 패치를 자동으로 제안하고, 이를 검증하여 실제 코드베이스에 적용하는 워크플로우를 구축했습니다. * 이를 통해 코드 소유자인 엔지니어의 업무 부담을 최소화하면서도 전체 시스템의 보안 기술 부채를 빠르게 해소할 수 있게 되었습니다. 대규모 서비스를 운영하는 기업이라면 보안 문제를 개별 개발자의 주의력에 맡기기보다, 프레임워크를 통해 '보안이 쉬운 환경'을 만들고 생성형 AI로 전환 비용을 낮추는 Meta의 전략을 참고할 수 있습니다. 특히 자동화된 보안 패치 시스템은 대규모 인프라를 관리하는 보안 팀에게 강력한 효율성을 제공할 것입니다.

API 설계생성형 AI자동화mobile-security+3

datadog·2026년 3월 4일원문

에이전트를 위한 MCP 도구 설계: Datadog의 MCP 서버 구축을 통해 배운 교훈 (새 탭에서 열림)

AI 에이전트를 위한 관측성(Observability) 인터페이스 구축 시, 단순히 기존 API를 그대로 노출하는 방식은 컨텍스트 창의 한계와 비용 문제로 인해 한계가 명확합니다. Datadog은 MCP(Model Context Protocol) 서버를 구축하며 데이터 포맷 최적화, SQL 기반 쿼리 도입, 도구의 효율적 관리라는 세 가지 핵심 설계를 통해 에이전트의 작업 효율을 극대화했습니다. 결과적으로 이러한 설계 변경은 에이전트의 추론 정확도를 높이는 동시에 토큰 사용량을 줄여 운영 비용을 절감하는 효과를 가져왔습니다. ### 컨텍스트 창 효율성 극대화 * **데이터 포맷 최적화**: JSON은 프로그래밍 방식에는 적합하지만 토큰 소모가 큽니다. 평면적인 데이터에는 CSV(토큰 약 50% 절감)를, 계층 구조가 있는 데이터에는 YAML(약 20% 절감)을 사용하여 동일한 컨텍스트 내에 더 많은 정보를 담았습니다. * **필드 트리밍**: 에이전트에게 불필요한 필드를 기본 출력에서 제거하고 필요한 경우에만 요청하게 함으로써, 동일한 토큰 예산 내에서 레코드 수용량을 최대 5배까지 늘렸습니다. * **토큰 기반 페이지네이션**: 레코드 개수 단위로 데이터를 끊어 보내는 전통적인 방식 대신, 실제 소비되는 토큰량을 기준으로 응답을 제한하여 에이전트의 컨텍스트 창이 예기치 않게 가득 차는 문제를 방지했습니다. ### 단순 조회를 넘어선 SQL 기반 쿼리 도입 * **서버 측 집계**: 에이전트가 수천 개의 로그를 직접 내려받아 트렌드를 분석하는 대신, 서버에서 SQL을 실행하여 요약된 결과만 받도록 개선했습니다. * **비용 및 성능 개선**: SQL을 통해 꼭 필요한 필드만 선택(SELECT)하고 행을 제한(LIMIT)함으로써, 평가 시나리오에서 실행 비용을 약 40% 절감하고 정답률을 높였습니다. * **에이전트 적응력**: AI 에이전트는 SQL 작성에 매우 능숙하며, 이를 통해 컨텍스트 윈도우에 들어갈 데이터를 스스로 세밀하게 제어할 수 있게 되었습니다. ### 도구 비대화 방지 및 관리 전략 * **유연한 도구 설계**: 개별 API 엔드포인트마다 도구를 만드는 대신, 하나의 도구가 여러 유즈케이스를 처리할 수 있도록 스키마를 범용적으로 설계하여 도구의 총 개수를 줄였습니다. * **도구 세트(Toolsets) 분리**: 모든 도구를 한꺼번에 노출하지 않고, 핵심 도구와 특정 워크플로우를 위한 선택적 도구 세트를 구분하여 에이전트의 혼란을 방지하고 컨텍스트 소모를 최소화했습니다. * **도구 계층화**: "어떻게 작업을 수행할지"를 묻는 도구와 실제 동작 도구를 분리하여 검색 효율을 높였습니다. 다만, 이 방식은 레이턴시 증가라는 기회비용이 발생하므로 신중한 적용이 필요합니다. AI 에이전트를 위한 도구를 설계할 때는 인간 사용자를 위한 API 설계와는 다른 접근이 필요합니다. 에이전트가 데이터를 직접 처리하게 두기보다, 서버 측에서 데이터를 가공하고 요약할 수 있는 강력한 쿼리 기능을 제공하고 전송 포맷을 최적화하는 것이 성능과 비용 측면에서 모두 유리합니다.

API 설계데이터베이스 설계datadog옵저버빌리티+4

cloudflare·2026년 2월 27일원문

립트에는 더 나 (새 탭에서 열림)

현재의 WHATWG 스트림 표준(Web Streams)은 설계된 지 10년이 지나 현대적인 JavaScript 개발 방식과 동떨어져 있으며, 심각한 사용성 및 성능 문제를 안고 있습니다. 비동기 반복문(`for await...of`)이 도입되기 전에 수립된 이 API는 불필요하게 복잡한 리더/라이터 모델과 잠금(locking) 메커니즘에 의존하고 있어, 현대적 언어 기능을 활용한 대안적인 접근 방식을 통해 최대 120배까지 성능을 개선할 수 있다는 것이 핵심 주장입니다. **역사적 배경과 설계의 시대적 한계** - Web Streams 표준은 2014~2016년 사이에 개발되었으며, 이는 JavaScript의 비동기 반복문(`for await...of`)이 등장(2018년)하기 훨씬 전의 일입니다. - 당시에는 비동기 시퀀스를 처리하는 관용적인 방법이 없었기 때문에, 표준은 리더와 라이터를 획득하고 관리하는 독자적인 모델을 구축해야만 했습니다. - 결과적으로 Node.js와 같은 서버 사이드 런타임들은 호환성을 위해 나중에 이 복잡한 표준을 도입하게 되었고, 이는 현대적인 JavaScript 개발 흐름과 충돌하는 원인이 되었습니다. **과도한 상용구 코드와 사용성 저하** - 스트림을 끝까지 읽는 단순한 작업조차 리더 획득, `read()`의 반복 호출, `{ value, done }` 프로토콜 처리, 그리고 `finally` 블록을 통한 명시적인 잠금 해제 등 복잡한 과정을 거쳐야 합니다. - 나중에 비동기 반복문이 지원되기는 했으나, 이는 기존의 복잡한 구조 위에 덧씌워진 형태에 불과하여 BYOB(Bring Your Own Buffer) 같은 세부적인 기능을 제대로 활용할 수 없는 한계가 있습니다. - 개발자들은 여전히 내부의 리더, 잠금, 컨트롤러 구조를 이해해야 하며, 문제 발생 시 추상화 뒤에 숨은 복잡성 때문에 디버깅에 어려움을 겪습니다. **수동 잠금(Locking) 모델의 치명적 결함** - Web Streams는 다중 소비자의 간섭을 막기 위해 독점적 잠금 모델을 사용하지만, 이를 관리하는 방식이 매우 위험합니다. - `getReader()`를 통해 잠긴 스트림은 반드시 `releaseLock()`을 호출해야 하며, 이를 잊을 경우 스트림이 영구적으로 잠겨 파이프나 취소 등 다른 모든 작업을 수행할 수 없게 됩니다. - 잠금 상태(`locked`)에 대한 정보는 제공되지만, 누가 왜 잠갔는지 혹은 잠금이 유효한지에 대한 구체적인 맥락을 알 수 없어 운영 환경에서의 실수를 유발하기 쉽습니다. **현대적 대안을 통한 비약적인 성능 향상** - 저자가 제시하는 대안적인 접근 방식은 JavaScript 언어 자체의 원시 기능을 활용하며, 기존 Web Streams 대비 모든 런타임(Node.js, Deno, Bun, 브라우저 등)에서 2배에서 최대 120배 빠른 성능을 보입니다. - 이러한 성능 차이는 단순한 최적화의 결과가 아니라, 10년 전의 낡은 설계 결정을 현대적인 JavaScript 패턴에 맞게 근본적으로 다시 설계함으로써 얻어진 결과입니다. 개발자들은 이제 기존 Web Streams의 복잡한 수동 관리 방식에서 벗어나, 현대적인 비동기 반복 기반의 더 직관적이고 효율적인 스트림 API로의 전환을 논의해야 할 시점에 와 있습니다.

API 설계JavaScript성능 최적화node.js+3

toss·2026년 2월 26일원문

쓰기 쉬운 Toss Front SDK (새 탭에서 열림)

좋은 SDK는 단순히 기능을 제공하는 것을 넘어, 사용자가 올바른 방법으로만 사용하도록 유도하고 휴먼 에러를 구조적으로 방지해야 합니다. 이를 위해 복잡한 내부 로직을 사용자의 ‘의도’를 중심으로 추상화하는 퍼사드(Facade) 패턴을 적용하여, 사용자가 최소한의 코드로도 안정적인 결과물을 만들 수 있는 환경을 구축해야 합니다. 고수준 인터페이스를 통해 대다수의 유즈케이스를 해결하면서도, 특수한 상황을 위한 저수준 인터페이스라는 ‘탈출구’를 마련하는 것이 설계의 핵심입니다. ### 의도 기반의 퍼사드(Facade) 패턴 재정의 - 퍼사드 패턴의 본질은 단순히 복잡한 기능을 숨기는 것이 아니라, 내부 구현을 ‘사용자의 의도(Intent)’를 기준으로 재구성하는 데 있습니다. - "서버를 열고, 핸들러를 등록하고, 에러를 처리한다"는 개별적인 절차를 "서버를 시작한다"는 하나의 자연스러운 목적으로 통합합니다. - 인증, 재시도 로직, 상태 관리, 클린업(Cleanup) 등 인지 부하를 일으키는 요소들을 SDK 내부로 은닉하여 사용자 측의 실수를 원천 차단합니다. ### AWS CDK 사례를 통한 추상화 계층의 이해 - AWS CDK의 L1 구문은 리소스의 모든 속성을 제어하는 저수준(low-level) 인터페이스인 반면, L2 구문은 직관적인 의도 기반의 고수준(high-level) 추상화를 제공합니다. - S3 버킷 생성 시 L1은 모든 세부 설정을 직접 챙겨야 하지만, L2는 자주 쓰이는 옵션을 간단한 프로퍼티로 제공하고 내부적인 변환은 SDK가 담당합니다. - SDK 설계 시에도 이와 같이 복잡한 주변 구성을 자연스러운 API 흐름으로 이어 붙일 수 있도록 설계해야 합니다. ### 파레토 법칙을 적용한 인터페이스 설계 - 전체 사용 사례의 80%에 해당하는 공통 유즈케이스는 고수준 인터페이스(Facade)를 통해 워크플로우를 자동화하여 제공합니다. - 나머지 20%의 특수한 요구사항이나 세밀한 제어가 필요한 상황을 위해 저수준 API인 ‘탈출구(Escape Hatch)’를 함께 유지합니다. - 이러한 이중 구조는 단기적인 개발자 경험(DX) 향상뿐만 아니라, SDK의 장기적인 호환성과 확장성을 보장하는 핵심 전략이 됩니다. ### 편의성과 유연성 사이의 트레이드오프 관리 - 추상화 수준이 높아지면 사용자는 편리해지지만, SDK 내부에서는 더 정교한 오케스트레이션 로직을 관리해야 하는 유지보수 비용이 발생합니다. - 세밀한 제어가 차단될 경우 특정 상황에서 제약이 될 수 있으므로, 고수준 인터페이스에만 의존하지 않고 저수준 조작이 가능한 균형점을 찾는 것이 중요합니다. - 결과적으로 잘 설계된 인터페이스는 사용자가 별도의 가이드 없이도 올바른 패턴을 유지하며 메모리 누수와 같은 장애 상황을 방지하게 합니다. 단순히 "동작하는" SDK를 만드는 단계를 넘어, 사용자가 직관적으로 이해하고 안전하게 사용할 수 있는 "쓰기 쉬운" SDK를 지향해야 합니다. 이를 위해 사용자의 의도를 최우선으로 고려한 추상화 계층을 설계하고, 대다수의 편의성과 소수의 유연성을 동시에 잡을 수 있는 다층적 구조를 도입할 것을 권장합니다.

API 설계software-architectureinterface-designfrontend+4

cloudflare·2026년 2월 21일원문

2026년 (새 탭에서 열림)

2026년 2월 20일, Cloudflare는 사용자 지정 IP(BYOIP) 서비스 관리 방식의 변경 과정에서 발생한 소프트웨어 오류로 인해 약 6시간 동안 서비스 장애를 겪었습니다. 이번 장애는 내부 자동화 시스템이 유효한 IP 접두사(Prefix)들을 실수로 인터넷 경로(BGP)에서 철회하면서 발생했으며, 이로 인해 일부 고객 서비스와 Cloudflare의 1.1.1.1 웹사이트 접속이 불가능해졌습니다. Cloudflare는 즉각적인 롤백과 수동 복구 작업을 통해 문제를 해결했으며, 향후 자동화 배포의 안전성을 강화하기 위한 체계적인 개선을 약속했습니다. ### Addressing API와 자동화 프로세스의 결함 * **Addressing API의 역할**: Cloudflare 네트워크에 존재하는 주소 데이터의 단일 진실 공급원(Source of Truth)으로, 여기서 발생한 변경 사항은 즉시 전 세계 에지(Edge) 네트워크로 전파됩니다. * **위험한 수동 작업의 자동화**: 기존에 수동으로 이루어지던 BYOIP 접두사 삭제 작업을 자동화하기 위해 '정기 정리 하위 태스크'를 도입했습니다. 이는 배포 규모를 작게 유지하고 안전성을 높이려는 'Code Orange: Fail Small' 프로젝트의 일환이었습니다. * **API 쿼리 버그**: 정리 태스크가 API를 호출할 때 `pending_delete` 매개변수를 처리하는 로직에 버그가 있었습니다. 삭제 대기 중인 객체만 불러와야 했으나, 코드상에서 매개변수의 존재 여부만 체크하는 오류로 인해 정상적인 접두사들까지 삭제 대상에 포함되는 결과를 초래했습니다. ### 고객 서비스 영향 및 BGP 경로 탐색 현상 * **IP 접두사 철회**: 전체 BYOIP 접두사 중 약 25%에 해당하는 1,100개의 접두사가 인터넷 광고에서 제외되었습니다. 이로 인해 해당 IP를 사용하는 서비스는 외부에서 접근할 수 없는 상태가 되었습니다. * **BGP 경로 탐색(Path Hunting)**: 접두사가 철회되자 사용자 연결은 목적지를 찾기 위해 여러 네트워크를 헤매는 '경로 탐색' 현상을 겪었으며, 결국 연결 타임아웃과 실패로 이어졌습니다. * **특정 서비스 오류**: Cloudflare의 재귀 DNS 리졸버 웹사이트(1.1.1.1) 접속 시 403 오류("Edge IP Restricted")가 발생했습니다. 다만, 실제 DNS 질의 서비스와 DoH(DNS over HTTPS)는 이번 장애의 영향을 받지 않았습니다. ### 복구 과정에서의 기술적 난관 * **단계적 복구**: 엔지니어들이 변경 사항을 감지하고 롤백을 시작하면서 약 800개의 접두사가 먼저 복구되었습니다. 일부 고객은 대시보드를 통해 직접 IP를 재광고함으로써 자가 복구를 수행하기도 했습니다. * **소프트웨어 버그로 인한 지연**: 나머지 300여 개의 접두사는 단순한 경로 철회를 넘어 에지 서버에서 서비스 구성 정보 자체가 삭제되는 추가적인 소프트웨어 버그가 발생했습니다. 이로 인해 대시보드 설정만으로는 복구가 불가능했습니다. * **수동 상태 전파**: 엔지니어들은 삭제된 설정 상태를 에지 서버에 다시 강제로 전파하는 수동 작업을 수행해야 했으며, 장애 발생 6시간 7분 만인 23:03 UTC에 모든 서비스가 정상화되었습니다. Cloudflare는 이번 사고를 계기로 모든 주소 관리 워크플로우에서 수동 개입을 완전히 배제하고, 자동화된 헬스 체크 기능을 강화할 계획입니다. BYOIP를 사용하는 기업 고객은 유사한 장애 발생 시 Cloudflare 대시보드를 통해 IP 광고 상태를 직접 제어함으로써 복구 시간을 단축할 수 있는 운영 매뉴얼을 숙지해 두는 것이 권장됩니다.

API 설계Godnsbgp+3

spotify·2026년 2월 9일원문

더 스마트한 광고를 위한 우리의 (새 탭에서 열림)

Spotify는 광고 비즈니스의 다양한 구매 채널 간에 발생하는 의사결정 로직의 파편화 문제를 해결하기 위해 멀티 에이전트 아키텍처를 도입했습니다. 기존의 하드코딩된 워크플로우 대신, 광고주의 의도를 이해하고 공유된 신호를 바탕으로 추론하는 '프로그래밍 가능한 의사결정 계층'을 구축하여 모든 채널에서 일관된 최적화를 달성하고자 합니다. 이를 통해 복잡한 비즈니스 제약 조건을 유연하게 처리하고, 기존 광고 서비스들을 에이전트가 활용하는 도구로 재정의함으로써 시스템 전반의 운영 효율성을 극대화하는 것이 이 글의 핵심입니다. ### 기존 워크플로우의 구조적 한계와 파편화 * **채널별 로직 불일치:** 동일한 백엔드 인프라를 공유함에도 불구하고 Direct, Self-Serve, Programmatic 등 각 구매 채널별로 의사결정 로직과 휴리스틱이 다르게 구현되어 동작의 불일치가 발생합니다. * **중복 구현과 기술 부채:** 예산 할당이나 인벤토리 선택과 같은 핵심 로직이 각 채널 및 사용자 접점(Spotify Ads Manager, Salesforce, Slack 등)마다 중복 구현되어 관리 비용이 증가하고 로직의 변질(Drift)이 일어납니다. * **의도 계층(Intent Layer)의 부재:** 기존 시스템은 "브라질 내 도달 범위 극대화 및 비디오 인벤토리 보호"와 같은 복합적인 목표를 이해하고 이를 실행 가능한 도구 호출 순서로 변환하는 능력이 부족했습니다. ### 멀티 에이전트 기반 의사결정 계층의 도입 * **모듈형 에이전트 구조:** 복잡하고 확률적인 광고 로직을 정적인 규칙 엔진(Rules Engine)에 가두는 대신, 상황에 따라 추론하고 실행하는 독립적인 에이전트들의 집합으로 구성했습니다. * **공유 신호 기반 최적화:** 모든 에이전트는 인벤토리, 오디언스, 성능 이력 등 동일한 기저 신호를 공유하며 광고주의 목표와 Spotify의 비즈니스 제약 조건을 동시에 고려하여 최적의 경로를 찾습니다. * **기존 서비스의 도구화:** 기존 광고 서비스들을 처음부터 다시 만드는 대신, 에이전트가 목적에 따라 호출하여 사용할 수 있는 '도구(Tools)'로 활용함으로써 오케스트레이션 성능을 높였습니다. ### 에이전트 중심 설계를 위한 기술적 패러다임 전환 * **API 설계의 변화:** 단순히 데이터를 생성하고 수정하는 CRUD 방식에서 벗어나, 에이전트가 특정 기능을 실행하기 위해 직관적으로 이해하고 사용할 수 있는 '도구 중심 API'로 재설계했습니다. * **행동 중심의 평가:** 전통적인 유닛/통합 테스트를 넘어, 에이전트가 내린 결정이 비즈니스 목표에 부합하는지 확인하는 '행동 평가(Behavioral Evaluation)' 체계를 구축했습니다. * **추론 과정의 관측성:** 시스템 성능 지표뿐만 아니라 "에이전트가 왜 그런 결정을 내렸는가"에 대한 추론 과정을 추적하여 투명성을 확보했습니다. * **자율성을 제어하는 가드레일:** 입력값 검증 수준을 넘어 반자율적인 에이전트의 결정이 비즈니스 규칙과 안전 가이드라인 내에서 유지되도록 하는 가드레일 메커니즘을 도입했습니다. 복잡한 비즈니스 로직이 여러 플랫폼에 흩어져 있다면, 이를 개별 서비스로 관리하기보다 통합된 '의사결정 엔진'으로서의 에이전트 플랫폼을 구축하는 것이 장기적인 유지보수와 기능 확장 면에서 유리합니다. Spotify는 이를 미디어 플래닝(Media Planning) 영역에 우선 적용하여 복잡한 변수 속에서도 일관된 최적화 성능을 증명하고 있습니다.

API 설계AI 에이전트머신러닝multi-agent-systems+3

github·2026년 2월 2일·3분 읽기큐레이션 요약

GitHub Copilot의 에이전

GitHub Copilot의 에이전트 기능은 단순한 코드 자동완성보다 시스템 설계, 리팩터링, 마이그레이션, 다중 파일 변경을 지원하는 협업 도구로 활용할 수 있다. 다만 Copilot이 개발자의 판단을 대체하는 것은 아니며, 개발자는 제안된 구조와 변경 사항을 검토하고 반박할 수 있어야 한다. 핵심은 기능 구현 전에 아키텍처 경계와 영향 범위를 분석하도록 Copilot을 활용하는 것이다. ## 시스템 설계와 모듈 분해 - 코드를 바로 작성하기보다 먼저 다음 영역의 경계를 식별한다. - 도메인 로직 - 데이터 접근 계층 - 인터페이스와 컨트롤러 - 모듈 간 상호작용 - Copilot에 서비스 구조를 분석하도록 요청하면 다음 문제를 발견하는 데 도움을 받을 수 있다. - 모듈 경계와 계층 간 결합 - 비동기 처리 및 트랜잭션 관련 위험 - 중복 로직과 책임 혼재 - 테스트 가능성과 관측성 문제 - 헥사고날 아키텍처와 계층형 아키텍처를 비교하게 하고, 현재 코드베이스의 제약 조건에 맞는 선택과 트레이드오프를 설명하도록 할 수 있다. - 이 과정에서 Copilot은 자동완성 도구가 아니라 설계 리뷰어처럼 활용된다. ## 의존성 역전 기반의 모듈형 서비스 구축 - 도메인, 컨트롤러, 리포지토리를 독립적인 모듈로 나누도록 요청할 수 있다. - 의존성 역전을 적용하면 상위 수준의 도메인 로직이 특정 데이터베이스나 인프라 구현에 직접 의존하지 않게 된다. - Copilot은 다음과 같은 결과물을 생성할 수 있다. - 도메인 모델 인터페이스 - 리포지토리 추상화 - 도메인 서비스를 호출하는 컨트롤러 - 각 모듈의 책임, 가정, 계약을 설명하는 Markdown 문서 - 초급 개발자는 실제 서비스 설계 패턴을 학습하고, 숙련 개발자는 반복적인 기본 코드 작성 시간을 줄일 수 있다. ## 태깅 기능 추가 시 고려할 아키텍처 영향 - “노트에 태그 추가”는 단순한 기능처럼 보이지만 여러 계층에 영향을 준다. - 데이터 모델링 방식부터 결정해야 한다. - 노트에 태그를 직접 내장할지 - 정규화된 태그 테이블을 만들지 - 다대다 관계를 사용할지 - 검색 기능에서는 태그가 색인, 필터링, 검색 관련성에 어떤 영향을 주는지 검토해야 한다. - API에서 태그를 독립적인 리소스로 노출할지, 내부 구현 세부사항으로 둘지도 결정해야 한다. - 검증 규칙과 불변식을 어느 계층에서 강제할지 명확히 해야 한다. - 마이그레이션 방식과 배포·롤백 전략도 함께 설계해야 한다. - Copilot에 먼저 영향 범위를 분석하게 하면 다음 항목을 확인할 수 있다. - 태그와 노트의 관계 - 스키마 마이그레이션 필요성 - 검색 및 캐시·색인 영향 - 검증 로직 변경 - 테스트와 외부 API 소비자에 대한 영향 - 잠재적인 회귀 문제 ## 다중 파일 변경과 일관된 구현 - 설계가 끝난 뒤에는 도메인 모델, 스키마, 리포지토리, 컨트롤러를 하나의 의도로 연결해 구현하도록 Copilot에 요청할 수 있다. - 테스트와 문서도 함께 갱신하게 하고, 각 변경 사항을 diff 형태로 제시하도록 하면 검토가 쉬워진다. - 예시로 태그를 JSON 배열로 저장하는 스키마 변경, `Tag`와 `Note` 인터페이스 추가, 컨트롤러에서 태그 추가 서비스를 호출하는 코드가 제시된다. - 에이전트 모드의 장점은 한 파일의 코드 생성이 아니라 여러 파일에 걸친 변경을 조정하고 일관성을 유지하는 데 있다. ## 안전한 스키마 마이그레이션 - 중요한 것은 SQL 문법 자체보다 변경을 운영 환경에 안전하게 적용하는 전략이다. - 마이그레이션은 다음 조건을 고려해야 한다. - 기존 클라이언트와 호환될 것 - 변경을 되돌릴 수 있을 것 - 높은 부하에서도 안전할 것 - 의존 시스템에 변경 사항이 투명하게 전달될 것 - Copilot에게 마이그레이션을 작성하게 하기 전에 호환성, 가역성, 부하 상황을 기준으로 설계를 검토하게 하는 것이 바람직하다. ## 실용적인 활용 방식 Copilot에게 곧바로 “코드를 작성하라”고 요청하기보다, 먼저 구조 분석과 영향 범위 파악을 시킨 뒤 구현·테스트·문서화까지 단계적으로 진행하는 방식이 효과적이다. 생성된 결과는 반드시 개발자가 계약, 마이그레이션, 회귀 가능성, 운영 환경의 위험을 직접 검토해야 한다.

원문 읽기(새 탭에서 열림)

API 설계TypeScriptgithub-copilotsoftware-architecture+3