ProjectA

Imported from jaba001/ProjectA (AGENTS.md). Install upstream with npx skills add jaba001/ProjectA. Copyright stays with the author.

ProjectA 작업 규칙

코드 스타일

• 한 줄로 작성 가능한 코드는 불필요하게 줄바꿈하지 않는다.
• 중괄호는 Allman 스타일로 작성한다.
• 주석은 코드 옆에 작성하지 않고, 설명할 코드의 윗줄에 영어와 한글로 작성한다.

엔진 콘텐츠 위치

• 원본 에셋은 기존 경로에서 직접 참조하며, 작업 편의나 폴더 통일을 위한 User_JeHoon 복제를 하지 않는다. 이 규칙은 이후 모든 작업에 계속 적용한다.
• 중복 정리 대상은 외부 원본에서 User_JeHoon으로 복사한 사본이다. 외부 팩끼리 겹치는 에셋은 비교·통합하지 않는다. 기존 사본은 원본과의 실제 차이·사용 참조·저장된 경로 호환을 확인하며 이름만으로 삭제하지 않는다. 사용자 수정본·필요한 리타깃 결과·원본 FBX와 임포트 결과를 단순 중복으로 취급하지 않는다.
• 새 프로젝트 전용 맵·Blueprint·Widget·DataAsset·Material·FX·필수 리타깃 결과는 Content/User_JeHoon/ (/Game/User_JeHoon/)에 작성한다. 기존 폴더 대소문자를 유지하며 외부 팩 기반의 필수 파생 결과는 원본 팩명·하위 폴더 구조를 유지한다. 검증용 에셋을 반복 복제하지 않고 필요한 경우 기존 /Game/User_JeHoon/Validation/T12를 재사용한다.
• 원본을 변경해야 하는 경우에도 단순 참조·자식 Blueprint·Material Instance·엔진 확장 설정으로 해결할 수 있는지 먼저 확인한다. 별도 사본이 반드시 필요하면 이유와 용량 영향을 사용자에게 먼저 설명한다. C++·설정·생성 명세·로그는 각각 기존 Source·Config·Saved 위치를 유지한다.
• 기존 에셋 이동은 Unreal AssetTools 등 엔진 기능으로 수행하고 참조 갱신·Redirector 정리를 확인한다. 탐색기에서 uasset/umap만 이동하지 않는다. 엔진이 관리하는 External Actors/Objects 경로도 임의로 옮기지 않는다.

데이터와 멀티플레이 확장 원칙

• Unreal 기본 기능과 공식 확장 지점을 우선 활용한다. 저장·데이터·능력·네트워크 기능은 USaveGame·USTRUCT/DataAsset·GAS·Replication 등 기존 엔진 기능으로 해결할 수 있는지 먼저 확인한다.
• 아이템·적 유닛·스킬·효과의 분류와 조합, 후보 선별 및 향후 확률 가중치 확장은 GAS·GameplayTag 기반을 설계 원칙으로 한다. PoE처럼 콘텐츠의 태그를 공통 조건으로 활용하려는 사용자 의도를 유지하며, 특정 게임의 세부 규칙이나 확률 공식을 그대로 채택한 것으로 해석하지 않는다.
• 기존 GAS 태그와 에셋의 태그 설정·참조·의미를 보존한다. 신규 구현과 리팩터링에서 태그 기반 조건·이벤트·효과 연결을 이름·클래스·enum별 하드코딩으로 대체하거나 실행 경로에서 우회하지 않는다. 내부 단계·고정 실행 종류를 표현하는 enum은 사용할 수 있으나 콘텐츠 태그 분류와 조건 판정을 대신하지 않는다.
• 후보의 필수·제외 태그 등 조건은 GameplayTagContainer/GameplayTagQuery 등 엔진 기능을 우선 활용하고, 기본 가중치·태그 조건별 보정은 DataAsset/USTRUCT 등 데이터로 관리한다. 후보 필터·가중치 계산·추첨을 재사용 가능한 공통 로직으로 분리하여 아이템·적 유닛·스킬마다 같은 규칙을 중복 구현하지 않는다.
• 라운드 조정자는 실행 시점·순서·상태 전이를 조율하고, 개별 스킬 실행·효과 적용과 콘텐츠 후보 선별·가중치 계산은 별도 책임으로 분리한다. 스킬·효과는 GAS 공식 확장 지점과 태그 조건을 통해 연결하며, 태그 등록만 남긴 채 실제 선택·실행에서 사용하지 않는 상태를 태그 기반 구현 완료로 기록하지 않는다.
• 태그 계층·가중치 결합 방식·추첨 시점·중복 허용·최종 수치는 미결정 시 임의로 확정하지 않는다. 콘텐츠 선택 확률과 전투 명중 판정은 구분한다. 이 확장 원칙만으로 기존 서버 충돌 판정이나 제거된 자동 스킬 추첨을 변경하지 않으며, 현재 실행 경로의 태그 연동과 향후 가중치 확장은 실제 구현·검증 상태를 별도로 기록한다.
• T14 기획의 Async PvP와 Listen Server 기반 Co-op 방향을 따른다. 첫 Vertical Slice와 기본 Run은 싱글플레이를 유지하며 전체 Replication 리팩터링을 즉시 진행하지 않는다.
• 새 Run/Party/Encounter/Combat 데이터는 직렬화 가능한 Runtime Data와 Command를 우선한다. Actor reference에 과도하게 의존하거나 향후 Snapshot·Replication 확장을 방해하는 강한 로컬 PlayerController 의존성을 만들지 않는다.
• Co-op은 최대 4인, 첫 동기화 검증은 2인으로 진행한다. 캐릭터의 원래 소유자는 고정하며 다른 사람이 대신 조작하거나 같은 Run에 대체 참가할 수 없다. Host 권위의 승계와 캐릭터 소유권을 구분한다.
• 서버가 Action Request를 검증·실행하고 CombatManager·TurnManager·Grid Occupancy·Unit State·HP/AP·사망·Combat Result의 최종 권위를 가진다. 새 Host도 타인 캐릭터의 인간 조작권을 얻지 않는다.
• 최초 Host는 참가 번호 1, 나머지는 최초 합류 순서대로 2·3·4번을 유지한다. 명시적 재개에 참여하는 인간 중 가장 작은 번호가 Host를 승계하며 혼자 재개하면 본인이 Host가 된다. 캐릭터 슬롯이나 재접속 순서로 번호를 다시 부여하지 않는다.
• 정상 종료·돌발 끊김만으로 Host를 자동 변경하거나 캐릭터를 AI로 전환하지 않는다. AI 전환은 사전 동의 없이 Host가 단독 확정한다. 싱글로 전환하면 나머지는 해당 Run 종료까지 AI를 유지하며 소유자가 돌아와도 인간 조작을 되돌리지 않는다. 노드 선택·Continue는 현재 Host가 결정한다. 인간 참가자만 MMR 반영, 확정 턴 경계 복구와 세부 경계는 멀티플레이 설계를 따른다. 미결정 랭크 이탈 정책은 임의로 확정하지 않는다.
• 온라인 연결은 Steam P2P와 Unreal Listen Server를 우선한다. 선택한 Steam+PlayFab 조합에는 운영비를 피하려는 사용자 조건이 있으므로 무료 개발 범위와 출시 운영비를 구분하고 유료 리소스를 임의로 활성화하지 않는다. P2P만으로 중앙 저장·중복 진행 방지·MMR 검증이 해결됐다고 기록하지 않는다.
• Async PvP의 초기 로컬 Snapshot 전투와 경쟁 콘텐츠의 서버 데이터·결과 검증을 구분한다. 일부 복제 선언이나 로컬 테스트만으로 네트워크 지원 완료로 기록하지 않는다.
• 작업 중 애매하거나 결정이 필요한 정책은 구체적인 선택지와 영향을 사용자에게 피드백한다. 미결정 정책을 임의로 확정하지 않고, 해당 결정에 의존하지 않는 작업은 계속 진행한다.

Visual Studio 사용

• 작업 완료 시 Unreal Editor를 자동으로 실행하거나 다시 열지 않는다. 해당 작업에서 사용자가 별도로 요청한 경우에만 열린 상태로 마무리한다.
• 작업 완료나 변경 파일 안내를 위해 Visual Studio를 자동으로 실행하거나 활성화하지 않는다. 사용자가 요청하거나 작업 수행에 필요한 경우에만 연다.
• 명령줄에서 가능한 빌드·정적 검사·Git 작업은 IDE를 열지 않고 진행한다.

작동 테스트와 보고서

• 작동 테스트는 사용자가 수행한다. 사용자가 이후 특정 실행을 명시적으로 요청하지 않는 한 Codex는 PIE, 게임 플레이, Unreal 자동화 테스트, 패키지 실행 등 프로그램을 구동하는 검증을 시작하지 않는다.
• Codex는 필요한 명령줄 컴파일, 코드·문서·링크·diff 정적 검사를 수행한다. 컴파일 성공과 실제 게임 동작 확인을 구분한다.
• 사용자가 삭제한 Docs/TEST_REPORT.md는 복원하거나 다시 만들지 않는다. 추가 확인이 필요한 동작만 TODO에 실행 방법·기대 결과를 1~3줄로 기록한다. 별도 테스트 문서를 늘리지 않는다.
• 문서와 완료 보고는 간략하게 작성한다. 최종 답변은 기본 3~5줄로 변경 내용·검증 결과·필요한 사용자 확인·커밋/push를 요약한다. 파일 목록·로그·상세 경고는 문제 해결에 필요할 때만 추가한다.
• 사용자 결과가 오기 전에는 작동 검증을 완료로 표시하지 않는다. 이전 실행 기록은 당시 코드 기준의 이력으로 구분하며 최신 수정의 성공 근거로 대체하지 않는다.
• 사용자의 일반 플레이 이상 없음 보고는 해당 플레이 범위의 결과로 기록한다. 구체적으로 확인하지 않은 협동·저장 실패 등 예외 시나리오의 완료로 확대하지 않는다.

문서 관리

• 문서 분류 번호는 숫자를 사용한다. 대분류는 1, 세부 항목은 1-1 형식으로 작성하고 관련 참조·링크도 함께 갱신한다. 기존 작업 ID와 코드·명령·경로의 식별자는 유지한다.

• Markdown은 공식 기술 문서 문체로 간결하게 작성한다. 대화체·반복 설명은 제거하고 확정 정책·제안·미구현·검증 결과를 구분한다. TODO의 제안에는 아래 선택 번호를 유지한다. 중복 상세는 기준 문서에 통합하되 실행 명령·수용 조건·검증 근거는 보존한다.

• TODO의 제안은 제안 1 이런식으로 작성한다. 각 항목에 현재 상태, 2~3개의 구체적인 대안, 권장안과 짧은 이유·영향, 선택 후 작업과 수용 조건을 함께 기록한다. 번호는 다른 제안에 재사용하지 않는다.

• 제안의 선택 체크와 작업 완료를 구분한다. 선택지 1개만 체크하면 채택 요청으로 읽으며, 미선택은 대기하고 복수 선택은 임의로 해석하지 않는다. 권장안은 자동 선택하지 않는다. 구현·컴파일·사용자 작동 확인의 상태는 Codex가 별도로 기록한다.

• 사용자가 TODO 진행을 요청하면 Docs/TODO.md를 작업 범위·선택 결과·우선순위의 기준으로 읽고 추가 설명을 요구하지 않고 진행한다. 실제 코드·기술 기준·검증 세부는 필요할 때 관련 파일을 확인한다. 미선택 제안에 의존하는 작업만 보류하고 독립 작업은 계속한다.

• 로컬 Docs/TODO.md에 저장된 체크를 기준으로 한다. Notion에서 원본 파일에 직접 저장했다면 업로드·원격 연동을 추가로 요구하지 않는다. 별도 복사본을 사용하는 경우에만 최신 Markdown 또는 명시적으로 연결한 페이지에서 선택 결과를 TODO.md에 반영한다. 자동 동기화를 가정하지 않으며, 원격 페이지 연결은 TODO에 기록하고 읽지 않은 체크를 읽었다고 보고하지 않는다.

• Docs는 GAME_DESIGN(목표 기획), PROJECT_PLAN(현재 구조·설정), UI_README(UI 구조·생성 명세), TODO(남은 작업·간단 확인), MULTIPLAYER(멀티플레이 계약), HISTORY(완료 이력)의 6개 문서를 기준으로 관리한다.

• 작업·세션·T14 세부 번호마다 별도 Markdown 파일을 늘리지 않는다. 기존 문서의 해당 절을 갱신하고 중복 설명은 링크로 연결한다. 원문과 상세 변경 과정은 Git 이력으로 조회한다.

작업 완료와 자동 커밋·Push

• 사용자가 별도로 지시하지 않으면, 파일을 수정하는 작업은 필요한 검증을 통과한 뒤 Git 커밋과 원격 push까지 자동으로 완료한다. 분석이나 질문 답변만 하는 작업에는 커밋을 만들지 않는다.
• 작업 시작과 커밋 직전에 Git 상태를 확인한다. 사용자가 별도로 제외를 지시하지 않으면 이번 작업과의 관련 여부나 작성자에 관계없이 저장소에 남아 있는 추가·수정·삭제를 모두 함께 커밋한다. 기존 변경을 임의로 되돌리거나 덮어쓰지 않고 현재 내용을 보존하여 포함한다. Git이 무시하는 생성물은 강제로 추가하지 않는다.
• 커밋 전에 루트 README.md와 변경 내용의 일치 여부를 확인하고, 기능이나 사용 방법에 영향이 있으면 함께 갱신한다.
• C++ 변경은 Development Editor / Win64 컴파일과 관련 정적 검사를 수행하고, 문서만 변경한 경우에는 내용과 링크를 확인한다. 추가 작동 확인은 TODO의 간단한 절차로 사용자에게 인계한다. 현재 변경에 대해 이미 성공한 검사는 불필요하게 반복하지 않는다.
• 커밋 전에 git diff --check와 스테이징된 전체 diff를 확인한다. 함께 포함하는 기존 변경도 해당 유형에 필요한 검증 범위에 넣는다. 필요한 컴파일·정적 검사가 실패했거나 완료되지 않았다면 자동 커밋하지 않고 해결하거나 원인을 보고한다. 남은 사용자 작동 확인은 TODO와 커밋 본문에 명시하고, 컴파일·정적 검사 통과 후 커밋·push할 수 있다.
• 커밋 메시지와 Git 설명은 한글로 간결하게 작성한다. 변경이 없으면 빈 커밋을 만들지 않는다.
• Codex가 만드는 커밋의 Summary(제목)는 반드시 [codex] 로 시작한다. Description(본문)도 빠짐없이 작성하고, 변경 내용과 이유 및 실제 검증 결과를 한글로 기록한다.
• 커밋 후 현재 브랜치의 upstream으로 일반 push를 실행한다. upstream이 없으면 원격과 대상 브랜치를 확인해 설정한다. 강제 push는 하지 않으며, push 실패 시 원인을 보고한다.
• 커밋·push 후 Git 상태를 다시 확인한다. 작업 완료 시 커밋 해시, 함께 포함한 기존 변경, 검증 결과와 push 결과를 보고하며 미커밋 변경이 남았다면 이유를 명시한다.