조직에 최적화된 이슈 트래커/문서화 도구 만들기

## 왜 직접 만들었습니까

회사에 기획자, 개발자, QA, 디자이너가 있습니다. 개발자는 GitHub Issue를 쓰고, 기획자는 스프레드시트를 쓰고, QA는 Google Chat에 버그를 올립니다. 이슈가 세 곳에 흩어져 있으니 매번 "그 건 어디에 있어요?"가 반복됐습니다.

각자의 툴이 다르고 비논리적이고 정리되지 않은 협업이 쌓여만 가는 와중에 개발자와 비개발자 모두에게 유용한 칸반 보드가 필요했습니다.

## 진행방법

Claude Code와 함께 대화를 시작하며 세가지 조건을 가지고 기획부터 시작했습니다.

- 비개발 직군이 메인 사용자 (개발자는 GitHub가 주력)

- GitHub Issue 양방향 동기화 (개발자가 두 곳에 입력하지 않게)

- 서버 비용 $0/월 (사이드 프로젝트니까)

### 기술 선택 — Full Cloudflare 서버리스

인프라 논의에서 네 가지 옵션을 검토했습니다.

옵션 A를 선택했습니다.

Claude는 인프라에 대한 장단점을 정리해주었습니다. 프론트엔드 개발자였던 제 입장에서 생소한 서비스는 클로드와의 대화를 통해 기능을 확인하고 조직 규모와 환경에 적절한 선택을 할 수 있도록 도와줬습니다.

최종 스택:

프론트엔드: React 19 + Vite + Tailwind v4 + shadcn/ui
백엔드:    Hono + Drizzle ORM + D1(SQLite) + R2(파일)
실시간:    Durable Objects WebSocket
인프라:    Cloudflare Pages + Workers
비용:      $0/월

저는 Cloudflare 서버리스 서비스를 처음 접해봤습니다. 물론 호스팅이나 CDN서비스를 계속 사용해오고 있었으나 cloud를 사용한건 이번이 처음입니다. 그러나 클로드는 웹에서 필요한 세팅도 코치해주기 때문에 배포 세팅이 그렇게 오래 걸리지 않았습니다. 진행하면서 막히는게 있다면 그저 물어보기만 하면 됩니다.

### 1단계: 설계 — AI와 팀 토론 시뮬레이션

Claude Code에 기획자, 개발자, QA, 디자이너 역할을 맡겨서 각 관점에서 요구사항을 도출했습니다. 이 과정에서 핵심 설계 결정 두 가지가 나왔습니다.

보드 구조. 처음에는 "프로젝트별 칸반 보드"였다가, 2차 토론에서 뒤집었습니다. 이 트래커의 주 사용자가 비개발 직군이라면, 프로젝트를 오가는 것보다 한 화면에서 필터로 전환하는 게 더 편합니다. "통합 칸반 보드 + 프로젝트 필터"로 확정했습니다.

계정 연동. Google OAuth 단일 로그인으로 결정했습니다. GitHub 계정이 없는 기획자/디자이너도 모든 기능을 쓸 수 있어야 합니다. GitHub 미연동 사용자의 이슈는 GitHub App(Bot)이 대리 생성합니다.

### 2단계: 칸반 보드 — 핵심 업무 허브

가장 많은 기능이 집중된 영역입니다.

- DnD 칸반 보드: @dnd-kit 기반 드래그앤드롭, Optimistic Update로 즉각 반응

- 복합 필터링: 우선순위/카테고리/담당자/라벨 조합, URL과 사용자 preferences 양방향 동기화

- 리스트 뷰: 칸반/리스트 토글, 모바일에서는 컬럼별 아코디언으로 자동 전환

- 이슈 상세: TipTap 에디터, 댓글, R2 첨부파일, 프로젝트 변경

- 빠른 생성: 제출 즉시 입력창 초기화, 서버 응답을 기다리지 않고 연속 입력

### 3단계: 외부 연동 — GitHub + Google Chat

개발자는 GitHub를, 비개발 직군은 이슈 트래커를 쓰되 양쪽이 동기화되는 구조입니다.

- GitHub 양방향 동기화: 이슈 생성/수정/이동/삭제/댓글이 양방향으로 반영됩니다. 한글 이슈는 영어로 자동 번역 후 GitHub에 업로드됩니다.

- GitHub 상태↔칼럼 매핑: 설정 페이지에서 GitHub close/reopen 시 이동할 칼럼을 지정합니다.

- Google Chat 알림: Card v2 포맷으로 5개 이벤트(생성/이동/댓글/close/reopen)를 알립니다. 딥링크(`?issue=xxx`)로 알림에서 바로 이슈를 열 수 있습니다.

- 무한 루프 방지: Congkong→GitHub 댓글에 서명을 넣고, Webhook에서 해당 서명을 감지하면 무시합니다.

### 4단계: 모바일 최적화

Google Chat 딥링크로 진입하는 모바일 시나리오가 가장 빈번하다는 걸 확인하고, 3 Phase에 걸쳐 최적화했습니다.

- 하단 탭바, 칸반 대신 리스트 강제, 풀스크린 모달

- 터치 타겟 44px, 필터 바텀시트

- 아코디언 뷰에서 네이티브 select로 상태 변경

### 5단계: Congkong Docs — 기존 인프라 100% 재활용

사내 문서가 Google Docs, Notion, 로컬 파일에 흩어져 있던 문제를 해결했습니다. 새로운 인프라 없이 기존 D1/R2/Workers 위에 Docs를 추가했습니다.

- TipTap 에디터 + 자동 저장, 폴더 트리, Cmd+K 검색

- 파일 DnD 업로드, Mermaid 다이어그램 렌더링, 마크다운 자동 변환

- 퍼블리싱(공개 링크 공유), 사이드바 리사이즈, PDF 뷰어

- JWT 쿠키 domain을 .congkong.net으로 확장하여 재로그인 불필요

### 6단계: 대시보드 + 다국어 + 브랜드

- 대시보드: KPI 카드 4종 + 칼럼/우선순위/카테고리/담당자별 CSS 바 차트, WebSocket 실시간 갱신

- i18n: 한국어/영어/힌디어 3개 언어, 브라우저 감지 + 프로필 선택기

- 한/영 자동 번역: 이슈/댓글 작성 시 비동기 번역, 원문+번역 병기 표시

- 다크모드: BX 브랜드 컬러 기반 Deep Charcoal 6단계 팔레트, 26개 컴포넌트 일괄 적용

저희 조직에는 인도 개발자가 있습니다. 커뮤니케이션을 위해 안되는 AI번역과 하찮은 영어를 사용해 협업하고 있었죠. 구성원 각자의 언어로 입력하여 각자가 편한 언어로 업무를 확인하는 것이 불필요한 번역 과정을 해소해줄것이라고 생각하여 도입한 기능으로 구글 번역 API를 이용하였습니다.

## 바이브코딩에서 배운 것

### 1. 설계 문서가 프롬프트입니다

Claude Code에게 "칸반 보드 만들어줘"라고 하면 평범한 결과가 나옵니다. 하지만 팀 토론 기록, 보드 구조 결정 과정, 기술 선택 근거를 먼저 문서로 만들어두면, 그 맥락 위에서 구현합니다. 설계 문서 품질이 곧 코드 품질입니다.

프로젝트 루트의 CLAUDE.md에 스키마, API 목록, 컨벤션을 정리해두면, 매 세션마다 프로젝트 설정을 반복할 필요가 없습니다. 프로젝트가 커질수록 이 파일의 가치가 올라갑니다.

### 2. 대화형 설계가 놀랍도록 잘 됩니다

보드 구조를 "프로젝트별"에서 "통합 + 필터"로 바꾼 건, AI에게 여러 역할을 맡긴 2차 토론에서 나왔습니다. 실제 팀 회의와 다른 점은 감정적 대립 없이 결론에 도달한다는 것입니다. 다만, 실제 사용자의 암묵지는 AI가 대체할 수 없으니 실사용 피드백은 별도로 수집해야 합니다.

### 3. AI는 "초벌 구현자"로 가장 강합니다

GitHub 양방향 동기화, WebSocket 실시간, 복합 필터 URL 인코딩 같은 기능을 처음부터 구현하라고 하면 놀라울 정도로 빠릅니다. 하지만 플랫폼 특화 에지 케이스(D1의 PRAGMA 미지원, CF Pages의 UTF-8 검증 실패 등)는 함께 삽질하는 수밖에 없었습니다.

AI에게 80%를 빠르게 만들게 하고, 나머지 20%는 직접 디버깅하며 AI를 보조 도구로 활용하는 것이 효과적입니다.

### 4. 기반 코드가 탄탄하면 이후 작업이 기하급수적으로 빨라집니다

DB 스키마와 API를 견고하게 만들어두니, 그 위의 UI 작업은 하루에 10개 이상의 기능을 쌓아올릴 수 있었습니다. 보드 구조를 초반에 바꾼 결정이 없었다면, 이후 작업의 절반은 리팩토링이었을 것입니다.

## 결과물 요약

## 마치며

바이브코딩은 "AI가 코드를 대신 짜주는 것"이 아닙니다. 설계를 대화로 하고, 구현을 가속하고, 반복을 자동화하는 것입니다. 기획서를 쓰는 시간이 줄어드는 게 아니라, 기획서가 곧 구현 프롬프트가 되는 것입니다.

14일 동안 가장 많은 시간을 쓴 건 코딩이 아니라 의사결정이었습니다. AI는 결정을 돕지만 대신 해주지는 않습니다. 결국 좋은 제품은 좋은 판단에서 나옵니다.

다만, 그 판단이 코드가 되기까지의 시간이 극적으로 줄어듭니다. 그게 바이브코딩의 진짜 가치입니다.