← 최신 가이드

md 지침 가이드

v1.0 · 2026-10-06 갱신 · 공통 원칙 28개 · Unity 원칙 10개

AI에 바로 적용하기

Claude Code나 Codex를 프로젝트 폴더에서 열고 붙여 넣으세요. 현재 지침 파일을 조사해 점검표를 만들고, 계획을 확인받은 뒤 고칩니다.

이 저장소의 AI 지침 파일(CLAUDE.md, AGENTS.md 등)을 아래 "md 지침 가이드 v1.0" (2026-10-06, 범위: 공통 + Unity)에 맞게 정리해 줘. 대상은 Claude Code와 Codex가 함께 쓰는 저장소다.
- 이 저장소는 Unity 프로젝트다. 공통 원칙(G)과 Unity 원칙(U)을 모두 적용하고, 루트 AGENTS.md는 "AGENTS.md (루트 · Unity 완성본)" 형식을 따른다.
- "Claude 전용" 원칙은 Claude Code 설정(.claude/, CLAUDE.md)에만 반영한다.

## 작업 절차
1. 현재 상태 조사: 루트와 하위 폴더의 CLAUDE.md, AGENTS.md, .claude/rules/, .claude/agents/, .claude/skills/,
   그 밖에 지침으로 쓰이는 문서(docs/ 등)를 찾고 파일별 줄 수를 센다. 아직 아무것도 고치지 않는다.
2. 점검표 작성: 아래 원칙마다 현재 상태를 "충족 / 위반 / 해당 없음"으로 판정하고 근거를 `파일:줄`로 적는다.
3. 변경 계획을 보여 주고 내 확인을 받은 뒤 수정한다. (확인 없이 바로 적용하려면 이 줄을 지운다)
4. 적용 규칙
   - 프로젝트 고유 정보(빌드·테스트 명령, 경로, 팀 규칙)는 보존한다. 지우거나 옮기는 줄은 보고서에 이유와 함께 적는다.
   - 템플릿은 형식 참고용이다. 저장소에 없는 도구·폴더·규칙을 지어내지 않는다. 모르는 값은 수정하지 말고 질문 목록에 넣는다.
   - 공통 지침은 AGENTS.md에 두고, CLAUDE.md는 `@AGENTS.md` 가져오기 + Claude 전용 몇 줄로 만든다 (Codex와 공유).
   - 포맷·스타일 규칙은 지침에 쓰지 말고 .editorconfig·분석기·훅으로 옮길 수 있는지 제안만 한다.
5. 검증: 바뀐 지침 파일의 줄 수를 다시 센다. 지침에 적은 경로·파일이 실제로 있는지 확인한다.
   Claude Code면 `/memory`로 로드되는 파일을 확인한다.
   Codex면 `codex --ask-for-approval never "Summarize the current instructions."`로 확인한다.
6. 보고: 바뀐 파일과 줄 수 변화(전→후), 삭제·이동한 내용과 이유, 남은 질문을 표로 정리한다.

## 가이드 v1.0 원칙 (공통 + Unity)
### 크기와 범위
- G01 루트 지침 파일은 200줄 이하, 목표는 100~150줄 + 짧은 참조 문서 몇 개 — 이유: 루트 파일은 매 세션 컨텍스트를 차지하고, 길어지면 규칙이 묻혀 무시됩니다
- G02 줄마다 "이 줄을 지우면 실수할까?"를 묻고, 아니면 삭제 — 이유: 모델이 이미 아는 것·코드에서 읽히는 것은 토큰만 씁니다
- G03 루트에는 모든 작업에 해당하는 것만: 빌드·테스트 명령, 비표준 규칙, 함정 — 이유: 루트는 항상 로드되므로 가끔 쓰는 내용은 낭비입니다
- G04 아키텍처 개요, 파일별 설명, 일반 코딩 상식은 넣지 않음 — 이유: 모델이 코드를 읽어 알 수 있고, 무관한 맥락이 판단을 흐립니다
- G05 /init 등 자동 생성 결과는 초안으로만 쓰고 사람이 줄여서 확정 — 이유: 자동 생성 파일은 개요 위주라 효과가 낮고 비용만 늘었다는 측정이 있습니다
### 분리와 연결
- G06 특정 파일 유형·폴더에만 필요한 규칙은 .claude/rules/*.md + paths: 로 분리 — 이유: 해당 파일을 읽거나 고칠 때만 로드되어 평소 컨텍스트를 아낍니다 (적용 도구: Claude 전용)
- G07 Codex와 공유할 폴더 규칙은 하위 폴더 AGENTS.md + 같은 폴더 CLAUDE.md(@AGENTS.md 한 줄) — 이유: 규칙 원본을 하나로 두고 두 도구가 모두 읽게 합니다
- G08 가끔 쓰는 절차·도메인 지식은 스킬(.claude/skills/<이름>/SKILL.md)로 — 이유: 시작 시 설명(description)만 로드되고 본문은 필요할 때 읽힙니다 (적용 도구: Claude 전용)
- G09 단, 자주 필요한 지식의 색인은 루트 파일에 직접 둠 — 이유: 스킬은 모델이 꺼낼지 판단해야 해서 놓칠 수 있고, 루트는 항상 보입니다
- G10 분리한 문서는 반드시 루트에서 링크하고 언제 읽을지 한 줄로 적음 — 이유: 어디서도 가리키지 않는 문서는 거의 읽히지 않습니다
- G11 코드 내용을 복사하지 말고 경로:줄 포인터로 — 이유: 복사본은 코드가 바뀌면 낡은 정보가 됩니다
- G12 @경로 가져오기(import)는 정리 용도로만 사용 — 이유: import한 파일도 시작 시 전부 로드되므로 토큰은 줄지 않습니다 (적용 도구: Claude 전용)
### 문장 쓰는 법
- G13 "하지 마"에는 "대신 이렇게"를 붙임 — 이유: 금지만 있으면 모델이 대안을 찾느라 과하게 탐색합니다
- G14 선택이 갈리는 곳은 결정 표(상황 → 선택) — 이유: 구현 전에 모호함을 없앱니다
- G15 반복 작업은 번호 매긴 절차 — 이유: 빠뜨리는 단계가 줄어듭니다
- G16 코드 예시는 실제 코드 3~10줄 — 이유: 짧은 실물 예시가 기존 패턴 재사용을 늘립니다
- G17 강조("IMPORTANT")는 한 줄에만, 나머지는 구체적 행동으로 표현 — 이유: 여러 줄을 강조하면 아무것도 두드러지지 않습니다
- G18 "think step by step", "think carefully" 류 문장 삭제 — 이유: Opus 5.5는 사고가 항상 켜져 있고 노력 수준(effort)으로 조절합니다 (적용 도구: Claude 전용)
### 도구로 강제
- G19 포맷·스타일 규칙은 린터·포매터·훅으로 — 이유: CLAUDE.md는 권고라 어길 수 있고, 훅은 매번 실행이 보장됩니다
- G20 완료 조건은 실행 가능한 검사(테스트, 빌드, 스크린샷)로 지정 — 이유: 검사가 없으면 "끝난 것처럼 보임"이 유일한 신호가 됩니다
- G21 압축(compaction) 때 보존할 것을 한 줄로 지정 — 이유: 긴 세션 요약에서 수정 파일 목록·테스트 명령이 빠지는 것을 막습니다 (적용 도구: Claude 전용)
### 측정과 정리
- G22 /context, /memory로 실제 로드된 파일과 토큰을 확인 — 이유: 어떤 파일이 얼마나 차지하는지 보아야 줄일 곳이 보입니다 (적용 도구: Claude 전용)
- G23 규칙을 바꾸면 같은 작업으로 행동이 실제로 달라지는지 확인, 안 달라지면 삭제 — 이유: 효과 없는 줄은 비용만 남깁니다
### 멀티 에이전트
- G24 지침을 4층으로: ① 공통 AGENTS.md ② 영역별(rules·폴더) ③ 역할별(agents·roles) ④ 인계(work/ 폴더) — 이유: 공통 파일에 역할 설명까지 넣으면 모든 역할이 남의 규칙을 읽게 됩니다
- G25 리드(비싼 모델)는 계획·지시서·총정리, 하위 세션은 지시서대로 수행하고 보고서 파일을 남김 — 이유: 대화 대신 파일로 인계하면 새 세션의 맥락이 깨끗하고 다른 도구도 읽을 수 있습니다
- G26 조사·리뷰는 서브에이전트, 여러 파일을 고치는 구현은 별도 세션 — 이유: 서브에이전트는 별도 컨텍스트에서 요약만 돌려줘 리드 컨텍스트를 아낍니다 (적용 도구: Claude 전용)
- G27 서브에이전트 model: 로 비용 분담 (탐색 haiku/sonnet, 리뷰 opus, 기본 inherit) — 이유: 작업 난이도에 맞는 모델로 비용을 줄입니다 (적용 도구: Claude 전용)
- G28 공통 파일을 짧게 유지 (일반 서브에이전트도 CLAUDE.md 계층 전체를 로드) — 이유: 역할 수만큼 공통 파일이 반복 로드됩니다 (적용 도구: Claude 전용)
### Unity · 환경과 검증
- U01 Unity 버전, 렌더 파이프라인, 대상 플랫폼, 에디터 실행 경로를 루트 지침에 적음 — 이유: 버전·파이프라인마다 API가 달라 모델이 추측하면 틀린 코드를 씁니다
- U02 검증 명령으로 배치 모드 테스트 명령을 적음 (-batchmode -projectPath . -runTests -testPlatform EditMode -testResults <파일>) — 이유: 에디터를 열지 않고도 모델이 완료 여부를 스스로 확인할 수 있습니다
### Unity · 에셋과 직렬화
- U03 에셋을 옮기거나 이름을 바꿀 때 .meta 파일을 함께 옮기라고 명시 — 이유: Unity 밖에서 에셋만 옮기면 .meta 짝이 깨져 새 에셋으로 취급되고 참조가 끊깁니다
- U04 직렬화 필드 이름을 바꿀 때 [FormerlySerializedAs("옛이름")]를 붙이라고 명시 — 이유: 이름만 바꾸면 인스펙터에 저장된 값이 사라집니다
- U05 씬·프리팹(.unity/.prefab) YAML은 텍스트로 직접 고치지 말고 에디터(Unity MCP)로 수정하거나 보고서에 적게 함 — 이유: 참조 ID가 얽힌 YAML을 손으로 고치면 깨지기 쉽고, 깨져도 바로 드러나지 않습니다
- U06 Library/, Temp/, Logs/, obj/ 는 읽지도 고치지도 않게 명시 — 이유: 자동 생성 폴더라 읽으면 토큰만 쓰고, 고쳐도 다시 만들어집니다
### Unity · 도구와 세션
- U07 코드 스타일 규칙은 .editorconfig + Roslyn 분석기로 강제 (분석기는 플러그인으로 등록) — 이유: 지침 파일의 스타일 규칙은 어길 수 있지만 분석기 경고는 컴파일 때마다 나옵니다
- U08 셰이더·UI 등 영역 규칙은 paths 규칙(**/*.shader, **/*.hlsl) 또는 폴더 AGENTS.md로 분리 — 이유: 셰이더 규칙을 C# 작업 때까지 읽을 필요가 없습니다
- U09 에디터 조작은 Unity MCP(예: CoplayDev unity-mcp)에 맡기되, 에디터 담당 세션은 하나만 — 이유: MCP는 열려 있는 에디터에 연결되므로 여러 세션이 같은 에디터를 조작하면 상태가 꼬입니다
- U10 코드만 고치는 역할은 git 워크트리, 에디터가 필요한 역할은 본 프로젝트에서 — 이유: 새 워크트리에는 Library/가 없어 Unity로 열면 재임포트가 필요합니다

## 최종 형태 템플릿 (형식 참고용, < > 는 프로젝트 값으로)
#### CLAUDE.md (루트)
````
@AGENTS.md

## Claude Code 전용
- 코드베이스 조사는 explorer 서브에이전트에 맡기고 요약만 받는다
- 구현을 끝내기 전에 reviewer 서브에이전트로 diff를 검토한다
- 압축할 때는 수정한 파일 목록, 검증 명령, 현재 작업 번호를 반드시 보존한다
````

#### .claude/agents/reviewer.md (서브에이전트)
````
---
name: reviewer
description: 구현이 끝난 뒤 diff를 검토할 때 사용. 버그와 요구사항 누락만 보고
tools: Read, Grep, Glob, Bash
model: opus
---
너는 코드 리뷰어다.
1. `git diff`와 해당 지시서(work/tasks/)를 읽는다
2. 요구사항 누락, 널 참조, 경계 조건, 지침 파일의 프로젝트 고유 규칙 위반을 확인한다
3. 취향·스타일 의견은 보고하지 않는다
4. 발견마다 `파일:줄`, 문제, 수정 제안을 한 줄씩 쓴다
````

#### docs/roles/<역할>.md + 지시서 (별도 세션용)
````
# 역할: <역할명>
- 범위: <이 역할이 수정하는 폴더> 만 수정한다
- 시작 시 읽을 것: 지시서, <해당 폴더의 AGENTS.md>
- 끝낼 때: 검증 명령 실행 → work/reports/<번호>.md 작성 (AGENTS.md의 보고 형식)

--- work/tasks/<번호>-<역할>.md ---
# <번호> <작업 제목>
- 목표: <한 문장>
- 범위 밖: <건드리지 않을 것>
- 완료 조건: <실행해서 확인할 검사>

--- 세션 시작 메시지 (Claude Code·Codex 공통) ---
docs/roles/<역할>.md 와 work/tasks/<번호>-<역할>.md 를 읽고 그 역할로 진행해.
````

#### AGENTS.md (루트 · Unity 완성본)
````
# <프로젝트명> — 에이전트 공통 지침

## 환경
- Unity <6000.x.y>, C# <버전>, 렌더 파이프라인 <URP>, 대상 <Android/iOS>
- 에디터 실행 파일: <C:\Program Files\Unity\Hub\Editor\6000.x.y\Editor\Unity.exe>

## 검증 명령 (작업 끝나면 반드시 실행)
- EditMode 테스트: `"<Unity.exe>" -batchmode -projectPath . -runTests -testPlatform EditMode -testResults work/test-results.xml`
- 실패하면 결과 XML의 실패 항목을 고친 뒤 다시 실행

## 프로젝트 고유 규칙
- 에셋을 옮기거나 이름을 바꿀 때는 `.meta`를 함께 옮긴다 (짝이 깨지면 참조가 끊김)
- 직렬화 필드 이름을 바꿀 때는 `[FormerlySerializedAs("옛이름")]`을 붙인다
- 씬·프리팹(.unity/.prefab)은 텍스트로 직접 고치지 않는다
  → 대신 Unity MCP로 에디터에서 수정하거나, 필요한 변경을 보고서에 적는다
- `Library/`, `Temp/`, `Logs/`, `obj/`는 읽거나 수정하지 않는다
- <그 밖의 팀 규칙> → 대신 <이렇게>

## 결정 표
| 상황 | 선택 |
|---|---|
| 데이터 정의 | ScriptableObject (`Assets/Data/`) |
| 비동기 처리 | <UniTask 또는 Awaitable> |
| 에셋 로드 | <Addressables> |

## 문서 색인 (필요할 때만 읽기)
- UI 작업: `Assets/Scripts/UI/AGENTS.md`
- 셰이더 작업: `.claude/rules/shaders.md`
- 왜 이렇게 됐는지: `docs/decisions.md`

## 인계 규칙
- 지시서는 `work/tasks/`, 보고는 `work/reports/<같은 번호>.md`
- 보고 형식: 바꾼 파일 / 검증 결과(명령과 출력) / 남은 문제 / 리드가 결정할 것
- 다른 역할의 파일을 고쳐야 하면 고치지 말고 보고서에 적는다
````

#### Assets/Scripts/UI/AGENTS.md (폴더 전용)
````
# UI 폴더 규칙
- UI는 <UI Toolkit>. 새 화면은 `Assets/UI/Screens/`에 UXML+USS 한 쌍
- 화면 클래스는 `ScreenBase`를 상속 (예: `Assets/Scripts/UI/Screens/ShopScreen.cs:12`)
- 문자열은 하드코딩하지 않는다 → Localization 테이블 키 사용

(같은 폴더의 CLAUDE.md 내용: @AGENTS.md 한 줄)
````

#### .claude/rules/shaders.md (확장자 기준, Claude 전용)
````
---
paths:
  - "**/*.shader"
  - "**/*.hlsl"
  - "**/*.shadergraph"
---
# 셰이더 규칙
- URP 셰이더는 SRP Batcher 호환 유지: 속성은 `CBUFFER_START(UnityPerMaterial)` 안에
- 모바일 대상이므로 half 정밀도 우선, 필요할 때만 float
````

#### .claude/skills/unity-test/SKILL.md (스킬)
````
---
name: unity-test
description: Unity EditMode/PlayMode 테스트를 배치 모드로 실행하고 실패를 정리할 때
disable-model-invocation: true
---
1. 에디터가 같은 프로젝트를 열고 있으면 사용자에게 닫아 달라고 한다
   (같은 프로젝트를 두 번 열 수 없음)
2. AGENTS.md의 검증 명령을 실행한다. PlayMode면 `-testPlatform PlayMode`
3. work/test-results.xml에서 실패한 테스트 이름과 메시지만 뽑는다
4. 실패마다 원인 추정과 관련 파일:줄을 표로 보고한다
````

이 저장소의 AI 지침 파일(CLAUDE.md, AGENTS.md 등)을 아래 "md 지침 가이드 v1.0" (2026-10-06, 범위: 공통)에 맞게 정리해 줘. 대상은 Claude Code와 Codex가 함께 쓰는 저장소다.
- "Claude 전용" 원칙은 Claude Code 설정(.claude/, CLAUDE.md)에만 반영한다.

## 작업 절차
1. 현재 상태 조사: 루트와 하위 폴더의 CLAUDE.md, AGENTS.md, .claude/rules/, .claude/agents/, .claude/skills/,
   그 밖에 지침으로 쓰이는 문서(docs/ 등)를 찾고 파일별 줄 수를 센다. 아직 아무것도 고치지 않는다.
2. 점검표 작성: 아래 원칙마다 현재 상태를 "충족 / 위반 / 해당 없음"으로 판정하고 근거를 `파일:줄`로 적는다.
3. 변경 계획을 보여 주고 내 확인을 받은 뒤 수정한다. (확인 없이 바로 적용하려면 이 줄을 지운다)
4. 적용 규칙
   - 프로젝트 고유 정보(빌드·테스트 명령, 경로, 팀 규칙)는 보존한다. 지우거나 옮기는 줄은 보고서에 이유와 함께 적는다.
   - 템플릿은 형식 참고용이다. 저장소에 없는 도구·폴더·규칙을 지어내지 않는다. 모르는 값은 수정하지 말고 질문 목록에 넣는다.
   - 공통 지침은 AGENTS.md에 두고, CLAUDE.md는 `@AGENTS.md` 가져오기 + Claude 전용 몇 줄로 만든다 (Codex와 공유).
   - 포맷·스타일 규칙은 지침에 쓰지 말고 .editorconfig·분석기·훅으로 옮길 수 있는지 제안만 한다.
5. 검증: 바뀐 지침 파일의 줄 수를 다시 센다. 지침에 적은 경로·파일이 실제로 있는지 확인한다.
   Claude Code면 `/memory`로 로드되는 파일을 확인한다.
   Codex면 `codex --ask-for-approval never "Summarize the current instructions."`로 확인한다.
6. 보고: 바뀐 파일과 줄 수 변화(전→후), 삭제·이동한 내용과 이유, 남은 질문을 표로 정리한다.

## 가이드 v1.0 원칙 (공통)
### 크기와 범위
- G01 루트 지침 파일은 200줄 이하, 목표는 100~150줄 + 짧은 참조 문서 몇 개 — 이유: 루트 파일은 매 세션 컨텍스트를 차지하고, 길어지면 규칙이 묻혀 무시됩니다
- G02 줄마다 "이 줄을 지우면 실수할까?"를 묻고, 아니면 삭제 — 이유: 모델이 이미 아는 것·코드에서 읽히는 것은 토큰만 씁니다
- G03 루트에는 모든 작업에 해당하는 것만: 빌드·테스트 명령, 비표준 규칙, 함정 — 이유: 루트는 항상 로드되므로 가끔 쓰는 내용은 낭비입니다
- G04 아키텍처 개요, 파일별 설명, 일반 코딩 상식은 넣지 않음 — 이유: 모델이 코드를 읽어 알 수 있고, 무관한 맥락이 판단을 흐립니다
- G05 /init 등 자동 생성 결과는 초안으로만 쓰고 사람이 줄여서 확정 — 이유: 자동 생성 파일은 개요 위주라 효과가 낮고 비용만 늘었다는 측정이 있습니다
### 분리와 연결
- G06 특정 파일 유형·폴더에만 필요한 규칙은 .claude/rules/*.md + paths: 로 분리 — 이유: 해당 파일을 읽거나 고칠 때만 로드되어 평소 컨텍스트를 아낍니다 (적용 도구: Claude 전용)
- G07 Codex와 공유할 폴더 규칙은 하위 폴더 AGENTS.md + 같은 폴더 CLAUDE.md(@AGENTS.md 한 줄) — 이유: 규칙 원본을 하나로 두고 두 도구가 모두 읽게 합니다
- G08 가끔 쓰는 절차·도메인 지식은 스킬(.claude/skills/<이름>/SKILL.md)로 — 이유: 시작 시 설명(description)만 로드되고 본문은 필요할 때 읽힙니다 (적용 도구: Claude 전용)
- G09 단, 자주 필요한 지식의 색인은 루트 파일에 직접 둠 — 이유: 스킬은 모델이 꺼낼지 판단해야 해서 놓칠 수 있고, 루트는 항상 보입니다
- G10 분리한 문서는 반드시 루트에서 링크하고 언제 읽을지 한 줄로 적음 — 이유: 어디서도 가리키지 않는 문서는 거의 읽히지 않습니다
- G11 코드 내용을 복사하지 말고 경로:줄 포인터로 — 이유: 복사본은 코드가 바뀌면 낡은 정보가 됩니다
- G12 @경로 가져오기(import)는 정리 용도로만 사용 — 이유: import한 파일도 시작 시 전부 로드되므로 토큰은 줄지 않습니다 (적용 도구: Claude 전용)
### 문장 쓰는 법
- G13 "하지 마"에는 "대신 이렇게"를 붙임 — 이유: 금지만 있으면 모델이 대안을 찾느라 과하게 탐색합니다
- G14 선택이 갈리는 곳은 결정 표(상황 → 선택) — 이유: 구현 전에 모호함을 없앱니다
- G15 반복 작업은 번호 매긴 절차 — 이유: 빠뜨리는 단계가 줄어듭니다
- G16 코드 예시는 실제 코드 3~10줄 — 이유: 짧은 실물 예시가 기존 패턴 재사용을 늘립니다
- G17 강조("IMPORTANT")는 한 줄에만, 나머지는 구체적 행동으로 표현 — 이유: 여러 줄을 강조하면 아무것도 두드러지지 않습니다
- G18 "think step by step", "think carefully" 류 문장 삭제 — 이유: Opus 5.5는 사고가 항상 켜져 있고 노력 수준(effort)으로 조절합니다 (적용 도구: Claude 전용)
### 도구로 강제
- G19 포맷·스타일 규칙은 린터·포매터·훅으로 — 이유: CLAUDE.md는 권고라 어길 수 있고, 훅은 매번 실행이 보장됩니다
- G20 완료 조건은 실행 가능한 검사(테스트, 빌드, 스크린샷)로 지정 — 이유: 검사가 없으면 "끝난 것처럼 보임"이 유일한 신호가 됩니다
- G21 압축(compaction) 때 보존할 것을 한 줄로 지정 — 이유: 긴 세션 요약에서 수정 파일 목록·테스트 명령이 빠지는 것을 막습니다 (적용 도구: Claude 전용)
### 측정과 정리
- G22 /context, /memory로 실제 로드된 파일과 토큰을 확인 — 이유: 어떤 파일이 얼마나 차지하는지 보아야 줄일 곳이 보입니다 (적용 도구: Claude 전용)
- G23 규칙을 바꾸면 같은 작업으로 행동이 실제로 달라지는지 확인, 안 달라지면 삭제 — 이유: 효과 없는 줄은 비용만 남깁니다
### 멀티 에이전트
- G24 지침을 4층으로: ① 공통 AGENTS.md ② 영역별(rules·폴더) ③ 역할별(agents·roles) ④ 인계(work/ 폴더) — 이유: 공통 파일에 역할 설명까지 넣으면 모든 역할이 남의 규칙을 읽게 됩니다
- G25 리드(비싼 모델)는 계획·지시서·총정리, 하위 세션은 지시서대로 수행하고 보고서 파일을 남김 — 이유: 대화 대신 파일로 인계하면 새 세션의 맥락이 깨끗하고 다른 도구도 읽을 수 있습니다
- G26 조사·리뷰는 서브에이전트, 여러 파일을 고치는 구현은 별도 세션 — 이유: 서브에이전트는 별도 컨텍스트에서 요약만 돌려줘 리드 컨텍스트를 아낍니다 (적용 도구: Claude 전용)
- G27 서브에이전트 model: 로 비용 분담 (탐색 haiku/sonnet, 리뷰 opus, 기본 inherit) — 이유: 작업 난이도에 맞는 모델로 비용을 줄입니다 (적용 도구: Claude 전용)
- G28 공통 파일을 짧게 유지 (일반 서브에이전트도 CLAUDE.md 계층 전체를 로드) — 이유: 역할 수만큼 공통 파일이 반복 로드됩니다 (적용 도구: Claude 전용)

## 최종 형태 템플릿 (형식 참고용, < > 는 프로젝트 값으로)
#### AGENTS.md (루트 · 공통 골격)
````
# <프로젝트명> — 에이전트 공통 지침

## 검증 명령 (작업 끝나면 반드시 실행)
- 빌드: `<빌드 명령>`
- 테스트: `<테스트 명령>` — 실패하면 고친 뒤 다시 실행

## 프로젝트 고유 규칙 (코드만 봐서는 모르는 것만)
- <하지 말 것> → 대신 <이렇게>
- <건드리면 안 되는 폴더>는 읽거나 수정하지 않는다

## 결정 표
| 상황 | 선택 |
|---|---|
| <선택이 갈리는 상황> | <정한 방법> |

## 문서 색인 (필요할 때만 읽기)
- <작업 종류>: `<경로>`
- 왜 이렇게 됐는지: `docs/decisions.md`

## 인계 규칙
- 지시서는 `work/tasks/`, 보고는 `work/reports/<같은 번호>.md`
- 보고 형식: 바꾼 파일 / 검증 결과(명령과 출력) / 남은 문제 / 리드가 결정할 것
- 다른 역할의 파일을 고쳐야 하면 고치지 말고 보고서에 적는다
````

#### CLAUDE.md (루트)
````
@AGENTS.md

## Claude Code 전용
- 코드베이스 조사는 explorer 서브에이전트에 맡기고 요약만 받는다
- 구현을 끝내기 전에 reviewer 서브에이전트로 diff를 검토한다
- 압축할 때는 수정한 파일 목록, 검증 명령, 현재 작업 번호를 반드시 보존한다
````

#### .claude/agents/reviewer.md (서브에이전트)
````
---
name: reviewer
description: 구현이 끝난 뒤 diff를 검토할 때 사용. 버그와 요구사항 누락만 보고
tools: Read, Grep, Glob, Bash
model: opus
---
너는 코드 리뷰어다.
1. `git diff`와 해당 지시서(work/tasks/)를 읽는다
2. 요구사항 누락, 널 참조, 경계 조건, 지침 파일의 프로젝트 고유 규칙 위반을 확인한다
3. 취향·스타일 의견은 보고하지 않는다
4. 발견마다 `파일:줄`, 문제, 수정 제안을 한 줄씩 쓴다
````

#### docs/roles/<역할>.md + 지시서 (별도 세션용)
````
# 역할: <역할명>
- 범위: <이 역할이 수정하는 폴더> 만 수정한다
- 시작 시 읽을 것: 지시서, <해당 폴더의 AGENTS.md>
- 끝낼 때: 검증 명령 실행 → work/reports/<번호>.md 작성 (AGENTS.md의 보고 형식)

--- work/tasks/<번호>-<역할>.md ---
# <번호> <작업 제목>
- 목표: <한 문장>
- 범위 밖: <건드리지 않을 것>
- 완료 조건: <실행해서 확인할 검사>

--- 세션 시작 메시지 (Claude Code·Codex 공통) ---
docs/roles/<역할>.md 와 work/tasks/<번호>-<역할>.md 를 읽고 그 역할로 진행해.
````

이 저장소의 AI 지침 파일(CLAUDE.md, AGENTS.md 등)을 아래 "md 지침 가이드 v1.0" (2026-10-06, 범위: 공통 + Unity)에 맞게 정리해 줘. 대상은 Claude Code와 Codex가 함께 쓰는 저장소다.
- 이 저장소는 Unity 프로젝트다. 공통 원칙(G)과 Unity 원칙(U)을 모두 적용하고, 루트 AGENTS.md는 "AGENTS.md (루트 · Unity 완성본)" 형식을 따른다.
- "Claude 전용" 원칙은 Claude Code 설정(.claude/, CLAUDE.md)에만 반영한다.

## 작업 절차
1. 현재 상태 조사: 루트와 하위 폴더의 CLAUDE.md, AGENTS.md, .claude/rules/, .claude/agents/, .claude/skills/,
   그 밖에 지침으로 쓰이는 문서(docs/ 등)를 찾고 파일별 줄 수를 센다. 아직 아무것도 고치지 않는다.
2. 점검표 작성: 아래 원칙마다 현재 상태를 "충족 / 위반 / 해당 없음"으로 판정하고 근거를 `파일:줄`로 적는다.
3. 변경 계획을 보여 주고 내 확인을 받은 뒤 수정한다. (확인 없이 바로 적용하려면 이 줄을 지운다)
4. 적용 규칙
   - 프로젝트 고유 정보(빌드·테스트 명령, 경로, 팀 규칙)는 보존한다. 지우거나 옮기는 줄은 보고서에 이유와 함께 적는다.
   - 템플릿은 형식 참고용이다. 저장소에 없는 도구·폴더·규칙을 지어내지 않는다. 모르는 값은 수정하지 말고 질문 목록에 넣는다.
   - 공통 지침은 AGENTS.md에 두고, CLAUDE.md는 `@AGENTS.md` 가져오기 + Claude 전용 몇 줄로 만든다 (Codex와 공유).
   - 포맷·스타일 규칙은 지침에 쓰지 말고 .editorconfig·분석기·훅으로 옮길 수 있는지 제안만 한다.
5. 검증: 바뀐 지침 파일의 줄 수를 다시 센다. 지침에 적은 경로·파일이 실제로 있는지 확인한다.
   Claude Code면 `/memory`로 로드되는 파일을 확인한다.
   Codex면 `codex --ask-for-approval never "Summarize the current instructions."`로 확인한다.
6. 보고: 바뀐 파일과 줄 수 변화(전→후), 삭제·이동한 내용과 이유, 남은 질문을 표로 정리한다.

## 가이드 v1.0 원칙 (공통 + Unity)
### 크기와 범위
- G01 루트 지침 파일은 200줄 이하, 목표는 100~150줄 + 짧은 참조 문서 몇 개 — 이유: 루트 파일은 매 세션 컨텍스트를 차지하고, 길어지면 규칙이 묻혀 무시됩니다
- G02 줄마다 "이 줄을 지우면 실수할까?"를 묻고, 아니면 삭제 — 이유: 모델이 이미 아는 것·코드에서 읽히는 것은 토큰만 씁니다
- G03 루트에는 모든 작업에 해당하는 것만: 빌드·테스트 명령, 비표준 규칙, 함정 — 이유: 루트는 항상 로드되므로 가끔 쓰는 내용은 낭비입니다
- G04 아키텍처 개요, 파일별 설명, 일반 코딩 상식은 넣지 않음 — 이유: 모델이 코드를 읽어 알 수 있고, 무관한 맥락이 판단을 흐립니다
- G05 /init 등 자동 생성 결과는 초안으로만 쓰고 사람이 줄여서 확정 — 이유: 자동 생성 파일은 개요 위주라 효과가 낮고 비용만 늘었다는 측정이 있습니다
### 분리와 연결
- G06 특정 파일 유형·폴더에만 필요한 규칙은 .claude/rules/*.md + paths: 로 분리 — 이유: 해당 파일을 읽거나 고칠 때만 로드되어 평소 컨텍스트를 아낍니다 (적용 도구: Claude 전용)
- G07 Codex와 공유할 폴더 규칙은 하위 폴더 AGENTS.md + 같은 폴더 CLAUDE.md(@AGENTS.md 한 줄) — 이유: 규칙 원본을 하나로 두고 두 도구가 모두 읽게 합니다
- G08 가끔 쓰는 절차·도메인 지식은 스킬(.claude/skills/<이름>/SKILL.md)로 — 이유: 시작 시 설명(description)만 로드되고 본문은 필요할 때 읽힙니다 (적용 도구: Claude 전용)
- G09 단, 자주 필요한 지식의 색인은 루트 파일에 직접 둠 — 이유: 스킬은 모델이 꺼낼지 판단해야 해서 놓칠 수 있고, 루트는 항상 보입니다
- G10 분리한 문서는 반드시 루트에서 링크하고 언제 읽을지 한 줄로 적음 — 이유: 어디서도 가리키지 않는 문서는 거의 읽히지 않습니다
- G11 코드 내용을 복사하지 말고 경로:줄 포인터로 — 이유: 복사본은 코드가 바뀌면 낡은 정보가 됩니다
- G12 @경로 가져오기(import)는 정리 용도로만 사용 — 이유: import한 파일도 시작 시 전부 로드되므로 토큰은 줄지 않습니다 (적용 도구: Claude 전용)
### 문장 쓰는 법
- G13 "하지 마"에는 "대신 이렇게"를 붙임 — 이유: 금지만 있으면 모델이 대안을 찾느라 과하게 탐색합니다
- G14 선택이 갈리는 곳은 결정 표(상황 → 선택) — 이유: 구현 전에 모호함을 없앱니다
- G15 반복 작업은 번호 매긴 절차 — 이유: 빠뜨리는 단계가 줄어듭니다
- G16 코드 예시는 실제 코드 3~10줄 — 이유: 짧은 실물 예시가 기존 패턴 재사용을 늘립니다
- G17 강조("IMPORTANT")는 한 줄에만, 나머지는 구체적 행동으로 표현 — 이유: 여러 줄을 강조하면 아무것도 두드러지지 않습니다
- G18 "think step by step", "think carefully" 류 문장 삭제 — 이유: Opus 5.5는 사고가 항상 켜져 있고 노력 수준(effort)으로 조절합니다 (적용 도구: Claude 전용)
### 도구로 강제
- G19 포맷·스타일 규칙은 린터·포매터·훅으로 — 이유: CLAUDE.md는 권고라 어길 수 있고, 훅은 매번 실행이 보장됩니다
- G20 완료 조건은 실행 가능한 검사(테스트, 빌드, 스크린샷)로 지정 — 이유: 검사가 없으면 "끝난 것처럼 보임"이 유일한 신호가 됩니다
- G21 압축(compaction) 때 보존할 것을 한 줄로 지정 — 이유: 긴 세션 요약에서 수정 파일 목록·테스트 명령이 빠지는 것을 막습니다 (적용 도구: Claude 전용)
### 측정과 정리
- G22 /context, /memory로 실제 로드된 파일과 토큰을 확인 — 이유: 어떤 파일이 얼마나 차지하는지 보아야 줄일 곳이 보입니다 (적용 도구: Claude 전용)
- G23 규칙을 바꾸면 같은 작업으로 행동이 실제로 달라지는지 확인, 안 달라지면 삭제 — 이유: 효과 없는 줄은 비용만 남깁니다
### 멀티 에이전트
- G24 지침을 4층으로: ① 공통 AGENTS.md ② 영역별(rules·폴더) ③ 역할별(agents·roles) ④ 인계(work/ 폴더) — 이유: 공통 파일에 역할 설명까지 넣으면 모든 역할이 남의 규칙을 읽게 됩니다
- G25 리드(비싼 모델)는 계획·지시서·총정리, 하위 세션은 지시서대로 수행하고 보고서 파일을 남김 — 이유: 대화 대신 파일로 인계하면 새 세션의 맥락이 깨끗하고 다른 도구도 읽을 수 있습니다
- G26 조사·리뷰는 서브에이전트, 여러 파일을 고치는 구현은 별도 세션 — 이유: 서브에이전트는 별도 컨텍스트에서 요약만 돌려줘 리드 컨텍스트를 아낍니다 (적용 도구: Claude 전용)
- G27 서브에이전트 model: 로 비용 분담 (탐색 haiku/sonnet, 리뷰 opus, 기본 inherit) — 이유: 작업 난이도에 맞는 모델로 비용을 줄입니다 (적용 도구: Claude 전용)
- G28 공통 파일을 짧게 유지 (일반 서브에이전트도 CLAUDE.md 계층 전체를 로드) — 이유: 역할 수만큼 공통 파일이 반복 로드됩니다 (적용 도구: Claude 전용)
### Unity · 환경과 검증
- U01 Unity 버전, 렌더 파이프라인, 대상 플랫폼, 에디터 실행 경로를 루트 지침에 적음 — 이유: 버전·파이프라인마다 API가 달라 모델이 추측하면 틀린 코드를 씁니다
- U02 검증 명령으로 배치 모드 테스트 명령을 적음 (-batchmode -projectPath . -runTests -testPlatform EditMode -testResults <파일>) — 이유: 에디터를 열지 않고도 모델이 완료 여부를 스스로 확인할 수 있습니다
### Unity · 에셋과 직렬화
- U03 에셋을 옮기거나 이름을 바꿀 때 .meta 파일을 함께 옮기라고 명시 — 이유: Unity 밖에서 에셋만 옮기면 .meta 짝이 깨져 새 에셋으로 취급되고 참조가 끊깁니다
- U04 직렬화 필드 이름을 바꿀 때 [FormerlySerializedAs("옛이름")]를 붙이라고 명시 — 이유: 이름만 바꾸면 인스펙터에 저장된 값이 사라집니다
- U05 씬·프리팹(.unity/.prefab) YAML은 텍스트로 직접 고치지 말고 에디터(Unity MCP)로 수정하거나 보고서에 적게 함 — 이유: 참조 ID가 얽힌 YAML을 손으로 고치면 깨지기 쉽고, 깨져도 바로 드러나지 않습니다
- U06 Library/, Temp/, Logs/, obj/ 는 읽지도 고치지도 않게 명시 — 이유: 자동 생성 폴더라 읽으면 토큰만 쓰고, 고쳐도 다시 만들어집니다
### Unity · 도구와 세션
- U07 코드 스타일 규칙은 .editorconfig + Roslyn 분석기로 강제 (분석기는 플러그인으로 등록) — 이유: 지침 파일의 스타일 규칙은 어길 수 있지만 분석기 경고는 컴파일 때마다 나옵니다
- U08 셰이더·UI 등 영역 규칙은 paths 규칙(**/*.shader, **/*.hlsl) 또는 폴더 AGENTS.md로 분리 — 이유: 셰이더 규칙을 C# 작업 때까지 읽을 필요가 없습니다
- U09 에디터 조작은 Unity MCP(예: CoplayDev unity-mcp)에 맡기되, 에디터 담당 세션은 하나만 — 이유: MCP는 열려 있는 에디터에 연결되므로 여러 세션이 같은 에디터를 조작하면 상태가 꼬입니다
- U10 코드만 고치는 역할은 git 워크트리, 에디터가 필요한 역할은 본 프로젝트에서 — 이유: 새 워크트리에는 Library/가 없어 Unity로 열면 재임포트가 필요합니다

## 최종 형태 템플릿 (형식 참고용, < > 는 프로젝트 값으로)
#### CLAUDE.md (루트)
````
@AGENTS.md

## Claude Code 전용
- 코드베이스 조사는 explorer 서브에이전트에 맡기고 요약만 받는다
- 구현을 끝내기 전에 reviewer 서브에이전트로 diff를 검토한다
- 압축할 때는 수정한 파일 목록, 검증 명령, 현재 작업 번호를 반드시 보존한다
````

#### .claude/agents/reviewer.md (서브에이전트)
````
---
name: reviewer
description: 구현이 끝난 뒤 diff를 검토할 때 사용. 버그와 요구사항 누락만 보고
tools: Read, Grep, Glob, Bash
model: opus
---
너는 코드 리뷰어다.
1. `git diff`와 해당 지시서(work/tasks/)를 읽는다
2. 요구사항 누락, 널 참조, 경계 조건, 지침 파일의 프로젝트 고유 규칙 위반을 확인한다
3. 취향·스타일 의견은 보고하지 않는다
4. 발견마다 `파일:줄`, 문제, 수정 제안을 한 줄씩 쓴다
````

#### docs/roles/<역할>.md + 지시서 (별도 세션용)
````
# 역할: <역할명>
- 범위: <이 역할이 수정하는 폴더> 만 수정한다
- 시작 시 읽을 것: 지시서, <해당 폴더의 AGENTS.md>
- 끝낼 때: 검증 명령 실행 → work/reports/<번호>.md 작성 (AGENTS.md의 보고 형식)

--- work/tasks/<번호>-<역할>.md ---
# <번호> <작업 제목>
- 목표: <한 문장>
- 범위 밖: <건드리지 않을 것>
- 완료 조건: <실행해서 확인할 검사>

--- 세션 시작 메시지 (Claude Code·Codex 공통) ---
docs/roles/<역할>.md 와 work/tasks/<번호>-<역할>.md 를 읽고 그 역할로 진행해.
````

#### AGENTS.md (루트 · Unity 완성본)
````
# <프로젝트명> — 에이전트 공통 지침

## 환경
- Unity <6000.x.y>, C# <버전>, 렌더 파이프라인 <URP>, 대상 <Android/iOS>
- 에디터 실행 파일: <C:\Program Files\Unity\Hub\Editor\6000.x.y\Editor\Unity.exe>

## 검증 명령 (작업 끝나면 반드시 실행)
- EditMode 테스트: `"<Unity.exe>" -batchmode -projectPath . -runTests -testPlatform EditMode -testResults work/test-results.xml`
- 실패하면 결과 XML의 실패 항목을 고친 뒤 다시 실행

## 프로젝트 고유 규칙
- 에셋을 옮기거나 이름을 바꿀 때는 `.meta`를 함께 옮긴다 (짝이 깨지면 참조가 끊김)
- 직렬화 필드 이름을 바꿀 때는 `[FormerlySerializedAs("옛이름")]`을 붙인다
- 씬·프리팹(.unity/.prefab)은 텍스트로 직접 고치지 않는다
  → 대신 Unity MCP로 에디터에서 수정하거나, 필요한 변경을 보고서에 적는다
- `Library/`, `Temp/`, `Logs/`, `obj/`는 읽거나 수정하지 않는다
- <그 밖의 팀 규칙> → 대신 <이렇게>

## 결정 표
| 상황 | 선택 |
|---|---|
| 데이터 정의 | ScriptableObject (`Assets/Data/`) |
| 비동기 처리 | <UniTask 또는 Awaitable> |
| 에셋 로드 | <Addressables> |

## 문서 색인 (필요할 때만 읽기)
- UI 작업: `Assets/Scripts/UI/AGENTS.md`
- 셰이더 작업: `.claude/rules/shaders.md`
- 왜 이렇게 됐는지: `docs/decisions.md`

## 인계 규칙
- 지시서는 `work/tasks/`, 보고는 `work/reports/<같은 번호>.md`
- 보고 형식: 바꾼 파일 / 검증 결과(명령과 출력) / 남은 문제 / 리드가 결정할 것
- 다른 역할의 파일을 고쳐야 하면 고치지 말고 보고서에 적는다
````

#### Assets/Scripts/UI/AGENTS.md (폴더 전용)
````
# UI 폴더 규칙
- UI는 <UI Toolkit>. 새 화면은 `Assets/UI/Screens/`에 UXML+USS 한 쌍
- 화면 클래스는 `ScreenBase`를 상속 (예: `Assets/Scripts/UI/Screens/ShopScreen.cs:12`)
- 문자열은 하드코딩하지 않는다 → Localization 테이블 키 사용

(같은 폴더의 CLAUDE.md 내용: @AGENTS.md 한 줄)
````

#### .claude/rules/shaders.md (확장자 기준, Claude 전용)
````
---
paths:
  - "**/*.shader"
  - "**/*.hlsl"
  - "**/*.shadergraph"
---
# 셰이더 규칙
- URP 셰이더는 SRP Batcher 호환 유지: 속성은 `CBUFFER_START(UnityPerMaterial)` 안에
- 모바일 대상이므로 half 정밀도 우선, 필요할 때만 float
````

#### .claude/skills/unity-test/SKILL.md (스킬)
````
---
name: unity-test
description: Unity EditMode/PlayMode 테스트를 배치 모드로 실행하고 실패를 정리할 때
disable-model-invocation: true
---
1. 에디터가 같은 프로젝트를 열고 있으면 사용자에게 닫아 달라고 한다
   (같은 프로젝트를 두 번 열 수 없음)
2. AGENTS.md의 검증 명령을 실행한다. PlayMode면 `-testPlatform PlayMode`
3. work/test-results.xml에서 실패한 테스트 이름과 메시지만 뽑는다
4. 실패마다 원인 추정과 관련 파일:줄을 표로 보고한다
````

md 파일 · 최종 형태

원칙을 합친 출발용 예시입니다. < > 부분을 프로젝트 값으로 바꾸세요.

# <프로젝트명> — 에이전트 공통 지침

## 검증 명령 (작업 끝나면 반드시 실행)
- 빌드: `<빌드 명령>`
- 테스트: `<테스트 명령>` — 실패하면 고친 뒤 다시 실행

## 프로젝트 고유 규칙 (코드만 봐서는 모르는 것만)
- <하지 말 것> → 대신 <이렇게>
- <건드리면 안 되는 폴더>는 읽거나 수정하지 않는다

## 결정 표
| 상황 | 선택 |
|---|---|
| <선택이 갈리는 상황> | <정한 방법> |

## 문서 색인 (필요할 때만 읽기)
- <작업 종류>: `<경로>`
- 왜 이렇게 됐는지: `docs/decisions.md`

## 인계 규칙
- 지시서는 `work/tasks/`, 보고는 `work/reports/<같은 번호>.md`
- 보고 형식: 바꾼 파일 / 검증 결과(명령과 출력) / 남은 문제 / 리드가 결정할 것
- 다른 역할의 파일을 고쳐야 하면 고치지 말고 보고서에 적는다

@AGENTS.md

## Claude Code 전용
- 코드베이스 조사는 explorer 서브에이전트에 맡기고 요약만 받는다
- 구현을 끝내기 전에 reviewer 서브에이전트로 diff를 검토한다
- 압축할 때는 수정한 파일 목록, 검증 명령, 현재 작업 번호를 반드시 보존한다

---
name: reviewer
description: 구현이 끝난 뒤 diff를 검토할 때 사용. 버그와 요구사항 누락만 보고
tools: Read, Grep, Glob, Bash
model: opus
---
너는 코드 리뷰어다.
1. `git diff`와 해당 지시서(work/tasks/)를 읽는다
2. 요구사항 누락, 널 참조, 경계 조건, 지침 파일의 프로젝트 고유 규칙 위반을 확인한다
3. 취향·스타일 의견은 보고하지 않는다
4. 발견마다 `파일:줄`, 문제, 수정 제안을 한 줄씩 쓴다

# 역할: <역할명>
- 범위: <이 역할이 수정하는 폴더> 만 수정한다
- 시작 시 읽을 것: 지시서, <해당 폴더의 AGENTS.md>
- 끝낼 때: 검증 명령 실행 → work/reports/<번호>.md 작성 (AGENTS.md의 보고 형식)

--- work/tasks/<번호>-<역할>.md ---
# <번호> <작업 제목>
- 목표: <한 문장>
- 범위 밖: <건드리지 않을 것>
- 완료 조건: <실행해서 확인할 검사>

--- 세션 시작 메시지 (Claude Code·Codex 공통) ---
docs/roles/<역할>.md 와 work/tasks/<번호>-<역할>.md 를 읽고 그 역할로 진행해.

# <프로젝트명> — 에이전트 공통 지침

## 환경
- Unity <6000.x.y>, C# <버전>, 렌더 파이프라인 <URP>, 대상 <Android/iOS>
- 에디터 실행 파일: <C:\Program Files\Unity\Hub\Editor\6000.x.y\Editor\Unity.exe>

## 검증 명령 (작업 끝나면 반드시 실행)
- EditMode 테스트: `"<Unity.exe>" -batchmode -projectPath . -runTests -testPlatform EditMode -testResults work/test-results.xml`
- 실패하면 결과 XML의 실패 항목을 고친 뒤 다시 실행

## 프로젝트 고유 규칙
- 에셋을 옮기거나 이름을 바꿀 때는 `.meta`를 함께 옮긴다 (짝이 깨지면 참조가 끊김)
- 직렬화 필드 이름을 바꿀 때는 `[FormerlySerializedAs("옛이름")]`을 붙인다
- 씬·프리팹(.unity/.prefab)은 텍스트로 직접 고치지 않는다
  → 대신 Unity MCP로 에디터에서 수정하거나, 필요한 변경을 보고서에 적는다
- `Library/`, `Temp/`, `Logs/`, `obj/`는 읽거나 수정하지 않는다
- <그 밖의 팀 규칙> → 대신 <이렇게>

## 결정 표
| 상황 | 선택 |
|---|---|
| 데이터 정의 | ScriptableObject (`Assets/Data/`) |
| 비동기 처리 | <UniTask 또는 Awaitable> |
| 에셋 로드 | <Addressables> |

## 문서 색인 (필요할 때만 읽기)
- UI 작업: `Assets/Scripts/UI/AGENTS.md`
- 셰이더 작업: `.claude/rules/shaders.md`
- 왜 이렇게 됐는지: `docs/decisions.md`

## 인계 규칙
- 지시서는 `work/tasks/`, 보고는 `work/reports/<같은 번호>.md`
- 보고 형식: 바꾼 파일 / 검증 결과(명령과 출력) / 남은 문제 / 리드가 결정할 것
- 다른 역할의 파일을 고쳐야 하면 고치지 말고 보고서에 적는다

# UI 폴더 규칙
- UI는 <UI Toolkit>. 새 화면은 `Assets/UI/Screens/`에 UXML+USS 한 쌍
- 화면 클래스는 `ScreenBase`를 상속 (예: `Assets/Scripts/UI/Screens/ShopScreen.cs:12`)
- 문자열은 하드코딩하지 않는다 → Localization 테이블 키 사용

(같은 폴더의 CLAUDE.md 내용: @AGENTS.md 한 줄)

---
paths:
  - "**/*.shader"
  - "**/*.hlsl"
  - "**/*.shadergraph"
---
# 셰이더 규칙
- URP 셰이더는 SRP Batcher 호환 유지: 속성은 `CBUFFER_START(UnityPerMaterial)` 안에
- 모바일 대상이므로 half 정밀도 우선, 필요할 때만 float

---
name: unity-test
description: Unity EditMode/PlayMode 테스트를 배치 모드로 실행하고 실패를 정리할 때
disable-model-invocation: true
---
1. 에디터가 같은 프로젝트를 열고 있으면 사용자에게 닫아 달라고 한다
   (같은 프로젝트를 두 번 열 수 없음)
2. AGENTS.md의 검증 명령을 실행한다. PlayMode면 `-testPlatform PlayMode`
3. work/test-results.xml에서 실패한 테스트 이름과 메시지만 뽑는다
4. 실패마다 원인 추정과 관련 파일:줄을 표로 보고한다

최근 변경 · v1.0 (2026-10-06)

초기 가이드 작성: 공통 원칙 28개 + Unity 원칙 10개, 템플릿 8개

원칙

기록