월 매출 38만 달러 앱의 CLAUDE.md: 규칙은 사고가 난 날 생겼고, 가장 많이 고친 곳엔 규칙이 없었다

월 매출 38만 달러 앱의 CLAUDE.md: 규칙은 사고가 난 날 생겼고, 가장 많이 고친 곳엔 규칙이 없었다

한 달 구독 매출이 38만 달러인 앱이 있습니다. 코드가 GitHub에 공개돼 있는데, Claude Code에게 주는 규칙 파일 CLAUDE.md까지 같이 공개돼 있습니다.

그 파일의 변경 기록을 따라가 보면, 규칙 대부분이 실제 사고를 고친 그날 생겼습니다. 그런데 더 재미있는 점이 있습니다. 가장 많이 고친 곳에는 규칙이 한 줄도 없습니다.

이 글에서는 다음을 차례로 봅니다.

  1. Postiz는 어떤 앱이고, CLAUDE.md는 무엇인가
  2. 설정 전체 그림: 부탁(CLAUDE.md)과 강제(settings.json)
  3. 규칙이 생긴 날과 그날의 버그
  4. 이 팀이 놓친 곳
  5. 교훈을 어디에 둘까
  6. 같은 모양의 작은 앱으로 직접 고쳐 보기
  7. 규칙이 정말 효과가 있나: 5회씩 실측

숫자 읽는 법. [공식 문서] 는 Postiz 저장소 기록이나 Anthropic·Stripe 같은 회사가 직접 낸 자료, [직접 측정] 은 저희가 직접 세거나 돌려 본 숫자, [커뮤니티 보고] 는 사용자 제보나 제3자 사이트 값입니다. 숫자는 2026년 11월 8일에 본 값입니다.

1. Postiz와 CLAUDE.md

TrustMRR의 Postiz 페이지. MRR 387,731달러, 활성 구독 11,400개

결제 계정을 직접 연결해 매출을 인증해 주는 사이트 TrustMRR에 따르면, Postiz의 MRR(매달 반복해서 들어오는 구독 매출)은 387,731달러, 활성 구독은 11,400개입니다 [커뮤니티 보고] (TrustMRR). 제품은 오픈소스이고, 커밋 기록으로 보면 핵심 개발자는 세 명입니다.

Postiz는 소셜 미디어 글 예약 앱입니다. 글을 써서 달력에 올려 두면, 정해진 시각에 뒤에서 도는 작업(워크플로)이 깨어나 X, Instagram, LinkedIn, YouTube 같은 스물여덟 개가 넘는 채널에 대신 글을 올립니다. 남의 플랫폼에 대신 글을 올리고 구독료를 받는 앱이라, 플랫폼 연결이나 결제가 깨지면 손님이 바로 떠납니다.

Claude Code는 터미널에서 코드를 읽고 고치는 AI 에이전트입니다. CLAUDE.md는 프로젝트 폴더에 두는 글자 파일 하나로, Claude Code가 일을 시작할 때 먼저 읽습니다 [공식 문서] (Claude Code 메모리 문서). 새로 온 동료에게 건네는 안내문이라고 생각하면 됩니다.

2. 설정 전체 그림: 부탁과 강제

Postiz 저장소 맨 위에는 .claude 폴더가, 조금 아래에는 CLAUDE.md가 있습니다.

CLAUDE.md 에는 크게 다섯 가지가 들어 있습니다 [공식 문서] (CLAUDE.md).

  • 지도: apps 아래에 백엔드, 뒤에서 도는 작업(오케스트레이터), 프론트엔드가 있고 공유 코드는 libraries에 있다는 설명. 이게 없으면 에이전트가 코드를 엉뚱한 폴더에 만들거나 있는 기능을 또 만듭니다.
  • 패턴: 백엔드는 Controller → Service → Repository 순서로 쓰고 "no shortcuts", 지름길 금지. 에이전트는 빨리 끝내려고 Controller에서 바로 DB를 부르는 코드를 곧잘 쓰는데, 그러면 권한 검사와 입력 검사가 통째로 빠집니다.
  • 운영 사고에서 나온 규칙: 아래 3절에서 봅니다.
  • 먼저 물어보라는 규칙
  • PR 확인 절차: 리뷰어가 따라 할 수 있는 확인 방법을 쓰라는 규칙

.claude/settings.json 은 짧습니다. 전부 deny, 거부 목록입니다. .env 파일을 읽는 길을 Read, Edit뿐 아니라 cat, head, tail, vim까지 하나씩 막았습니다 [공식 문서] (settings.json).

왜 이것만 따로 막았을까요. 문서에 쓴 규칙은 메모지입니다. 보통은 지키지만 대화가 길어지면 잊을 수 있습니다. 권한 설정은 잠긴 문입니다. 시도하는 순간 시스템이 거절합니다 [공식 문서] (Claude Code 설정 문서). 비밀 값은 한 번만 새도 끝이니까, 메모지가 아니라 자물쇠를 건 겁니다. 이 글 내내 이 구분이 나옵니다.

3. 규칙이 생긴 날

CLAUDE.md 변경 기록. 10월 5일 웹훅 규칙, 10월 1일 자격 증명 규칙, 9월 30일 공유 조회 규칙

CLAUDE.md는 1월 30일에 처음 생겼고, main 브랜치에 커밋이 열한 번 있습니다 [공식 문서] (변경 기록). 첫날에는 지도와 패턴뿐이었고 운영 규칙은 한 줄도 없었습니다. 규칙을 미리 상상해서 쓰지 않았다는 뜻입니다.

그 뒤로 보안 수정, .env 차단, 워크플로 수정, 조회 함수 변경, 테스트 도입, 응답 노출과 결제 웹훅까지, 사고가 날 때마다 한 줄씩 붙었습니다. 규칙이 추가된 날과 같은 영역의 버그를 고친 날을 나란히 놓으면 거의 겹칩니다. 날짜를 맞춰 본 것이라 일부 대응은 저희 추정입니다.

워크플로: 배포된 순서표는 고치지 않는다

워크플로는 며칠에 걸칠 수도 있는 긴 일의 순서표입니다. 글을 받고, 기다리고, 플랫폼에 올리고, 결과를 기록합니다. Postiz가 쓰는 Temporal은 기록을 되짚어 어디까지 했는지 찾는데 [공식 문서] (Temporal 워크플로 정의), 기다리는 도중에 순서표 중간에 단계를 끼워 배포하면 기록과 새 순서표가 맞지 않아 기다리던 작업이 실패합니다.

그래서 규칙은 "한번 main에 들어간 워크플로는 바꾸지 말고 새 버전을 만들어라"이고, 이유(바꾸면 모든 액티비티가 실패한다)까지 적혀 있습니다. 이유가 있어야 에이전트가 비슷한 다른 상황에도 적용할 수 있습니다. 바로 옆에는 "추가한 코드는 기존 코드와 비슷해 보여야 하고, 끝나면 다른 에이전트로 이상한 패턴이 없는지 대조하라"는 검사 절차도 있습니다.

공유 조회: 바꾸기 전에 쓰는 곳을 전부 찾아라

조직 정보를 읽는 공유 함수 하나를 웹 화면, 공개 API, MCP 도구, 웹훅이 같이 씁니다. 웹 화면에 칸 하나가 필요해 조회 결과에 넣으면 다른 세 곳에도 같이 나갑니다. 그래서 공유 조회를 바꾸기 전에 쓰는 곳을 전부 찾아보라는 규칙과 함께, "저장된 칸을 외부로 내보내는 건 데이터 노출 결정이니 먼저 물어보라"는 줄이 생겼습니다(9월 30일 커밋). 금지가 아니라 질문입니다. 판단이 필요한 일은 금지보다 질문이 맞습니다.

자격 증명: 주변 코드가 달라 보여도 지켜라

DB의 채널 한 줄에는 이름 말고도 플랫폼 출입에 쓰는 토큰이 들어 있습니다. 이 줄을 그대로 응답으로 돌려주면 다른 사람 계정으로 글을 올릴 수 있는 열쇠가 밖으로 나갑니다. 채널 삭제 API와 조직 목록 API가 필요 이상으로 많은 칸을 돌려주던 것을 고친 뒤, "자격 증명이 든 모델의 행을 응답에 그대로 내보내지 말 것"이라는 규칙이 생겼습니다(10월 1일 커밋). 끝에는 "주변 코드가 달라 보여도 적용하라" 는 문장이 붙어 있습니다. 에이전트는 주변 코드를 따라 하는 습관이 있으니, 나쁜 코드 옆에서도 지키라고 미리 말해 둔 겁니다.

결제 웹훅: 예외를 던지지 말고 잡아서 기록하라

Stripe 구독 중복 방지 PR #2061

웹훅은 고객이 결제하면 결제 회사 Stripe가 우리 서버로 보내는 알림입니다. Stripe는 잘 받았다는 답을 못 받으면 같은 알림을 다시 보내고, 그래서 받는 쪽은 중복 전달을 처리해야 합니다 [공식 문서] (Stripe 웹훅 문서). 처리 코드가 이걸 모르면 같은 알림으로 구독이 두 개 생깁니다.

실제 수정 PR의 제목은 "고객당 Stripe 구독이 중복되지 않게 막는다"입니다 [공식 문서] (PR #2061). 안의 커밋 하나는 웹훅이 재시도될 때 이미 취소된 구독을 또 취소하려다 나던 오류를 막았습니다.

하나가 더 있습니다. 웹훅 처리 도중에 예외가 나면 첫 단계는 저장됐는데 그다음이 실행되지 않습니다. 구독은 있는데 크레딧은 안 들어온 고객, 돈은 냈는데 서비스를 못 쓰는 사람이 생깁니다. 그래서 "웹훅이 부르는 코드에서는 예외를 던지지 말고 잡아서 기록하라"는 규칙이 생겼고(10월 5일 커밋), 마지막 문장은 웹훅이 예외를 던지면 결제 상태가 반쯤만 반영된다는 이유입니다. 사고를 고치고, 왜 위험한지까지 한 문장으로 남기는 것이 Postiz 방식입니다.

4. 이 팀이 놓친 곳

테스트가 늘 빨간불

Postiz 테스트 실행 기록. 줄지어 실패

staging 브랜치의 CLAUDE.md에는 "동작을 바꾸는 PR은 테스트를 추가하거나 고쳐야 한다"는 규칙이 있습니다 [공식 문서] (staging CLAUDE.md). 테스트는 9월 7일에 들어왔고 지금은 테스트 파일이 97개입니다.

그런데 최근 테스트 실행 100회 중 실패가 99회, 성공은 0회였습니다. 10월 8일부터 11월 7일까지 전부 빨간불이었고, 11월 8일 실행에서는 단위 테스트 파일 26개가 실패했습니다 [직접 측정] (테스트 실행 기록). 규칙은 있지만, 빨간불이 일상이 되면 불이 켜져도 아무도 멈추지 않습니다. 빨간불 사이에도 커밋은 계속 들어갑니다.

많이 고친 곳은 규칙이 되지 않았다

올해 staging에 들어간 수정 커밋 418개를 제목 키워드로 영역별로 나눠 봤습니다 [직접 측정].

영역고친 횟수그 영역의 CLAUDE.md 규칙 줄 수
발행·재시도450
토큰340
권한300

제목 키워드로 나눈 값이라 대략이지만 방향은 분명합니다. 한 번에 크게 아픈 사고는 규칙이 됐는데, 작게 수십 번 반복된 사고는 규칙이 되지 않았습니다.

열려 있는 이슈도 이 영역에 몰려 있습니다 [커뮤니티 보고].

  • 토큰: 유튜브 채널을 다시 연결했더니 리프레시 토큰(출입증이 만료되면 새로 받는 재발급권)이 사라져, 한 시간 뒤부터 발행이 아무 말 없이 실패한다는 제보 (#2233)
  • 권한: 일반 사용자 역할이 관리자를 초대할 수 있다는 제보, 2025년 7월에 올라와 아직 열려 있음 (#866)
  • 중복 발행: 글 하나를 예약했는데 X에 17초 동안 네 번 올라갔다는 제보. 제보자는 응답이 늦을 때 확인 없이 다시 보낸 것 같다고 적었습니다. 원인이 확정된 것은 아닙니다 (#2375)

빈자리 일곱 가지

  1. 테스트 빨간불이 일상이 됐다.
  2. 많이 고친 영역이 규칙으로 올라오지 않는다.
  3. 돈이 오가는 흐름의 규칙이 한 줄뿐이다.
  4. 재시도가 중복을 만든다.
  5. 경로 탐색이나 서버 쪽 요청 위조 같은 보안 수정이 규칙으로 남지 않았다.
  6. 문서가 두 벌이다. main에는 프론트엔드가 Vite, staging에는 Next.js라고 적혀 있다.
  7. 되돌릴 수 없는 일까지, 사고가 난 뒤에야 규칙이 됐다. 매출이 이미 커진 다음에.

수익형 앱을 만든다면 이 일곱 가지는 처음부터 막고 시작하면 됩니다.

5. 교훈을 어디에 둘까

같은 교훈도 놓는 자리에 따라 지켜지는 정도가 다릅니다. 아래로 갈수록 가볍고, 위로 갈수록 확실하지만 만드는 비용이 듭니다 [공식 문서] (메모리, 훅, 커맨드).

자리언제 쓰나
권한 차단(settings.json deny)절대 안 되는 일
훅·테스트에이전트가 잊어도 기계가 잡아야 할 일
서브에이전트판단이 필요한 검토를 다른 맥락에서
슬래시 커맨드사람이 시작하는 반복 작업
스킬절차가 길 때
경로 규칙(.claude/rules)그 폴더를 건드릴 때만 필요한 지식
CLAUDE.md 한 줄어디서나 통하는 지식

한 줄로 시작하고, 또 터지면 한 칸 올리는 것을 추천합니다.

6. 같은 모양의 작은 앱으로 직접 고쳐 보기

Postiz와 같은 모양으로 작은 예약 앱을 만들었습니다. 달력 화면에서 글을 예약하면 API가 받고, 뒤에서 발행 워커가 시각을 보다가 연습용 SNS 서버에 글을 올립니다. 연습 서버는 X처럼 중복 방지 키가 없습니다. 결제 쪽은 실제 Stripe가 아니라 같은 모양의 알림을 코드로 보내 처리하는 부분만 만들었습니다. 그리고 Postiz 이슈와 같은 종류의 버그 세 개를 심었습니다. 테스트는 전부 통과하는 상태로요.

버그 1: 같은 글이 네 번

연습용 SNS 피드에 같은 글이 4개

플랫폼 응답이 조금 늦는 상황을 만들자 같은 글이 네 개 올라갔습니다 [직접 측정]. 워커가 글을 보내고, 플랫폼은 저장까지 끝냈는데 답이 늦어 워커의 기다리는 시간이 끝납니다. 워커는 실패한 줄 알고 다시 보냅니다. 응답이 늦은 건 실패가 아니라 "모르는 상태" 입니다. 다시 보내기 전에 이미 올라갔는지 먼저 확인해야 합니다.

결제도 같은 알림을 두 번 보내자 구독이 두 개, 크레딧이 200이 됐습니다. 한 번 결제했는데 두 번 받은 겁니다 [직접 측정].

Claude Code에게 맡기기

설정은 Postiz처럼 처음부터 지도 파일과 .env 차단을 넣어 뒀습니다. 일부러 .env를 열어 달라고 하자, 권한 설정에서 막혀 있어 열지 못했다고 답했고 cat 같은 다른 방법으로 우회하지도 않았습니다.

버그를 맡길 때 부탁은 세 덩어리였습니다. 이슈를 고쳐 달라, 실패하는 테스트부터 만들어 달라, 같은 실수가 다시 안 나오게 규칙을 남겨 달라. 테스트를 먼저 쓰고 고치기 전에 실패하는 것을 보는 게 중요합니다. 고친 뒤에 쓰면 처음부터 통과해서, 그 테스트가 정말 버그를 잡는지 알 수 없습니다.

발행 버그는 재전송을 없애고, 응답이 늦으면 글이 올라갔는지 확인한 뒤 올라갔을 때만 완료로 기록하도록 고쳤습니다. 보내기 전에 글을 먼저 차지하는(선점) 처리도 같이 들어갔습니다.

경로 규칙

.claude/rules/worker.md. 맨 위 paths가 적용 범위

규칙은 .claude/rules 폴더에 파일로 생겼습니다. 맨 위 paths에 경로를 적으면, Claude Code가 그 경로의 파일을 건드릴 때만 이 규칙을 읽습니다 [공식 문서] (메모리 문서). 메인 CLAUDE.md에 다 쓰면 결제를 고칠 때도 발행 규칙을 읽어야 하지만, 이렇게 나누면 필요할 때만 불러옵니다. 내용은 "타임아웃은 실패가 아니라 결과를 모름"이고, 마지막 줄은 "발행 경로를 바꾸면 응답 지연 테스트를 넣고 올라간 글 개수를 확인하라"입니다. 규칙과 검사 방법을 같이 적었습니다.

결제 버그는 처리한 알림 ID를 기록해 이미 처리한 알림은 건너뛰고, 전체 처리를 트랜잭션(다 되거나 아예 안 되거나 둘 중 하나만 있는 묶음)으로 묶었습니다. 구독은 있는데 크레딧이 없는 상태가 사라집니다. 시키지 않았는데 웹훅 서명 검증이 없어 누구나 가짜 알림으로 크레딧을 받을 수 있다는 점도 짚어 줬습니다. 맞는 말입니다. 실제 Stripe 웹훅은 서명을 확인해야 합니다 [공식 문서] (Stripe 웹훅 문서).

토큰 노출 버그는 응답 칸을 id, name, platform으로 제한했고, 이미 밖으로 나간 토큰은 폐기하고 다시 발급해야 한다고 알려 줬습니다. 규칙 파일에는 응답을 만드는 쿼리에 SELECT *를 쓰지 말라는 줄이 들어갔습니다. 테이블에 칸이 추가되면 저절로 따라 나가기 때문입니다.

Stop 훅: 빨간불에서 끝내지 못하게

settings.json의 Stop 훅. 테스트가 실패하면 종료 코드 2

놓친 것 첫 번째, 빨간불이 일상이 되는 문제를 막습니다. 훅은 에이전트가 특정 시점에 이르면 시스템이 대신 실행하는 명령이고, Stop은 에이전트가 일을 끝내려는 순간입니다. 이 훅은 pnpm test를 돌리고 실패하면 종료 코드 2로 끝납니다. 종료 코드 2를 받으면 그 메시지가 에이전트에게 전달되고, 에이전트는 끝내지 않고 이어서 일합니다 [공식 문서] (훅 문서).

새 세션에서 일부러 "크레딧 값을 200으로 바꾸고, 테스트는 돌리지 말고 바로 끝내"라고 부탁했습니다. webhook.ts를 읽자 billing.md 경로 규칙이 따라 불려 왔고, 끝내려는 순간 훅이 테스트를 돌려 6개가 실패했습니다. 결국 실패한 기댓값을 고치고 나서야 끝났습니다 [직접 측정]. 다만 값을 실수로 바꾼 경우라면 테스트를 고칠 게 아니라 사람이 이 변경을 봐야 합니다.

rule-audit 커맨드: 반복되는 사고를 숫자로

놓친 것 두 번째, 많이 고친 곳이 규칙으로 안 올라오는 문제는 사람이 잘 못 느낍니다. 그래서 세어 주는 커맨드를 만들었습니다. .claude/commands에 rule-audit.md를 두면 /rule-audit으로 부를 수 있습니다 [공식 문서] (커맨드 문서). 저장소 경로를 받아 수정 커밋과 규칙 줄 수를 세서 표로 보고하고, 파일은 바꾸지 않습니다.

실제 Postiz 저장소에 돌리자 최근 6개월 수정 커밋 410개를 찾았고, 가장 많이 고친 libraries 폴더에는 전용 규칙이 없다고 나왔습니다 [직접 측정]. 앞에서 손으로 센 것과 같은 방향입니다. 한 달에 한 번 돌리면, 작게 반복되는 사고가 언제 규칙이 돼야 하는지 숫자로 보입니다.

7. 규칙이 정말 효과가 있나

처음 상태의 앱에 새 기능 세 가지를 부탁했습니다. 규칙 없는 상태와 경로 규칙이 있는 상태로 다섯 번씩, 매번 새 세션으로 돌렸습니다(Claude Code, sonnet 모델, 2026-11-08) [직접 측정].

부탁규칙 없음규칙 있음
"지금 올리기" 버튼에 재시도 넣기 (중복 없이 1개만 올라가면 통과)5/55/5
결제 알림 invoice.paid 처리 추가 (예외를 던지지 않으면 통과)0/55/5
채널 상세 조회 API 추가 (토큰이 안 나가면 통과)5/55/5

재시도와 토큰 노출은 규칙이 없어도 다섯 번 다 막았습니다. 이 정도 일반 상식은 요즘 모델이 스스로 생각합니다. 결제 알림은 달랐습니다. 규칙이 없으면 다섯 번 모두 처음 보는 고객에게 예외를 던졌습니다. 옆 코드가 예외를 던지니까 그대로 따라 한 겁니다. 규칙이 있으면 다섯 번 모두 던지지 않았습니다.

일반 상식은 모델이 이미 압니다. 규칙은 그 앱만의 약속, 주변 코드와 다른 약속을 적을 때 효과가 큽니다. Postiz 규칙에 "주변 코드가 달라 보여도 적용하라"는 말이 있던 이유가 이것입니다.

정리와 한계

정리하면 이렇습니다.

  1. 매출이 큰 앱의 Claude Code 설정은 화려하지 않았습니다. 파일 하나에, 사고마다 이유가 붙은 규칙이 쌓여 있었습니다.
  2. 그대로 따라 할 필요는 없습니다. 돈, 자격 증명, 외부 데이터 노출, 실행 중인 작업, 되돌리기 어려운 이 네 가지는 출시 전에 규칙과 테스트를 먼저 두는 것을 추천합니다.
  3. 나머지는 사고가 났을 때 이유와 함께 한 줄 적고, 또 터지면 한 칸 올리면 됩니다.
  4. 문서만 믿지 말고 기계로 막으세요. Stop 훅으로 빨간불에서 끝내지 못하게 하고, 한 달에 한 번 규칙 점검을 돌립니다.

한계도 있습니다.

  • 규칙 추가일과 버그 수정일의 대응 일부는 날짜를 맞춰 본 추정입니다.
  • 영역별 수정 횟수는 커밋 제목 키워드로 나눈 대략값입니다.
  • 실측은 저희가 만든 작은 연습 앱에서 과제 셋을 조건마다 5회 돌린 결과입니다. 모델·버전·앱이 달라지면 결과도 달라질 수 있습니다.
  • 매출·이슈·테스트 기록은 2026년 11월 8일에 본 값입니다. 읽는 날짜의 원 페이지를 다시 확인하세요.

영상으로 보기

Postiz 설정 파일과 변경 기록, 연습 앱에서 Claude Code로 버그를 고치는 과정을 실제 화면으로 담았습니다.

출처

Postiz (공식 문서) 이슈 (커뮤니티 보고) 매출 (커뮤니티 보고) 문서 (공식 문서)
Comments0
No comments yet.

Related Posts