본문으로 건너뛰기

코딩 & 에셋 컨벤션

v1.0 | 2026-03-30

1. 개요​

The Hon: Joseon 프로젝트의 코딩/에셋/데이터 컨벤션을 정의한다. 상세 규칙은 .claude/rules/ 하위 파일에 정의되어 있으며, 해당 파일 작업 시 자동 로드된다.

2. 규칙 파일 참조​

규칙 파일적용 경로내용
.claude/rules/gdscript-style.mdgame/src/**/*.gd, game/test/**/*.gdGDScript 스타일 가이드
.claude/rules/pixel-art.mdgame/res/sprites/**, game/res/tilesets/**픽셀아트 제작 규칙
.claude/rules/audio-spec.mdgame/res/audio/**오디오 사양
.claude/rules/json-data.mdgame/data/**/*.jsonJSON 데이터 포맷
.claude/rules/testing.mdgame/test/**테스트 규칙 (GdUnit4)

3. GDScript 스타일 요약​

상세: .claude/rules/gdscript-style.md 일반 GDScript 패턴 및 베스트 프랙티스 (State Machine, Component, Pooling 등): /godot-gdscript-patterns skill 참조

3-1. 네이밍​

대상스타일예시
클래스명PascalCaseYinYangSystem, WeaponManager
변수/함수snake_casecurrent_hp, get_damage()
상수UPPER_SNAKEMAX_WEAPONS, BASE_SPEED
시그널snake_case (과거형)health_changed, enemy_killed
노드 경로PascalCase$HUD/HealthBar
파일명snake_caseyin_yang_system.gd

3-2. 파일 구조​

game/src/
├── autoloads/     # 싱글톤 12개 (EventBus, GameManager, DataManager 등)
├── components/    # 재사용 컴포넌트 (Health, Hitbox, Hurtbox, Movement, EtherealShield)
├── systems/       # 코어 게임 시스템 12개 (YinYang, Resonance, Capture, Curse 등)
├── player/        # 플레이어 엔티티
├── enemies/       # 적 + bosses/ 서브디렉토리
├── weapons/       # 무기 12종 (각 무기별 서브디렉토리)
├── souls/         # 영혼 4종 (각 영혼별 서브디렉토리)
├── equipment/     # 장비 로직
├── ui/            # UI 스크립트 20+
├── hub/           # 거점 (NPC, 스테이지 선택)
└── pickups/       # 픽업 아이템 (XP 젬, 장비 드롭)

3-3. 핵심 규칙​

  • class_name 선언 필수 (모든 .gd 파일)
  • 타입 힌트 필수 (매개변수, 반환값, 변수)
  • EventBus 패턴으로 시스템 간 통신 (직접 참조 최소화)
  • 오브젝트 풀링 사용 (투사체, 적, 경험치 오브)
  • JSON 데이터 파일에서 밸런스 수치 로드 (하드코딩 금지)

4. 데이터 컨벤션​

상세: .claude/rules/json-data.md

4-1. 파일 위치​

파일내용
game/data/characters.json캐릭터 스탯
game/data/weapons.json무기 스탯
game/data/enemies.json적 스탯
game/data/souls.json영혼 스탯
game/data/equipment.json장비
game/data/yinyang.json음양 상태
game/data/curses.json저주
game/data/levelup.json레벨업 테이블
game/data/stages.json스테이지
game/data/waves/웨이브 (스테이지별)

4-2. JSON 규칙​

  • SSOT 원칙: 밸런스 수치의 유일한 출처
  • 수정 시 add-changelog.sh로 변경이력 필수 기록
  • 배열 ID는 문자열 (예: "bujeok", "exorcist")
  • 날짜: ISO 8601 (예: "2026-03-30")
  • 들여쓰기: 2칸 스페이스

5. 에셋 컨벤션​

5-1. 스프라이트​

상세: .claude/rules/pixel-art.md

  • 팔레트: Endesga 32 + 오방색
  • 캐릭터: 16×16 또는 16×24px
  • 보스: 64×64 ~ 128×128px
  • 배경 투명 (PNG)
  • Git LFS 관리

5-2. 오디오​

상세: .claude/rules/audio-spec.md

  • 포맷: OGG Vorbis
  • BGM: 30초+ 심리스 루프
  • SFX: 0.5초 이내
  • 볼륨: -1dB 노멀라이즈
  • Git LFS 관리

5-3. 네이밍​

에셋 종류패턴예시
스프라이트{대상}_{상태}.pngexorcist_idle.png
타일셋tileset_{스테이지}_{변형}.pngtileset_village_ground.png
BGMbgm_{대상}_{변형}.oggbgm_stage01_main.ogg
SFXsfx_{카테고리}_{대상}.oggsfx_weapon_bujeok_fire.ogg

6. 테스트 컨벤션​

상세: .claude/rules/testing.md

  • 프레임워크: GdUnit4
  • 파일 위치: game/test/ (소스 미러 구조)
  • 네이밍: test_{대상}.gd (예: test_yin_yang_system.gd)
  • 테스트 함수: test_ 접두사
  • 실행: ./scripts/game/run-tests.sh

7. Git 컨벤션​

7-1. 브랜치​

브랜치용도
master릴리즈 (보호)
dev개발 통합 (모든 작업은 여기서)

feature 브랜치 생성 금지 — dev에서 직접 작업.

7-2. 커밋 메시지​

<type>: <description>

Co-Authored-By: <agent> <noreply@anthropic.com>

타입: feat, fix, refactor, docs, test, chore, balance

7-3. LFS 추적 대상​

*.png, *.ogg, *.wav, *.tres, *.tscn (대형), *.import

8. 에이전트 워크플로우 컨벤션​

시점필수 액션
작업 시작Slack dashboard 알림 + 태스크보드 start
작업 완료Slack dashboard 알림 + 태스크보드 done + git commit/push
에러 발생Slack dashboard error 알림
밸런스 변경add-changelog.sh 실행
비자명한 결정docs/decisions/ ADR 작성
승인 필요Slack review-queue 알림