# Godot 개발 에이전트 지침서 (agents.md)

이 파일은 AI 코딩 에이전트가 본 Godot 프로젝트를 분석하고 코드를 작성하기 위한 필수 규칙을 정의합니다.

## 1. 프로젝트 및 기술 스택 정보
- **엔진 버전:** Godot 4.x (GDScript)
- **주력 언어:** GDScript
- **주요 아키텍처:** 싱글톤(AutoLoad), 노드 기반 트리 구조, 신호(Signal) 시스템 활용
- **핵심 폴더 구조:**
  - `res://scenes/`: 게임 씬 (.tscn) 파일
  - `res://scripts/`: GDScript (.gd) 파일
  - `res://assets/`: 스프라이트, 오디오, 폰트 등 리소스
  - `res://addons/`: 플러그인

## 2. GDScript 코딩 스타일 및 규칙
- **정적 타이핑:** 모든 함수 매개변수와 반환 타입, 변수에 타입을 명시하십시오. (예: `var player_health: int = 100`)
- **이름 짓기 규칙:** 
  - 클래스 및 노드 이름: PascalCase (`class_name PlayerCharacter`)
  - 변수 및 함수 이름: snake_case (`func take_damage()`)
  - 상수: UPPER_SNAKE_CASE (`const MAX_SPEED: int = 400`)
- **노드 참조:** `$` 기호 대신 `@onready` 키워드를 사용하여 노드를 안전하게 캐싱하십시오.
- **신호 연결:** 문자열 기반 연결 대신 콜러블(Callable)을 사용하십시오. (예: `button.pressed.connect(_on_button_pressed)`)

## 3. 에이전트 작업 지침
1. **절대 금지:** `.tscn` (씬) 파일의 원시 JSON/텍스트 데이터를 직접 수정하지 마십시오. 노드 생성 및 설정은 Godot 에디터를 통하거나 적절한 GDScript 코드로만 수행해야 합니다.
2. **참조 확인:** 코드를 수정하기 전에 관련된 씬 파일(`.tscn`)이나 기존 스크립트의 상속 구조를 먼저 분석하십시오.
3. **3D 노드 사용:** 3D 디펜스이므로 2D 노드(`Node2D`)가 아닌 3D 노드(`Node3D`, `CharacterBody3D`, `Path3D`, `PathFollow3D`)를 사용할 것.
4. **자원 관리:** `preload()`를 적극 활용하고, 복잡한 데이터는 커스텀 `Resource`를 만들어 관리할 것.
5. **독립성 유지:** 노드는 상위 노드를 직접 참조(`get_parent()`)하지 말고, 반드시 **시그널(Signal)**을 통해 통신할 것.

## 4. 커스텀 CLI 명령 (에이전트 전용)
에이전트는 아래의 명령을 수행하여 프로젝트를 관리할 수 있습니다.
- `run game`: `godot --main-pack project.pck` 또는 에디터 실행을 통해 게임을 시작합니다.
- `lint`: GDScript 내장 linter를 실행하여 코드 오류를 점검합니다.
- `clean`: `.godot/` 임시 캐시 폴더를 비웁니다.
