Grovarc 개발기 #2 — 설계 산출물 완성 & GitHub 프로젝트 세팅

Phase 0의 목표는 ‘코드 없이 설계를 완성하는 것’이었다. 유저 플로우, DB 스키마, API 명세를 문서로 먼저 정리하고, GitHub Projects로 전체 로드맵을 관리할 수 있는 틀을 잡았다.

목표

docs/ 설계 산출물 4종 완성
GitHub Projects 에픽-태스크 계층 구조 세팅
브랜치 전략 확립

핵심 구현 포인트

1) 유저 플로우 설계 — MVP 범위 확정

서비스 흐름을 A~E 5개 시나리오로 정리했다.

A. 온보딩         → 회원가입 → 프로필 설정 → 첫 로그 작성 유도
B. 일상 루프      → 로그 작성 → AI 즉각 피드백 → 대시보드
C. 주간 회고      → Celery Beat 자동 실행 → 초안 생성 → 유저 검토
D. 성장 코칭      → 3개월 로그 분석 → 로드맵 생성 (MVP 이후)
E. MCP 연동       → Cursor에서 로그/회고 직접 조회 (MVP 이후)

MVP는 A+B+C만 포함. D와 E는 Phase 이후로 미뤘다.

2) DB 스키마 — pgvector 포함 6개 테이블

PostgreSQL 기반으로 핵심 테이블 6개를 설계했다. RAG를 위한 벡터 컬럼도 처음부터 포함시켰다.

-- work_logs에 pgvector 컬럼 포함
embedding vector(1536)  -- OpenAI text-embedding-3-small 기준

-- IVFFlat 인덱스로 유사도 검색 최적화
CREATE INDEX ON work_logs USING ivfflat (embedding vector_cosine_ops);

MongoDB는 AI Agent가 생성하는 비정형 분석 결과 전용으로, 스키마를 미리 강제하지 않기 위해 분리했다.

3) GitHub Projects 에픽-태스크 계층

처음에는 이슈 본문에 - [ ] #8 형식의 Tasklist로 계층을 만들려 했는데, 이 계정에서는 Tasklist 베타가 지원이 안 됐다. 다른 레포에서 사용하던 방식을 확인해보니 GitHub Sub-issues REST API를 직접 호출하는 방식이었다.

핵심은 이슈 번호(number) 가 아니라 이슈 ID 를 사용해야 한다는 것이다.

# 이슈 ID 조회 (번호와 다름)
gh api /repos/projectmiluju/grovarc/issues/8 --jq '.id'
# → 4102095766

# sub-issue 연결
gh api --method POST \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /repos/projectmiluju/grovarc/issues/2/sub_issues \
  --input - <<< '{"sub_issue_id": 4102095766}'

이렇게 하면 GitHub Projects에서 Parent issue 계층이 정상으로 보인다.

4) develop을 default 브랜치로 변경

feature → develop PR 머지 시 Closes #이슈 자동 닫기가 동작하지 않는 문제가 있었다. GitHub의 자동 이슈 닫기는 default 브랜치에 머지될 때만 동작하기 때문이다. 1인 프로젝트에서 main에 자주 머지하지 않는 구조라 develop을 default로 바꿨다.

gh api --method PATCH /repos/projectmiluju/grovarc \
  -f default_branch=develop

트러블슈팅 / 고민 포인트

GitHub Sub-issues API — 번호가 아닌 ID

원인: sub_issue_id에 이슈 번호(8)를 넘겼더니 422 에러 발생
해결: GitHub 이슈의 내부 ID(수억 단위 숫자)를 먼저 조회한 후 전달

Closes #이슈 자동 닫기가 동작하지 않던 문제

원인: default 브랜치가 main이어서 feature → develop 머지 시엔 동작 안 함
해결: develop을 default 브랜치로 변경

결과

docs/user-flow.md — 유저 플로우 5개 시나리오
docs/db-schema.md — PostgreSQL 6테이블 + pgvector + MongoDB + Redis
docs/api-spec.md — REST API 전체 엔드포인트 명세
docs/kotlin-quickstart.md — Java 비교 기준 Kotlin 핵심 문법
GitHub Projects Phase 0~~6 에픽, Phase 1 태스크 #8~~#13 계층 구조 완성
develop default 브랜치 전환

다음 개선 아이디어

Phase 1 인프라 세팅 시작 (Dockerfile → docker-compose → CI → Terraform → k8s → 모니터링)
Kotlin Spring Boot 프로젝트 세팅

# Grovarc 개발기 #2 — 설계 산출물 완성 & GitHub 프로젝트 세팅