p:nder(pinder): 주소 입력 동선 자동 생성 플랫폼

여러 장소를 이동해야 하는 여행객을 위해, 목적지만 입력하면 AI가 동선과 일정을 자동으로 짜주는 서비스

항목	내용
팀명	인사팀
팀원	김예린(Next.js 전환·배포 환경 구축, DB·인증·이메일·지도·AI 연동, 플래너 경로 계산/최적화 개발), 류다연(서비스 기획·정책 문서화, AI 가중치 기반 최적경로 기능, 내 일정 권한·개인화 기능 개발), 양다연(AI 도우미(챗봇)·AI 동선 생성 기능 개발, 초대·공유 권한 체계, 탐색 페이지 콘텐츠 구성), 박유수(Route Planner·커뮤니티·알림 기능 개발, 온보딩(Product Tour)·화면 UI 다듬기, 모바일 반응형 전면 작업)
기간	2026.09.07 ~ 2026.09.21
배포 링크	https://pinder-one.vercel.app/
피그마	https://www.figma.com/make/ud387SQMeP4m5WJTFciCXg/Travel-Route-Planner-Wireframe?fullscreen=1&t=kdsf4qiqAWLw50Et-1&code-node-id=0-6
Claude Design	https://claude.ai/design/p/f9f84bdd-ea4c-4e76-b7bc-cad662483c31?file=Route+Planner+App.dc.html&via=share

---

1. 프로젝트 소개

문제 정의

• 타깃 사용자: 국내에서 여행·데이트·모임 등으로 여러 장소를 이동해야 하는 사람들(외국인 포함)
• 겪는 문제: 약속 장소나 목적지는 정해져 있어도, 주변에서 무엇을 할지와 장소 간 이동 순서를 함께 고려한 효율적인 일정을 짜기 어렵다
• 우리의 해결: 목적지를 입력하면 AI가 최적화된 일정과 이동 동선을 자동으로 생성해 주고("장소 입력 → AI가 최적 경로 생성 → 세부 정보 추가해 커스텀"), 생성 이후에도 같은 화면(플래너)에서 계속 수정할 수 있다

MVP 기능

우선순위	카테고리	기능	상태
1	장소 탐색	목적지 검색 및 추가	완료
2	장소 탐색	지도에 목적지 표시	완료
3	경로 계산	출발지 선택 및 경로 계산	완료
4	경로 계산	최단시간·최단거리 경로 계산	완료
5	경로 계산	변수·가중치 적용	완료

범위에서 제외한 것

• 교통·날씨 등 변동을 자동으로 감지해 동선을 재조정하는 기능 — 이유: 기획 단계에서 제외 결정, 대신 사용자가 "변수 추가"를 눌러야 재계산 시작

정상 흐름

1. 홈에서 "새 일정 만들기" 클릭 → 2. 생성 방식(직접/AI) 선택 및 날짜 지정 → 3. 방문지 추가(검색·지도클릭·현재위치, 또는 AI 자동 생성) → 4. 경로 계산 및 편집 → 5. 저장 완료

예외 흐름

상황	사용자에게 보이는 것	다음 행동	구현 여부
필수 입력이 비어 있음(예: 커뮤니티 글쓰기 시 사진 0장)	인라인 오류 문구(예: "사진을 1장 이상 첨부해주세요.")	값 보완 후 재시도	✅
데이터가 하나도 없음(빈 상태, 예: 커뮤니티 검색/필터 결과 없음)	"검색 결과가 없어요" / "아직 게시물이 없어요" 안내	다른 조건으로 검색 또는 첫 글 작성	✅
일정 저장 중 서버 오류	"저장하지 못했어요. 다시 시도해주세요." 토스트, 화면은 저장 전 상태 유지	다시 저장 시도	✅
비로그인 상태에서 저장/새 일정 만들기/편집 권한 요청 시도	화면마다 다름 — 로그인 필요 모달 또는 즉시 /login 이동	로그인 또는 회원가입	✅
AI 추천 장소의 좌표를 카카오에서 못 찾음(대체 후보로 최대 3회 재시도 후에도 실패)	"좌표 매칭에 실패했습니다" 모달 — 해당 장소는 제외하고 진행(전부 실패 시 "조건을 바꾸거나 다시 시도해주세요.")	나머지 장소로 계속 진행, 또는 조건 변경 후 재시도	✅

기획 문서

• 사전 기획(코딩 시작 직후 작성, 근거: git log상 커밋 d61b43b, 2026-09-15 17:22 — 첫 코드 커밋 16:58 직후): 문제 정의 · 요구사항 · 기능
• 사후 검증(배포된 코드를 기준으로 역산, 2026-09-18): PRD · 유저 스토리 · 화면 흐름

---

2. 디자인 시스템

사용 도구와 역할

도구	어느 단계에 썼나	원본 여부
피그마	초안 main 화면 참고 및 디자인 방향 확인 / 색상 팔레트 원본 정의	참고
Claude Design	Figma의 디자인과 색상 팔레트를 참고하여 초기 프로토타입 제작 및 UI/UX 구체화	원본
VS Code / Claude Code	Claude Design에서 구성한 프로토타입을 기반으로 실제 React/Next.js 화면 및 서비스 구현 및 UI/UX 수정	구현

정의

구분	정의	피그마	Claude Design
색상	Brand #7BCB93, Brand-strong #63B37E, Brand-accent #26AB4E, Light/Dark Background, Text 색상 사용	❌	✅
타이포	Pretendard 기반으로 화면·컴포넌트별 크기 및 굵기 적용	❌	❌
아이콘	Lucide 등 아이콘 라이브러리 미사용. PNG 래스터(public/icons/)가 주력이며, 이모지, 인라인 <svg> 및 유니코드 기호 혼용	❌	❌

컴포넌트 목록

src/components/ui/ 기준 실제 export된 컴포넌트 총 9개 사용

• Button (sm / md / lg, primary / secondary / disabled)
• Card (interactive)
• Header (desktop / mobile)
• Modal
• SegmentedControl
• DateRangeCalendar (date range)
• ImageCropModal (4:3 crop)
• PlaceholderImage
• AuthorAvatar
• HighlightedCaption (hashtag)
• NotificationBell
• ThemeToggle
• MobileMenu

디자인 vs 구현

피그마	Claude Design	실제 화면

---

3. Agent 구성

이 프로젝트는 화면을 직접 만드는 "디자이너→퍼블리셔" Agent 대신, 기획·문서 작업을 나눠 맡는 Agent 5개를 저장소에 정의해 썼다(근거: plan/.claude/agents/*.md).

flowchart LR
    T[팀원] -->|답변| PP[planning-partner]
    PP -->|기획 초안| PC[product-planner]
    PC -->|빠진 것·질문 목록| T
    T -->|재답변| PP
    LG["legacy: Claude Design export"] --> DA[design-abstractor]
    PP -->|기획 초안| PE[plan-example 폴더]
    DA -->|design-abstract.md| PE
    PE -->|내용·양식 참고| HW[hello-plan-writer]
    CB[배포 링크 + 코드베이스] --> HW
    HW -->|Hello-plan-docs 01~12| RW[rm-writer]
    RW -->|READ_ME.md 섹션별 초안| T
    T -->|섹션 승인| RW

역할별 Agent

Agent	역할	입력	출력	제약
planning-partner	기획 인터뷰 진행, 팀 답변을 문서 양식에 기록	팀의 답변(질문 1개씩)	기획 문서 초안, [제안]/[?] 표시	팀 대신 결정하지 않음, 지정된 문서 외 쓰기 금지
product-planner	기획 문서의 빈 칸·모호한 문장 검증	작성된 기획 문서	빠진 것/모호한 문장/질문 목록(문서는 직접 쓰지 않음)	Read 전용, 답을 대신 채우지 않음
design-abstractor	Claude Design export를 코드 기준으로 요약	legacy/ 폴더 원본	design-abstract.md(화면·요소·상호작용 표)	legacy 원본 수정 금지, design-abstract.md 외 쓰기 금지
hello-plan-writer	배포된 서비스를 코드·화면 기준으로 역산해 기획 문서화	배포 링크(읽기 전용 GET) + 레포 소스	plan/Hello-plan-docs/ 01~12번 문서	그 폴더 외 쓰기 금지, 추측·[제안]/[?] 금지, 근거 없으면 "미확인"
rm-writer	Hello-plan-docs 내용을 종합해 발표용 README 작성	Hello-plan-docs/ + 코드베이스(모두 읽기 전용)	READ_ME.md 한 파일, 섹션별 팀원 승인 절차	READ_ME.md 외 쓰기 금지, 근거 없는 내용은 <확인 필요>로 표시

지시문 핵심 발췌

가장 많은 이 문서의 근거를 만들어낸 hello-plan-writer의 절대 규칙:

1. Write/Edit는 오직 plan/Hello-plan-docs/ 안의 파일에만 한다.
2. plan-example/ 폴더는 양식(표 구조·섹션 순서)만 참고하고 내용은 전부 무시한다.
3. 추측하지 않는다. [제안]·[?] 태그를 쓰지 않는다. 확인이 안 되면 "미확인 — 근거 없음"으로만 표시한다.
4. 모든 서술 항목에는 근거를 남긴다. 형식: (근거: src/app/matches/page.tsx)
5. "계획"이 아니라 "실제로 지금 동작하는 것"만 쓴다.

지시문 수정 이력

• 없음 — 각 Agent 지시문 파일은 최초 작성 커밋 이후 수정된 적이 없다(근거: git log --follow 결과 파일마다 커밋 1개).

---

4. 프로젝트 규칙 (하네스)

CLAUDE.md 핵심

CLAUDE.md는 @AGENTS.md 한 줄만 있고, AGENTS.md는 next dev가 자동으로 재생성하는 안내문이라 팀이 직접 쓴 규칙이 아니다. 실제 팀 규칙은 docs/ARCHITECTURE.md·docs/CONTRIBUTING.md에 있다.

• 코드 컨벤션: 의존 방향은 app/ → components/ → lib·constants·types 한쪽으로만, 기본은 서버 컴포넌트(필요할 때만 'use client'), CSS는 *.module.css + tokens.css 변수만 사용
• 폴더 구조: src/app(라우팅) · components/{ui,layout,providers} · lib(도메인 로직) · constants · types · legacy/(구 프로토타입, 빌드 제외) · docs/(팀 문서)
• 금지 사항: 색상·간격·반경은 토큰만 사용(hex 직접 금지), 공통 컴포넌트는 고치지 말고 variant로 확장, API 키는 서버 라우트에서만(NEXT_PUBLIC_ 접두사 금지), main 직접 push 금지(PR만)

실제로 지켜졌는지: 색상 토큰 규칙은 지켜지지 않았다 — CSS 모듈 90건 이상에서 하드코딩된 hex가 발견되고(planner.module.css 약 50건), 다크모드 미대응을 스스로 주석으로 인정한 곳도 있다(근거: docs/ARCHITECTURE.md, plan/Hello-plan-docs/10-Hello-design-system.md).

만들어 둔 Skill / 재사용 프롬프트

저장소에 별도 Skill 파일(.claude/skills/)은 없고, 3번 섹션의 Agent 지시문 5개가 재사용 프롬프트 역할을 겸한다.

이름	하는 일	사용 횟수
hello-plan-writer	배포된 코드를 역산해 기획 문서 작성	Hello-plan-docs 12개 문서 생성
rm-writer	Hello-plan-docs를 종합해 README 작성	섹션 단위로 반복 사용 중
planning-partner / product-planner	기획 인터뷰 진행(작성) / 빈 칸·모호한 문장 검증(검토만, 직접 안 씀)	plan-example 초안 다수 생성 · 검증 라운드 다수
design-abstractor	Claude Design export를 코드 기준으로 요약	1회(design-abstract.md 생성)

검증 절차

1. 문서에 적은 주장은 코드를 직접 읽거나 grep해서 파일·줄번호까지 대조하고, 필요하면 git log로 실제 수정 이력까지 확인한다
2. 대조 결과가 다르면 짐작으로 고치지 않고, 재현되는 것만 반영한다 — 확인이 안 되는 부분은 <확인 필요>로 남긴다

실제 사례: AI가 추천한 장소의 좌표를 카카오에서 못 찾으면 좌표 없이 그대로 일정에 들어가고, 플래너가 이를 알리지 않은 채 가짜 이동시간·지하철 노선명을 지어내 보여주는 결함을 코드 추적(AiGenerateWizard.tsx → PlannerClient.tsx → route-engine.ts)으로 발견했다. 이후 AiGenerateWizard.tsx에 대체 후보 재시도(최대 3회)와 "좌표 매칭에 실패했습니다" 안내 모달이 추가되어, 실패한 장소는 가짜 데이터 대신 제외되도록 고쳐졌다(근거: 커밋 8d81aaa "지역 우선 매칭, 가짜 데이터 생성 금지, 좌표 매칭 실패 팝업").

---

5. 협업 방식

브랜치 전략

기획 단계(hello-planning) — 실제로 분기·병합이 일어난 브랜치, PR 1~16번 전부 반영

gitGraph
    commit id: "rule.md(브랜치명 규칙)"
    branch R-branch
    branch P-branch
    branch K-branch
    branch y-branch
    checkout R-branch
    commit id: "01-R" tag: "PR#1, 류다연 자가병합"
    checkout main
    merge R-branch
    checkout P-branch
    commit id: "01-P" tag: "PR#5, 박유수 자가병합"
    checkout main
    merge P-branch
    checkout y-branch
    commit id: "01-Y" tag: "PR#2, 양다연 자가병합"
    checkout main
    merge y-branch
    checkout K-branch
    commit id: "01-K" tag: "PR#4, 김예린 자가병합"
    checkout main
    merge K-branch
    checkout K-branch
    commit id: "04·05 정책 문서" tag: "PR#7, 김예린 자가병합"
    checkout main
    merge K-branch
    checkout K-branch
    commit id: "02-workflow 재구성" tag: "PR#10, 류다연이 대신 병합"
    checkout main
    merge K-branch
    checkout R-branch
    commit id: "기획서 02-05" tag: "PR#6, 미병합"
    branch new-R-Branch
    commit id: "2,3,4 기획서+행위자+memo" tag: "PR#11~13, 전부 미병합"
    branch cherry-branch
    commit id: "뉴브랜치+업무분석" tag: "PR#14,16, 전부 미병합"

• PR 13건 중 7건(#1,2,3,4,5,7,10)은 각자 자기 PR을 스스로 merge 버튼을 눌러 병합함(자가병합) — 유일하게 PR#10은 김예린이 열었지만("02-R-workflow.md 재구성... 류다님 확인 바랍니다") 실제 병합은 류다연이 함(55a6025, 09-10 17:11) — 이 저장소 전체에서 "내가 아닌 다른 사람이 리뷰하고 병합해준" 유일한 사례
• PR#6(류다연, R-branch)이 막힌 뒤 new-R-Branch(류다연이 실제 커밋 작성, PR은 김예린이 대신 열어줌 — git log상 커밋 작성자와 PR#11의 GitHub 작성자가 다름)로, 다시 cherry-branch로 두 번 더 새 브랜치를 파서 재시도했지만 PR#11~14·16 다섯 건 모두 병합되지 못함

개발 단계(pinder) — 09-17까지는 "브랜치"라는 이름은 있지만 실제로는 분기가 거의 없었음. 09-22 README 문서화부터 처음으로 실제 PR 기반 분기·병합이 자리 잡음

gitGraph
    commit id: "init(09-15 16:17)"
    commit id: "화면 이식 다수(같은 날 직접 커밋 — feat/* 이름표는 이 줄 위에 붙어있을 뿐 실제 분기 없음)"
    commit id: "이후 전원 main 직접 커밋 반복"
    commit id: "pull 충돌 병합 커밋 94개"
    branch feat/saved-view-past-trips
    commit id: "종료된 일정 읽기전용 뷰 전환(09-17, 병합되지 않고 방치됨)"
    checkout main
    branch R-branch
    commit id: "기획 문서 갱신, main을 계속 pull해서 추적"
    checkout main
    commit id: "문서 R-branch->Main 직접 복사(09-17, merge 없이 파일만 복사)"
    commit id: "chore/format-fix 병합" tag: "PR#9"
    commit id: "로그인 아이디/이메일 겸용 기능"
    branch P-branch
    commit id: "2절 디자인 시스템 작성"
    checkout main
    merge P-branch tag: "PR#11"
    branch feature/readme-1-3-4
    commit id: "1·3·4절 작성"
    checkout main
    merge feature/readme-1-3-4 tag: "PR#10"
    branch K-branch
    commit id: "5·6절 작성 + 이슈·PR 스크린샷"
    checkout main
    merge K-branch tag: "PR#7"
    branch Y-branch
    commit id: "7절 회고 작성"
    checkout main
    merge Y-branch tag: "PR#6"
    commit id: "루트 README.md 교체(직접 push)"

• feat/google-login·feat/home-page-port·feat/login-signup-screens·feat/planner-screen·feature/migration: 5개 브랜치 tip 커밋을 전부 확인한 결과 부모가 1개뿐임(git log -1 --format=%P) → 실제로 분기된 적이 없고, 같은 한 줄의 커밋 위에 이름표만 붙어 있는 상태. 그래서 위 그래프에는 넣지 않고 "화면 이식 다수" 한 줄로만 표시함

• feat/saved-view-past-trips: 09-17까지 기준으로는 유일하게 진짜로 갈라진 브랜치 — main에 없는 커밋이 정확히 1개 있음(a487d9a 김예린, 09-17 09:57, "종료된 일정을 KST 기준 저장된 뷰(읽기 전용)로 전환") — 지금까지 병합되지 않고 그대로 방치돼 있음. 이게 바로 02-Hello-workflow.md에서 "확인되지 않은 분기"로 적어둔 "일정 종료 후에도 편집·저장·초대가 그대로 동작한다"는 문제의 원인 — 그 기능을 실제로 만들다가 병합을 안 한 것

• R-branch: 기획 저장소의 R-branch와 이름만 같은 별개 브랜치. 류다연이 origin/main을 반복해서 merge해 들여오며(041905b 등) 기획 문서를 갱신하다가, 09-17에 결국 PR·merge 없이 069a41c 문서 R-branch->Main 옮김 커밋으로 파일만 main에 복사해 넣고 끝남

• 09-22 README 문서화 — 개발 저장소(pinder)에서 처음으로 실제 PR 분기·병합이 일어남: 기획 저장소의 K-branch·P-branch·Y-branch와 이름만 같은(내용은 무관한) 별개 브랜치를 pinder에도 새로 파서, 팀원별로 섹션을 나눠(2절 박유수, 1·3·4절 류다연, 5·6절 김예린, 7절 양다연) 각자 커밋 후 PR을 열고 실제로 GitHub에서 "Merge pull request" 버튼을 눌러 병합함(PR#6,7,10,11)

• 그동안 이 저장소는 PR 없이 main 직접 커밋만 반복했는데, 이번이 사실상 "PR 생성 → 리뷰 없이 병합" 방식으로나마 기획 저장소의 관행을 처음 재현한 사례. 다만 병합 도중 main에 먼저 들어와 있던 다른 기능 커밋(로그인 아이디/이메일 겸용, vercel-deployments.json 제거)과 충돌이 나서, Y-branch·P-branch는 각각 main을 다시 merge해 충돌을 해결한 뒤 재push해야 했음. 루트 README.md 교체 커밋만은 예외적으로 PR 없이 main에 직접 push함(문서 내용을 옮기는 후속 작업이라 팀 판단하에 생략)

• 브랜치 이름 규칙: 기획 단계는 <성 이니셜>-branch, 개발 단계 초기엔 feat/<화면명>(그러나 위에서 확인했듯 실제로 분기되지는 않음). 이슈 번호를 붙이는 규칙(feature/<이슈번호>-<기능명>)은 두 저장소 어디에서도 실제로 쓰인 적이 없음(전체 커밋 메시지에 #<숫자> 형태 이슈 참조 0건)

• 합치기 규칙: 기획 단계는 "PR 생성 → (대부분 자가)병합"을 실제로 시도했음(총 PR 13건 중 7건 병합, 아래 "PR 활용" 참고). 개발 단계로 넘어오면서는 PR 없이 "각자 main에 직접 커밋 → 로컬 git pull로 병합 → 충돌은 로컬에서 직접 해결"로 바뀌었음(병합 커밋 95개 전부 pull 충돌 해소용, Merge pull request 흔적 0건)

• 이번 README.md 문서화(2 ~ 5·6·7절)부터는 팀원별로 각자 브랜치를 파서 PR로 병합하는 방식을 다시 시도하기로 함 — 2절(디자인 시스템) 박유수, 3·4절(Agent 구성/프로젝트 규칙) 류다연, 5·6절(협업 방식·데모, 본 절 포함) 김예린, 7절(팀 회고) 양다연

이슈 활용

이슈	생성일	작성자(=사실상 담당)	라벨	담당자(assignee)	체크리스트 진행률	댓글	연결 PR	상태
#8 "9/10 - 프로토타입 기반으로 기획서 수정할 것"	09-10	류다연	(없음)	(없음)	6/6 (100%, 그날 오후 할 일 전부 완료 처리)	0	없음	open(닫힌 적 없음)
#9 "문서 2,3,4번 수정사항"	09-10	김예린	(없음)	(없음)	0/18 (0%)	0	없음	open(닫힌 적 없음)
#15 "할 일 정리"	09-14	류다연	(없음)	(없음)	1/219 (0.5%)	0	없음	open(닫힌 적 없음)

• #8은 그날(09-10) 오후에 할 일 6개(클로드 디자인 화면 흐름 정리, 코드 받아오기, 행위자 정리, 02문서 작성 등)를 적고 전부 체크 완료한, 하루짜리 실행 로그에 가까운 이슈
• #9는 김예린이 "2,3,4번 문서 위주로 손보면 4·5번은 저절로 고쳐질듯" 하는 메모로 시작해서, 02·03·04번 문서 각각에 번호가 붙은 수정 항목(예: "(25) 중요 변수 추가 - 날씨, 짐 등")을 나열했지만 체크된 항목이 하나도 없음 — 체크리스트를 실행 추적용이 아니라 "생각 정리용 메모"로만 쓴 사례
• #15는 세 이슈 중 가장 크고(체크박스 219개), 기획·화면 구현·권한 UI·Route Planner 기능·페이지 연결·실제 DB 연동·실제 권한 적용·공유 기능·실시간 동기화·테스트·회원가입/인증까지 11개 섹션으로 나눈 "시작 기능 구현" 전체 로드맵이며, 안에 A1(제작자)/A2(편집자)/Viewer/Saved-Viewer 역할 흐름을 그린 mermaid 다이어그램까지 포함돼 있음. 체크된 항목은 "사용자 역할 지정" 1개뿐이지만, 이 이슈에 적힌 역할·권한 흐름은 이후 실제 코드(src/db/schema.ts의 scheduleCollaborators.role, 02-Hello-workflow.md의 A1~A4 행위자 표)와 거의 그대로 일치함 — 체크박스로는 진행률을 전혀 추적하지 않았지만, 실질적으로는 설계 문서로 계속 참조된 것으로 보임
• 담당자(assignee) 필드는 세 이슈 모두 비어 있음 — "만든 사람이 곧 담당자"라는 암묵적 규칙만 있었고 GitHub의 담당자 지정 기능 자체를 쓰지 않음
• 댓글은 세 이슈 모두 0건 — 팀 내 논의는 이슈 댓글이 아니라 다른 채널(Slack 등, [확인 필요])로 이뤄진 것으로 보임
• 세 이슈 모두 지금까지 닫힌 적이 없음(closed_at: null) — 저장소가 pinder로 옮겨가면서 정리 없이 그대로 두고 온 것
• 이슈-PR 연결(Closes #, Fixes #) 관행은 0건 — 이슈 본문·PR 본문 어디에도 서로를 참조하는 표현이 없음
• 이슈 템플릿 사용 여부: 아니오 → 코드 저장소(pinder)의 .github/ISSUE_TEMPLATE/(버그 신고·기능 요청·화면 작업)는 만들어져 있지만 실제 이슈가 하나도 없음(0건). 기획 저장소(hello-planning)의 이슈 3건(위 표)도 템플릿 없이 자유 형식(체크리스트)으로 작성됐고 라벨도 전혀 쓰지 않음 — "추적할 문제"가 아니라 "todo 메모장"으로 쓴 것

이슈 목록	이슈 #15 상세

PR 활용

• PR 템플릿: pinder에는 .github/PULL_REQUEST_TEMPLATE.md 있음(작업 내용/관련 이슈/lint·typecheck·build 체크리스트/라이트·다크·모바일 확인/스크린샷) — 그러나 실제 PR 자체가 없어 쓰인 적이 없음. hello-planning에는 별도 템플릿 없이 자유 형식으로 PR을 열었음(본문이 "01-K" 한 줄뿐인 경우가 대부분)
• PR 본문 필수 항목(템플릿상): 작업 내용 / 스크린샷 / closes #이슈번호 — 그러나 실제 병합된 PR(hello-planning #1,2,3,4,5,7,10)의 본문은 한 줄 제목뿐이라 이 형식이 실제로 지켜진 적은 없음
• 리뷰 규칙: pinder의 CODEOWNERS(@팀장/@담당자)는 실제 GitHub 계정으로 치환되지 않은 채 남아 있어 강제되는 리뷰가 없었음. 다만 hello-planning의 PR#10 제목("...류다님 확인 바랍니다")처럼 특정 팀원을 지목해 리뷰를 요청하는 관행은 있었고, PR#6에는 실제 인라인 리뷰 코멘트가 12건 오갔음(양다연: "05번 파일 정책... 추가하면 좋을 거 같습니다", 김예린: "문서 2,3까지만 완료함" 등)
• 총 PR 수: hello-planning 13개(#1 ~ 16, 결번 8·9·15는 위 이슈 번호), pinder 5개(#6,7,9,10,11 — 아래는 이 5개 기준, hello-planning의 동일 번호와는 무관한 별개 저장소 번호). 리뷰 코멘트가 오간 PR: hello-planning 3개(#6에 12건, #12·#13에 각 1건) — 나머지 10개는 코멘트 없이 병합되거나 방치됨. pinder의 5개는 전부 코멘트 없이 병합됨. 병합 결과는 hello-planning 7건 병합(#1,2,3,4,5,7,10 — 전부 기획 첫 주 09-08 ~ 09-10) / 6건 미병합(#6,11,12,13,14,16 — 류다연이 R-branch→new-R-Branch→cherry-branch로 계속 새 브랜치를 파며 재시도했지만 끝내 병합되지 못하고 방치됨, 09-17에 069a41c 커밋으로 PR 없이 main에 직접 복사해 넣으며 마무리), pinder는 09-22에 연 5건 전부 병합(#9 chore/format-fix, #11 P-branch, #10 feature/readme-1-3-4, #7 K-branch, #6 Y-branch — 이 저장소가 생긴 이후 처음 발생한 PR이자 첫 병합)

역할 분담

[근거] 두 저장소의 커밋을 모두 합쳐서 다시 작성함 — 기획 저장소(hello-planning, 4명 합계 43커밋)는 git log --all --author=<계정>으로 실제 커밋 제목을 전부 읽고, 개발 저장소(pinder, 4명 합계 337커밋)는 git log --author=<계정> --numstat으로 실제 변경 파일을 집계함(커밋 메시지의 fix(범위): 스코프 표기가 아니라 실제 diff 기준).

팀원	기획 단계(hello-planning, 총 커밋)	개발 단계(pinder, 총 커밋)	담당 이슈	주요 PR
김예린 (paaaraaaeaaa)	12커밋 — "01-K" 작성 후 P/R/y 3개 브랜치를 K-branch로 직접 merge해 "01통합본" 정리, 04·05번 정책 문서 추가, 02-workflow 재구성(단 병합은 류다연이 대신 해줌)	135커밋 — 09-15 초기 화면 이식 다수를 직접 작성, 이후 플래너 핵심 로직(PlannerClient.tsx 46회)·인증(api/auth 24회)·일정 API(api/schedules 16회)·마이페이지(16회) 담당. 미병합 상태로 남은 feat/saved-view-past-trips("종료된 일정 읽기전용 뷰 전환")도 본인 작업	#9	#4, #7, #10 (전부 병합)
박유수 (yoosoo2217)	8커밋 — rule.md(브랜치명 규칙 자체를 작성)로 시작, "저장"(01-P), 유사 서비스 조사 3건, 01-merged.md 리네임·정리	94커밋 — 커뮤니티 화면(30회), 플래너 모바일 반응형 CSS(planner.module.css 21회 — 뒤로가기 버튼 위치를 5번 반복 수정한 것도 포함), 내 일정 카드(7회)	(없음)	#5 (병합)
양다연 (yang7493)	4커밋 — "첫번째 파일"(01-Y), 유사 서비스 조사·표 수정 2건	65커밋 — PlannerClient.tsx(17회)·내 일정(routes 17회)·AI 도우미(api/chat 13회, "생성 AI와 대화로 수정" 기능)·탐색 페이지(11회)·플래너 모바일 버튼 위치(7회, AI도우미/현재위치 버튼 겹침을 7번 반복 수정)	(없음)	#2 (병합)
류다연 (dyryoo316)	18커밋(4명 중 최다) — "pr 01파일 템플릿"·"01-R"로 시작, "문제상황 및 아이디어 1차 작성" 등 초기 기획을 주도. PR#6이 리뷰까지 받고도 막힌 뒤 new-R-Branch("2,3,4 기획서 커밋"·"02 파일 행위자·스탭 추가"·"로그인에 따른 행위자 기능 반영")→cherry-branch("뉴브랜치"·"업무 분석 커밋")로 두 번 더 재시도했지만 전부 미병합. 유일하게 김예린의 PR#10을 대신 병합해줌	43커밋 — PlannerClient.tsx(14회, "출발지 선택" 팝업 흐름)·내 일정 개인화(routes 7회)·커뮤니티(5회)·인증(api/auth 4회). 기획 저장소의 R-branch를 코드 저장소에서도 이어가다가 결국 09-17에 PR 없이 main에 문서를 직접 복사	#8, #15	#1, #3 (병합) · #6, #11~14, #16 (미병합)

PlannerClient.tsx는 네 명 모두가 상위권으로 고친 파일이고(김예린 46 · 양다연 17 · 류다연 14 · 박유수 8), planner.module.css도 세 명이 반복해서 고쳤다(박유수 21 · 김예린 18 · 양다연 13 — 류다연은 이 파일을 건드린 적 없음). 이렇게 겹치는 구조가 아래 "충돌 해결 사례"의 반복 수정·되돌림으로 이어졌다.

병렬 작업 방법

• 기획 단계: 팀원 성 이니셜별 브랜치로 문서 영역을 나눠 각자 작성(01-K/01-P/01-R/01-Y를 각자 담당). 이후 통합 문서(02~05번)는 김예린·류다연이 번갈아 정리
• 개발 단계: 이슈·PR로 사전 배분하지 않았지만, 실제 diff 기준으로 화면(디렉터리) 단위 분업이 어느 정도 자리 잡혀 있었음 — 김예린은 인증/일정 API 백엔드 + 플래너 로직, 박유수는 community + 플래너 CSS, 양다연은 explore/AI 챗 + 플래너 버튼, 류다연은 routes 개인화 + 플래너 팝업 흐름(근거: 위 역할 분담 표)
• 다만 PlannerClient.tsx·planner.module.css 두 파일은 네 명 전원의 작업 영역이 겹치는 지점이었고, 실제로 이 두 파일에서 반복 수정과 되돌림이 몰려 있었음(아래 참고)

충돌 해결 사례

• 기획 단계 — PR#6(류다연, R-branch) 리뷰는 했지만 끝내 병합 못함: 양다연·김예린이 실제로 인라인 리뷰 코멘트 12건을 남겼는데도("05번 파일 정책... 추가하면 좋을 거 같습니다" 등) 반영·재승인까지 이어지지 않고 09-11에 병합 없이 종료됨. 류다연은 이후 new-R-Branch(PR#11~13)→cherry-branch(PR#14, 16)로 계속 새 브랜치를 만들어 재시도했지만 전부 병합되지 못했고, 결국 코드 저장소로 넘어온 뒤 09-17에 069a41c 커밋으로 PR 없이 main에 문서를 직접 복사해 넣으며 마무리함 — "리뷰는 있었지만 반영·재병합 절차가 끝까지 지켜지지 않은" 사례
• 회원탈퇴 후 로그인 화면 이동 — Revert 충돌(2026-09-16): 김예린이 MyPageClient.tsx의 일반 탈퇴 처리(onConfirmWithdraw)에 router.push('/login') 3줄을 추가(067f9fc, 11:39) → 13분 뒤 양다연이 그 3줄을 git revert로 통째로 삭제(1e8c103, 11:52) → 10분 뒤 김예린이 같은 3줄을 재적용(7f59765, 12:02)하며 커밋 메시지에 "팀원이 별다른 설명 없이 revert 했는데, 테스트로 확인된 실제 버그 수정이라 다시 적용한다"고 직접 기록. diff가 3줄 추가/3줄 삭제로 완전히 대칭이라 코드 충돌은 아니고, 사전 소통 없이 되돌렸다가 다시 되돌려진 사건임(왜 되돌렸는지는 기록에 남아있지 않아 [확인 필요]). 개선안: 같은 영역(인증/마이페이지) 작업 전 담당·범위를 먼저 공지하고, git revert처럼 되돌리는 작업은 사유를 남기기
• 플래너의 "출발지 선택" 팝업 흐름 — 류다연이 같은 날 4번 고침: 114ecb4(추가 후 되돌아갈 팝업을 "목록"에서 "출발지 확정"으로 변경) → b4eacf0("취소"를 "이전"으로 바꾸고 스크롤 추가) → 7d8159b(ESC/뒤로가기 처리에 returnToOriginPickerAfterAdd 상태 확인 로직 추가) → b2d8349·3349a20(위 흐름 재조정). git 충돌은 아니지만, 추가 후 어느 팝업으로 돌아가야 하는지에 대한 요구사항이 구현 중 계속 바뀐 사례
• 플래너 모바일 버튼 위치 — 박유수·양다연이 planner.module.css를 반복 수정: 박유수는 지도 화면 "뒤로가기" 버튼이 검색 오버레이와 겹치는 문제를 09-17에 5번 수정(602267a에서 버튼 JSX를 mapCol 밖에서 mapArea 안으로 옮김); 양다연은 AI 도우미·현재 위치 버튼이 하단 요약바와 겹치는 문제를 09-18 아침에 7번 연속 수정(ddcc42c→...→f27b62e) — 전부 CSS position/z-index만 계속 바꾸며 한 번에 맞는 값을 못 찾은 패턴

PR 화면

---

6. 데모

실행 방법

• 배포 링크: https://pinder-one.vercel.app/ — main에 push하면 Vercel Git Integration이 자동으로 새 프로덕션 배포를 만듦. 이 저장소 자체의 CI(ci.yml)는 lint·typecheck·build 검증만 하고 실제 배포는 하지 않으므로, 배포 성공 여부는 GitHub 커밋 상태가 아니라 Vercel 대시보드(또는 PR에 자동으로 달리는 Vercel 프리뷰 배포 코멘트)에서 확인해야 함 [확인 필요: Vercel 대시보드 접근 권한이 없는 팀원은 이 문서에 스크린샷으로 배포 상태를 남겨둘 것]
• 브랜치·PR을 만들면 그 커밋에 대한 프리뷰 배포도 Vercel이 자동으로 생성함 — 이번 README 문서화(2~7절)처럼 브랜치별로 PR을 여는 방식으로 바뀌면, 앞으로는 리뷰어가 코드를 직접 받지 않고도 PR의 프리뷰 링크로 화면을 바로 확인할 수 있음
• 로컬에서 직접 띄워야 할 경우, 값을 하나씩 채우는 대신 Vercel에 이미 등록된 실제 배포용 환경 변수를 그대로 받아오는 방법을 씀:

  npm i -g vercel              # Vercel CLI (이 개발 환경에는 아직 설치돼 있지 않음 — 최초 1회만)
  vercel login
  vercel link                  # 이미 연결된 프로젝트 "pinder"를 선택 (.vercel/repo.json 참고)
  vercel env pull .env.local   # KAKAO_JS_KEY / KAKAO_REST_API_KEY / GEMINI_API_KEY / GOOGLE_CLIENT_ID / DATABASE_URL 등을 실제 배포값 그대로 받아옴
  npm install
  npm run dev                  # http://localhost:3000
  

• 키를 하나도 못 받아와도 앱 자체는 뜨고, 해당 기능(지도·AI 도우미·구글 로그인 등)만 오류 메시지를 보여줌(근거: README.md "환경 변수" 절 "키가 없어도 앱은 뜨고, 해당 기능만 오류 메시지를 보여준다")

시연 순서

1. 로그인 — 홈에서 "내 일정" 클릭 → 로그인 진행(helloteam / eulji2026@)

2. 내 일정 — 미리 제작된 내 일정 진입 → 제목·일정 수정 → 온보딩 설명("다시 보지 않기") → 최단 시간 / 최단 거리 옵션 확인 → 이동수단 설정(일괄 적용, 개별 변경, 카카오맵 연동까지) → 방문지 추가(주소 검색 / 지도 클릭 / 현위치) → 경로 계산 팝업에서 출발지 설정(방문지 목록 선택, 검색, 현위치 선택) 및 변수 추가

3. 최적 동선 생성하기 — AI 일정 생성 → 이틀 일정 선택 → **"다시 추천받기"**로 재생성 → "이 일정으로 시작하기" → 경로 계산 → 전체보기에서는 추가 입력이 불가능함을 언급 → 저장하지 않고 나갈 때 "저장하시겠습니까?" 확인창 시연

4. 여행지 탐색 — 경북 선택 → 포항 진입 → "일정짜기" → 이틀로 변경 → 전체보기에서 주소를 추가하는 방법 시연(주소 검색은 불가, 지도 클릭으로만 가능) → 경로 계산 → AI 도우미에 "포항에서 진짜 유명한 곳으로 추천해줘" 입력 → **"호미곶을 일정에 추가해줘"**로 추가 → 제시된 예시 문항을 선택해 추가 → 저장 → 편집 링크 공유(다른 팀원이 따로 권한 신청) → 홈 화면 이동 알림창 언급 → 내 일정에서 권한 관리 팝업 시연

5. 편집 링크 접속 — 편집자 화면 시연: 처음에는 보기 전용 상태 → 권한 신청 → 승인 후 편집자 화면으로 전환되는 과정 및 제작자 화면과의 차이점 언급

6. 커뮤니티 — 게시물 작성 / 댓글 / 좋아요 / 저장 기능 시연 → 내 프로필에서 저장 목록 확인 → 여행지 검색 기능 시연

---

7. 회고

잘 된 점

• 사용자가 글이 안 올라간 걸 모를 수 있는 "성공으로 잘못 처리되는" 버그(커뮤니티 글 작성)를 놓치지 않고 찾아내 바로잡음 — 조용히 묻힐 수 있는 종류의 버그를 잡아낸 사례
• Neon DB 네트워크 사용량 소진이라는 인프라 문제를 스키마 구조는 그대로 유지한 채 Supabase로 재배포해 해결 — 스키마와 인프라를 분리해 둔 덕에 DB를 교체해도 나머지 코드에 영향이 크지 않았음
• 실패한 구간만 골라 재시도할 수 있게 만들고, 동시 요청 과부하 문제도 원인을 짚어 처리 방식을 고쳐 안정성을 높임(경로 계산 기능)
• 팀원 다같이 모여 실제 웹을 함께 실행해보며 오류를 찾아내고 그 자리에서 수정함

실패 사례와 개선

무엇이 실패했나	왜	어떻게 고쳤나
커뮤니티 글 작성 실패를 성공으로 처리	에러 응답을 성공 케이스로 잘못 분기 처리	실패 응답을 실패로 처리하도록 분기 로직 수정
UI 요소 겹침·간격 문제를 여러 번 임시방편으로 반복 수정	레이아웃 구조(z-index, 앵커 기준 등)를 먼저 정하지 않고 그때그때 다르게 시도	여러 차례 수정을 거쳐 최종 배치로 수렴
동시 경로 요청이 몰려 일부 이동수단 경로 계산 실패	여러 이동수단 API를 동시에 호출해 요청 과부하	요청 처리 방식을 수정해 과부하 해소
Neon DB의 네트워크 사용량을 모두 소진해 사용 불가	네트워크 사용량 한도 초과	Supabase로 새 데이터베이스를 구축해 재배포, 기존 스키마 구조만 그대로 이전

팀 안에서 공유한 Claude 활용 노하우

• 모든 에이전트에 "AI가 채운 부분과 사실을 구분하는 태그" 규칙을 공통으로 넣음 — 팀이 확정한 내용은 그대로, AI가 보탠 제안은 [제안], 근거가 없는 추정은 [확인 필요]/[?]로 표시해 나중에 섞여서 사실처럼 보이지 않게 함
• CLAUDE.md에 규칙을 직접 적지 않고 @AGENTS.md, @docs/ARCHITECTURE.md, @docs/CONTRIBUTING.md로만 연결(bdeddd9) — 컨벤션·폴더 구조가 바뀌어도 CLAUDE.md를 따로 고칠 필요 없이 원본 문서만 갱신하면 Claude Code가 항상 최신 규칙을 읽게 함

다음 프로젝트에서 다르게 할 것

1. 같은 영역(인증/마이페이지 등) 작업 전에 이슈나 Slack으로 담당·범위를 먼저 공지한다
2. 직접 push 대신 PR 단위로 병합하고 리뷰를 거쳐, 되돌림(revert) 사고를 리뷰 단계에서 먼저 걸러낸다
3. 같은 UI 겹침·간격 문제를 여러 번 임시방편으로 고치기보다, 레이아웃 구조(z-index, 앵커 기준 등)를 먼저 정하고 수정한다