Imported from yellow-pang/RWR-mini-project (AGENTS.md). Install upstream with npx skills add yellow-pang/RWR-mini-project. Copyright stays with the author.

AGENTS.md

RWR: Run Walk Random 프로젝트에서 AI 개발 에이전트가 따라야 할 저장소 기준 안내서입니다. 길게 설명하기보다, 작업 중 판단 기준이 되는 규칙만 둡니다.

프로젝트 기준

클라이언트는 React + Vite SPA, 서버는 Node.js + Express, 데이터 저장소는 PostgreSQL Docker DB입니다.
코스, 즐겨찾기, 최근 추천 이력은 PostgreSQL 기준으로 판단합니다.
정적 routeData.js 배열이나 즐겨찾기/이력 localStorage 배열을 기준 데이터로 되살리지 않습니다.
사용자 식별은 브라우저 localStorage의 rwr_user_id 익명 UUID를 사용합니다.
현재 MVP의 큰 방향은 주소 입력 기반 코스 생성이며, GPS는 보조 기능입니다.
상세 기능 흐름은 docs/03-requirements.md, docs/06-data-spec.md, 현재 작업 plan 문서를 기준으로 확인합니다.

작업 전 확인 문서

새 기능, 수정, 리뷰를 시작하기 전에 필요한 범위에서 아래 문서를 확인합니다.

docs/01-overview.md
docs/03-requirements.md
docs/06-data-spec.md
docs/07-tech-stack.md
현재 작업과 관련된 최신 plan 문서: docs/plans/plan-XX-작업명.md
직전 완료 Step 문서: docs/steps/step-XX-작업명.md
직전 PR 문서가 있으면 확인: docs/pr/pr-XX-작업명.md

docs/plans, docs/steps, docs/pr는 번호가 가장 큰 최신 문서를 우선 확인합니다. 현재 작업 plan이 없으면 요구사항을 분석한 뒤 새 plan 작성이 필요한지 판단합니다.

문서와 실제 코드 또는 package.json이 다르면, 코드와 실제 스크립트를 확인한 뒤 차이를 사용자에게 짧게 알립니다.

작업 규모 기준

작은 수정은 plan 문서 없이 진행할 수 있습니다.
- 예: 오타, 문구, 단순 CSS, 명백한 lint 오류, 단일 파일의 작은 버그
중간 이상 작업은 코드 수정 전 plan 문서를 작성하거나 갱신합니다.
- 예: API 흐름, 컴포넌트 구조, 주요 UX, 서버 로직 변경
큰 작업은 반드시 사용자 확인 후 진행합니다.
- 예: DB 스키마, Docker, 환경변수, 외부 API, MVP 범위 확대

기본 흐름은 요구사항 요약, git status 확인, 브랜치 확인, 구현, 검증, 변경 요약 순서입니다. 새 작업이면 브랜치 이름을 추천하고, 브랜치 생성/전환은 사용자가 직접 하도록 안내합니다.

코드 작업 워크플로우

요구사항과 최종 목표를 요약한다.
현재 브랜치와 미커밋 변경 상태를 확인한다.
새 작업이면 브랜치 이름을 추천하고 사용자가 직접 전환하도록 안내한다.
코드 수정 전 Plans 문서를 작성하거나 갱신한다.
사용자 승인 후 코드 수정, 검증을 진행한다.
사용자가 작성된 코드를 확인하고 커밋하도록 안내한다.
PR/Step 문서화를 진행한다. 7-1. PR 문서의 경우 다른 PR 문서와 양식을 통일한다. 7-2. Step 문서의 경우 이전 문서와 양식을 통일할 필요는 없다. 7-2. Step 문서는 다른 사람이 보아도 변경점을 쉽게 알 수 있고 변경된 내용이 어떻게 변경되었는지 코드 방식, 중요점 등을 알 수 있게 상세히 작성해야 한다.
한글 Conventional Commit 메시지 제목과 내용을 출력한다.

사용자 승인 없이 하지 않는다.

실제 git commit, git push
DB 스키마 변경
Docker 설정 변경
server/.env 수정
대규모 seed 데이터 교체

구현 규칙

React 코드는 함수형 컴포넌트와 Hooks만 사용합니다.
함수, 변수 이름은 이름만 보아도 알 수 있도록 쉽고 명확하게 작성합니다.
컴포넌트에서 직접 fetch를 호출하지 않고 client/src/api/ 모듈을 경유합니다.
주소 기반 생성형 ORS 코스와 저장된 DB 코스는 즐겨찾기, 상세 링크, 공유 가능 여부가 다를 수 있으므로 구분해서 처리합니다.
API 응답 형식은 가능한 한 아래 구조를 유지합니다.
- 성공: { success: true, data }
- 성공 메시지: { success: true, message }
- 실패: { success: false, message }
- 검증 오류: { success: false, message, errors }
UI 변경 시 모바일 375px부터 데스크톱 1280px 이상까지 레이아웃을 고려합니다.

패키지와 구조 변경 규칙

새 npm 패키지는 사용자 승인 없이 추가하지 않습니다.
상태 관리 라이브러리, 라우팅 구조, 폴더 구조, API 응답 형식은 사용자 요청 없이 대규모로 변경하지 않습니다.
기존 코드 스타일을 우선 따르며, 기능 변경과 전체 포맷팅을 한 작업에 섞지 않습니다.
불필요한 리팩터링을 하지 않습니다.
사용하지 않는 파일 삭제는 명백한 경우가 아니면 사용자 확인 후 진행합니다.

수정 전 사용자 확인이 필요한 항목

server/src/db/schema.sql 변경
server/src/db/seed.sql 변경
Docker 설정 변경
.env, .env.example, 환경변수 이름 변경
외부 API 키, 비밀값, 배포 Secret 관련 변경
DB 마이그레이션, 데이터 삭제, 초기화 작업
MVP 범위를 넘어서는 신규 기능 추가
CORS, Helmet, rate limit 등 보안 설정 변경

보안 기준

클라이언트 코드에 외부 API Secret, DB 정보, 서버 비밀값을 넣지 않습니다.
SQL은 문자열 직접 조합 대신 파라미터 바인딩을 사용합니다.
서버 입력값은 필요한 범위에서 검증합니다.
에러 응답에 내부 스택 트레이스, SQL, 환경변수 값을 노출하지 않습니다.

문서 작성 규칙

기능 변경 후 관련 문서를 필요한 범위에서 갱신합니다.
기존 문서 내용을 삭제하기보다, 날짜와 Step 기준의 "보정 기록" 또는 "변경 기록"을 추가합니다.
계획 문서는 docs/plans/plan-XX-작업명.md에 작성합니다.
구현 완료 문서는 docs/steps/step-XX-작업명.md에 작성합니다.
PR 요약 문서는 docs/pr/pr-XX-작업명.md에 작성합니다.
PR 요청 문서는 이전 문서를 확인하여 양식을 비슷하게 작성합니다.
한글 문서는 UTF-8 인코딩을 유지합니다.

검증 기준

가능한 범위에서 아래 검증을 실행하고 결과를 보고합니다.

클라이언트 lint: npm.cmd --prefix client run lint
클라이언트 build: npm.cmd --prefix client run build
서버 문법 확인: 수정한 서버 JS 파일에 대해 node --check <file>

검증 실패 시 실패 로그의 핵심 원인, 수정 여부, 남은 문제를 구분해서 보고합니다. 검증을 실행하지 못한 경우에는 이유와 남은 리스크를 명확히 적습니다.

커뮤니케이션 규칙

답변은 기본적으로 한국어로 작성합니다.
초보 개발자가 이어서 작업할 수 있도록 용어를 풀어서 설명합니다.
요구사항이 복잡하면 분석, 질문, 브랜치 추천, 계획, 구현, 검증 순서로 단계를 나눕니다.
데이터 삭제, DB 구조 변경, MVP 범위 확대, 외부 API 추가는 반드시 질문합니다.
UI 문구, 작은 CSS 조정, 명백한 버그 수정은 합리적으로 판단해 진행하고 결과에 이유를 남깁니다.
마지막에 한글 Conventional Commit 메시지를 제목과 내용까지 함께 제안합니다.
git commit, git push는 사용자가 직접 진행합니다.

커밋 메시지 예시

제목: feat: 출발-도착 랜덤 코스 생성 추가

내용: -출발지와 도착지를 따로 선택하는 point-to-point 코스 생성 흐름을 추가한다. -서버는 랜덤 경유지를 포함해 ORS 경로를 생성하고 실패 시 최대 3회 재시도한다. -홈 화면 모드 선택, 결과 재추천 분기, 지도 출발/도착 마커 표시, 관련 문서를 갱신한다.

RWR-mini-project

About