StudyDad

문서화와 인수인계 시리즈 9/9기술 블로그를 쓰려고 하면 종종 막막해진다.무엇을 써야 할지, 어디까지 공개해도 되는지, 이미 다른 사람이 더 잘 설명한 기술을 다시 써도 되는지 고민하게 된다.그럴 때 가장 좋은 재료 중 하나가 내가 실제로 남긴 실무 문서다.HANDOVER, 아키텍처 문서, ADR, 용어집, 트러블슈팅 가이드, 배포 가이드에는 내가 어떤 문제를 겪었고 어떻게 판단했는지가 들어 있다.이 문서들이 쌓이면 단순 기록을 넘어 개인의 일하는 방식을 보여주는 자산이 된다.기술 블로그는 지식 자랑이 아니다기술 블로그를 단순히 "내가 아는 것을 설명하는 공간"으로 보면 부담이 커진다.이미 공식 문서가 있고, 더 깊은 전문가의 글도 많다.하지만 실무 글의 가치는 다른 곳에 있다.내가 어떤 조건에서 어떤 ..

문서화와 인수인계 시리즈 8/9실무에서 만든 문서는 좋은 블로그 재료가 된다.아키텍처 문서, HANDOVER, 트러블슈팅 가이드, 배포 가이드, 용어집에는 실제 경험이 들어 있다. 검색해서 만든 글보다 훨씬 구체적이고, 판단의 흔적이 남아 있다.하지만 내부 문서를 그대로 공개하면 안 된다.실제 회사명, 도메인, 리소스 이름, API 경로, 인증 방식, 장애 날짜, 운영 데이터가 노출될 수 있다. 그래서 공개 글로 바꾸기 전에 익명화 과정이 필요하다.공개할 수 있는 것과 없는 것먼저 구분해야 한다.공개해도 좋은 것은 보편적인 판단 기준이다.왜 콘솔을 분리했는가왜 S3와 CloudFront를 썼는가왜 Lambda와 상주 서버를 나눴는가왜 job table로 비동기 작업을 관리했는가왜 CORS를 Gateway..

문서화와 인수인계 시리즈 7/9배포 가이드를 쓰다 보면 명령어만 나열하기 쉽다.npm run buildaws s3 sync build/ ...aws cloudfront create-invalidation ...물론 명령어는 필요하다. 하지만 배포 가이드가 명령어 모음으로 끝나면 위험하다.좋은 배포 가이드는 "무엇을 실행할지"뿐 아니라 "언제 실행하고, 무엇을 조심하고, 어떻게 확인하고, 실패하면 어떻게 되돌릴지"를 설명해야 한다.문제 상황운영 콘솔 배포에는 여러 종류가 있었다.React SPA 빌드 후 S3 업로드CloudFront 캐시 무효화Lambda 함수 코드 업데이트Lambda Layer 유지EC2의 Node API 서버 배포Google Apps Script 배포API Gateway stage 배..

문서화와 인수인계 시리즈 6/9장애가 나면 사람은 급해진다. 어디를 봐야 할지 기억나지 않고, 이전에 해결했던 문제도 다시 검색하게 된다. 로그 위치를 찾다가 시간을 쓰고, 같은 명령어를 다시 조합한다.그래서 트러블슈팅 문서는 장애가 난 뒤 쓰면 늦다.물론 실제 장애를 겪은 뒤 보강되는 부분은 있다. 하지만 최소한 자주 발생할 수 있는 증상과 확인 순서는 미리 정리해두는 것이 좋다.문제 상황운영 콘솔에서 반복적으로 나올 수 있는 문제는 대체로 정해져 있다.화면이 로딩되지 않는다.API 호출이 CORS 오류로 실패한다.데이터가 갱신되지 않는다.다운로드 작업이 끝나지 않는다.Lambda가 timeout 된다.DB 연결이 실패한다.배포했는데 이전 화면이 계속 보인다.이런 문제는 원인이 하나가 아니다. 화면이 ..

정산 업무는 단순히 금액을 더하고 빼는 일이 아니다.카테고리별 수수료율이 다르고, 예외 거래가 있고, 부분 환불이 있고, 공급가와 부가세를 나눠야 한다. 월마감 전에는 빠진 거래가 없는지도 확인해야 한다.문제는 이런 기준들이 보통 한 곳에 모여 있지 않다는 점이다.수수료율은 누군가의 기억에 있고, 예외 거래는 메신저에 남아 있고, 환불 반영 여부는 별도 파일을 봐야 한다. 파트너별 지급액은 매달 새로 피벗을 만들고, 월마감 체크는 구두로 끝나는 경우도 많다.이렇게 운영하면 정산은 언젠가 흔들린다.정산 업무를 엑셀로 관리해야 한다면, 최소한 아래 항목은 먼저 구조화해야 한다.카테고리별 수수료 규칙예외 거래 기준환불 반영 방식공급가와 부가세 분리 기준파트너별 지급액 계산 방식월마감 체크리스트정산 기준 변경 ..

3.3% 원천징수·연말정산·기한후신고 체크포인트 정리부업 수익이 있으면 3.3% 원천징수가 있었더라도 종합소득세 신고 대상 여부를 한 번 더 확인해보는 것이 좋습니다.특히 블로그 광고 수익, 외주 수익, 플랫폼 정산금, 전자책·강의 수익처럼 여러 형태의 부업 소득이 섞여 있다면 소득 유형과 지급 내역에 따라 확인 방식이 달라질 수 있습니다.실제로는 소액이라 괜찮겠지, 3.3%를 이미 떼였으니 끝난 것 아닐까, 직장인은 연말정산 했으니 별도 신고가 없겠지라고 생각했다가 뒤늦게 자료를 다시 정리하는 경우도 적지 않습니다.이 글에서는 부업 종합소득세와 관련해 많이 헷갈리는 체크포인트 5가지를 정리해보겠습니다.※ 본 글은 일반적인 종합소득세 확인 흐름을 설명한 정보성 콘텐츠입니다.실제 신고 대상 여부와 세액 판..

문서화와 인수인계 시리즈 5/9프로젝트 문서에 용어집이 필요한가?처음에는 과해 보일 수 있다. CORS, Lambda, CloudFront, API Gateway 같은 용어는 검색하면 정의가 나온다. 공식 문서도 있고, 블로그 글도 많다.하지만 프로젝트 안에서의 용어집은 일반 사전과 역할이 다르다.일반 사전은 "무엇인가"를 설명한다.프로젝트 용어집은 "이 프로젝트에서 왜 중요한가"를 설명한다.문제 상황운영 콘솔 문서를 정리하면서 여러 기술 용어가 반복해서 등장했다.CORSpreflightAPI GatewayLambda Function URLLambda LayerCloudFrontCache TTLinvalidationSSO cookiewithCredentialsSource of Truthjob tablec..

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

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

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