md 지침 가이드

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

버전◀ 처음최신 ▶두 버전 비교

CLAUDE.md · AGENTS.md 같은 지침 파일의 현재 기준입니다. 매일 리포트를 만들 때 수집한 글과 대조해, 바뀐 점이 있으면 새 버전을 만들고 이유를 기록합니다.

근거 등급: 공식 = 개발사 문서·변경 기록, 실험 = 외부 측정 결과(조건부), 외부 글 = 경험담, 해석 = 이 가이드의 판단. 공식 근거 원칙은 공식 출처로만 수정·삭제됩니다.

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 를 읽고 그 역할로 진행해.
````

프롬프트 미리보기 (공통 + Unity)

이 저장소의 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 파일 · 최종 형태

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

프로젝트	쓰는 파일
Unity	루트 AGENTS.md는 Unity 줄의 완성본 하나만 씁니다(공통 골격 대신). CLAUDE.md·reviewer·역할 파일은 공통 줄 것을, 나머지 Unity 파일은 필요한 것만 추가합니다.
일반	공통 줄 파일만 씁니다.

공통

Unity

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 를 읽고 그 역할로 진행해.

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. 실패마다 원인 추정과 관련 파일:줄을 표로 보고한다

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

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

원칙

크기와 범위

ID	방법	이유	효과 · 근거	등급	버전
G01	루트 지침 파일은 200줄 이하, 목표는 100~150줄 + 짧은 참조 문서 몇 개	루트 파일은 매 세션 컨텍스트를 차지하고, 길어지면 규칙이 묻혀 무시됩니다	Augment 측정: 100~150줄 + 참조 문서 조합이 지표 10~15% 개선 Claude Code 문서: 메모리 · Claude Code 문서: 모범 사례 · Augment: How to write good AGENTS.md	공식+실험	v1.0
G02	줄마다 "이 줄을 지우면 실수할까?"를 묻고, 아니면 삭제	모델이 이미 아는 것·코드에서 읽히는 것은 토큰만 씁니다	규칙 수가 줄어 남은 규칙의 준수율이 올라감 (공식 문서의 경고: 긴 파일은 지시를 무시하게 만듦) Claude Code 문서: 모범 사례	공식	v1.0
G03	루트에는 모든 작업에 해당하는 것만: 빌드·테스트 명령, 비표준 규칙, 함정	루트는 항상 로드되므로 가끔 쓰는 내용은 낭비입니다	arXiv: 불필요한 요구사항이 과제를 어렵게 만듦 → 최소 요구사항만 쓰라고 권고 Claude Code 문서: 모범 사례 · arXiv 2602.11988 Evaluating AGENTS.md	공식+실험	v1.0
G04	아키텍처 개요, 파일별 설명, 일반 코딩 상식은 넣지 않음	모델이 코드를 읽어 알 수 있고, 무관한 맥락이 판단을 흐립니다	Augment: 과도한 아키텍처 문서로 완성도 25% 하락 사례 Claude Code 문서: 모범 사례 · Augment: How to write good AGENTS.md	공식+실험	v1.0
G05	/init 등 자동 생성 결과는 초안으로만 쓰고 사람이 줄여서 확정	자동 생성 파일은 개요 위주라 효과가 낮고 비용만 늘었다는 측정이 있습니다	arXiv: 컨텍스트 파일이 성공률을 낮추고 추론 비용을 20% 넘게 늘림 arXiv 2602.11988 Evaluating AGENTS.md	실험	v1.0

분리와 연결

ID	방법	이유	효과 · 근거	등급	버전
G06	*특정 파일 유형·폴더에만 필요한 규칙은 .claude/rules/.md + paths: 로 분리** Claude 전용	해당 파일을 읽거나 고칠 때만 로드되어 평소 컨텍스트를 아낍니다	"어떤 건 어디만 보기"를 사람이 지시하지 않아도 경로로 자동 선택 (Claude Code 전용) Claude Code 문서: 메모리	공식	v1.0
G07	Codex와 공유할 폴더 규칙은 하위 폴더 AGENTS.md + 같은 폴더 CLAUDE.md(@AGENTS.md 한 줄)	규칙 원본을 하나로 두고 두 도구가 모두 읽게 합니다	Codex는 루트~시작 폴더까지만 읽으므로 루트 색인에 경로를 함께 적어야 함 Claude Code 문서: 메모리 · Codex 문서: AGENTS.md	공식	v1.0
G08	가끔 쓰는 절차·도메인 지식은 스킬(.claude/skills/<이름>/SKILL.md)로 Claude 전용	시작 시 설명(description)만 로드되고 본문은 필요할 때 읽힙니다	SKILL.md는 500줄 이하 권장, 부속 파일은 필요 시 로드 Claude Code 문서: 스킬 · Claude Code 문서: 모범 사례	공식	v1.0
G09	단, 자주 필요한 지식의 색인은 루트 파일에 직접 둠	스킬은 모델이 꺼낼지 판단해야 해서 놓칠 수 있고, 루트는 항상 보입니다	Vercel: 압축 문서 색인(8KB)을 AGENTS.md에 넣었을 때 100%, 스킬만 53%, 스킬+명시 지시 79% Vercel: AGENTS.md outperforms skills	실험	v1.0
G10	분리한 문서는 반드시 루트에서 링크하고 언제 읽을지 한 줄로 적음	어디서도 가리키지 않는 문서는 거의 읽히지 않습니다	Augment: 참조 없는 문서 폴더는 세션의 10% 미만에서만 발견 Augment: How to write good AGENTS.md	실험	v1.0
G11	코드 내용을 복사하지 말고 경로:줄 포인터로	복사본은 코드가 바뀌면 낡은 정보가 됩니다	문서 유지 비용 감소, 잘못된 옛 코드 모방 방지 HumanLayer: Writing a good CLAUDE.md	외부 글	v1.0
G12	@경로 가져오기(import)는 정리 용도로만 사용 Claude 전용	import한 파일도 시작 시 전부 로드되므로 토큰은 줄지 않습니다	토큰 절약이 목적이면 rules(paths)나 스킬을 써야 함 Claude Code 문서: 메모리	공식	v1.0

문장 쓰는 법

ID	방법	이유	효과 · 근거	등급	버전
G13	"하지 마"에는 "대신 이렇게"를 붙임	금지만 있으면 모델이 대안을 찾느라 과하게 탐색합니다	Augment: 금지+대안 짝이 경고만 있는 문서보다 우수 Augment: How to write good AGENTS.md	실험	v1.0
G14	선택이 갈리는 곳은 결정 표(상황 → 선택)	구현 전에 모호함을 없앱니다	Augment: 결정 표가 있는 모듈의 best_practices 점수 25% 높음 Augment: How to write good AGENTS.md	실험	v1.0
G15	반복 작업은 번호 매긴 절차	빠뜨리는 단계가 줄어듭니다	Augment: 6단계 절차로 누락 40%→10%, 정확도 25% 개선 Augment: How to write good AGENTS.md	실험	v1.0
G16	코드 예시는 실제 코드 3~10줄	짧은 실물 예시가 기존 패턴 재사용을 늘립니다	Augment: 재사용 지표 20% 증가 Augment: How to write good AGENTS.md	실험	v1.0
G17	강조("IMPORTANT")는 한 줄에만, 나머지는 구체적 행동으로 표현	여러 줄을 강조하면 아무것도 두드러지지 않습니다	Opus 5.5 가이드: 강조어보다 구체적 지시가 효과적 Claude Code 문서: 모범 사례 · Opus 5.5 프롬프트 가이드	공식	v1.0
G18	"think step by step", "think carefully" 류 문장 삭제 Claude 전용	Opus 5.5는 사고가 항상 켜져 있고 노력 수준(effort)으로 조절합니다	불필요한 지시 제거. /doctor prompt-audit(v2.1.283+)가 옛 모델용 문장을 찾아 줌 Opus 5.5 프롬프트 가이드 · Claude Code 변경 기록	공식	v1.0

도구로 강제

ID	방법	이유	효과 · 근거	등급	버전
G19	포맷·스타일 규칙은 린터·포매터·훅으로	CLAUDE.md는 권고라 어길 수 있고, 훅은 매번 실행이 보장됩니다	LLM 린트는 느리고 비쌈 ("never send an LLM to do a linter's job") Claude Code 문서: 모범 사례 · HumanLayer: Writing a good CLAUDE.md	공식+외부 글	v1.0
G20	완료 조건은 실행 가능한 검사(테스트, 빌드, 스크린샷)로 지정	검사가 없으면 "끝난 것처럼 보임"이 유일한 신호가 됩니다	모델이 스스로 실행·수정 반복 → 사람이 검증 루프가 되지 않음 Claude Code 문서: 모범 사례	공식	v1.0
G21	압축(compaction) 때 보존할 것을 한 줄로 지정 Claude 전용	긴 세션 요약에서 수정 파일 목록·테스트 명령이 빠지는 것을 막습니다	예: "When compacting, always preserve the full list of modified files and any test commands" Claude Code 문서: 모범 사례	공식	v1.0

측정과 정리

ID	방법	이유	효과 · 근거	등급	버전
G22	/context, /memory로 실제 로드된 파일과 토큰을 확인 Claude 전용	어떤 파일이 얼마나 차지하는지 보아야 줄일 곳이 보입니다	로드 누락·중복 로드를 바로 발견 Claude Code 문서: 모범 사례 · Claude Code 문서: 메모리	공식	v1.0
G23	규칙을 바꾸면 같은 작업으로 행동이 실제로 달라지는지 확인, 안 달라지면 삭제	효과 없는 줄은 비용만 남깁니다	규칙을 어기면 파일이 너무 긴 것, 파일에 답이 있는데 질문하면 문장이 모호한 것 (공식 진단 기준) Claude Code 문서: 모범 사례	공식	v1.0

멀티 에이전트

ID	방법	이유	효과 · 근거	등급	버전
G24	지침을 4층으로: ① 공통 AGENTS.md ② 영역별(rules·폴더) ③ 역할별(agents·roles) ④ 인계(work/ 폴더)	공통 파일에 역할 설명까지 넣으면 모든 역할이 남의 규칙을 읽게 됩니다	공통 파일이 짧게 유지되고, 역할·영역 규칙은 필요한 세션에서만 로드 Claude Code 문서: 메모리 · Claude Code 문서: 서브에이전트	해석	v1.0
G25	리드(비싼 모델)는 계획·지시서·총정리, 하위 세션은 지시서대로 수행하고 보고서 파일을 남김	대화 대신 파일로 인계하면 새 세션의 맥락이 깨끗하고 다른 도구도 읽을 수 있습니다	공식 문서도 "스펙 작성 후 새 세션에서 실행"을 권장 Claude Code 문서: 모범 사례	공식+해석	v1.0
G26	조사·리뷰는 서브에이전트, 여러 파일을 고치는 구현은 별도 세션 Claude 전용	서브에이전트는 별도 컨텍스트에서 요약만 돌려줘 리드 컨텍스트를 아낍니다	Writer/Reviewer 패턴: 새 컨텍스트의 리뷰가 자기 코드 편향이 없음 Claude Code 문서: 모범 사례 · Claude Code 문서: 서브에이전트	공식+해석	v1.0
G27	서브에이전트 model: 로 비용 분담 (탐색 haiku/sonnet, 리뷰 opus, 기본 inherit) Claude 전용	작업 난이도에 맞는 모델로 비용을 줄입니다	model 값: sonnet, opus, haiku, fable, 전체 모델 ID, inherit. CLAUDE_CODE_SUBAGENT_MODEL로 일괄 지정 가능 Claude Code 문서: 서브에이전트	공식	v1.0
G28	공통 파일을 짧게 유지 (일반 서브에이전트도 CLAUDE.md 계층 전체를 로드) Claude 전용	역할 수만큼 공통 파일이 반복 로드됩니다	필요 없으면 omitClaudeMd: true로 생략 가능 (v2.1.271+). Explore·Plan은 원래 생략 Claude Code 문서: 서브에이전트 · Claude Code 변경 기록	공식	v1.0

Unity · 환경과 검증

ID	방법	이유	효과 · 근거	등급	버전
U01	Unity 버전, 렌더 파이프라인, 대상 플랫폼, 에디터 실행 경로를 루트 지침에 적음	버전·파이프라인마다 API가 달라 모델이 추측하면 틀린 코드를 씁니다	Built-in/URP/HDRP 혼동, 없는 API 사용 감소	해석	v1.0
U02	검증 명령으로 배치 모드 테스트 명령을 적음 (-batchmode -projectPath . -runTests -testPlatform EditMode -testResults <파일>)	에디터를 열지 않고도 모델이 완료 여부를 스스로 확인할 수 있습니다	공통 원칙 '완료 조건은 실행 가능한 검사'의 Unity 구현. 결과 XML로 실패 항목을 바로 읽음 Unity Test Framework: 명령줄 실행	공식	v1.0

Unity · 에셋과 직렬화

ID	방법	이유	효과 · 근거	등급	버전
U03	에셋을 옮기거나 이름을 바꿀 때 .meta 파일을 함께 옮기라고 명시	Unity 밖에서 에셋만 옮기면 .meta 짝이 깨져 새 에셋으로 취급되고 참조가 끊깁니다	머티리얼 텍스처 연결·스크립트 연결이 사라지는 사고 방지 Unity 매뉴얼: Asset Metadata	공식	v1.0
U04	직렬화 필드 이름을 바꿀 때 [FormerlySerializedAs("옛이름")]를 붙이라고 명시	이름만 바꾸면 인스펙터에 저장된 값이 사라집니다	리팩터링 중 프리팹·씬 데이터 손실 방지 Unity API: FormerlySerializedAs	공식	v1.0
U05	씬·프리팹(.unity/.prefab) YAML은 텍스트로 직접 고치지 말고 에디터(Unity MCP)로 수정하거나 보고서에 적게 함	참조 ID가 얽힌 YAML을 손으로 고치면 깨지기 쉽고, 깨져도 바로 드러나지 않습니다	씬·프리팹 손상 위험 감소	해석	v1.0
U06	Library/, Temp/, Logs/, obj/ 는 읽지도 고치지도 않게 명시	자동 생성 폴더라 읽으면 토큰만 쓰고, 고쳐도 다시 만들어집니다	탐색 범위가 줄어 토큰·시간 절약	해석	v1.0

Unity · 도구와 세션

ID	방법	이유	효과 · 근거	등급	버전
U07	코드 스타일 규칙은 .editorconfig + Roslyn 분석기로 강제 (분석기는 플러그인으로 등록)	지침 파일의 스타일 규칙은 어길 수 있지만 분석기 경고는 컴파일 때마다 나옵니다	공통 원칙 '포맷·스타일은 도구로'의 Unity 구현 Unity 매뉴얼: Roslyn 분석기	공식	v1.0
U08	셰이더·UI 등 영역 규칙은 paths 규칙(/.shader, /.hlsl) 또는 폴더 AGENTS.md로 분리**	셰이더 규칙을 C# 작업 때까지 읽을 필요가 없습니다	영역 작업 때만 로드되어 공통 파일이 짧게 유지됨 Claude Code 문서: 메모리	공식	v1.0
U09	에디터 조작은 Unity MCP(예: CoplayDev unity-mcp)에 맡기되, 에디터 담당 세션은 하나만	MCP는 열려 있는 에디터에 연결되므로 여러 세션이 같은 에디터를 조작하면 상태가 꼬입니다	씬·에셋 동시 수정 충돌 방지 CoplayDev unity-mcp	해석	v1.0
U10	코드만 고치는 역할은 git 워크트리, 에디터가 필요한 역할은 본 프로젝트에서	새 워크트리에는 Library/가 없어 Unity로 열면 재임포트가 필요합니다	재임포트 시간 절약, 병렬 작업 시 파일 충돌 방지	해석	v1.0

기록

버전	날짜	구분	항목	이유	근거
v1.0	2026-10-06	—	초기 가이드 작성: 공통 원칙 28개 + Unity 원칙 10개, 템플릿 8개

삭제된 원칙이 없습니다.

Claude Code 변경 기록에는 날짜가 없어 버전만 적었습니다.

시점	무엇이 바뀌었나	가이드에 준 영향	출처
Claude Code 0.2.107	CLAUDE.md에서 @경로로 다른 파일 가져오기(import) 지원	긴 지침을 파일로 나눌 수 있게 됨 (단, 토큰은 그대로)	Claude Code 변경 기록
Claude Code 2.0.64	.claude/rules/ 지원	주제별 규칙 파일 분리 가능	Claude Code 변경 기록
agents.md 2025-08	AGENTS.md 공개 형식 등장 (여러 코딩 에이전트 공용)	도구마다 따로 쓰던 지침 파일을 하나로 공유하는 흐름 시작	agents.md 공개 형식
HumanLayer 글 2025-11-25	300줄 이하(자사 60줄 미만), 점진적 공개, 린터 일은 린터에게	"짧게 + 필요할 때 읽게"가 커뮤니티 표준이 됨	HumanLayer: Writing a good CLAUDE.md
Vercel 실험 2026-01	문서 색인을 AGENTS.md에 직접 넣으면 100%, 스킬만 53%	항상 필요한 지식은 스킬보다 루트에 두는 근거	Vercel: AGENTS.md outperforms skills
arXiv 2602.11988 2026-02-12	컨텍스트 파일이 성공률을 낮추고 비용을 20%+ 늘림	"최소 요구사항만" 원칙의 근거, 자동 생성 파일 경계	arXiv 2602.11988 Evaluating AGENTS.md
Claude Code 2.1.69	InstructionsLoaded 훅 추가, 조건부 rules가 -p 모드에서 로드되도록 수정	어떤 지침이 언제 로드되는지 추적 가능	Claude Code 변경 기록
Claude Code 2.1.72	CLAUDE.md의 HTML 주석(<!-- -->)을 모델에게 숨김	사람용 메모를 토큰 비용 없이 남길 수 있음	Claude Code 변경 기록
Claude Code 2.1.84	rules·skills의 paths: 에 YAML 목록 허용	여러 확장자를 한 규칙에 묶기 쉬워짐	Claude Code 변경 기록
Augment 측정 2026-04-22	100~150줄 + 참조 문서, 결정 표, 절차, 금지+대안, 3~10줄 예시	문장 쓰는 법 원칙들의 수치 근거	Augment: How to write good AGENTS.md
Claude Code 2.1.169	"CLAUDE.md가 너무 길다" 경고 기준이 모델 컨텍스트 크기에 비례	모델별로 다른 길이 한도 경고	Claude Code 변경 기록
Claude Code 2.1.206	/doctor가 코드에서 유도 가능한 CLAUDE.md 내용을 삭제 후보로 제안	군더더기 점검 자동화	Claude Code 변경 기록
Claude Code 2.1.271	서브에이전트 frontmatter에 omitClaudeMd 추가	역할별 세션이 공통 지침을 생략할 수 있음	Claude Code 변경 기록
Claude Code 2.1.277 2026-09 중순 (HN 게시 기준)	CLAUDE.md가 없으면 AGENTS.md를 읽음 (/config의 Project instructions로 변경)	Codex와 지침 파일 공유가 공식 지원됨	Claude Code 변경 기록
Claude Code 2.1.281	AGENTS.md가 Bedrock·Vertex·텔레메트리 끈 세션에서도 동작, 긴 지침 경고가 여러 파일 합계로 계산	import로 나눠도 총량 경고가 뜸	Claude Code 변경 기록
Claude Code 2.1.283	/doctor prompt-audit 추가: 옛 모델용 프롬프트 패턴 점검	"think step by step" 같은 문장을 자동으로 찾음	Claude Code 변경 기록
Claude Code 2.1.290	@멘션한 파일의 하위 폴더 AGENTS.md 첨부, Write/Edit로 만든 파일에도 rules·하위 CLAUDE.md 로드	폴더 전용 규칙이 더 확실히 적용됨	Claude Code 변경 기록