아래는 App Check를 켜고 다시 배포했더니 사이트가 텅 비어 보이고, 나중에는 AI 생성까지 멈췄던 실제 경험을 순서대로 정리한 기록이에요. 화면을 하나씩 따라 하면 같은 문제를 스스로 풀 수 있습니다.

가이드 정보

• 난이도: 초보자
• 예상 시간: 약 1시간 (설정 반영을 기다리는 시간 약 20분 포함)
• 준비물: 4개
• 확인 날짜: 2026-09-29
• 예시 환경: 프로젝트 내-프로젝트-id(여러분의 Firebase 프로젝트 ID로 바꿔 읽으세요), 사이트 bluel.moonlang.com, React + Vite + Firebase

목차

• 증상별 빠른 찾기
• 0. 이 튜토리얼로 할 수 있는 것
• 1. App Check가 뭔가요?
• 2. reCAPTCHA Enterprise 키는 어떻게 만드나요?
• 3. Firebase 콘솔에서 App Check 등록
• 4. 코드에 App Check 연결하기
• 5. 403 API_KEY_HTTP_REFERRER_BLOCKED는 왜 뜨나요?
• 6. Browser key에 도메인은 어떻게 추가하나요?
• 7. 확인하기
• 8. AI Logic “deactivated” 오류는 어떻게 고치나요?
• 9. 적용 뒤 localhost 개발은 어떻게 하나요? (주의할 점)
• 10. 체크리스트, 자주 막히는 곳
• 공식 문서

증상별 빠른 찾기

이미 문제가 생겼다면 여기서 내 증상을 찾고, 오른쪽 링크로 바로 가세요.

0. 이 튜토리얼로 할 수 있는 것

다 읽고 따라 하면 이런 걸 할 수 있어요.

• 내 Firebase 웹앱에 App Check(출입증 확인)를 처음부터 붙이기
• 배포 뒤 사이트가 비어 보이는 API_KEY_HTTP_REFERRER_BLOCKED 403 오류 고치기
• “Firebase AI Logic has been deactivated” 오류가 났을 때 AI Logic에 App Check 적용하기

전체 흐름 한눈에 보기

상자 앞 숫자가 이 글의 단계 번호예요. 위에서 아래로 따라가면 되고, 빨간 점선과 EX 구역은 “막혔을 때” 가는 길이에요. 왼쪽 위 구역 번호(01·02·04)와 범례는 그림 도구가 붙인 분류라 신경 쓰지 않아도 돼요.

준비물

• Firebase 프로젝트와, 거기에 등록된 웹 앱 1개
• Google Cloud 콘솔에 들어갈 수 있는 같은 구글 계정 (Firebase 프로젝트는 Google Cloud 프로젝트이기도 해요)
• React + Vite 같은 웹앱 코드와, 다시 빌드해서 배포할 수 있는 환경
• 내 사이트 주소 (예: bluel.moonlang.com)

시간은 넉넉히 1시간쯤 잡으세요. 설정이 반영되기를 기다리는 구간(5분, 15분)이 있어요. 403만 고치면 되는 분은 5–7단계만 보면 돼서 훨씬 짧아요.

1. App Check가 뭔가요?

목표: App Check가 무엇을 막아 주는지, 왜 순서가 “키 → 등록 → 코드”인지 설명할 수 있어요.

App Check는 건물 출입증이라고 생각하면 쉬워요. Firebase(데이터베이스, 로그인, AI 같은 서비스)는 건물이고, 내 웹앱은 직원이에요. 출입증이 없던 시절엔 누구든 “저 직원이에요” 하고 들어올 수 있었죠. App Check를 켜면, 요청할 때마다 “진짜 우리 앱에서 온 요청”이라는 출입증(토큰)을 같이 보여줘야 해요.

1. 내 웹앱: 사람이 쓰는 진짜 앱
2. reCAPTCHA Enterprise: “진짜 내 사이트에서 온 요청 맞아요” 신원 확인만 맡아요
3. App Check: 그 확인 결과를 보고 출입증(App Check 토큰, 기본 유효시간 1시간)을 발급해요
4. Firebase 서비스: 출입증 확인 후 통과

정리하면 reCAPTCHA Enterprise는 신원을 확인하는 경비원이고, 출입증은 App Check가 발급해요. 그래서 순서가 reCAPTCHA 키 만들기 → App Check에 등록 → 코드에서 출입증 받기가 됩니다.

알아두면 좋은 말 2가지

모니터링(콘솔 표기: 적용되지 않음(모니터링만)): 출입증을 검사만 하고 막지는 않는 상태. 누가 출입증 없이 오는지 숫자로만 봐요.

적용(Enforce): 출입증 없으면 실제로 막는 상태. 이미 사용자가 있는 앱에서 바로 적용하면 옛 버전 앱이 막힐 수 있어서, 보통은 모니터링으로 먼저 지켜봐요.

✅ 이해했다면 “모니터링은 세기만, 적용은 실제로 막기”를 내 말로 말할 수 있어요.

↩️ 헷갈리면 위 목록을 위에서부터 다시 읽고, 2단계로 넘어가도 괜찮아요. 해 보면 더 잘 보여요.

2. reCAPTCHA Enterprise 키는 어떻게 만드나요?

목표: 내 사이트 주소가 들어간 reCAPTCHA 웹 키를 만들고 사이트 키를 복사해 둡니다.

App Check가 “진짜 내 사이트”인지 판정하려면 이 키가 먼저 있어야 해요.

Google Cloud 콘솔에서 reCAPTCHA 메뉴로 가서 키 만들기를 누릅니다. 화면에 “Fraud Defense”라고 보일 수 있는데, 공식 문서에 따르면 reCAPTCHA Enterprise는 Google Cloud Fraud Defense에 포함된 기능이에요. 화면 위쪽 프로젝트 선택기에서 올바른 프로젝트인지 먼저 확인하세요.

1. 표시 이름: 알아보기 쉬운 이름을 넣어요. 예: web-app-check-key
2. 애플리케이션 유형: 웹을 고릅니다. 화면 안내대로, 만든 뒤에는 바꿀 수 없어요.
3. 도메인 목록: 옆의 도메인 확인 사용 중지 토글은 켜지 말고 꺼 둔 채로 둡니다. Google Cloud 문서는 이 토글을 켜면 사이트 제한이 사라져 누구나 키를 쓸 수 있는 보안 위험이 생긴다고 설명해요. 그다음 이 키를 쓸 실제 서비스 주소를 하나씩 추가해요.
   • 내 도메인: bluel.moonlang.com
   • Firebase 기본 주소(쓰고 있다면): 내-프로젝트-id.web.app, 내-프로젝트-id.firebaseapp.com
4. 체크박스 문제(Use checkbox challenge)는 선택하지 않고 점수 기반(score-based) 키로 둡니다. App Check는 점수 기반 키만 쓰기 때문에 사용자가 퍼즐을 풀 필요가 없어요. (아래 화면에는 이 칸이 보이지 않아요.)
5. Create key를 누르고, 생성된 사이트 키를 복사해 둡니다.

localhost는 reCAPTCHA 키에 넣지 마세요

Firebase 공식 문서는 배포용 reCAPTCHA 키의 도메인에 localhost를 추가하지 말라고 경고해요. 그렇게 하면 누구든 자기 컴퓨터에서 내 앱을 돌려 통과할 수 있기 때문이에요. 내 컴퓨터에서 개발할 때는 9단계의 디버그 토큰을 쓰세요.

화면에서 볼 곳: 맨 위 표시 이름 → 애플리케이션 유형 “웹” → “도메인 확인 사용 중지” 토글은 꺼진 상태 그대로 → 도메인 목록에 도메인 추가 → 맨 아래 Create key. 오른쪽 요약에서 자물쇠 표시된 값은 나중에 못 바꿔요.

비용 참고

Firebase 문서에 따르면 reCAPTCHA Enterprise는 매월 평가 1만 건까지 무료이고, 그 뒤로는 비용이 나와요. App Check 라이브러리는 토큰 유효시간(TTL)의 절반쯤마다 토큰을 새로 받으니, 기본 TTL 1시간이면 사용자 한 명이 사이트를 계속 쓰는 동안 시간당 2번쯤 갱신해요. 무료 Spark 요금제에서는 쓸 수 있는 reCAPTCHA 점수 단계가 일부로 제한돼요.

사이트 키는 공개돼도 괜찮아요

reCAPTCHA 사이트 키는 원래 브라우저 코드에 들어가는 값이에요. 다만 서버용 비밀 키나 서비스 계정 파일은 절대 프런트엔드 코드에 넣으면 안 됩니다.

✅ 이렇게 보이면 성공 키 목록에 새 키가 생기고, 사이트 키를 복사해 뒀어요.

↩️ 아니면 유형을 “웹”으로 골랐는지 보세요. 잘못 만들었다면 새로 만드는 게 빨라요.

3. Firebase 콘솔에서 App Check에 웹 앱 등록

목표: 내 웹 앱의 App Check 상태를 “등록됨”으로 만들어요.

Firebase가 2단계에서 만든 키를 알아야 출입증을 확인할 수 있어요.

1. Firebase 콘솔에서 보안(Security) → App Check로 들어가 앱 탭을 엽니다.
2. 내 웹 앱 줄을 펼쳐서 증명 제공업체로 reCAPTCHA Enterprise(화면에는 “Fraud Defense(이전 명칭: reCAPTCHA Enterprise)”)를 고릅니다.
3. 2단계에서 복사한 사이트 키를 붙여넣어요.
4. 토큰 TTL(출입증 유효시간)은 기본값 1시간 그대로 둡니다. 공식 문서는 30분에서 7일 사이로 바꿀 수 있지만 대부분의 앱에는 1시간이 적당하다고 안내해요.
5. 저장하면 상태가 “등록됨”으로 바뀝니다.

화면에서 볼 곳: 앱 탭 → 증명 제공업체(Fraud Defense) → 사이트 키 입력칸 → 토큰 TTL 1시간 → 오른쪽 상태. 등록 전이라 상태가 “등록되지 않음”으로 보여요. (프로젝트 이름은 가렸어요.)

처음엔 적용(Enforce)을 서두르지 마세요

등록만 하고 API 탭의 각 서비스(Firestore, Authentication 등)는 모니터링 상태로 둡니다. 코드가 출입증을 제대로 붙이는지 숫자로 확인한 다음에 적용해도 늦지 않아요. 단, 아직 출시하지 않은 앱이라면 공식 문서는 바로 적용하는 것을 권해요(막힐 옛 버전 사용자가 없으니까요).

✅ 이렇게 보이면 성공 웹 앱 줄의 상태가 “등록됨”이에요.

↩️ 아니면 사이트 키 칸의 빨간 안내를 보세요. 키를 앞뒤 공백 없이 다시 붙여넣어요.

4. 코드에 App Check 연결하기

목표: 앱이 실제로 출입증을 받아 오도록 코드와 환경변수를 넣고, 다시 빌드·배포해요.

콘솔 설정만으로는 아무 일도 안 일어나요. 앱이 실제로 출입증을 받아 오도록 코드에 몇 줄 넣어야 합니다. Firebase를 초기화하는 파일(예: src/firebase.ts)에 추가해요.

1
2
3
4
5
6
7
8
9
10

import { initializeApp } from "firebase/app";
import { initializeAppCheck, ReCaptchaEnterpriseProvider } from "firebase/app-check";

const app = initializeApp(firebaseConfig);

// Firestore, Auth, AI 같은 다른 Firebase 기능을 쓰기 전에 실행되게 두세요
export const appCheck = initializeAppCheck(app, {
  provider: new ReCaptchaEnterpriseProvider(import.meta.env.VITE_RECAPTCHA_SITE_KEY),
  isTokenAutoRefreshEnabled: true, // 출입증을 알아서 새로 받아요 (기본값은 꺼짐)
});

공식 문서도 App Check 초기화 코드를 다른 Firebase 서비스에 접근하기 전에 실행하라고 안내하고, 토큰 자동 갱신은 isTokenAutoRefreshEnabled: true로 직접 켜야 한다고 적고 있어요. 사이트 키는 코드에 직접 쓰지 않고 환경변수로 넣어요.

1
2

# 내 컴퓨터: 프로젝트 폴더의 .env.local
VITE_RECAPTCHA_SITE_KEY=(복사한 사이트 키)

• Vite는 이름이 VITE_로 시작하는 변수만 브라우저 코드에 넣어 줘요.
• GitHub Actions 같은 CI로 배포한다면 저장소 Secret에 VITE_RECAPTCHA_SITE_KEY를 추가하고, 빌드 단계에서 환경변수로 넘겨주세요.

반영 순서는 코드 수정(initializeAppCheck) → 환경변수(.env.local / CI Secret) → 다시 빌드(npm run build) → 다시 배포예요.

빌드와 배포를 꼭 다시 하세요

Vite는 빌드할 때 import.meta.env 값을 코드에 그대로 바꿔 넣어요. 그래서 키를 바꾸거나 새로 넣었다면 반드시 다시 빌드하고 배포해야 사이트에 반영됩니다.

✅ 이렇게 보이면 성공 배포 뒤 App Check API 탭 메트릭에 확인된 요청이 생기기 시작해요.

↩️ 아니면 확인된 요청이 0이면 환경변수 이름과 재빌드·재배포를 다시 보세요. 사이트가 비어 보이면 5단계로.

5. 403 API_KEY_HTTP_REFERRER_BLOCKED는 왜 뜨나요?

목표: 내 문제가 “API 키 웹사이트 제한” 때문인지 콘솔 오류로 확인해요.

원인을 잘못 짚으면 App Check를 끄는 것처럼 엉뚱한 곳을 고치게 돼요.

App Check를 붙여 새 도메인으로 배포했더니, 로그아웃 상태에서 공개 강의 목록이 안 나오고 “로그인이 필요해요”만 보였어요. 강의 페이지도 자물쇠만 떴습니다.

막힌 상태 1: 공개 강의 자리에 “익명 접속에 실패했습니다” 안내만 보여요.

막힌 상태 2: 강의 페이지가 자물쇠 화면으로만 나와요.

브라우저에서 F12를 눌러 개발자도구 Console 탭을 보면 이런 오류가 있었어요.

1
2
3

403 PERMISSION_DENIED
API_KEY_HTTP_REFERRER_BLOCKED
Requests from referer https://bluel.moonlang.com/ are blocked.

원인

App Check 문제가 아니었어요. Firebase 웹앱이 쓰는 API 키에 “이 웹사이트에서만 쓸 수 있음” 제한(웹사이트 제한)이 걸려 있는데, 그 목록에 새 도메인이 없었던 거예요. 그래서 익명 로그인이 403으로 막혀서, 로그인이 필요한 데이터도 못 불러왔어요.

이 API 키는 Google Cloud 콘솔 API 및 서비스 → 사용자 인증 정보(Credentials)에 있어요. Firebase 공식 문서에 따르면 웹앱용 키는 보통 Browser key (auto created by Firebase)라는 이름으로 자동 생성됩니다.

고칠 키는 아래쪽 Browser key이고, 위쪽 Gemini Developer API key는 이번 문제와 상관없어요. (개인정보 보호를 위해 프로젝트 이름, 클라이언트 ID, 계정 정보는 검게 가렸어요.)

✅ 같은 증상이면 Console에 API_KEY_HTTP_REFERRER_BLOCKED가 보여요. 6단계로 가세요.

↩️ 다른 오류라면 증상별 빠른 찾기 표에서 비슷한 줄을 찾아보세요.

6. Browser key에 도메인은 어떻게 추가하나요?

목표: Browser key의 웹사이트 제한 목록에 내 도메인과 개발 주소를 넣고 저장해요.

이 목록에 없는 주소에서 오는 요청은 전부 403으로 막혀요.

1. Credentials 화면에서 Browser key (auto created by Firebase) 이름을 눌러요.
2. Application restrictions가 Websites로 되어 있는지 봅니다.
3. Website restrictions에서 원래 있던 항목은 지우지 말고 새 주소만 추가하세요. Add를 눌러 아래 주소를 넣어요.
   • 내 도메인: bluel.moonlang.com과 bluel.moonlang.com/* 두 줄 (Google Cloud 문서가 한 도메인의 모든 주소를 허용할 때 권하는 형태예요. 제 스크린샷에는 당시 넣은 https://bluel.moonlang.com/* 한 줄이 보여요.)
   • http://localhost:5173/* (Vite 개발 서버)
4. Firebase Auth 로그인 팝업이나 리디렉션을 쓰면 authDomain(기본값 내-프로젝트-id.firebaseapp.com/*)을, Firebase Hosting 기본 주소를 쓰면 내-프로젝트-id.web.app/*도 목록에 남겨 두세요. Firebase 문서에 따르면 authDomain에는 로그인 도우미 코드가 올라가 있어요.
5. 아래 API restrictions는 건드리지 않고 그대로 둔 채 Save를 누릅니다.
6. 화면 안내대로 반영까지 최대 5분쯤 걸릴 수 있어요. 잠깐 기다려요.

참고로 Google Cloud 문서는 웹사이트 제한에서 와일드카드(*)를 하위 도메인이나 경로 자리에만 쓸 수 있고 주소 중간에는 쓸 수 없다고 설명해요.

사이트를 새 도메인으로 옮겼고 구글 로그인을 쓴다면

Firebase 콘솔 Authentication → 설정 → 승인된 도메인에도 새 도메인을 추가하세요. Browser key 웹사이트 목록과는 별개의 설정이에요.

API 제한 목록: 할 것과 하지 말 것

같은 키 화면 아래쪽 API restrictions는 이번 문제에서는 건드리지 않아요. 나중에 정리하더라도 아래를 지키세요.

• 빼지 말 것: Firebase 문서의 필수 API 표에 따르면 Authentication에는 Identity Toolkit API와 Token Service API, App Check에는 Firebase App Check API가 필요해요. 이런 항목을 빼면 로그인과 App Check가 깨질 수 있어요.
• 들어 있으면 안 되는 것: Firebase 문서는 Browser key의 API 제한 목록에 Generative Language API가 있으면 안 된다고 안내해요.
• 콘솔에 API_KEY_SERVICE_BLOCKED 403이 보이면, 문서 안내대로 필요한 API가 모두 목록에 있는지 확인하세요.

Add를 누르면 주소 입력칸이 열려요. 한 줄에 주소 하나씩 넣고 Done.

화면에서 볼 곳: Websites 선택 → Add와 두 주소 → 아래 Save → “최대 5분” 안내. (프로젝트 이름은 가렸어요.)

흔한 실수: 다른 키를 고치기

Credentials에는 Gemini Developer API key (auto created by Firebase) 같은 다른 키도 있어요. 이름이 비슷해서 이 키를 고치기 쉬운데, 사이트가 막힌 건 이 키 때문이 아니에요.

• Browser key (auto created by Firebase): 웹사이트가 쓰는 키. 여기에 도메인 추가
• Gemini Developer API key (auto created by Firebase): 예전에 AI Logic용으로 자동 생성된 키예요. 2026년 중반부터 AI Logic은 이 키를 쓰지 않아요. 앱 코드나 .env에 절대 넣지 마세요. 이번 문제와는 상관없어요.

틀리면 이렇게 보여요: 다른 키를 고치는 중

제 경우에는 저장하려는데 “API 제한이 제거됩니다” 같은 경고와 함께 UPDATE를 직접 입력하라고 했을 때, 잘못된 키를 고치고 있었어요. 취소하고 화면 맨 위의 키 이름이 Browser key인지 다시 확인하세요.

틀리면 이렇게 보여요: 주소 모양이 다름

저장하고 5분이 지나도 같은 403이 난다면, 넣은 주소를 다시 보세요. https와 http가 바뀌었거나, 끝의 /*가 빠졌거나, 도메인 철자가 다르면 목록과 맞지 않아 계속 막힐 수 있어요.

어떤 키인지 확인하는 법

내 앱 코드의 firebaseConfig.apiKey 앞 몇 글자와 Credentials의 Show key로 본 앞부분을 비교하면 확실해요. 다만 키 전체를 채팅이나 스크린샷으로 공유하지는 마세요.

✅ 이렇게 보이면 성공 목록에 두 주소가 들어가고 Save 뒤 5분 안내가 보여요. 7단계로 확인하러 가요.

↩️ 아니면 UPDATE 입력을 요구하면 다른 키예요. 그대로면 자주 막히는 곳: 도메인을 추가했는데도 그대로예요를 보세요.

7. 확인하기

목표: 로그아웃 상태에서도 사이트가 정상으로 보이는지 눈으로 확인해요.

로그인한 상태로 보면 막힌 걸 놓칠 수 있어요. 처음 온 방문자 입장에서 봐야 해요.

1. 로그아웃한 상태에서 사이트를 엽니다. (시크릿 창을 쓰면 편해요.)
2. 새로고침한 뒤 공개 강의 목록이 보이는지 확인해요.
3. 강의 하나를 눌러서 커리큘럼이 나오는지 봅니다.
4. F12 → Console에 403이나 API_KEY_HTTP_REFERRER_BLOCKED가 더 이상 없는지 확인해요.

고친 뒤: 로그아웃 상태에서도 공개 강의 목록이 보여요.

고친 뒤: 강의 페이지에 커리큘럼이 정상으로 나와요.

✅ 이렇게 보이면 성공 공개 강의 목록과 커리큘럼이 보이고, Console에 403이 없어요.

↩️ 아니면 5분 더 기다린 뒤 강력 새로고침. 그래도 같으면 6단계의 “틀리면 이렇게 보여요”를 다시 보세요.

8. AI Logic “deactivated” 오류는 어떻게 고치나요?

목표: AI Logic의 App Check를 “기본 - 적용됨 / 재생 - 모니터링”으로 저장해요.

사이트는 살아났는데, 이번엔 AI로 강의를 만드는 기능이 이런 오류를 냈어요(실제로 본 오류 문구의 일부).

1

Firebase AI Logic has been deactivated ... you must enforce Firebase App Check

Firebase 공식 문서에 따르면 2026년 11월 2일부터 Firebase AI Logic을 쓰려면 App Check 적용(Enforce)이 필수이고, 그날부터는 자동으로 적용되며 끌 수 없어요. 콘솔 배너에도 같은 날짜가 나와요. 우리 앱은 “등록됨(적용되지 않음)” 상태였습니다. (공식 문서는 2026년 7월 초 이후 콘솔에서 AI Logic을 새로 설정하면 App Check가 자동으로 적용된다고 설명해요. 그 전에 설정한 프로젝트라면 직접 적용해야 합니다.)

AI Logic 화면의 노란 배너와 “등록됨(적용되지 않음)” 표시. (프로젝트 이름은 가렸어요.)

메트릭을 보면 요청 100%가 “확인되지 않음: 오래된 클라이언트 요청”이었고 상태는 “기본 - 모니터링”이었어요. 공식 문서에서 “오래된 클라이언트 요청”은 App Check 토큰이 빠진 요청을 뜻해요.

먼저 확인: 앱이 토큰을 붙이고 있나요?

메트릭에 ‘오래된 클라이언트 요청 100%’로 나오면 앱이 아직 토큰을 붙이지 않는 상태라서, 적용하면 AI 요청은 계속 막혀요. 4단계 코드가 들어간 버전을 먼저 배포하세요. 2026년 11월 2일부터는 자동으로 적용되고 끌 수 없어요.

적용 전: 확인된 요청 0, 오래된 클라이언트 요청 100%.

설정 순서

1. Firebase 콘솔 보안(Security) → App Check → API 탭에서 Firebase AI Logic 줄의 설정 메뉴(점 3개 ⋮ 또는 그래프 아래 설정 버튼)를 엽니다.
2. 1단계 기준 보호: “적용되지 않음(모니터링만)”과 “적용됨” 중 적용됨을 고르고 계속.
3. 2단계 재생 보호: 모니터링만을 고르고 계속.
4. 3단계 확인에서 저장합니다.

1단계 기준 보호 “적용됨”: 유효한 App Check 토큰이 없는 요청은 막혀요. 고른 뒤 계속.

2단계 재생 보호 “모니터링만”. 고른 뒤 계속, 그다음 확인 화면에서 저장.

재생 보호는 “적용됨”을 고르지 마세요 (지금은)

재생 보호를 “적용됨”으로 하면 요청마다 새로 발급한 한 번용(limited-use) 토큰만 통과해요. 앱 코드에서 limited-use 토큰 사용을 켜 두지 않았다면 내 앱 요청까지 막혀요. 공식 AI Logic 안내는 limited-use 토큰을 켜기 전까지 재생 보호를 “중지됨”으로 두라고 하고, 콘솔 화면은 “모니터링만”도 고를 수 있게 해 줘요. 저는 차단될 요청을 미리 보려고 “모니터링만”을 골랐어요.

틀리면 이렇게 보여요: 재생 보호까지 적용함

저장 뒤 AI 요청이 전부 막힌다면 재생 보호를 “적용됨”으로 저장했을 가능성이 커요. 같은 메뉴로 들어가 재생 보호를 모니터링만(또는 중지됨)으로 되돌리세요.

저장 후: “기본 - 적용됨 / 재생 - 모니터링”.

저장한 뒤에

• 공식 문서 기준으로 적용이 반영되기까지 최대 15분이 걸릴 수 있어요. 조금 기다립니다.
• 사이트에서 강력 새로고침(Windows Ctrl+Shift+R, Mac Cmd+Shift+R)을 해서 옛 코드 캐시를 비워요.
• 반영된 뒤에 AI 생성을 다시 시도해 보세요.
• App Check 메트릭에서 확인된 요청이 늘어나면 정상 신호예요.
• 계속 오래된 클라이언트 요청만 쌓인다면, 브라우저가 옛 번들을 쓰고 있거나 배포된 코드가 아직 출입증을 붙이지 않는 거예요. 4단계 코드가 들어간 버전으로 다시 빌드·배포됐는지 확인하세요.

솔직한 현재 상태

이 글을 쓰는 시점에는 적용 설정을 저장한 직후라, AI 생성이 다시 되는 것까지는 아직 확인하지 못했어요. 반영될 때까지 기다린 뒤 다시 시도해서 메트릭과 함께 확인해 주세요.

✅ 이렇게 보이면 설정 완료 AI Logic 상태가 “기본 - 적용됨 / 재생 - 모니터링”이에요. 반영된 뒤 AI 생성을 다시 시도하고, 확인된 요청이 늘어나는지 보세요.

↩️ 아니면 AI 요청이 전부 막히면 위 “재생 보호까지 적용함”을, 오래된 요청만 쌓이면 4단계 재빌드·재배포를 보세요.

9. 적용 뒤 localhost 개발은 어떻게 하나요? (주의할 점)

목표: 적용 뒤에 생기기 쉬운 문제 3가지를 미리 알고 대비해요.

적용은 “출입증 없으면 막기”라서, 내 개발 환경이나 직접 부르는 백엔드도 막힐 수 있어요.

1. 내 컴퓨터(localhost) 개발은 디버그 토큰이 필요해요

공식 문서에 따르면 App Check를 적용한 서비스는 localhost나 CI 환경에서 돌리는 앱을 유효한 기기로 인정하지 않아요. 이럴 땐 디버그 제공자(디버그 토큰)를 써요.

1. 개발용 빌드에서만, App Check를 초기화하기 전에 디버그 모드를 켭니다.
2. 로컬에서 앱을 열고 브라우저 개발자도구 콘솔에 출력된 디버그 토큰을 복사해요.
3. Firebase 콘솔 보안 → App Check → 앱 탭에서 내 앱의 ⋮ 메뉴 → 디버그 토큰 관리에 그 토큰을 등록해요.
4. 이제 localhost에서도 통과해요.

1
2
3
4
5
6

// 개발용 빌드에서만! 배포용 코드에는 절대 넣지 마세요
if (import.meta.env.DEV) {
  // TypeScript에서 타입 오류가 나지 않도록 any로 씁니다
  (self as any).FIREBASE_APPCHECK_DEBUG_TOKEN = true;
}
// 그다음 initializeAppCheck(...)

디버그 토큰은 비밀번호처럼

디버그 토큰이 있으면 검증되지 않은 기기에서도 백엔드에 접근할 수 있어요. 공개 저장소에 커밋하지 말고, 배포용 빌드에 디버그 모드가 켜지지 않게 하세요. 토큰이 유출되면 콘솔에서 바로 삭제하세요.

2. Firestore와 Authentication 적용은 메트릭을 보고

AI Logic은 필수라서 먼저 켰지만, 이미 사용자가 있는 앱이라면 Firestore와 Authentication은 서두르지 않아도 돼요. 공식 문서는 API 탭 메트릭에서 최근 요청이 거의 모두 확인된 요청일 때 적용을 고려하고, 오래된 클라이언트 요청이 많으면 사용자들이 업데이트할 때까지 기다리라고 안내해요. 저는 하루쯤 지켜본 뒤 켜는 편을 권해요. 확인 안 된 요청이 많은데 켜면 실제 사용자가 막혀요.

3. 내 함수·백엔드를 fetch로 직접 부른다면

공식 문서에 따르면 Cloud Functions 클라이언트 SDK로 호출 가능 함수(httpsCallable)를 부르면 App Check 토큰이 자동으로 붙어요. 하지만 fetch로 내 백엔드 주소를 직접 부른다면 토큰을 직접 받아서 X-Firebase-AppCheck 헤더에 넣어야 해요. 토큰은 URL이나 쿼리 문자열에 넣지 말라고 문서가 강조해요.

1
2
3
4
5
6
7
8

import { getToken } from "firebase/app-check";

const { token } = await getToken(appCheck, /* forceRefresh */ false);
await fetch(FUNCTION_URL, {
  method: "POST",
  headers: { "Content-Type": "application/json", "X-Firebase-AppCheck": token },
  body: JSON.stringify(data),
});

이때 받는 쪽(내 백엔드)도 이 헤더의 토큰을 검증하도록 만들어 둬야 실제 보호가 돼요. 방법은 아래 공식 문서의 “커스텀 백엔드에서 토큰 확인”을 참고하세요.

✅ 준비됐다면 디버그 토큰 등록 방법을 알고, Firestore·Authentication은 메트릭을 본 뒤 켜기로 했어요.

↩️ 막혔다면 localhost는 1번, fetch로 부른 백엔드가 거부하면 3번을 다시 보세요.

10. 체크리스트, 자주 막히는 곳

체크리스트

• reCAPTCHA Enterprise 웹 키를 만들고 실제 서비스 도메인(내 도메인, 쓰고 있다면 .web.app·.firebaseapp.com)을 넣었다 (localhost는 넣지 않음)
• App Check 앱 탭에서 웹 앱을 reCAPTCHA Enterprise로 등록했다 (TTL 기본 1시간)
• 코드에 initializeAppCheck를 넣고 VITE_RECAPTCHA_SITE_KEY를 .env.local과 CI Secret에 넣었다
• 다시 빌드하고 배포했다
• Credentials의 Browser key에서 원래 항목은 지우지 않고, 내 도메인(내도메인, 내도메인/*)과 http://localhost:5173/*를 추가했다
• 구글 로그인을 쓰면 authDomain(내-프로젝트-id.firebaseapp.com/*), 기본 호스팅을 쓰면 내-프로젝트-id.web.app/*가 목록에 남아 있다
• 새 도메인으로 옮겼다면 Authentication 승인된 도메인에도 추가했다
• Browser key의 API 제한 목록에서 필요한 API를 빼지 않았고, Generative Language API는 들어 있지 않다
• 로그아웃 상태에서 공개 강의가 보이고, 콘솔에 403이 없다
• AI Logic: 기준 보호 “적용됨”, 재생 보호 “모니터링만”으로 저장했다
• 15분쯤 뒤 강력 새로고침하고 AI 생성을 다시 시도했다
• 메트릭에서 확인된 요청이 늘어나는지 봤다

자주 막히는 곳

Q. 403이 났는데 App Check를 끄면 되나요?

API_KEY_HTTP_REFERRER_BLOCKED라면 App Check와는 상관없어요. Browser key 웹사이트 목록에 도메인을 추가하세요. 6단계

Q. reCAPTCHA v3와 Enterprise 중 뭘 써야 하나요?

새로 붙인다면 Enterprise예요(공식 권장).

Q. localhost를 reCAPTCHA 키에 넣어도 되나요?

안 돼요. 디버그 토큰을 쓰세요. 9단계 1번

Q. 코드에 API 키가 보여도 괜찮나요?

Firebase용으로 제한된 Browser key라면 괜찮아요. Gemini 키, 비밀 키, 서비스 계정 파일은 절대 코드에 넣으면 안 돼요.

Q. 11월 2일 이후 AI Logic은 어떻게 되나요?

App Check가 자동으로 적용되고 끌 수 없어요.

Q. 도메인을 추가했는데도 그대로예요.

5분쯤 기다린 뒤 강력 새로고침을 해 보세요. 그래도 안 되면 주소 모양(/*, https와 http 구분), 그리고 고친 키가 정말 Browser key인지 다시 확인하세요. 6단계 흔한 실수

Q. 재생 보호도 적용하는 게 더 안전하지 않나요?

보호 수준은 더 높지만, 앱 코드에서 limited-use 토큰을 쓰도록 바꾼 뒤에 켜야 해요. 준비 없이 켜면 내 앱도 막혀요. 공식 문서는 요청마다 새 토큰을 만들어서 지연 시간과 비용이 늘 수 있다는 점도 알려 줘요. 8단계

이것만 기억하세요

• 403 API_KEY_HTTP_REFERRER_BLOCKED는 App Check가 아니라 Browser key 웹사이트 제한 목록 문제예요.
• App Check는 끄지 말고 키 → 등록 → 코드 → 다시 빌드·배포 순서로 붙여요.
• AI Logic은 기준 보호만 적용, 재생 보호는 limited-use 토큰 준비 전까지 모니터링만(또는 중지됨). 반영된 뒤 다시 시도해요.

확인 날짜: 2026-09-29. 스크린샷은 실제 작업 화면이며, 개인정보(프로젝트 이름, 계정 이메일, 클라이언트 ID 등)는 가림 처리했어요. 콘솔 메뉴 이름과 배치는 Google이 바꿀 수 있으니, 화면이 조금 달라도 같은 이름의 메뉴를 찾아 주세요.

공식 문서

• Firebase: 웹 앱에서 reCAPTCHA Enterprise로 App Check 시작하기
• Firebase: 웹 앱에서 App Check 디버그 제공자 사용하기
• Firebase: App Check 요청 메트릭 모니터링
• Firebase: App Check 적용 사용 설정(재생 보호 포함)
• Firebase: Firebase AI Logic과 App Check
• Firebase: 커스텀 백엔드 요청에 App Check 토큰 보내기(웹)
• Firebase: 커스텀 백엔드에서 App Check 토큰 확인
• Firebase: Cloud Functions 호출 가능 함수에 App Check 적용
• Firebase: Firebase API 키 사용 및 관리
• Google Cloud: API 키 관리(웹사이트 제한)
• Google Cloud: 웹사이트용 reCAPTCHA 키 만들기(도메인 확인)
• Firebase: AI Logic FAQ(11월 2일 적용, Gemini API 키 변경)
• Firebase: App Check 개요(할당량과 비용)
• Firebase: reCAPTCHA v3 제공자(Enterprise 권장 안내)
• Firebase: signInWithRedirect 권장사항(authDomain)
• Firebase: 웹에서 Google 로그인(승인된 도메인)
• Vite: 환경변수와 모드

처음에는 CLAUDE.md, AGENTS.md, .cursor/rules/*.mdc를 전부 심링크로 묶을 생각이었습니다. 문서를 다시 읽고 직접 돌려 보니 필요한 링크는 그보다 적었습니다. 이 글은 그 확인 기록입니다. 스킬 파일(SKILL.md)을 여러 도구에서 같이 쓰는 문제는 SKILL.md 하나로 Codex·Claude·Antigravity·Grok에서 모두 쓸 수 있을까?에서 따로 다뤘습니다.

기준일. 도구별 동작은 2026-09-30(KST) 기준 각 공식 문서와 소스 코드에서 확인했습니다. 문서에 없는 내용은 출처(포럼, GitHub PR)를 따로 밝혔습니다. 링크는 글 끝 출처에 모았습니다.

도구마다 어떤 규칙 파일을 읽나?

Claude Code: CLAUDE.md, 그리고 이제는 AGENTS.md도

• 프로젝트 규칙은 ./CLAUDE.md 또는 ./.claude/CLAUDE.md에 둡니다. 작업 디렉터리와 그 위 디렉터리의 파일을 모두 이어 붙여 읽습니다.
• v2.1.277부터는 AGENTS.md를 직접 읽습니다. 다만 기본값에서는 작업 디렉터리나 그 위에 CLAUDE.md·.claude/CLAUDE.md·CLAUDE.local.md가 하나도 없을 때만 AGENTS.md를 읽습니다. 둘 다 있으면 CLAUDE.md만 읽습니다. ~/.claude/CLAUDE.md와 .claude/rules/는 이 판정에 들어가지 않습니다.
• 개인용 CLAUDE.local.md를 하나 만들기만 해도 AGENTS.md를 읽지 않게 됩니다. 둘 다 읽게 하려면 /config에서 Project instructions를 claude-md-and-agents-md로 바꿉니다.
• 문서가 AGENTS.md를 못 읽는다고 적어 둔 세션도 있습니다. v2.1.277 이전 버전, 내장 agents-md 플러그인을 끈 경우, v2.1.276 이하에서 업그레이드한 직후 첫 세션(일부), 그리고 v2.1.281 이전의 Amazon Bedrock·텔레메트리를 끈 일부 세션입니다.
• 설정으로 읽힌 AGENTS.md는 CLAUDE.md와 다르게 동작하는 곳이 있습니다. InstructionsLoaded 훅이 발동하지 않고(CLAUDE.md가 import하거나 심링크한 AGENTS.md는 발동), --add-dir과 CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD로 추가한 디렉터리의 AGENTS.md는 읽지 않습니다.
• 문서가 직접 두 가지 연결 방법을 소개합니다. CLAUDE.md 안에 @AGENTS.md 한 줄을 넣는 import 방식과, ln -s AGENTS.md CLAUDE.md 심링크 방식입니다.
• 심링크를 쓸 때 문서가 적어 둔 제약이 두 가지 있습니다.
  • Claude는 링크를 통해 CLAUDE.md를 읽지만, Edit·Write 도구는 심링크 너머로 쓰지 않고 원본(AGENTS.md)을 고치라고 안내합니다.
  • Windows에서 작업하는 사람이 있으면 import 방식을 쓰라고 합니다. 심링크를 만들려면 관리자 권한이나 개발자 모드가 필요하고, core.symlinks가 꺼진 클론에서는 CLAUDE.md가 한 줄짜리 텍스트 파일로 풀리기 때문입니다.
• .claude/rules/도 심링크를 지원합니다. 단, 링크 대상이 작업 디렉터리 밖이면 외부 import처럼 취급해 승인 전까지 불러오지 않습니다. 네트워크 경로를 가리키는 링크는 따라가지 않습니다.

Codex: AGENTS.md가 기본

• 전역은 Codex 홈 디렉터리(기본 ~/.codex, CODEX_HOME으로 변경 가능)의 AGENTS.override.md, 없으면 AGENTS.md를 읽습니다. 이 단계에서는 비어 있지 않은 첫 파일 하나만 씁니다.
• 프로젝트는 루트(보통 Git 루트)부터 현재 디렉터리까지 내려가며 디렉터리마다 AGENTS.override.md → AGENTS.md → project_doc_fallback_filenames에 적은 이름 순으로 하나씩 찾습니다. 빈 파일은 건너뜁니다.
• 합친 크기가 project_doc_max_bytes(기본 32 KiB)에 닿으면 파일을 더 붙이지 않습니다.
• CLAUDE.md는 기본 탐색 대상이 아닙니다. 다른 파일 이름을 쓰고 싶으면 ~/.codex/config.toml의 project_doc_fallback_filenames에 추가합니다.
• 심링크는 공식 가이드에는 나오지 않습니다. 대신 소스 코드(codex-rs/core/src/agents_md.rs)의 탐색 함수 주석에 “Symlinks are allowed.”라고 적혀 있고, 탐색 성능 PR(#29870)의 Symlinks 절에는 링크 대상이 일반 파일이면 읽고 깨진 링크는 없는 파일로 취급한다고 나옵니다.
• 같은 소스 파일에는 신뢰하지 않은(untrusted) 프로젝트로 표시된 경우 프로젝트의 AGENTS.md를 읽지 않는 분기가 있습니다. 공식 가이드가 아니라 소스 기준입니다.

Cursor: .cursor/rules/*.mdc 또는 AGENTS.md

• 프로젝트 규칙은 .cursor/rules 안의 .mdc 파일입니다. 문서는 확장자가 .md인 파일은 규칙 시스템이 무시한다고 명시합니다. frontmatter에 description, globs, alwaysApply를 적어 언제 적용할지 정하기 때문입니다.
• 같은 문서가 “plain markdown을 원하면 AGENTS.md를 쓰라”고 합니다. 루트와 하위 디렉터리의 AGENTS.md를 읽고, 하위 폴더의 파일이 더 구체적인 지시로 우선합니다.
• 프로젝트 루트의 .cursorrules는 공식 도움말 기준 legacy이고 deprecated 예정입니다.
• .cursor/rules의 심링크는 공식 문서에 설명이 없습니다. Cursor 커뮤니티 포럼에는 2025년 12월(2.2.x)에 심링크된 .mdc를 읽지 못한다는 버그 보고가 있었고, 2026년 2월 Cursor 스태프가 같은 스레드에 “2.5에서 고쳐졌다”고 답했습니다.
• 2026년 2월 말 스레드(2.5.25)에서는 심링크한 디렉터리 안 규칙이 안 잡힌다는 보고에 스태프가 Reload Window를 권했지만, 보고자는 다시 불러오거나 재시작해도 안 된다고 답했습니다. 결국 보고자가 찾은 원인은 그 폴더 이름(generated/)이 .gitignore에 걸려 있던 것이었습니다. 같은 보고에서 개별 .mdc 파일 심링크는 정상 동작했다고 합니다. 둘 다 공식 문서가 아니라 포럼 글이라는 점은 감안해야 합니다.

정리하면

심링크는 언제 필요하고, git에는 어떻게 저장되나?

AGENTS.md 공식 사이트도 기존 파일을 옮길 때 mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md처럼 심링크로 하위 호환을 유지하라고 안내합니다. 심링크 자체는 흔한 방법입니다. 다만 위 표대로라면 AGENTS.md만 두면 세 도구가 다 읽습니다. CLAUDE.md 링크가 필요한 경우는 이 정도입니다.

• 문서가 AGENTS.md를 못 읽는다고 적은 Claude Code 세션(v2.1.277 이전, v2.1.281 이전의 Bedrock·텔레메트리 끈 세션, 업그레이드 직후 첫 세션 등)이 팀에 섞여 있을 때
• 팀원 중 누군가 CLAUDE.local.md를 쓰고 있을 때(이 파일이 있으면 기본값에서 AGENTS.md를 안 읽음)
• InstructionsLoaded 훅을 쓰거나 --add-dir로 다른 디렉터리 규칙을 불러올 때(설정으로 읽힌 AGENTS.md는 훅이 안 뜨고, 추가 디렉터리의 AGENTS.md는 안 읽힘)

아래는 리눅스(git 2.47) 임시 디렉터리에서 원본 AGENTS.md 하나에 CLAUDE.md와 .cursor/rules/core.mdc를 심링크로 걸어 본 결과입니다. 출력은 실제로 나온 그대로입니다. 파일 시스템과 git 동작만 본 것이고, 각 도구가 실제로 파일을 읽는지는 이 데모에서 확인하지 않았습니다.

만들기

1
2
3
4
5
6
7
8
9
10
11
12
13
14

mkdir -p /tmp/rules-demo && cd /tmp/rules-demo
git init -q -b main .

cat > AGENTS.md <<'MD'
# 프로젝트 규칙

- 패키지 매니저는 pnpm을 쓴다.
- 커밋 전에 `pnpm lint && pnpm test`를 돌린다.
- `dist/`는 생성물이므로 직접 고치지 않는다.
MD

ln -s AGENTS.md CLAUDE.md
mkdir -p .cursor/rules
ln -s ../../AGENTS.md .cursor/rules/core.mdc

링크 대상은 링크가 있는 위치 기준 상대 경로입니다. .cursor/rules/core.mdc에서 루트의 AGENTS.md까지는 두 단계 위라서 ../../AGENTS.md가 됩니다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

$ tree -a -I .git
.
├── .cursor
│   └── rules
│       └── core.mdc -> ../../AGENTS.md
├── AGENTS.md
└── CLAUDE.md -> AGENTS.md

3 directories, 3 files

$ ls -la . .cursor/rules
.:
total 44
drwxr-xr-x 4 box  box   4096 Sep 30 10:47 .
drwxrwxrwt 1 root root 20480 Sep 30 10:47 ..
drwxr-xr-x 3 box  box   4096 Sep 30 10:47 .cursor
drwxr-xr-x 7 box  box   4096 Sep 30 10:47 .git
-rw-r--r-- 1 box  box    179 Sep 30 10:47 AGENTS.md
lrwxrwxrwx 1 box  box      9 Sep 30 10:47 CLAUDE.md -> AGENTS.md

.cursor/rules:
total 8
drwxr-xr-x 2 box box 4096 Sep 30 10:47 .
drwxr-xr-x 3 box box 4096 Sep 30 10:47 ..
lrwxrwxrwx 1 box box   15 Sep 30 10:47 core.mdc -> ../../AGENTS.md

$ readlink CLAUDE.md .cursor/rules/core.mdc
AGENTS.md
../../AGENTS.md

git은 심링크를 “링크”로 저장한다

1
2
3
4
5
6
7
8
9
10

$ git add -A

$ git ls-files -s
120000 b7e6491d3a0dda1d656cc3c4320f5c013cdbc02d 0.cursor/rules/core.mdc
100644 f469d6a0a1be5a6ce9db905553c85667281bf894 0AGENTS.md
120000 47dc3e3d863cfb5727b87d785d09abf9743c0a72 0CLAUDE.md

$ git cat-file -p :CLAUDE.md
AGENTS.md
$ git commit -q -m init

일반 파일은 모드 100644, 심링크는 120000으로 들어갑니다. 저장소에 담기는 건 원본 내용이 아니라 링크 대상 경로 문자열(AGENTS.md)입니다. 그래서 받는 쪽이 심링크를 풀어 주지 않으면 이 문자열이 그대로 파일이 됩니다.

커밋한 저장소를 core.symlinks를 끈 채로 클론해 Windows에서 생길 수 있는 상황을 흉내 내 봤습니다.

1
2
3
4
5
6
7

$ git clone -q -c core.symlinks=false /tmp/rules-demo /tmp/rules-demo-nosym

$ ls -la /tmp/rules-demo-nosym/CLAUDE.md
-rw-r--r-- 1 box box 9 Sep 30 10:47 /tmp/rules-demo-nosym/CLAUDE.md

$ cat /tmp/rules-demo-nosym/CLAUDE.md
AGENTS.md

9바이트짜리 일반 파일이 생겼고, 내용은 AGENTS.md 한 단어입니다. git 문서의 core.symlinks 설명 그대로입니다. 이 값이 false면 심링크를 “링크 텍스트가 담긴 작은 일반 파일”로 체크아웃합니다. 기본값은 true지만 git clone·git init이 파일 시스템을 확인해 적절하면 false로 설정합니다. Claude Code 문서가 Windows 사용자가 있으면 import 방식을 권하는 이유가 여기에 있습니다. 이 상태의 CLAUDE.md는 규칙 대신 단어 하나만 담고 있으니까요.

상대 경로로 걸어야 하는 이유

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

$ mkdir -p /tmp/abs-demo && cd /tmp/abs-demo

$ echo "# 규칙" > AGENTS.md

$ ln -s AGENTS.md CLAUDE.md

$ ln -s /tmp/abs-demo/AGENTS.md CLAUDE.abs.md

$ mv /tmp/abs-demo /tmp/abs-demo-moved && cd /tmp/abs-demo-moved

$ head -n 1 CLAUDE.md
# 규칙

$ head -n 1 CLAUDE.abs.md
head: cannot open 'CLAUDE.abs.md' for reading: No such file or directory

절대 경로 링크는 디렉터리를 옮기거나 다른 사람이 클론하면 바로 깨집니다. 저장소에 커밋하는 링크는 상대 경로로 겁니다.

.cursor/rules에 AGENTS.md를 심링크하면 안 되나?

링크는 잘 걸립니다. 문제는 내용입니다.

1
2
3
4

$ head -n 3 .cursor/rules/core.mdc
# 프로젝트 규칙

- 패키지 매니저는 pnpm을 쓴다.

core.mdc를 열면 AGENTS.md 본문이 그대로 나오고, frontmatter가 없습니다. Cursor 문서의 표에 따르면 alwaysApply가 false이고 description·globs가 모두 없으면 채팅에서 @멘션할 때만 규칙이 들어갑니다. frontmatter가 아예 없는 경우를 따로 적진 않았지만, 이대로면 이 링크는 자동으로 적용되지 않을 가능성이 큽니다. 그렇다고 AGENTS.md 맨 위에 alwaysApply: true 같은 frontmatter를 넣으면 Codex와 Claude Code가 그 줄까지 규칙 본문으로 읽을 수 있습니다.

Cursor는 AGENTS.md를 직접 읽으니 이 링크는 뺐습니다. 특정 경로에만 거는 Cursor 전용 규칙이 필요하면 그때 frontmatter를 갖춘 진짜 .mdc 파일을 따로 만듭니다.

최종 구성

앞의 git 실험은 링크를 지우기 전 상태에서 했습니다. 실제로 남기는 구성은 core.mdc 링크를 지운 쪽입니다.

1

rm .cursor/rules/core.mdc

1
2
3

.
├── AGENTS.md                # 원본. Codex, Cursor, Claude Code(v2.1.277+)가 직접 읽음
└── CLAUDE.md -> AGENTS.md   # AGENTS.md를 못 읽는 Claude Code 세션용 (선택)

Windows 사용자가 있는 저장소라면 CLAUDE.md를 심링크 대신 한 줄짜리 일반 파일로 둡니다.

1

@AGENTS.md

로딩 확인은 이렇게 합니다.

• Claude Code: AGENTS.md가 직접 읽혔는지는 /memory에서 경로로 확인합니다(문서가 지정한 방법). 인터랙티브 세션을 시작할 때 no CLAUDE.md found; AGENTS.md loaded: … 같은 줄도 나옵니다. CLAUDE.md 심링크나 import를 쓴다면 /context의 Memory files 목록에 CLAUDE.md가 있는지 봅니다.
• Codex: 문서에 나온 대로 저장소 루트에서 아래 명령을 실행합니다.

1

codex --ask-for-approval never "Summarize the current instructions."

dot-agents 같은 도구를 써야 하나?

이 작업을 대신해 준다는 도구로 dot-agents(www.dot-agents.com, github.com/dot-agents/dot-agents)를 검토했습니다. 규칙·스킬·MCP 설정을 ~/.agents/에 모아 두고 Cursor, Claude Code, Codex, OpenCode 프로젝트에 심링크로 뿌려 주는 무료 bash CLI이고, 라이선스는 MIT입니다. 설치는 하지 않고 저장소 코드만 읽었습니다. 커밋은 모두 dottybotdev 한 계정에서 나왔고, v0.1.9(2026-01-13) 직후 1월 중순 커밋을 마지막으로 2026-09-30 현재 약 8개월 반째 새 커밋이 없습니다. 사이트에는 tasks, history, snapshot, restore 같은 명령이 소개돼 있지만 “출시 후 제공” 항목으로 묶여 있고, 코드에 들어 있는 명령은 add, doctor, explain, hooks, init, remove, skills, status, sync 9개입니다. 직접 하기로 한 이유는 설정 파일 처리였습니다. init은 ~/.claude/settings.json이 없을 때, 또는 --force를 주면 기존 파일이 있어도 그 자리를 심링크로 바꿉니다. add는 ~/.agents에 해당 설정이 있으면 프로젝트의 .mcp.json과 .codex/config.toml을 ln -sf로 심링크로 바꿉니다. hooks examples가 보여 주는 예제(기본 설치는 아니고 hooks add로 직접 추가해야 함) 중에는 입력한 프롬프트를 ~/.claude/prompts.log에, 실행한 명령을 ~/.claude/command-log.txt에 평문으로 남기는 훅이 있어, 그대로 쓰면 토큰이 섞인 입력도 파일에 남습니다. 설치 방법 중 하나가 curl | bash라는 점, 이름이 비슷한 다른 프로젝트 getsentry/dotagents와 헷갈리기 쉽다는 점도 걸렸습니다. 도구가 나쁘다는 이야기는 아닙니다. 필요한 건 링크 한두 개였고, 그 정도면 ln -s 한 줄로 끝나기 때문에 설정 파일까지 맡길 이유가 없었습니다.

적용 전에 무엇을 확인하나? (체크리스트)

• 원본은 AGENTS.md 하나. 다른 파일은 링크나 @AGENTS.md import로만 잇는다
• 링크는 링크 위치 기준 상대 경로로 건다(ln -s AGENTS.md CLAUDE.md). 절대 경로는 클론하거나 옮기면 깨진다
• Windows 사용자가 있으면 CLAUDE.md는 심링크 대신 @AGENTS.md 한 줄짜리 일반 파일
• 규칙 파일에 API 키, 토큰, 내부 URL 같은 비밀값을 넣지 않는다. 커밋되고, 매 세션 모델 컨텍스트에 들어간다
• settings.json, .mcp.json, config.toml 같은 설정 파일은 심링크로 묶지 않는다. 형식도 도구마다 다르고(JSON, TOML), 한 곳을 고치면 모든 도구에 바로 반영된다
• .cursor/rules에 넣는 파일은 .mdc 확장자와 frontmatter를 갖춘 진짜 파일로
• 심링크한 규칙 폴더 이름이 .gitignore에 걸려 있지 않은지 본다(포럼 사례)
• CLAUDE.local.md를 만들면 Claude Code가 기본값에서 AGENTS.md를 안 읽는다는 점을 팀에 공유
• Codex는 합친 규칙이 32 KiB(기본값)에 닿으면 파일을 더 붙이지 않는다. 규칙이 길어지면 하위 디렉터리로 나눈다
• 바꾼 뒤에는 Claude Code /memory·/context, Codex 요약 명령으로 실제로 읽히는지 확인한다

자주 묻는 질문

Q. Claude Code는 AGENTS.md를 읽나요?A. v2.1.277부터 직접 읽습니다. 단 기본값에선 작업 디렉터리나 그 위에 CLAUDE.md류가 없을 때만 읽고, 둘 다 읽으려면 /config에서 Project instructions를 claude-md-and-agents-md로 바꿉니다.

Q. CLAUDE.md를 AGENTS.md 심링크로 만들어도 되나요?A. 공식 문서가 안내하는 방법입니다. 상대 경로(ln -s AGENTS.md CLAUDE.md)로 걸고, Windows 사용자가 있으면 @AGENTS.md 한 줄 import를 쓰세요.

Q. Windows에서 CLAUDE.md가 한 줄짜리 파일이 되는 이유는?A. core.symlinks가 false인 클론에선 git이 심링크를 링크 경로 문자열이 담긴 일반 파일로 체크아웃하기 때문입니다.

Q. Codex가 CLAUDE.md를 읽게 할 수 있나요?A. 기본은 아니고, ~/.codex/config.toml의 project_doc_fallback_filenames에 추가하면 됩니다.

Q. Cursor의 .cursorrules는 아직 쓰나요?A. 공식 도움말상 legacy이고 deprecated 예정입니다. .cursor/rules/*.mdc나 AGENTS.md로 옮기세요.

출처

도구 공식 문서·소스

• Claude Code, How Claude remembers your project(CLAUDE.md, AGENTS.md, .claude/rules, 심링크·Windows 주의): https://code.claude.com/docs/en/memory
• OpenAI Codex, Custom instructions with AGENTS.md: https://learn.chatgpt.com/docs/agent-configuration/agents-md
• openai/codex 소스 codex-rs/core/src/agents_md.rs(“Symlinks are allowed.”, untrusted 프로젝트 분기): https://github.com/openai/codex/blob/main/codex-rs/core/src/agents_md.rs
• openai/codex PR #29870(탐색 성능 PR, Symlinks 절): https://github.com/openai/codex/pull/29870
• Cursor, Rules: https://cursor.com/docs/rules
• Cursor 도움말, Rules(.cursorrules 이전): https://cursor.com/help/customization/rules
• AGENTS.md 공식 사이트: https://agents.md/
• Git, git-config core.symlinks: https://git-scm.com/docs/git-config

포럼(공식 문서 아님)

• Cursor Forum, Cursor no longer can follow symlinks to rules .mdc files: https://forum.cursor.com/t/cursor-no-longer-can-follow-symlinks-to-rules-mdc-files/146010
• Cursor Forum, Rules in a symlinked subfolder (.mdc) are not followed (again): https://forum.cursor.com/t/rules-in-a-symlinked-subfolder-mdc-are-not-followed-again/152918

dot-agents 관련

• dot-agents 사이트: https://www.dot-agents.com
• dot-agents 저장소: https://github.com/dot-agents/dot-agents
• getsentry/dotagents(이름이 비슷한 별개 프로젝트): https://github.com/getsentry/dotagents

관련 글

• SKILL.md 하나로 Codex·Claude·Antigravity·Grok에서 모두 쓸 수 있을까?: https://devlog.moonlang.com/2026/09/08/agent-skills-format-conversion/