StudyDad

문서화와 인수인계 시리즈 4/9아키텍처 결정 기록, 흔히 ADR이라고 부르는 문서는 거창해 보인다. 대규모 조직이나 플랫폼 팀에서나 쓰는 문서처럼 느껴질 수도 있다.하지만 작은 운영 도구를 만들 때도 ADR은 필요하다.이유는 단순하다. 시간이 지나면 왜 그렇게 만들었는지 잊어버리기 때문이다.코드는 최종 결과만 보여준다. 하지만 그 결과에 도달하기까지의 선택지, 제약, 포기한 것, 다시 검토해야 할 조건은 코드에 남지 않는다.문제 상황운영 콘솔을 만들면서 여러 결정을 내려야 했다.React SPA를 어디에 배포할 것인가API 앞에 Gateway를 둘 것인가Lambda만 쓸 것인가, 상주 서버도 둘 것인가RDB를 둘 것인가, 파일 기반 저장소로 충분한가오래 걸리는 엑셀 생성은 동기 API로 처리할 것인가CO..

문서화와 인수인계 시리즈 3/9프로젝트 문서를 정리하다 보면 모든 내용을 README에 넣고 싶어진다. 가장 눈에 잘 띄고, 새로 들어온 사람이 먼저 열어보는 파일이기 때문이다.하지만 운영 중인 시스템에서는 README 하나로 충분하지 않다. 개발 시작을 돕는 문서, 시스템 구조를 설명하는 문서, 운영 인수인계를 위한 문서는 목적이 다르다.문서가 목적별로 나뉘지 않으면 두 가지 문제가 생긴다.첫째, README가 너무 길어져 아무도 끝까지 읽지 않는다.둘째, 중요한 운영 정보가 개발 가이드 사이에 묻힌다.세 문서의 차이가장 단순하게 나누면 이렇다.문서주요 독자답해야 하는 질문README처음 실행하는 개발자어떻게 설치하고 실행하는가아키텍처 문서구조를 이해하려는 개발자시스템이 어떻게 나뉘어 있고 왜 그런가H..

문서화와 인수인계 시리즈 2/9인수인계 문서를 쓰려고 하면 막막하다. 무엇을 어디까지 적어야 할지 애매하다. 너무 적으면 쓸모가 없고, 너무 많이 적으면 아무도 읽지 않는다.운영 시스템의 HANDOVER는 목적이 분명해야 한다. 새 담당자가 시스템을 이해하고, 배포하고, 장애를 확인하고, 위험한 변경을 피할 수 있어야 한다.이 글은 운영 콘솔을 정리하면서 사용한 HANDOVER 문서 구조를 일반화한 것이다.1. 시스템 개요문서의 시작은 기술 스택이 아니라 시스템의 목적이어야 한다.예를 들어 다음 질문에 답한다.이 시스템은 누구를 위한 것인가어떤 업무를 처리하는가내부 사용자만 쓰는가, 외부 사용자도 보는가데이터 원천은 어디인가운영상 가장 중요한 기능은 무엇인가좋은 개요는 한 문단으로 시스템을 설명할 수 있..

문서화와 인수인계 시리즈 1/9프로젝트를 넘겨줄 때 가장 먼저 떠올리는 문서는 보통 README다. 설치 방법, 실행 방법, 폴더 구조, 주요 명령어를 적는다. README는 중요하다. 하지만 실제 운영 중인 시스템을 넘겨줄 때 README만으로는 부족하다.운영 중인 시스템에는 코드 밖의 정보가 많다. 어디에 배포되어 있는지, 어떤 API가 어떤 저장소를 보는지, 장애가 나면 어떤 로그를 봐야 하는지, 배포할 때 어떤 파일을 건드리면 안 되는지, 특정 기능이 느릴 때 어디부터 확인해야 하는지 같은 정보다.이런 정보는 코드만 읽어서는 바로 알기 어렵다. 그래서 인수인계 문서는 코드 설명서가 아니라 운영 지도여야 한다.문제 상황운영 콘솔 두 개를 정리하면서 비슷한 문제가 보였다.하나는 외부 입력과 공개 페이..

AWS EC2에서 Docker 빌드 중 “no space left on device” 오류 해결기최근 AWS EC2 인스턴스에서 Docker 이미지를 빌드하는 과정 중, 예상치 못한 디스크 용량 부족 문제를 겪었습니다.이번 글에서는 문제 원인 파악부터 EBS 볼륨 확장 및 파티션 조정, 파일시스템 리사이즈까지 진행한 과정을 단계별로 정리해 보겠습니다.문제 상황: Docker 빌드 중 “no space left on device” 오류 발생Docker 빌드 중 다음과 같은 에러 메시지를 확인했습니다.error Error: ENOSPC: no space left on device, copyfile '/frontend/.cache/yarn/v6/npm-plotly-js-1.58.5-.../world_110m...

🪙 정산 자동화 시리즈 #2GAS + Lambda로 정산 데이터 자동 수집, 가공, 리포트 발송하기1️⃣ 목표이 단계에서는 다음을 자동화하여 정산 보고 프로세스를 구축한다:✅ 매일/매주 거래 데이터 자동 수집✅ 카테고리별 수수료율, 반품/환불 데이터 자동 가공✅ 엑셀 리포트 생성 및 자동 이메일 발송✅ Slack/메일 보고 자동화2️⃣ 아키텍처 개요구조 설명사용자 → Google Sheets 메뉴 클릭GAS → Lambda URL로 action, params 전송Lambda:DB 조회Excel 리포트 생성SES 이메일 발송사용자 → Slack/메일로 보고 받음Google Apps Script (GAS): 시트 기반 유저 인터페이스, Lambda 호출, Slack 연동AWS Lambda + EventBr..

📌 정산 자동화 시리즈 #1왜 정산 자동화가 필요한가![정산자동화1편]1️⃣ 정산 자동화를 시작한 이유✅ 반복 작업의 시간 낭비매월 수작업 정산에만 팀원이 10시간 이상 소모‘월 마감’이 다가올수록 본 업무를 멈추고 데이터 정제와 오류 검증에 몰두수기로 돌리다 보니 사람이 빠뜨리거나 잘못 입력해 재검증 반복✅ 정확하지 못한 데이터 기반 운영카테고리별 수익률 분석이 어려워 ‘느낌’에 의존해 광고, 재고, 가격 전략을 결정어떤 카테고리가 수익성이 좋은지, 반품·환불 비율이 높은지 알기 어려움결국 현금 흐름 예측과 사업 의사결정이 불투명✅ 사업 확장 시 한계거래 건수가 늘어날수록 수작업 정산은 리스크와 비용만 증가데이터 기반 의사결정이 필요한 시점에 ‘데이터 신뢰성’부터 흔들림2️⃣ 정산 자동화가 가져올 변..

[반복되는 폼 자동화] 시리즈 안내1편: 도입 – 왜 자동화가 필요했을까?2편: 실전 – 구글 앱스 스크립트로 자동 폼 만들기3편: 트리거 활용 – 완전 자동화의 완성 (현재 글)각 편은 독립적으로 읽을 수 있으며, 시리즈 전체를 따라오시면 자동화의 모든 과정을 쉽게 익히실 수 있습니다.트리거로 완성하는 완전 자동화 – 반복 업무에서 완전히 손을 떼다광고 신청 폼은 자동으로 생성되고,응답 시트는 보기 좋게 정리되며,공유용 시트도 알아서 완성된다.이 시점에서 드는 생각은 하나다."그럼 이제 이걸 매달 누가 실행하지?"사람이 버튼을 누르지 않아도매달 같은 날, 같은 시간에모든 게 자동으로 시작되면 완벽하다.이번 편에서는 그 마지막 퍼즐 – 트리거에 대해 이야기하려고 한다.1. 트리거는 자동화의 관제탑이다자동..

[반복되는 폼 자동화] 시리즈 안내1편: 도입 – 왜 자동화가 필요했을까?2편: 실전 – 구글 앱스 스크립트로 자동 폼 만들기 (현재 글)3편: 트리거 활용 – 완전 자동화의 완성각 편은 독립적으로 읽을 수 있으며, 시리즈 전체를 따라오시면 자동화의 모든 과정을 쉽게 익히실 수 있습니다.👉 다음 편이 궁금하다면 [3편: 트리거 활용 – 완전 자동화의 완성]를 확인해보세요!실전! 자동 폼 생성과 응답 처리 – 광고 신청 업무를 완전히 자동화하다“폼은 만들었고, 공유도 했는데... 시트가 또 꼬였네.”광고 신청 업무를 담당하면서 내가 가장 자주 들었던 말이다.매달 반복되는 업무지만, 그때마다 꼭 하나씩 빠지거나 어긋난다.날짜가 틀렸거나, 응답 시트가 덮여버렸거나, 보기용 파일이 빠져 있거나.작은 실수가 쌓..

[반복되는 폼 자동화] 시리즈 안내1편: 도입 – 왜 자동화가 필요했을까? (현재 글)2편: 실전 – 구글 앱스 스크립트로 자동 폼 만들기3편: 트리거 활용 – 완전 자동화의 완성각 편은 독립적으로 읽을 수 있으며, 시리즈 전체를 따라오시면 자동화의 모든 과정을 쉽게 익히실 수 있습니다.👉 다음 편이 궁금하다면 [2편: 실전 – 구글 앱스 스크립트로 자동 폼 만들기]를 확인해 보세요!반복되는 폼 작업, 왜 자동화해야 했을까?매달 돌아오는 신청 업무. 나는 늘 이렇게 시작했다.지난달 구글 폼을 복사한다.제목의 날짜를 바꾼다.질문 내용을 조금 수정한다.링크를 따서 공유한다.응답 시트를 연동하고 확인한다.처음엔 이게 빠르고 편리하다고 생각했다. 하지만 매달 반복할수록 깨달았다.이건 자동화되어야 할 일이라는 ..