Skip to content

Development Guide

Jump to bottom
ClarusIubar edited this page May 14, 2026 · 8 revisions

개발 가이드

목적

이 문서는 JamIssue를 로컬에서 개발하고 검증할 때 따라야 하는 기본 절차를 정리합니다.

기본 원칙

  • 사용자에게 보이는 문구는 기능 버그, 깨진 인코딩, 명백한 오표기가 아니면 바꾸지 않습니다.
  • 리팩터링은 구조, 책임 경계, 이름 안전성, 의존성 흐름, 테스트 보강에 한정합니다.
  • 작업은 이슈 기준으로 진행하고, 완료 판단 근거 없이 체크리스트를 닫지 않습니다.
  • 문서 링크는 클릭 가능한 Wiki 링크를 사용합니다.

로컬 개발 흐름

  1. 최신 기준 브랜치를 확인합니다.
  2. 작업 이슈와 완료 조건을 확인합니다.
  3. 필요한 환경 변수를 확인합니다.
  4. 프론트엔드, Worker, FastAPI 중 작업 범위를 구분합니다.
  5. 변경 후 로컬 검증을 실행합니다.
  6. PR에는 테스트 결과와 완료 근거를 남깁니다.

자주 쓰는 명령

npm run lint
npm run typecheck
npm run build
npm run test:unit

FastAPI 변경이 있을 때:

cd backend
python -m pytest tests

브랜치와 PR

  • 운영 기준 브랜치: main
  • main 직접 커밋은 금지합니다.
  • PR은 관련 이슈를 명시하고, 체크리스트와 검증 결과를 포함해야 합니다.

부모 이슈는 작업 전체의 목적, 범위, 완료 기준을 관리합니다. 실제 구현은 서브 이슈별 브랜치에서 진행합니다.

브랜치 이름은 이슈 번호나 작성자/도구 접두사보다 목적을 우선합니다.

권장 형식:

<area>-<purpose>

예시:

  • worker-baseline-refactor-gate
  • worker-contract-boundaries
  • worker-base-data-read-model
  • worker-review-domain-service
  • worker-account-community-admin-boundaries
  • worker-routing-runtime-cleanup
  • worker-docs-release-traceability
  • wiki-navigation-and-handoff-docs
  • notification-overlay-z-index-fix
  • oauth-session-secret-guard
  • api-compatibility-contract-tests

금지:

  • codex/
  • copilot/
  • 개인명 prefix
  • 이슈 번호 prefix
  • refactor, fix, docs, cleanup처럼 너무 넓은 이름

이슈 번호는 브랜치명에 넣지 않고 PR 본문의 Closes #서브이슈번호, 부모 이슈 체크리스트, merge SHA, 릴리즈 근거로 연결합니다.

GitHub 작업 방식

GitHub CLI 또는 REST API를 사용할 때 UI 로그인 흐름을 새로 열지 않습니다.

권장 순서:

  1. gh auth token 확인
  2. Git Credential Manager token 사용
  3. GitHub REST API 호출

PowerShell에서 이슈 본문을 작성할 때 Markdown 백틱이 깨질 수 있습니다. 코드 span이 필요한 본문은 single-quoted here-string 등 안전한 방식으로 작성합니다.

주요 문서

상세 작업 단위 기준

작업 단위는 아래 중 하나로 유지합니다.

작업 유형 예시 주의
feature 새 사용자 기능 PRD/릴리즈 노트 필요
fix 버그 수정 재현 조건과 회귀 테스트 필요
refactor 구조 개선 동작/copy/API shape 변경 금지
docs 문서 수정 [skip ci] 가능 여부 확인
test 테스트 보강 fixture 문구 임의 변경 금지
chore 운영 정리 사용자 영향 없음 명시

리팩터링 체크리스트

  • 어떤 책임 경계를 개선하는지 명시
  • 사용자-facing copy 변경 없음
  • API path/response shape 변경 없음
  • DB schema 변경 없음
  • OAuth 성공 경로 변경 없음
  • 테스트 또는 검증 명령 실행
  • 관련 이슈 체크리스트에 근거 기록

UI/UX 기대 동작 추적

UI/UX 관련 버그나 화면 변경은 UI/UX QA 매트릭스의 UIUX-### ID와 연결합니다.

PR 본문에는 아래 항목을 기록합니다.

  • 영향받는 UIUX-### ID
  • 재현 경로
  • 자동 테스트 파일 또는 명령
  • 수동 QA가 필요한 경우 기기와 브라우저
  • 관련 issue, PR, merge SHA, CI 링크

자동 테스트 또는 수동 QA 근거 없이 UI/UX 이슈를 close하지 않습니다.

Config hardening 기준

production code에 의미 있는 raw number를 직접 추가하지 않습니다. 새 수치가 필요하면 먼저 소유 영역을 정합니다.

영역 기준
지도/좌표/마커 src/config/mapConfig.ts
UI token과 visual config src/config/uiTokenConfig.ts, src/styles/tokens.css
프론트 런타임 limit src/config/runtimeLimitConfig.ts
Worker runtime deploy/api-worker-shell/config/runtime.ts
FastAPI local/fallback runtime backend/app/runtime_config.py
허용 예외 config/numeric-literal-allowlist.json

기본 허용 예외는 0, 1, -1, index, HTTP status, test fixture, protocol/version literal처럼 의미가 코드 문맥에서 명확한 값입니다. 그 외 production numeric literal은 allowlist에 category와 reason을 남기거나 config class/CSS token으로 이동합니다.

로컬 검증 세부

Frontend/Worker:

npm run check:numeric-literals
npm run lint
npm run typecheck
npm run test:unit
npm run build

전체 검증이 필요할 때:

npm run test:all

FastAPI:

cd backend
python -m pytest tests

문서 작성 기준

Repo docs:

  • 코드와 함께 버전 관리되어야 하는 기준을 둡니다.
  • PR과 함께 review됩니다.

GitHub Wiki:

  • 사람이 빠르게 찾아야 하는 운영/설계/인수인계 기준을 둡니다.
  • 한글 문서를 기본으로 합니다.
  • Agent 주입용 문서만 영어를 유지합니다.

에이전트 위임 기준

다른 agent에게 맡기기 전 확인:

  • parent issue가 있는가?
  • sub issue가 있는가?
  • checklist가 있는가?
  • 완료 판단 근거가 정의됐는가?
  • 금지 변경 사항이 적혀 있는가?
  • handoff 문서가 연결됐는가?

없으면 구현을 시작하지 않습니다.

Clone this wiki locally