블로그 자동화 코드 오픈소스화 — GitHub 공개와 포트폴리오 활용

← 27편: 뉴스레터 자동화 — Mailchimp API 연동으로 구독자 관리 시스템 만들기

블로그 자동화 프로젝트를 시작한 지 벌써 네 달 가까이 됐다. 어느 날 문득 이런 생각이 들었다. “이 코드, 내가 이력서에 쓸 수 있지 않나?”

솔직히 처음엔 부끄러웠다. 코드가 지저분하다. 함수 이름도 제멋대로고, 주석도 없고, 에러 처리도 대충이다. 실제로 돌아가는 프로덕션 코드긴 한데, 남한테 보여주기엔 너무 날것 그대로였다. “이걸 GitHub에 올린다고? 창피하지 않나?”

그런데 한편으론 이런 생각도 들었다. 실제로 돌아가는 자동화 시스템을 만든 사람이 얼마나 되겠어. 코드가 좀 지저분해도, 28편 분량의 블로그를 자동 발행하는 시스템을 혼자 만든 건 분명 포트폴리오 가치가 있다. 이 글은 그 과정을 있는 그대로 정리한 기록이다.

공개 전 반드시 해야 하는 것 — 보안 체크부터

GitHub에 올리기로 결심했을 때 가장 먼저 든 생각은 “혹시 API 키가 코드에 박혀 있나?”였다. 예전에 급하게 작업하다 하드코딩했던 부분이 분명히 있을 것 같았다. 실제로 히스토리를 뒤졌더니 아니나 다를까, 초기 테스트할 때 WordPress 비밀번호를 변수에 직접 박아뒀던 커밋이 있었다. 아찔했다.

공개 전 보안 체크 순서는 이렇게 잡았다.

먼저 git log –all –full-history로 전체 커밋 히스토리를 훑으면서 민감 정보가 포함된 커밋이 있는지 확인했다. 있었다. 그래서 공개 레포는 새로 만들고 클린한 상태에서 코드만 복사해서 올리는 방식을 택했다. 히스토리 rebase로 지우는 방법도 있지만, 이미 지저분한 상황에서 히스토리까지 건드리면 더 복잡해질 것 같아서 깔끔하게 새 레포를 파는 걸 선택했다.

다음으로 .gitignore를 먼저 작성했다. 아무리 조심해도 .env 파일을 실수로 add하는 경우가 생긴다. .gitignore에 .env를 추가해두면 그 사고를 원천 차단할 수 있다.

⚙️ 사전 준비: .gitignore 작성 시 .env, *.log, __pycache__/, .DS_Store 등 기본 항목을 반드시 포함한다.

# .gitignore 핵심 항목
.env
.env.*
*.log
__pycache__/
*.pyc
.DS_Store
node_modules/
*.sqlite3

마지막으로 코드 전체에서 하드코딩된 문자열을 grep으로 찾았다. “http://”, “password”, “token”, “secret” 같은 키워드로 검색해서 하나하나 확인했다. 이 과정이 귀찮았지만 절대 건너뛰면 안 된다. 나중에 토큰 탈취당하고 AWS 요금 폭탄 맞는 이야기를 너무 많이 들어왔다.

공개 전 보안 체크는 선택이 아니라 필수다. 새 레포, 새 시작, .gitignore부터 설정하는 것이 가장 안전한 방법이다.

GitHub 레포 구조 — 남이 봐도 이해되게 정리하기

레포를 새로 만들고 나서 폴더 구조를 어떻게 잡을지 한참 고민했다. 내 개인용 코드는 src/ 하나에 다 때려넣는 스타일이었는데, 남이 봤을 때 “아 이건 이런 프로젝트구나” 싶어야 포트폴리오 효과가 있다.

최종적으로 정한 구조는 이렇다.

• ✅ src/ — 핵심 스크립트 (publish.py, threads_post.py, notion_logger.py 등)
• ✅ data/ — 발행 이력(published.json), 토픽 로드맵(topics.json)
• ✅ drafts/ — 작성된 글 원고 (실제 HTML 파일들)
• ✅ .env.example — 환경변수 예시 파일 (실제 값 없이 키 이름만)
• ✅ README.md — 프로젝트 설명 + 설치 가이드
• ✅ requirements.txt — 의존성 명세

여기서 중요한 포인트가 하나 있다. .env.example 파일이다. 실제 .env 파일은 .gitignore에 막혀 있으니, 다른 사람이 이 프로젝트를 클론해서 쓰려면 어떤 환경변수가 필요한지 알 방법이 없다. .env.example을 통해 “WP_URL=”, “WP_PASSWORD=”, “THREADS_ACCESS_TOKEN=” 같은 형태로 키 이름만 적어두면 된다. 이걸 빠뜨리면 사용자가 코드를 열어서 환경변수를 일일이 추적해야 한다. 불친절한 오픈소스가 되는 것이다.

레포 구조는 남이 5분 안에 파악할 수 있어야 한다. 폴더명, .env.example, requirements.txt — 이 세 가지가 갖춰져야 제대로 된 오픈소스다.

README 잘 쓰는 법 — 포트폴리오의 80%는 README가 결정한다

솔직히 README를 대충 쓰면 의미가 없다. 아무리 코드가 좋아도 README가 허술하면 면접관이 “이 사람 협업 못하겠다”고 판단한다. 나는 과거에 GitHub 레포를 만들고 README를 “To Do” 한 줄만 적어두고 방치한 적이 있었는데, 지금 생각하면 정말 부끄럽다.

이번에는 제대로 쓰기로 했다. README에 들어가야 할 핵심 항목들이다.

1. 프로젝트 소개 (3줄 이내) — 이게 뭐고, 왜 만들었고, 어떤 문제를 해결하는지. 길게 쓰면 아무도 안 읽는다.

2. 아키텍처 다이어그램 — 텍스트로만 된 설명은 따라가기 힘들다. 나는 간단한 ASCII 다이어그램을 넣었다. Claude Code가 글 작성 → publish_draft.py → WordPress 발행 + Notion 기록 + Threads 포스팅 이 흐름을 한눈에 보여주는 것만으로도 훨씬 이해하기 쉬워진다.

3. 설치 및 실행 방법 — 코드를 클론하고 실행하는 데까지 필요한 모든 단계를 순서대로. “python publish.py 실행하면 됩니다”만 써두면 `ModuleNotFoundError`가 뜨는 순간 독자는 창을 닫는다. `pip install -r requirements.txt` 부터 시작해야 한다.

4. 환경변수 목록 — .env.example을 인용하거나, 각 변수가 어디서 발급받는지 링크까지 넣어주면 금상첨화다.

5. 기술 스택 및 레이어 설명 — WordPress REST API, JWT 인증, Threads API, Notion API 각각 어떤 역할인지 짧게 설명. 면접에서 이 프로젝트를 소개할 때 구술로 설명하기 전에 문서로 정리가 되어 있으면 훨씬 자신감이 생긴다.

README는 코드보다 먼저 읽힌다. 프로젝트의 첫인상이자 포트폴리오의 80%를 결정짓는 문서다.

코드 정리 — 부끄럽지 않을 최소한의 기준

공개를 결심하고 나서 코드를 다시 보니까 진짜 너무 지저분했다. 변수명이 `a`, `b`, `tmp`인 것들이 있었고, 에러 핸들링이 없어서 요청 실패하면 그냥 500 에러 떨어지는 것도 있었다. 완벽하게 리팩터링하면 좋겠지만, 그러면 영원히 못 올린다. “완벽한 시스템보다 일단 돌아가는 것 먼저”라는 내 원칙을 코드에도 적용했다.

최소한의 기준만 잡았다.

• ✅ 함수명과 변수명은 의미를 알 수 있게 — a 같은 건 전부 수정
• ✅ 각 함수에 한 줄 docstring — 이 함수가 뭘 하는지 한 줄만
• ✅ API 호출 부분에는 try/except + 실패 시 명확한 에러 메시지 출력
• ✅ 마법 숫자(magic number)는 상수로 — category_id = 3 같은 건 변수에 담기

이 네 가지만 지켜도 “최소한 이 사람은 코드를 읽히게 쓸 줄 안다”는 인상은 줄 수 있다. 완벽한 아키텍처나 디자인 패턴은 나중 문제다. 일단 읽히는 코드가 먼저다.

사실 이 과정에서 가장 도움이 됐던 건 블로그에 이 시리즈를 쓰고 있다는 사실 자체였다. “이 코드를 블로그에서 설명해야 한다”고 생각하니 자연스럽게 남이 읽기 좋은 코드를 쓰게 되더라. 기록이 코드 품질을 높이는 부수 효과가 있었다.

완벽한 코드를 기다리다가는 영원히 못 올린다. 읽히는 코드, 에러를 감추지 않는 코드, 이 두 가지만 지켜도 충분히 공개할 만하다.

포트폴리오로 활용하기 — 이 프로젝트의 진짜 가치

GitHub 레포를 공개하고 나서 이걸 포트폴리오로 어떻게 활용할지 고민했다. 단순히 “이런 프로젝트 했습니다”가 아니라, 이 프로젝트가 왜 가치 있는지를 보여줘야 한다.

내가 이 프로젝트로 어필하려는 포인트는 크게 세 가지다.

첫째, 실제로 운영 중인 프로젝트라는 점. 많은 포트폴리오 프로젝트가 “만들어놓고 방치”다. 이 시스템은 지금도 매일 돌아가고 있고, 28편의 글이 실제로 발행됐다. commit history를 보면 매일 업데이트되는 걸 확인할 수 있다. “살아있는 프로젝트”라는 건 생각보다 강력한 차별점이다.

둘째, 여러 외부 API를 연동한 경험. WordPress REST API(JWT 인증), Threads API(OAuth), Notion API, GitHub Actions — 단순한 CRUD가 아니라 다양한 인증 방식과 API 통합을 경험했다는 걸 코드로 보여줄 수 있다.

셋째, 문제를 스스로 정의하고 해결했다는 것. “블로그 자동화”라는 비즈니스 문제를 기술로 해결하는 과정 전체를 기록했다. 이건 단순 구현 능력이 아니라 문제 정의와 설계 능력을 보여주는 것이다. 면접에서 “이 프로젝트에서 가장 어려웠던 점”을 물어보면 할 말이 넘친다.

이력서에는 GitHub 링크와 함께 “실제 운영 중인 AI 블로그 자동화 파이프라인 구축 — WordPress, Threads, Notion API 연동, GitHub Actions 기반 CI”라고 한 줄로 정리했다. 이걸 보고 궁금해하는 사람이 링크를 클릭하면, 잘 정리된 README와 실제 돌아가는 코드가 나온다. 내가 말로 설명하는 것보다 훨씬 강력하다.

실제로 돌아가는 프로젝트 하나가 만들어놓고 방치한 열 개보다 강하다. 이 시스템의 포트폴리오 가치는 “살아있다”는 것 하나만으로도 충분하다.

공개하고 나서 느낀 것들

솔직하게 털어놓자면, 오픈소스 공개가 생각보다 떨렸다. 코드를 공개한다는 건 내 실력을 세상에 노출하는 것이기도 하다. “이 코드 보고 비웃으면 어떡하지”라는 생각이 들었다. 5년차라고 이런 지저분한 코드를 공개한다고 창피하지 않나.

그런데 공개하고 나니 오히려 홀가분했다. “어차피 공개됐으니까 더 잘 짜야지”라는 동기부여가 생겼다. 코드를 고칠 때 “이걸 남이 봐도 이해하나?”를 기준으로 생각하게 됐다. 부끄러움이 품질을 높이는 동기가 된 것이다.

그리고 의외의 수확도 있었다. 블로그 시리즈를 읽다가 GitHub 레포를 발견한 독자가 Star를 눌러줬다. 처음 받아본 Star였는데, 솔직히 뭔가 뭉클했다. 혼자 묵묵히 짜던 코드가 누군가에게 닿았다는 기분이 이런 거구나 싶었다.

아직 갈 길이 멀다. 테스트 코드도 없고, 문서화도 더 필요하다. 하지만 지금 이 상태로도 공개하길 잘했다. 완벽함을 기다리다가 아무것도 못 공개하는 것보다, 일단 공개하고 조금씩 나아지는 편이 훨씬 낫다.