Imported from digitie/pinvi (SKILL.md). Install upstream with npx skills add digitie/pinvi. Copyright stays with the author.

SKILL — Pinvi 에이전트 매뉴얼

이 파일은 당신(AI 에이전트 — Claude / Codex / Antigravity / Cursor / Copilot 누구든)이 작업을 시작하기 전 반드시 읽어야 한다. 1회만 읽으면 30분 이상의 디버깅을 줄일 수 있다.

도구별 1차 진입:

• Claude — CLAUDE.md → AGENTS.md → 본 파일
• Codex / Antigravity — AGENTS.md → 본 파일
• 두 진입 파일(AGENTS.md + CLAUDE.md)은 항상 같은 결정을 반영 (ADR-016).

1. 정체성

본 저장소(GitHub 이름 pinvi)는 한국 여행 계획·기록·공유 애플리케이션의 모노레포다. 백엔드(FastAPI) + 프론트(Next.js) + 모바일 Expo Dev Client 앱 (apps/mobile, 활성 — Sprint M-1) + ETL(Dagster) + 인프라 manifest + 문서가 들어 있다.

지도 feature(place / event / notice / price / weather / route / area) 정규화· 저장은 본 저장소가 아니라 별 저장소 kor-travel-map이 소유한다. Pinvi ↔ kor-travel-map은 최신 OpenAPI HTTP 계약으로 통신한다(ADR-026).

이전(v1) 구현은 v1 브랜치에 보존되어 있다. master(main)는 v2 사양으로 처음부터 다시 구현한다(ADR-001).

식별자 매핑

개발 환경 (Linux / WSL / N150) — ADR-051

• git / 편집 / commit / PR: Linux worktree에서 Linux git으로 수행한다.
• CodeGraph: Linux native codegraph만 사용한다. /mnt/c/..., .exe, .cmd Windows shim으로 잡히면 중지하고 PATH/설치를 고친다.
• 의존성 설치 / pytest / docker / 장기 실행 / 프론트 검증: Linux에서 수행한다.
• Playwright: N150에서만 실행하고, 기본은 scripts/n150-playwright-runner.sh Docker runner다. N150 Docker runner와 host browser 실행이 모두 불가능하면 gate를 중단한다.
• 데이터(dataset/, refdocs/): 변경 금지 원본은 절대경로/심볼릭 링크로 참조한다.
• 절차·함정 전체는 docs/dev-environment.md + docs/agent-workflow.md, 반복 실패는 docs/agent-failure-patterns.md.

2. 빠른 시작 (코드 작성 단계 이후)

cd /mnt/f/dev/pinvi-claude                            # Linux git/source-of-truth worktree
sudo apt install -y libgdal-dev gdal-bin libpq-dev          # 시스템 의존성

# 백엔드 (uv 권장)
uv venv && uv pip install -e "apps/api[dev]"

# 프론트
npm install
scripts/dev-up.sh                                           # API 12801 / Web 12805 / Dagster 12802

# 인프라 (RustFS API 12101 / console 12105)
docker compose -f infra/docker-compose.yml up -d postgres rustfs

# Docker app build/run/smoke
npm run docker:app:smoke

# kor-travel-map 독립 프로그램은 별 저장소에서 실행 (API/Admin API 12701)

# Alembic (app schema만)
uv run --package apps/api alembic upgrade head

# kor-travel-map alembic은 별 저장소에서 실행 (feature schema 소유)

# 단위 테스트
pytest apps/api/tests -q

# 통합 테스트 (PostGIS 필요)
pytest apps/api/tests/integration -q

현재 저장소는 Sprint 1~4 산출물과 v0.1.0 릴리즈 정리 문서가 함께 존재한다. 실행 전에는 docs/resume.md, docs/runbooks/local-dev.md, 관련 Sprint 문서를 먼저 확인한다.

3. 디렉토리 지도 (계획)

apps/
  api/                       ← FastAPI 백엔드 (uv, pyproject.toml)
    app/
      api/routes/            ← FastAPI 라우터
      core/                  ← 설정, 의존성 등
      models/                ← SQLAlchemy 매핑 (app schema만)
      schemas/               ← Pydantic v2
      services/              ← 비즈니스 로직
      etl_bridge/            ← kor-travel-map 클라이언트 주입
    alembic/                 ← app schema migration (feature schema는 별 저장소)
    tests/
  web/                       ← Next.js App Router + admin
    app/
    public/
    tests/
  etl/                       ← Dagster definitions/jobs/schedules
    definitions.py
    assets/                  ← Pinvi 자체 Dagster job / 외부 갱신 trigger

packages/                    ← 공유 TS 패키지 (필요 시)
  ui/
  schemas/                   ← Zod schema 공용
  api-client/                ← fetch wrapper + query keys
  design-tokens/             ← 16색 팔레트 + Tailwind preset
  hooks/                     ← useUserLocation 등 공용 React hook

infra/
  docker-compose.yml         ← 개발용
  docker-compose.app.yml     ← 운영용
  n150/                      ← N150 운영 manifest

docs/
  architecture.md
  agent-guide.md
  dev-environment.md
  data-model.md              ← app 도메인 (사용자/여행계획/POI)
  postgres-schema.md
  decisions.md
  journal.md
  resume.md
  tasks.md
  test-strategy.md
  kor-travel-map-integration.md
  sprints/
    README.md
    SPRINT-1.md
    ...

dataset/                     ← 로컬 원본 보관 (.gitignore)
refdocs/                     ← 외부 spec/문서 (.gitignore)

본 저장소의 의존 방향(계획): schemas → models → services → routes. pinvi.etl은 pinvi.api.services와 분리된 코드 위치이며 같은 DB schema (app)에 책을 댄다.

apps/api는 PINVI_KOR_TRAVEL_MAP_API_BASE_URL의 OpenAPI HTTP 계약으로 feature를 조회한다. apps/etl은 Pinvi 자체 job과 외부 서비스 갱신 trigger를 담당한다.

4. 절대 하지 말 것 (DO NOT)

1. main에 직접 push 금지 — feature branch + PR (ADR-001 후속).
2. feature/provider_sync schema에 Pinvi가 직접 DDL/migration 작성 금지 — 해당 schema는 kor-travel-map이 소유. Pinvi는 app schema와 자체 도메인만 관리.
3. provider raw → DTO 변환 직접 작성 금지 — kor-travel-map.providers에 위임. 새 provider는 그쪽 저장소에 PR.
4. Pinvi 사용자 경로에서 kor-travel-map import 금지 — 최신 openapi.user.json 기반 HTTP client만 사용한다.
5. feature 도메인 wrapper 신규 생성 금지 — HTTP client는 transport 역할만. provider 변환, feature 정규화, dedup 같은 도메인 로직은 kor-travel-map 저장소에서 처리한다.
6. Windows git / Windows shim으로 개발 명령 실행 금지 — git, CodeGraph, pytest, docker, npm, rg는 Linux native로 실행한다(ADR-051). command -v가 /mnt/c/..., .exe, .cmd를 가리키면 중지한다. Playwright는 N150에서만 실행하고, N150이 불가하면 gate를 중단한다.

Telegram 완료 알림 MCP (모든 agent)

각 worktree에는 mcp-telegram MCP 설정(claude.json/.codex/config.toml/ .gemini/mcp.json/antigravity.json)과 로컬 .env.mcp-telegram credential (API_ID/API_HASH, gitignore)이 있다. 단위 작업을 PR로 마무리하면 최종 응답 전 send_message로 완료 요약 + PR 링크를 Telegram에 보낸다. GitHub secret/워크플로는 쓰지 않는다. 셋업·로그인은 docs/runbooks/codegraph-worktrees.md. 7. 좌표 순서 혼동 금지 — 모든 외부 인터페이스는 (lon, lat). 라이브러리 DTO와 동일. 8. 카테고리/마커 매핑 하드코드 금지 — kor-travel-map의 카테고리 표 사용. Pinvi UI는 그 표에서 읽어 maki/icon 매핑. 9. 외부 API 키 평문 커밋 금지 — SecretStr. .env 권한 600 또는 systemd EnvironmentFile/vault. 10. 시간 직접 사용 금지 — 모든 datetime은 KST aware (Asia/Seoul). naive datetime을 DTO/DB에 넣지 않는다. kor-travel-map의 kst_now() 또는 동등 helper 사용. 11. 데이터/원천 파일을 git에 커밋 금지 — dataset/, refdocs/, data/, artifacts/는 .gitignore. 로컬 보관. 12. 공간 쿼리 술어에서 ST_Transform 금지 — 입력 좌표는 CTE/파라미터로 한 번만 변환. 술어는 ST_DWithin(t.coord_5179, p.geom, :radius_m)처럼 인덱스 있는 컬럼을 그대로 둔다. 반경 검색은 coord_5179(meter) 기준. 13. SQLAlchemy bulk insert().values(rows) 파라미터 폭주 금지 — 한 쿼리당 65,535개 한도. row × column이 ~30,000 이상이면 psycopg.copy_* 또는 gdal.VectorTranslate(... PG_USE_COPY=YES) 전환. 14. 작업 큐 상태를 in-memory만 신뢰 금지 — app.import_jobs 또는 동등 영속 테이블 사용. 다중 워커는 pg_try_advisory_lock + FOR UPDATE SKIP LOCKED. 15. Feature.detail을 자유 dict로 사용 금지 — kor-travel-map의 PlaceDetail/EventDetail 등 Pydantic 모델 인스턴스 → .model_dump(). 16. 사용자 데이터를 클라이언트 응답에 평문으로 다 노출 금지 — 권한 별로 필드 마스킹. 토큰/세션/이메일/전화는 보안 정책에 따른다. 17. Admin 권한 체크를 클라이언트만 신뢰 금지 — 모든 보호 라우터는 서버 middleware/dependency에서 권한 검증. UI 라우팅은 보조. 18. Telegram/Resend/AI companion webhook payload 무검증 금지 — HMAC/signature/idempotency 검증 후 처리. 19. Dagster asset이 kor-travel-map의 infra//providers/를 직접 부르지 말 것 — kor-travel-map provider 적재는 그 저장소의 API/Admin/Dagster가 소유한다. 20. apps/web에서 외부 API 키 직접 호출 금지 — 모든 외부 호출은 백엔드 경유. 클라이언트는 Pinvi API만 호출. 21. 컴포넌트 / 함수 / 서비스를 영향도 평가 없이 수정 금지 (ADR-017) — 수정 전 codegraph_explore로 관련 심볼 source + 호출 관계를 한 번에 본다. 보조: codegraph_impact (반경) / codegraph_callers (호출자) / codegraph_trace (경로). grep / Read fan-out으로 같은 일을 재현하지 않는다.

전체 룰은 추가될 수 있다. 작업 중 발견하면 ADR과 함께 본 §4에 추가.

5. 자주 묻는 작업

6. 도메인 어휘

추가 도메인 어휘는 docs/data-model.md §용어 사전에 정렬.

7. 작업 후 체크리스트

• pytest apps/api/tests -q 통과 (단위 + 일부 통합)
• ruff check apps/api / mypy --strict apps/api/app 통과
• npm run lint / npm run typecheck / npm run build (apps/web)
• docs/journal.md에 작업 항목 추가 (역시간순)
• docs/resume.md의 진척도 갱신
• 의사결정이 있었다면 docs/decisions.md에 ADR 추가
• 사용자 가시 변경이면 CHANGELOG.md 갱신 (코드 작성 단계 진입 후)
• DTO/스키마 변경이면 OpenAPI export 재실행 (코드 작성 단계 진입 후)

8. 첫 5분 진입 프로토콜

새 세션이 들어오면 이 순서로 읽는다:

1. 도구별 1차 진입 파일
   • Claude: CLAUDE.md
   • Codex / Antigravity / Cursor / Copilot: AGENTS.md
2. AGENTS.md — 작업 룰
3. 본 파일 SKILL.md — DO NOT, 도메인 어휘
4. docs/agent-guide.md — 기록·ADR·PR 워크플로
5. docs/sprints/README.md — Sprint 1~N 계획
6. docs/resume.md — 현재 상태와 다음 한 작업
7. docs/journal.md 최신 3건 — 직전 컨텍스트
8. README.md — 저장소 정체성과 문서 지도
9. 관련 ADR (docs/decisions.md)

9. 현재 단계 메모

초기 문서화 단계의 "코드 작성 금지" 규칙은 더 이상 현재 상태를 설명하지 않는다. 현 기준선은 Sprint 1~3 머지 완료, Sprint 4 릴리즈 게이트 충족 및 v0.1.0 tag/릴리즈 노트 정리 단계다.

• 코드 변경 가능 범위와 책임 경계는 AGENTS.md의 "현재 단계 정책"을 따른다.
• 구현 우선순위는 docs/resume.md, docs/tasks.md, docs/sprints/SPRINT-4.md를 함께 본다.
• kor-travel-map 책임 범위를 넘는 기능은 이 저장소에서 직접 구현하지 않는다.