← 전체 리포트 · Unity 가이드 · 모델 벤치마크

md 지침 가이드

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

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

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

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

AI에 바로 적용하기

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

프롬프트 미리보기 (공통 + 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. 적용 규칙
   - 프로젝트 고유 정보(빌드·테스트 명령, 경로, 팀 규칙)는 보존한다. 지우거나 옮기는 줄은 보고서에 이유와 함께 적는다.
   - 템플릿은 형식 참고용이다. 저장소에 없는 도구·폴더·규칙을 지어내지 않는다.
   - 템플릿의 < > 칸은 각 템플릿 아래 "채울 것" 안내를 따른다. "AI" 칸은 저장소 파일을 읽어 직접 채우고,
     "AI→직접" 칸은 후보를 채운 뒤 확인 표시를 남기고, "직접" 칸(팀 규칙·금지 사항 등)은 추측하지 말고 질문 목록에 넣는다.
     "선택" 칸은 저장소에 필요 없으면 지운다.
   - 공통 지침은 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 (루트)
놓는 위치: 저장소 루트의 CLAUDE.md (AGENTS.md와 같은 폴더)
- 채울 것 [그대로] @AGENTS.md: 첫 줄은 그대로 둔다 (AGENTS.md를 가져와 Codex와 공유)
- 채울 것 [선택] explorer·reviewer 줄: 해당 서브에이전트 파일을 만들지 않으면 그 줄을 지운다 (확인: .claude/agents/ 폴더)
- 채울 것 [그대로] 압축 보존 줄: 그대로 써도 된다
````
@AGENTS.md

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

#### .claude/agents/reviewer.md (서브에이전트)
놓는 위치: .claude/agents/reviewer.md
- 채울 것 [직접] model: opus: 리뷰를 싸게 돌리려면 sonnet. 품질 우선이면 opus 유지 (확인: 모델 벤치마크 페이지의 작업별 추천)
- 채울 것 [선택] 2번 확인 항목: 프로젝트에서 자주 나는 버그 유형을 한두 개 더할 수 있다 (확인: 지난 버그·리뷰 기록)
````
---
name: reviewer
description: 구현이 끝난 뒤 diff를 검토할 때 사용. 버그와 요구사항 누락만 보고
tools: Read, Grep, Glob, Bash
model: opus
---
너는 코드 리뷰어다.
1. `git diff`와 해당 지시서(work/tasks/)를 읽는다
2. 요구사항 누락, 널 참조, 경계 조건, 지침 파일의 프로젝트 고유 규칙 위반을 확인한다
3. 취향·스타일 의견은 보고하지 않는다
4. 발견마다 `파일:줄`, 문제, 수정 제안을 한 줄씩 쓴다
````

#### docs/roles/<역할>.md + 지시서 (별도 세션용)
놓는 위치: docs/roles/<역할>.md (역할마다 하나), work/tasks/ (지시서), work/reports/ (보고)
- 채울 것 [직접] <역할명>, <이 역할이 수정하는 폴더>: 역할을 어떻게 나눌지. 예: UI 담당 → Assets/Scripts/UI/ (확인: 작업 구조)
- 채울 것 [AI] <해당 폴더의 AGENTS.md>: 그 역할 폴더에 규칙 파일이 있으면 경로, 없으면 줄 삭제 (확인: 폴더 구조)
- 채울 것 [AI] 지시서 (work/tasks/…): 리드 세션이 작업마다 작성한다. 템플릿은 형식 예시
- 채울 것 [선택] 파일 전체: 혼자 한 세션으로 일하면 만들지 않아도 된다
````
# 역할: <역할명>
- 범위: <이 역할이 수정하는 폴더> 만 수정한다
- 시작 시 읽을 것: 지시서, <해당 폴더의 AGENTS.md>
- 끝낼 때: 검증 명령 실행 → work/reports/<번호>.md 작성 (AGENTS.md의 보고 형식)

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

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

#### AGENTS.md (루트 · Unity 완성본)
놓는 위치: 저장소 루트의 AGENTS.md (공통 골격 대신 이 파일 하나)
- 채울 것 [AI] <프로젝트명>: 프로젝트 이름 (확인: 폴더 이름)
- 채울 것 [AI] Unity <6000.x.y>: 에디터 버전 (확인: ProjectSettings/ProjectVersion.txt 의 m_EditorVersion)
- 채울 것 [선택] C# <버전>: 모르면 줄에서 빼도 된다
- 채울 것 [AI] 렌더 파이프라인 <URP>: URP / HDRP / Built-in (확인: Packages/manifest.json 에 com.unity.render-pipelines.universal(URP)·high-definition(HDRP), 둘 다 없으면 Built-in)
- 채울 것 [직접] 대상 <Android/iOS>: 출시할 플랫폼 (확인: 빌드 설정, 본인 확인)
- 채울 것 [AI] <Unity.exe> 경로: 이 PC의 에디터 실행 파일 (확인: Unity Hub → 설치 → 폴더 보기. 보통 C:\Program Files\Unity\Hub\Editor\<버전>\Editor\Unity.exe)
- 채울 것 [AI→직접] 검증 명령: 테스트가 있으면 그대로. 없으면 비워 두고 AI에게 검증 방법을 묻는다 (확인: Packages/manifest.json 에 com.unity.test-framework, Tests 폴더)
- 채울 것 [그대로] Unity 규칙 4줄 (.meta·FormerlySerializedAs·씬·Library): Unity 공통 규칙이라 그대로 쓴다
- 채울 것 [직접] <그 밖의 팀 규칙>: 팀이 정한 금지 사항과 대안. 예: "Update에서 GetComponent 금지 → Awake에서 캐시" (확인: 리뷰 지적, AI가 반복한 실수)
- 채울 것 [AI→직접] 결정 표 3줄: 예시다. 실제 쓰는 것으로 바꾸거나 지운다 (확인: Packages/manifest.json (com.cysharp.unitask, com.unity.addressables 등), 기존 코드)
- 채울 것 [AI] 문서 색인: UI·셰이더 규칙 파일을 안 만들면 그 줄을 지운다 (확인: 실제 만든 파일)
- 채울 것 [선택] 인계 규칙 섹션: 여러 세션으로 나눠 일할 때만 필요
````
# <프로젝트명> — 에이전트 공통 지침

## 환경
- 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 스크립트가 있는 실제 폴더 + 같은 폴더에 CLAUDE.md(@AGENTS.md 한 줄)
- 채울 것 [AI] 파일 위치: 프로젝트의 실제 UI 폴더 경로에 맞춘다 (확인: Assets/ 폴더 구조)
- 채울 것 [AI] <UI Toolkit>: UGUI인지 UI Toolkit인지 (확인: 코드·패키지)
- 채울 것 [AI] ScreenBase, ShopScreen.cs:12: 예시 이름이다. 실제 기반 클래스와 대표 예시 파일:줄로 바꾼다 (확인: UI 코드의 상속 구조)
- 채울 것 [AI→직접] Localization 줄: 로컬라이즈를 안 쓰면 지운다 (확인: com.unity.localization 패키지)
````
# 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 전용)
놓는 위치: .claude/rules/shaders.md (Claude Code 전용. Codex와 나누려면 셰이더 폴더의 AGENTS.md로)
- 채울 것 [그대로] paths 패턴: 프로젝트에서 쓰는 셰이더 확장자. 보통 그대로 둔다 (확인: Assets 안의 셰이더 파일)
- 채울 것 [직접] 셰이더 규칙 2줄: 예시다. 본인이 지키는 셰이더 규칙으로 바꾼다 (정밀도, 키워드 개수, 배칭 등) (확인: 본인 셰이더 작업 기준)
- 채울 것 [AI] SRP Batcher 줄: URP·HDRP가 아니면 지운다 (확인: 렌더 파이프라인)
````
---
paths:
  - "**/*.shader"
  - "**/*.hlsl"
  - "**/*.shadergraph"
---
# 셰이더 규칙
- URP 셰이더는 SRP Batcher 호환 유지: 속성은 `CBUFFER_START(UnityPerMaterial)` 안에
- 모바일 대상이므로 half 정밀도 우선, 필요할 때만 float
````

#### .claude/skills/unity-test/SKILL.md (스킬)
놓는 위치: .claude/skills/unity-test/SKILL.md
- 채울 것 [그대로] 파일 전체: 그대로 쓴다. 단, AGENTS.md에 검증 명령이 있어야 한다 (확인: AGENTS.md)
- 채울 것 [AI] 사용 조건: Unity Test Framework 패키지와 테스트가 있어야 의미가 있다 (확인: Packages/manifest.json 의 com.unity.test-framework)
````
---
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 파일 · 최종 형태

원칙을 합친 출발용 예시입니다. 파일마다 "채울 것" 표를 보고 < > 칸과 예시 줄을 정리하세요. 누가: AI 적용 프롬프트를 쓰면 AI가 저장소에서 읽어 채움 · AI→직접 AI가 후보를 넣고 본인이 확인 · 직접 본인이 정해야 함 · 그대로 수정 불필요 · 선택 필요 없으면 삭제

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

놓는 위치 · 저장소 루트의 AGENTS.md (Unity 프로젝트는 이 파일 대신 Unity 완성본)

채울 것무엇을 넣나어디서 확인누가
<프로젝트명>저장소 이름폴더 이름, READMEAI
<빌드 명령>평소 빌드할 때 치는 명령package.json scripts, Makefile, .sln, CI 설정(.github/workflows)AI
<테스트 명령>테스트 실행 명령위와 같은 곳AI
<하지 말 것> → 대신 <이렇게>AI가 자주 틀리는 것, 팀이 금지한 것과 그 대안. 예: "DB 스키마 직접 수정 금지 → 마이그레이션 파일 추가"코드 리뷰에서 반복된 지적, AI가 반복한 실수직접
<건드리면 안 되는 폴더>자동 생성물, 외부 코드, 빌드 산출물.gitignore, vendor/, 생성 폴더AI→직접
결정 표팀이 정한 기술 선택. 예: 상태 관리 방식, 로깅 라이브러리기존 코드의 관례, 팀 논의AI→직접
문서 색인따로 분리한 문서의 경로와 언제 읽을지docs/ 폴더AI
인계 규칙 섹션여러 세션으로 나눠 일할 때만 필요—선택
# <프로젝트명> — 에이전트 공통 지침

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

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

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

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

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

놓는 위치 · 저장소 루트의 CLAUDE.md (AGENTS.md와 같은 폴더)

채울 것무엇을 넣나어디서 확인누가
@AGENTS.md첫 줄은 그대로 둔다 (AGENTS.md를 가져와 Codex와 공유)—그대로
explorer·reviewer 줄해당 서브에이전트 파일을 만들지 않으면 그 줄을 지운다.claude/agents/ 폴더선택
압축 보존 줄그대로 써도 된다—그대로
@AGENTS.md

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

놓는 위치 · .claude/agents/reviewer.md

채울 것무엇을 넣나어디서 확인누가
model: opus리뷰를 싸게 돌리려면 sonnet. 품질 우선이면 opus 유지모델 벤치마크 페이지의 작업별 추천직접
2번 확인 항목프로젝트에서 자주 나는 버그 유형을 한두 개 더할 수 있다지난 버그·리뷰 기록선택
---
name: reviewer
description: 구현이 끝난 뒤 diff를 검토할 때 사용. 버그와 요구사항 누락만 보고
tools: Read, Grep, Glob, Bash
model: opus
---
너는 코드 리뷰어다.
1. `git diff`와 해당 지시서(work/tasks/)를 읽는다
2. 요구사항 누락, 널 참조, 경계 조건, 지침 파일의 프로젝트 고유 규칙 위반을 확인한다
3. 취향·스타일 의견은 보고하지 않는다
4. 발견마다 `파일:줄`, 문제, 수정 제안을 한 줄씩 쓴다
docs/roles/<역할>.md + 지시서 (별도 세션용)

놓는 위치 · docs/roles/<역할>.md (역할마다 하나), work/tasks/ (지시서), work/reports/ (보고)

채울 것무엇을 넣나어디서 확인누가
<역할명>, <이 역할이 수정하는 폴더>역할을 어떻게 나눌지. 예: UI 담당 → Assets/Scripts/UI/작업 구조직접
<해당 폴더의 AGENTS.md>그 역할 폴더에 규칙 파일이 있으면 경로, 없으면 줄 삭제폴더 구조AI
지시서 (work/tasks/…)리드 세션이 작업마다 작성한다. 템플릿은 형식 예시—AI
파일 전체혼자 한 세션으로 일하면 만들지 않아도 된다—선택
# 역할: <역할명>
- 범위: <이 역할이 수정하는 폴더> 만 수정한다
- 시작 시 읽을 것: 지시서, <해당 폴더의 AGENTS.md>
- 끝낼 때: 검증 명령 실행 → work/reports/<번호>.md 작성 (AGENTS.md의 보고 형식)

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

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

놓는 위치 · 저장소 루트의 AGENTS.md (공통 골격 대신 이 파일 하나)

채울 것무엇을 넣나어디서 확인누가
<프로젝트명>프로젝트 이름폴더 이름AI
Unity <6000.x.y>에디터 버전ProjectSettings/ProjectVersion.txt 의 m_EditorVersionAI
C# <버전>모르면 줄에서 빼도 된다—선택
렌더 파이프라인 <URP>URP / HDRP / Built-inPackages/manifest.json 에 com.unity.render-pipelines.universal(URP)·high-definition(HDRP), 둘 다 없으면 Built-inAI
대상 <Android/iOS>출시할 플랫폼빌드 설정, 본인 확인직접
<Unity.exe> 경로이 PC의 에디터 실행 파일Unity Hub → 설치 → 폴더 보기. 보통 C:\Program Files\Unity\Hub\Editor\<버전>\Editor\Unity.exeAI
검증 명령테스트가 있으면 그대로. 없으면 비워 두고 AI에게 검증 방법을 묻는다Packages/manifest.json 에 com.unity.test-framework, Tests 폴더AI→직접
Unity 규칙 4줄 (.meta·FormerlySerializedAs·씬·Library)Unity 공통 규칙이라 그대로 쓴다—그대로
<그 밖의 팀 규칙>팀이 정한 금지 사항과 대안. 예: "Update에서 GetComponent 금지 → Awake에서 캐시"리뷰 지적, AI가 반복한 실수직접
결정 표 3줄예시다. 실제 쓰는 것으로 바꾸거나 지운다Packages/manifest.json (com.cysharp.unitask, com.unity.addressables 등), 기존 코드AI→직접
문서 색인UI·셰이더 규칙 파일을 안 만들면 그 줄을 지운다실제 만든 파일AI
인계 규칙 섹션여러 세션으로 나눠 일할 때만 필요—선택
# <프로젝트명> — 에이전트 공통 지침

## 환경
- 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 스크립트가 있는 실제 폴더 + 같은 폴더에 CLAUDE.md(@AGENTS.md 한 줄)

채울 것무엇을 넣나어디서 확인누가
파일 위치프로젝트의 실제 UI 폴더 경로에 맞춘다Assets/ 폴더 구조AI
<UI Toolkit>UGUI인지 UI Toolkit인지코드·패키지AI
ScreenBase, ShopScreen.cs:12예시 이름이다. 실제 기반 클래스와 대표 예시 파일:줄로 바꾼다UI 코드의 상속 구조AI
Localization 줄로컬라이즈를 안 쓰면 지운다com.unity.localization 패키지AI→직접
# 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 전용)

놓는 위치 · .claude/rules/shaders.md (Claude Code 전용. Codex와 나누려면 셰이더 폴더의 AGENTS.md로)

채울 것무엇을 넣나어디서 확인누가
paths 패턴프로젝트에서 쓰는 셰이더 확장자. 보통 그대로 둔다Assets 안의 셰이더 파일그대로
셰이더 규칙 2줄예시다. 본인이 지키는 셰이더 규칙으로 바꾼다 (정밀도, 키워드 개수, 배칭 등)본인 셰이더 작업 기준직접
SRP Batcher 줄URP·HDRP가 아니면 지운다렌더 파이프라인AI
---
paths:
  - "**/*.shader"
  - "**/*.hlsl"
  - "**/*.shadergraph"
---
# 셰이더 규칙
- URP 셰이더는 SRP Batcher 호환 유지: 속성은 `CBUFFER_START(UnityPerMaterial)` 안에
- 모바일 대상이므로 half 정밀도 우선, 필요할 때만 float
.claude/skills/unity-test/SKILL.md (스킬)

놓는 위치 · .claude/skills/unity-test/SKILL.md

채울 것무엇을 넣나어디서 확인누가
파일 전체그대로 쓴다. 단, AGENTS.md에 검증 명령이 있어야 한다AGENTS.md그대로
사용 조건Unity Test Framework 패키지와 테스트가 있어야 의미가 있다Packages/manifest.json 의 com.unity.test-frameworkAI
---
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
G07Codex와 공유할 폴더 규칙은 하위 폴더 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방법이유효과 · 근거등급버전
U01Unity 버전, 렌더 파이프라인, 대상 플랫폼, 에디터 실행 경로를 루트 지침에 적음버전·파이프라인마다 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
U06Library/, 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.02026-10-06—초기 가이드 작성: 공통 원칙 28개 + Unity 원칙 10개, 템플릿 8개

삭제된 원칙이 없습니다.

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

시점무엇이 바뀌었나가이드에 준 영향출처
Claude Code 0.2.107CLAUDE.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.69InstructionsLoaded 훅 추가, 조건부 rules가 -p 모드에서 로드되도록 수정어떤 지침이 언제 로드되는지 추적 가능Claude Code 변경 기록
Claude Code 2.1.72CLAUDE.md의 HTML 주석(<!-- -->)을 모델에게 숨김사람용 메모를 토큰 비용 없이 남길 수 있음Claude Code 변경 기록
Claude Code 2.1.84rules·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.281AGENTS.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 변경 기록