DB 포트 고정 정책 + 런타임 DB 검증 도입

앱 포트·DB 포트 모두 **프로젝트별 고정 할당(1-B)** 으로 통일하고, 앱 부팅 시 `current_database()`로 연결 DB를 검증하는 정책(E)을 추가했다. 자동 포트 탐색(find-port)은 **deprecated**. 중앙 레지

changes docs/changes/2026-04-15-db-port-policy.md

TL;DR

앱 포트·DB 포트 모두 프로젝트별 고정 할당(1-B) 으로 통일하고, 앱 부팅 시 current_database()로 연결 DB를 검증하는 정책(E)을 추가했다. 자동 포트 탐색(find-port)은 deprecated. 중앙 레지스트리 템플릿을 docs/reference/PORT_REGISTRY_TEMPLATE.md로 제공.

배경

2026-04-14 meetflow 데이터 소실 사건

meetflow와 ax-studio-plan이 둘 다 호스트 5432 사용. ax-studio-db 컨테이너가 5432 선점 → meetflow-postgres 컨테이너 Created 상태로 갇힘. meetflow 앱은 localhost:5432/meetflow_dev로 접속해서 실제로는 ax-studio-db 인스턴스에 meetflow_dev DB를 생성하고 회원가입 데이터를 적재. 포트 변경(5436) + docker compose down/up 이후 원래 볼륨에 붙었을 때 테이블이 비어 있음.

기존 규칙이 못 잡은 이유

07-db.md DB 이름 충돌 방지는 정상 작동 — meetflow_dev vs ax_studio_dev 이름이 달라 걸리지 않음
08-local-env.md 포트 충돌 체크 예시에 DB 포트(5432/3306/27017/6379)가 빠져 있었음
docker-compose.yml의 고정 포트 매핑이 충돌 시 Created 상태로 조용히 대기 → 에이전트/사람이 인지 못 함
앱은 "5432 연결 성공"만 보고 엉뚱한 인스턴스인지 검증하지 않음

결정

채택한 정책

앱 포트도 DB 포트도 1-B 프로젝트별 고정 할당
- 중앙 레지스트리 ~/.claude/projects/PORT_REGISTRY.md로 관리
- 템플릿: docs/reference/PORT_REGISTRY_TEMPLATE.md
- 한번 할당된 포트는 재사용 금지
런타임 DB 검증(E) 필수
- .env에 EXPECTED_DB_NAME 추가
- 앱 부팅 시 SELECT current_database(), inet_server_port() 로 검증
- 틀어지면 fail-fast로 즉시 터짐
find-port 자동 탐색 deprecated
- 신규 프로젝트 금지
- 기존 프로젝트는 점진적 제거

고려했지만 채택 안 한 대안

패턴 3 (Docker 내부 네트워크): DB 충돌 원천 차단 장점이 있지만, AI 에이전트가 psql/DBeaver로 직접 붙기 어렵고 docker compose exec 경유를 매번 상기해야 함. 에이전트 친화성이 떨어져 제외.
패턴 2 (자동 탐색) 유지 + DB 포트 예외: 앱 포트와 DB 포트의 정책이 갈려 에이전트가 혼란. 단순성 원칙에 어긋남.

결정 근거 비교표는 LOCAL_PORT_POLICY.md 참조.

변경 파일

파일	변경 내용
core/08-local-env.md	정책 개요 추가, 포트 스캔 예시에 DB 포트 포함, find-port deprecated 선언, 에이전트 실행 프로토콜 11단계로 확장
core/07-db.md	1-2 "DB 연결 검증" 섹션 신규 추가 (Prisma/SQLAlchemy 스니펫 포함), 2026-04-14 meetflow 사례 기록
docs/reference/PORT_REGISTRY_TEMPLATE.md	신규 생성 — 사용자가 `~/.claude/projects/PORT_REGISTRY.md`로 복사해 사용
docs/guide/LOCAL_PORT_POLICY.md	신규 생성 — 패턴 1-A/1-B/2/3 비교, 왜 AI 에이전트 환경에서 1-B가 최적인지 근거
docs/00_INDEX.md	새 가이드/레퍼런스/change log 링크 추가

영향

신규 프로젝트

세팅 체크리스트 5개 → 11개로 확장 (PORT_REGISTRY 조회/업데이트, DB 포트 스캔, Docker 상태 체크, 런타임 검증 추가)
find-port 스크립트 추가 금지

기존 프로젝트

즉시 강제 아님. 아래 상황에서 점진적 적용:

해당 프로젝트에서 .env 수정 또는 로컬 세팅 관련 작업이 생길 때
에이전트가 find-port 스크립트를 발견하면 deprecated 안내 + 고정 포트 전환 제안
DB 관련 이슈가 생기면 런타임 검증 스니펫 추가 제안

우선순위: meetflow > ax-studio-plan > aitem > 기타. meetflow는 방금 사고가 있었으므로 가장 먼저.

에이전트 행동 변화

신규 프로젝트 세팅 시 11단계 프로토콜을 출력하며 진행
포트 충돌/Docker Created 상태 감지 시 즉시 사용자에게 보고
.env에 EXPECTED_DB_NAME 없으면 추가 제안
DATABASE_URL 포트 ↔ docker-compose.yml ports 불일치 시 즉시 보고

후속 작업

~/.claude/projects/PORT_REGISTRY.md 실제 파일 생성 (사용자가 템플릿 복사 후 편집)
meetflow에 런타임 DB 검증(E) 스니펫 적용
ax-studio-plan, aitem 등 주요 프로젝트의 find-port 제거 + 고정 포트 전환
PORT_REGISTRY 운영 중 실제 충돌 사례 수집 → 필요 시 Hook 자동화 검토