AI 에이전트 시크릿 관리, rules에 키를 넣지 않는 법

AI 에이전트 시크릿 관리의 첫 규칙은 단순합니다. 규칙 파일에는 금지 문구만 두고, 실제 키·토큰·비밀번호는 두지 않습니다. .cursor/rules의 .mdc, 루트 AGENTS.md, 채팅에 붙여 넣는 “팀 규칙”은 버전 관리·공유·컨텍스트 주입 대상입니다. 여기에 리터럴 시크릿을 넣으면 레포·전사본·PR diff로 바로 새어 나갑니다.

이 글은 rules에 넣으면 안 되는 것 · 로컬 전용 값이 살 곳(.env·키체인·allowlist) · 유출 점검 체크리스트만 다룹니다. 실제 키 값·가격·플랜·개인 후기·발명된 UI 클릭 경로는 없습니다. 근거는 Cursor Rules, Ignore file, Cloud Agent Secrets & Network, Cloud Agent setup입니다.

rules에 넣으면 안 되는 것은?

한 줄 답: API 키·토큰·비밀번호·DB URL·개인 인증서·세션 쿠키 등 재사용 가능한 자격증명 리터럴과, 그 값을 재구성할 수 있는 조각입니다. rules에는 “무엇을 금지할지”만 적습니다.

프로젝트 Rules는 .cursor/rules의 .mdc로 커밋됩니다. alwaysApply든 globs든, 내용이 컨텍스트에 실리면 채팅·에이전트 도구 결과·커밋 메시지까지 따라갈 수 있습니다. 그래서 규칙 본문에 키를 넣는 순간 “보안 문서”가 아니라 유출 벡터가 됩니다.

넣지 말 것 (예시 이름만 — 값은 절대 예시로도 쓰지 않음)

종류왜 위험한가rules에 대신 적을 것
API 키·Bearer 토큰인덱스·PR·로그에 남음NEVER 리터럴 키. process.env / Secrets 이름만
DB·브로커 URL에 비밀번호 포함접속 문자열 한 줄이 전부호스트 역할만. 비밀번호는 env
.pem / 개인키 본문복구 불가능한 유출경로·권한 정책만 (chmod 600 등)
사내 웹훅·봇 토큰채팅에 그대로 재출력“이름만 언급, 값은 Cloud/로컬 Secrets”
고객 PII·실데이터 샘플규정·계약 위반합성 fixture·마스킹 규칙

넣어도 되는 것

  1. 금지 문장 — NEVER write secrets as literals; never commit .env*.
  2. 환경 변수 이름 — STRIPE_API_KEY처럼 이름만. 값 금지.
  3. 파일 위치 정책 — “시크릿은 .env.local / OS 키체인 / Cursor Secrets 탭”.
  4. 허용·거부 경로 — secrets/, *.pem은 커밋·@ 멘션 금지.
  5. 검증 습관 — 커밋 전 git diff에서 키 패턴 점검, pre-commit 훅 권장.
---
description: Secret hygiene (no literal credentials)
alwaysApply: true
---

# Secrets

- NEVER paste API keys, tokens, passwords, or private keys into rules, AGENTS.md, code, commits, or chat.
- Read credentials from environment variables or the OS/cloud secret store. Refer by **name** only.
- Do not commit `.env`, `.env.*`, `*.pem`, `credentials.json`, or `secrets/`.
- If a secret appears in a diff or tool output, stop, redact, rotate, and continue without the value.

위 블록은 정책입니다. 가짜 키 문자열을 “예시”로 넣지 않습니다. 모델이 비슷한 문자열을 생성·복사하는 습관을 키웁니다.

User Rules·Team Rules도 같습니다. 팀 규칙은 조직 전역 컨텍스트에 들어가므로, 개인 토큰을 넣으면 팀 전원 세션으로 확산됩니다.

로컬 전용 값은 어디에?

한 줄 답: 값은 로컬 .env(gitignore) · OS 키체인/시크릿 매니저 · Cloud Agent Secrets · (클라우드) 네트워크 allowlist에 두고, 레포에는 이름·로드 방법만 남깁니다. .cursorignore는 편의이지 보안 경계가 아닙니다.

로컬 Agent

위치역할주의
.env / .env.local앱·스크립트가 읽는 값.gitignore 필수. 기본 ignore에 .env*가 있어도 커밋 실수는 별개
OS 키체인·시크릿 매니저CLI/SDK가 런타임에 조회채팅에 export 결과를 붙여 넣지 않음
셸 환경 변수세션 한정 주입히스토리·스크린샷·에이전트 터미널 로그에 노출될 수 있음
.cursorignore인덱싱·Agent 파일 접근 완화문서: 터미널·MCP는 ignore를 우회할 수 있음. 완전한 차단 아님

Cursor는 .gitignore와 기본 목록(.env* 포함)을 인덱싱에서 제외합니다. 추가로 민감 경로가 있으면 .cursorignore에 패턴을 넣습니다. 다만 Ignore file 문서가 명시하듯, Agent의 터미널·MCP 도구는 같은 차단을 보장하지 않습니다. 진짜 차단은 파일 권한·시크릿 매니저·레포에 값을 두지 않기입니다.

에이전트에게 시킬 말:

  • “키 값은 읽지 말고, 변수 이름과 로드 경로만 확인해라.”
  • “.env.example에는 빈 자리·더미 설명만 두고 실값을 넣지 마라.”
  • “설정 파일에 리터럴을 쓰려 하면 멈추고 env 참조로 바꿔라.”

Cloud Agent

클라우드에서 돌릴 때는 로컬 디스크의 .env에 의존하지 말고, 대시보드 Secrets에 올립니다 (setup). 유형을 나눕니다 (Secrets & Network):

유형용도에이전트에게 보이는가
Environment Variable플래그·공개 URL 등 비민감 설정값 가시(여전히 암호화 저장)
Runtime SecretAPI 키 등 민감 자격증명도구 결과·전사·커밋에서 [REDACTED]
Build Secret이미지 빌드 단계만런타임 에이전트 env에 없음

민감 키는 Runtime Secret 쪽이 맞습니다. 그래도 사용자가 에이전트 환경 터미널에 직접 들어가면 보일 수 있으니, “채팅에 값을 찍어라”는 지시를 금지 규칙에 넣습니다. 시크릿을 추가·변경한 뒤에는 새 에이전트를 띄워야 주입됩니다.

장수명 클라우드 키 대신 OIDC 단기 토큰을 쓸 수 있으면 그쪽을 우선합니다. 아웃바운드가 걱정되면 Cloud Agent 네트워크 모드 + allowlist로 목적지 도메인을 제한합니다. allowlist에 와일드카드 S3를 넓히면 유출 경로가 되니, 문서가 경고하듯 필요한 호스트만 넣습니다.

레포에 남길 것 / 남기지 말 것

남길 것: .env.example(이름만), Secrets 이름 목록, “로컬은 키체인, CI는 OIDC” 한 단락, rules의 NEVER 문장.

남기지 말 것: 실값, 개인키, 프로덕션 접속 문자열, 채팅에서 복사한 export KEY=… 스크린샷.

유출 점검 체크리스트는?

한 줄 답: 커밋·PR·rules·채팅·클라우드 시크릿·ignore·회전(rotate) 순으로 확인합니다. 값이 보이면 즉시 폐기·재발급이 먼저입니다.

커밋·PR 전

  1. git status / git diff에 .env, *.pem, credentials.json, secrets/가 없는가.
  2. diff에 AKIA, Bearer , -----BEGIN, api_key= 형태가 실값으로 없는가 (예시는 만들지 않음).
  3. 커밋 메시지·PR 본문·스크린샷에 토큰이 없는가.
  4. pre-commit / secret scan 훅이 있다면 통과했는가.

rules·프롬프트

  1. .cursor/rules/**, AGENTS.md, User/Team Rules에 리터럴 시크릿이 없는가.
  2. “예시 키” 문자열을 넣어 두지 않았는가.
  3. 시크릿 이름과 금지 문장만 있는지.

로컬·ignore

  1. .env*가 .gitignore에 있는가. 이미 추적 중이면 git rm --cached 후 회전.
  2. 필요 시 .cursorignore에 민감 경로 추가. 터미널/MCP 우회를 전제로 운영.
  3. 에이전트에게 cat .env / “키 출력”을 시키지 않는가.

Cloud Agent

  1. 민감 값은 Secrets 탭의 Runtime Secret(또는 동등)인가. 스냅샷에 .env.local을 넣었다면 Secrets 탭으로 이전을 검토.
  2. 시크릿 변경 후 새 런을 시작했는가.
  3. 네트워크가 Allowlist 모드면 목적지가 최소 집합인가. 광역 *.s3… 같은 항목은 없는가.
  4. 채팅·PR에 [REDACTED]가 아닌 실값이 찍히지 않았는가.

유출이 보였을 때

  1. 회전(rotate) — 해당 키 폐기·재발급이 로그 삭제보다 우선.
  2. 공개/사내 gist·이슈·슬랙에 붙여 넣은 위치 목록화.
  3. rules/체크리스트에 “재발 방지 NEVER” 한 줄 보강 (값은 넣지 않음).

주간 점검으로 위의 1–7만 돌려도 rules 경유 유출의 대부분을 막습니다. 클라우드를 쓰면 11–14를 같이 봅니다.

마무리

규칙 파일 = 정책, 시크릿 저장소 = 값. .mdc/AGENTS.md에는 NEVER와 변수 이름만 두고, 값은 .env·키체인·Cloud Secrets(가능하면 Runtime Secret)·allowlist 쪽에 둡니다. .cursorignore는 인덱싱 보조일 뿐 보안 경계가 아니며, 유출이 보이면 회전이 먼저입니다. Skills vs Rules 선택·권한 모드는 다른 글에 두고, 이 글은 키를 rules에 넣지 않는 축만 다룹니다.

출처