CLAUDE.md

@@ -2,6 +2,8 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+> 루트 `AGENTS.md` 는 `@CLAUDE.md` 한 줄짜리 alias. Codex 등 다른 코딩 에이전트도 이 문서를 그대로 따른다.
+
 > The repository README.md is unusually thorough. Treat it as authoritative for stack, directory layout, env vars, routes, and troubleshooting — this file only highlights what's non-obvious or easy to get wrong.
 
 ## Project at a glance
@@ -91,10 +93,19 @@ Atoms live under `src/store/` and are split by domain (`canvasAtom`, `roofAtom`,
 - Upon task completion, update the CLAUDE.md and README.md documents if necessary.
 - When working, commit in meaningful units that can be explained in a single sentence.
 
+## `.agents/` skill 문서
+
+`.agents/skills/{next-best-practices,vercel-react-best-practices}/**` 에 Vercel·Next.js 모범사례 룰북이 들어 있음(총 95개 .md). Next/React 패턴 관련 결정을 내릴 때(렌더링 최적화, RSC 경계, 번들 분할, hydration 이슈, 서버/클라이언트 캐싱 등) 우선 참조.
+
+- Skill 진입점: 각 디렉토리의 `SKILL.md` 가 인덱스, 룰은 `rules/` 하위 토픽별 파일.
+- 이 문서들은 git 추적 대상이므로 변경하면 PR 에 함께 올릴 것.
+
 ## graphify
 
 A persistent knowledge graph of `src/` lives at `graphify-out/` (built by `/graphify src`). Prefer it over grep for architectural questions.
 
+> `graphify-out/` 는 **로컬 캐시**라 git 추적 대상이 아님(`.gitignore`). 새 클론·워크트리에서 비어 있으면 `graphify update .` 로 incremental 빌드, 아예 없으면 `/graphify src` 로 풀 빌드.
+
 **When to consult it**
 - Before answering "how does X relate to Y", "what depends on Z", or any cross-module question, read `graphify-out/GRAPH_REPORT.md` (god nodes, surprising connections) and use `graphify query "..."` / `graphify path "A" "B"` / `graphify explain "..."` — these traverse EXTRACTED + INFERRED edges instead of scanning files.
 - If `graphify-out/wiki/index.md` exists, prefer it over raw file reads.