작은 CLI 도구를 배포할 때 설정·로그·업데이트를 설계하는 법

개인적으로 쓰려고 만든 CLI는 실행만 되면 충분합니다. 그러나 다른 사람이 사용하기 시작하면 설정 파일이 어디에 있는지, 오류가 무엇을 뜻하는지, 업데이트 후 되돌릴 수 있는지를 설명해야 합니다.이번 글에서는 작은 도구를 배포할 때 코드 기능보다 먼저 결정해야 할 네 가지를 정리합니다. 패키지 레지스트리를 쓰든 실행 파일을 배포하든 공통으로 적용되는 기준입니다.첫 실행에서 알아야 할 것을 줄입니다CLI 사용자는 README를 끝까지 읽지 않고 명령을 실행합니다. 첫 실행에서 필요한 설정이 무엇인지, 기본 출력이 어디에 저장되는지, 실패했을 때 다음에 무엇을 해야 하는지가 바로 보여야 합니다.저는 설정을 명령행 인자, 환경 변수, 설정 파일 세 층으로 나누고 우선순위를 문서에 고정합니다. 비밀 값은 로그..

API 사용량 상한과 비용 알림을 붙인 기록

개인 프로젝트는 처음에 사용자가 적어 비용도 작습니다. 그래서 사용량 제한을 나중에 붙이려 합니다. 하지만 공개 주소가 알려지거나 자동화된 요청이 들어오면 비용과 장애가 동시에 커질 수 있습니다.저는 기능을 추가하기 전에 요청을 세고, 상한을 넘으면 알려 주고, 더 넘으면 안전하게 거절하는 흐름을 만들기로 했습니다. 이번 글에서는 숫자 자체보다 제한 정책을 정하는 순서를 설명합니다.API마다 비용과 위험이 다릅니다모든 엔드포인트에 같은 제한을 걸면 사용자는 불편하고 운영자는 중요한 기능을 구분하지 못합니다. 읽기 요청은 캐시로 흡수할 수 있지만, 외부 AI 호출이나 파일 변환은 한 번의 요청도 비용이 큽니다.저는 먼저 엔드포인트를 비용·시간·데이터 변경 여부로 나눕니다. 그 다음 사용자별 제한과 전체 제..

1인 서비스 장애 공지 페이지를 만드는 최소 구성

혼자 운영하는 서비스에서 장애가 나면 코드부터 고치고 싶습니다. 그러나 사용자는 원인이 무엇인지보다 지금 사용할 수 있는지, 언제 다시 확인하면 되는지를 먼저 알고 싶어 합니다. 공지가 늦으면 작은 장애도 불안으로 커집니다.이번 글에서는 복잡한 상태 페이지 제품이 아니라, 혼자서 실제로 갱신할 수 있는 장애 공지의 최소 구성을 정리합니다. 관측 데이터와 공지 문장을 연결해 사후 회고까지 이어지는 흐름을 목표로 합니다.장애 공지는 네 가지 사실로 시작합니다첫 공지에는 원인을 추측해 쓰지 않습니다. 발생 시각, 영향 범위, 현재 조치, 다음 업데이트 시각 네 가지만 적습니다. 원인이 확인되지 않았는데 ‘서버 문제’라고 단정하면 나중에 공지를 다시 고쳐야 합니다.영향 범위는 모든 사용자가 아니라 특정 기능·지..

작법서를 읽을 때는 밑줄을 많이 긋지만, 며칠 뒤 원고를 열면 무엇을 적용해야 할지 모르는 일이 많습니다. 저도 좋은 문장을 수집하는 데 시간을 쓰면서 실제 장면은 그대로 둔 적이 많았습니다.작법서의 가치를 확인하는 가장 빠른 방법은 한 가지 주장을 작은 장면에 적용해 보는 것입니다. 이번 글에서는 책의 내용을 요약하는 대신 실험 가능한 독서 노트를 만드는 방법을 정리합니다.책의 주장과 내 해석을 분리합니다독서 노트 첫 칸에는 책이 실제로 말한 내용을 짧게 적습니다. 다음 칸에는 내가 이해한 뜻을 적습니다. 이 둘을 섞으면 나중에 내 생각을 책의 주장처럼 기억하게 됩니다.인용은 필요한 만큼만 하고, 페이지나 장을 기록합니다. 요약만으로 충분하지 않은 경우에는 책을 다시 펼쳐 원문을 확인해야 합니다. 노트..

연재를 시작하면 댓글 하나가 다음 회차의 방향을 바꿀 만큼 크게 느껴집니다. 독자가 발견한 오류를 고치는 일도 중요하지만, 모든 요구를 즉시 반영하면 작가가 세운 이야기의 중심이 흔들릴 수 있습니다.저는 댓글을 찬반으로 읽지 않고 정보의 종류로 분류합니다. 사실 오류인지, 취향인지, 오해인지, 스포일러를 요구하는 말인지 나누면 반영할 것과 거리를 둘 것이 보입니다.댓글은 사실·취향·오해·스포일러로 분류합니다댓글을 읽을 때 처음부터 방어적으로 반응하면 모든 말이 공격처럼 느껴집니다. 반대로 전부 맞다고 생각하면 작품이 댓글의 투표로 움직입니다. 네 가지 분류를 먼저 적용하면 반응과 판단 사이에 짧은 거리가 생깁니다.사실 오류는 가능한 한 빨리 확인하되, 취향은 작품 방향과 맞을 때만 참고합니다. 오해는 본..

대화문을 고칠 때 사투리나 어미를 바꾸면 인물 목소리가 달라진 것처럼 보입니다. 하지만 몇 문장 지나면 모든 인물이 같은 방식으로 질문하고 설명하는 문제가 다시 드러납니다.인물의 목소리는 말투보다 무엇을 말하지 않는지, 어떤 정보를 먼저 꺼내는지에서 더 잘 보입니다. 이번 글에서는 대사만 추출해도 화자를 구분할 수 있는지 확인하는 편집 순서를 소개합니다.대사를 장면에서 떼어 내 먼저 읽습니다지문과 서술이 함께 있으면 인물의 차이가 과장되어 보일 수 있습니다. 저는 한 장면의 대사만 복사해 화자 이름을 가리고 읽습니다. 누가 말했는지 쉽게 맞힐 수 없다면 말투가 아니라 사고 방식이 겹친 것입니다.이때 문장을 예쁘게 고치지 않고 목적과 정보량을 표시합니다. 질문하는 인물인지, 회피하는 인물인지, 상대의 말을..

연재 글을 쓰다 보면 다음 회차를 읽게 만들기 위해 매번 큰 위기를 남기고 싶어집니다. 하지만 모든 회차가 같은 방식으로 끊기면 독자는 긴장보다 피로를 먼저 느낄 수 있습니다.회차의 끝은 반드시 폭발해야 하는 지점이 아니라, 이번 회차의 약속을 닫고 다음 질문을 여는 지점이라고 생각합니다. 세 가지 종료 방식을 나눠 보면 장면의 성격에 맞는 끝을 고르기 쉬워집니다.먼저 이번 회차의 약속을 한 문장으로 씁니다회차를 쓰기 전에 ‘이번 회차에서 독자가 반드시 확인해야 하는 것은 무엇인가’를 적습니다. 인물이 결심하는 회차인지, 비밀의 일부가 드러나는 회차인지, 관계가 틀어지는 회차인지 정하면 끝맺음의 방향도 달라집니다.약속을 닫지 않은 채 다음 회차의 질문만 남기면 독자는 아직 읽은 것이 끝나지 않았다고 느낄..

초고가 마음에 들지 않을 때 가장 먼저 전체를 고치고 싶어집니다. 하지만 첫 장면이 제 역할을 하지 못해서 뒤의 원고까지 불안하게 느껴지는 경우도 많습니다. 시작부를 작게 진단하면 무엇을 고쳐야 하는지 범위를 줄일 수 있습니다.이번 글에서는 첫 문장과 첫 장면만 떼어 내어 확인하는 점검표를 정리합니다. 정답 문장을 찾는 방법이 아니라, 독자가 무엇을 기대하게 되는지 확인하는 방법입니다.첫 문장은 분위기보다 약속을 전달해야 합니다첫 문장이 반드시 큰 사건으로 시작할 필요는 없습니다. 대신 독자가 어떤 종류의 이야기를 읽게 될지 약속해야 합니다. 인물의 문제인지, 세계의 이상인지, 관계의 긴장인지 한 가지가 보이면 다음 문장을 읽을 이유가 생깁니다.저는 첫 문장을 읽고 ‘이 장면에서 누가 무엇을 원하나’를 ..

연재가 길어질수록 설정집은 커지는데, 정작 다음 회차를 쓸 때 필요한 정보는 찾기 어려워집니다. 인물의 생일이나 외형보다 더 자주 바뀌는 것은 지금 알고 있는 사실과 감정입니다.저는 설정을 고정된 백과사전처럼 관리하지 않고, 회차가 끝날 때마다 상태를 갱신하는 표로 바꾸었습니다. 이번 글에서는 캐릭터 한 명의 현재 상태를 빠르게 확인하는 방법을 소개합니다.고정 정보와 회차 정보를 분리합니다이름·출신·말투처럼 쉽게 바뀌지 않는 정보와, 현재 목표·상대에 대한 의심·알게 된 사실처럼 회차마다 달라지는 정보를 한 표에 섞으면 업데이트가 어렵습니다. 저는 인물 카드와 상태표를 나눕니다.인물 카드는 작품 전체에서 유지할 약속이고, 상태표는 다음 장면을 쓰기 위한 작업 메모입니다. 상태표는 오래 보관할 문서가 아니..

예전에는 웹호스팅 계정 하나를 만들고 파일을 올리면 서비스가 시작됐습니다. 지금은 서버리스 함수, 오브젝트 스토리지, CDN, 관리형 데이터베이스를 조합해 훨씬 빠르게 시작할 수 있습니다. 대신 어디서 문제가 생겼는지 추적해야 할 지점도 늘었습니다.저는 비용이 싸다는 이유만으로 구조를 고르지 않으려고 합니다. 월 요금보다 중요한 것은 장애가 났을 때 누가 무엇을 확인해야 하는지, 데이터가 어디에 있고 어떻게 복구하는지 알 수 있는가입니다.호스팅 시대에는 책임이 한 덩어리였습니다공유 호스팅에서는 운영자가 관리할 수 있는 범위가 제한적이었습니다. 웹 서버 설정과 데이터베이스가 이미 준비돼 있었고, 사용자는 파일과 애플리케이션에 집중했습니다. 문제가 생기면 고객센터에 문의하는 것도 운영의 일부였습니다.이 구조..