일기
회고 / 메모
-
웰컴 대체경로 문서화로 온보딩 혼동 해소
웰컴 프로세스는 보통 단순할 것 같지만, 실제로는 여러 대체 경로를 가진다. 사용자가 충전 시스템을 통할 수도 있고, 본인인증 절차를 먼저 밟을 수도 있다. 지금까지 이 경로들이 명시적으로 문서화되지 않으면서, 신규 팀원들이 온보딩할 때마다 "어느 경로가 정식이고 어느 게 대체 경로냐"는 질문을 받곤 했다.
읽기 → -
문서를 의심하라
운영 문서의 신뢰성에 대한 규칙을 하나 추가했다. 간단해 보이지만 팀 문화에 작은 변화를 주는 항목이다.
읽기 → -
Play 구독 검증 환경 설정 누락 방지
한 서비스에 새로운 결제 수단이나 구매 검증 로직이 생기면, 그걸 운영하기 위해 꼭 필요한 환경 변수들이 있다. 이번에는 bible.스튜디오.com 백엔드에서 Play 구독 구매검증을 할 때 필요한 설정값들을 docs/sites-detail.md 문서에 정리했다. 단순한 문서 추가처럼 보이지만, 이 작은 작업이 배포 단계에서의 실수를 얼마나 줄일 수
읽기 → -
AdMob 광고 인벤토리를 중앙 정책으로 통일
모바일 플랫폼의 광고 네트워크 신뢰 설정을 한곳에 정리했다. AdMob app-ads.txt 관련 인프라 노트를 중앙 정책 문서(docs/스튜디오-CLAUDE.md)에 추가한 작업인데, 이게 생각보다 흥미로운 팀 관리 포인트라 기록해 둔다.
읽기 → -
다국어 지원 기능, 팀이 모르면 없는 거나 마찬가지
이미 구현되어 있던 위젯의 다국어(i18n) 지원 기능을 CLAUDE.md에 명시적으로 기록했다. 아주 작은 변경이지만, 팀 전체의 개발 효율과 중복 방지에 생각보다 큰 영향을 미친다.
읽기 → -
위젯의 감춘 지역화 기능 문서에 명시
프로젝트 공통 가이드 문서에 한 위젯이 지역화(i18n) 기능을 지원한다는 점을 명시했다. 겨우 한 줄 주석처럼 들릴 수 있지만, 소규모 팀에서 일하면서 느낀 건 이런 사소해 보이는 문서화가 얼마나 중요한지였다.
읽기 → -
Cloudflare 설정 관리를 단일 진실에 통합
Cloudflare 토큰과 설정 정보를 ops SSOT(Single Source of Truth) 문서에 명시적인 포인터로 추가했다.
읽기 → -
정산 최종 보고서를 저장소에 기록한 이유
결제 플랫폼과의 정산 완료 보고서를 깃 저장소에 PDF로 보관하기 시작했다. 한 줄 커밋이지만, 이 뒤에는 우리 팀이 결제 도메인에서 배운 작은 실수들이 담겨 있다.
읽기 → -
데이터 소유권 모델 정의로 팀 간 혼선 해결
동료 팀과 공유하는 데이터에 대해 명확한 소유 모델을 정의하고, 이를 문서에 기록했다. .md=진실 / DB=단방향미러 라는 단순하지만 명시적인 규칙을 세우면서, 동시에 특정 마이그레이션(/p/{id})을 하지 않기로 결정한 그 배경도 함께 남겼다.
읽기 → -
글 저장소 이중 기록 방식 기록 완성
동료가 작성한 데이터 레이어 설명 문서를 검토하다가 놓친 부분을 발견했다. 글이 단순히 하나의 데이터 저장소에만 쌓이는 줄 알았던 기록이 있었는데, 실제로는 두 곳에 중복으로 기록되는 하이브리드 방식이었다. cms_post DB에 별도로 id를 부여하고 적재되는 구조였는데, 그 부분의 설명이 누락되어 있었다. 91건 규모의 데이터가 이 방식으로 처리되고 있
읽기 → -
인프라 설정 문서를 동료와 정합했다
개인 저장소에서 팀 저장소로 전환하면서 마주하는 문제 중 하나가 **문서와 현실의 괴리**다. 특히 여러 사이트가 각기 다른 설정을 갖고 있을 때, 누가 언제 어떤 설정을 적용했는지, 그 설정이 왜 필요한지가 명확하지 않으면 나중에 유지보수하는 사람은 그야말로 지뢰밭을 걷게 된다. 이번엔 한 사이트의 인프라 설정 정보를 동료와 맞추고, 그 과정을 사이트 상
읽기 → -
서버 봇 지침 관리 일관성 확보
예전부터 여러 서버 인스턴스에 올려진 자동화 봇들이 각자 로컬 CLAUDE.md를 가지고 있었는데, 실제로는 전체 봇이 따라야 할 공통 규칙들이 있다. 이번에 그 공통 규칙을 ops 리포의 중앙화된 docs/server-global-CLAUDE.md에 한데 모으고, 각 서버의 /home/스튜디오/.claude/CLAUDE.md를 symlink로 가리키
읽기 → -
3년 쌓인 백업 파일 한 번에 정리한 기록
이번엔 인프라 정리 작업에 대한 회고다. 서버 스토리지를 둘러본 어느 날, 2.9GB를 차지하고 있는 .bak 디렉토리와 구식 archive 파일들을 발견했다. 단순히 디스크를 회수하는 것을 넘어서, 팀의 백업 정책과 레거시 관리 프로세스를 재점검하는 기회가 됐다.
읽기 → -
설정 문서의 평문 비밀 정보 제거
도입부: CLAUDE.md 파일에서 평문으로 노출되어 있던 DB 비밀번호를 발견하고 secrets.env 참조로 정리했다. 사소해 보이는 변경이지만, 팀 공동 문서의 보안 위험을 줄이는 중요한 작업이었다.
읽기 → -
지침 파일 분산 관리를 캐스케이드로 통합
Claude 봇들이 작동할 때 로드되는 지침 파일 CLAUDE.md 를 여러 환경에 걸쳐 관리하면서 문제가 생겼다. Mac 로컬 환경과 서버 환경에서 지침이 따로 존재하다 보니, 공통 규칙을 변경할 때마다 양쪽을 동시에 업데이트해야 했고, 손으로 직접 편집하면서 불일치가 발생할 수 있었다. 이번에 이 문제를 단일진실(single source of truth
읽기 → -
봇 지침 중복 제거로 운영 복잡도 낮추기
여러 봇과 도구가 함께 작동하는 환경에서 각각의 설정 지침을 관리하는 것은 생각보다 복잡하다. 내 경우, 공용 서버에서 동작하는 여러 봇들이 각자의 CLAUDE.md 를 가지고 있었는데, 공통 정책은 항상 중복되고, 어느 것을 수정해야 하는지 불명확했다.
읽기 → -
반복되는 지침을 계층별로 관리하기
telebot 이라는 새 봇을 배포하면서, 해당 봇만의 CLAUDE.md 를 추가하는 작업을 진행했다. 이것만 보면 단순한 문서 파일 생성처럼 보이지만, 사실 이 작업의 핵심은 **지침(프롬프트 정책)을 계층적으로 관리하는 구조를 구현**하는 것이었다.
읽기 → -
계층화된 지침 구조로 문서 관리 효율성 높인 일
admin 도구와 관련된 지침을 CLAUDE.md에 추가하면서, 동시에 문서의 계층화 구조를 정리했다. 서버에서 실제 동작을 검증하며 느낀 문서 설계의 중요성을 정리해본다.
읽기 → -
팀 규칙 문서를 계층별로 정리
CLAUDE.md는 우리 팀이 각 프로젝트와 환경에서 따르는 공통 지침이다. 이번 커밋은 작지만, 그 배경에는 "여러 계층의 문서들이 어떻게 연결되어 있는가"를 명시하고 검증하는 의도가 담겨 있었다.
읽기 → -
봇 지침 계층화로 전사 중복 제거
최근 여러 팀과 사이트가 사용하는 AI 봇들의 지침 파일(CLAUDE.md) 관리 구조를 개선했다. 개별 봇이나 사이트마다 전사 공통 규칙을 반복해서 작성하는 비효율을 없애기 위해 캐스케이드 방식의 계층화를 도입한 작업이다.
읽기 →