지시 파일(Instruction files)

지시 파일(Instruction files)

지시 파일은 각 대화 시작 시 자동으로 포함되는 지속적인 컨텍스트와 지침을 제공해요. 프로젝트의 규칙, 선호 도구, 코딩 스타일 또는 에이전트가 항상 염두에 두어야 할 모든 것에 대해 알려주는 데 사용하세요.

출처: Instruction files

본문

지원되는 파일 이름

CoCo Desktop은 이름으로 지시 파일을 자동으로 발견해요. 다음 파일 이름이 인식됩니다.

파일 이름 설명
AGENTS.md 프로젝트의 기본 지시 파일
CLAUDE.md Claude 호환 지시 파일
CORTEX.md Cortex 전용 지시 파일
SNOWFLAKE.md Snowflake 전용 지시 파일
RULES.md 일반 규칙 파일
.cursorrules Cursor 호환 규칙 파일
.cursor/rules/*.mdc Cursor MDC 규칙 파일
.claude/rules/*.md Claude 규칙 파일

파일 이름은 대소문자를 구분하지 않고 매치돼요. chat.instructionFilePatterns 설정으로 발견할 패턴을 사용자 정의할 수 있어요.

파일 위치

Workspace 범위(프로젝트 수준)

Workspace 범위 지시 파일은 프로젝트에 있으며 소스 제어를 통해 팀과 공유돼요. 다음 위치에서 검색됩니다.

  • Workspace 루트 — 예: /my-project/AGENTS.md
  • workspace 루트에서 git 루트까지의 모든 디렉터리 — workspace가 하위 디렉터리인 모노레포 지원
  • .cursor/rules/*.mdc — git 루트 기준
  • .claude/rules/*.md — git 루트 기준

팁: 모노레포에서 공유 규칙을 담은 루트 수준 AGENTS.md와 패키지별 지침을 담은 패키지별 AGENTS.md를 두세요. 패키지를 workspace로 열면 둘 다 자동으로 발견돼요.

User 범위(전역)

User 범위 지시 파일은 모든 프로젝트에 적용돼요. 다음에서 검색됩니다.

  • ~/.snowflake/cortex/ — 사용자 지시 파일의 기본 위치
  • ~/ — 홈 디렉터리(예: ~/CLAUDE.md)
  • ~/.claude/ — Claude 호환 위치

User 수준 .mdc 파일은 ~/.cursor/rules/에, User 수준 .md 규칙 파일은 ~/.claude/rules/에 둡니다.

팁: Agent Settings의 Personalization 페이지에 있는 Custom instructions 편집기는 user 범위 ~/.snowflake/cortex/AGENTS.md 파일을 읽고 씁니다. 따라서 파일을 직접 열지 않고 앱에서 전역 지침을 편집할 수 있어요. 어느 쪽에서든 변경한 내용은 동기화된 상태로 유지됩니다.

파일 형식

Markdown(.md)

일반 마크다운. 어떤 형식으로든 지침을 작성하세요. 전체 콘텐츠가 에이전트의 컨텍스트로 포함됩니다.

# Project conventions

- Use TypeScript strict mode
- All functions must have JSDoc comments
- Run `npm run lint` before committing
- Tests go in `__tests__/` directories next to the source

# Architecture

This is a Next.js app with:

- `/src/app` — App router pages
- `/src/lib` — Shared utilities
- `/src/components` — React components

MDC 파일(.mdc)

MDC 파일은 주입 전에 제거되는 선택적 YAML 프론트매터 헤더를 지원해요. 본문은 일반 마크다운입니다.

---
description: Git workflow conventions
globs: ["*.ts", "*.tsx"]
---

# Git workflow

- Use conventional commits (feat:, fix:, chore:)
- Squash merge to main
- Always run tests before pushing

applyTo가 있는 지시 파일(.instructions.md)

.instructions.md로 끝나는 파일(.github/instructions/에 배치)은 applyTo glob 패턴이 있는 YAML 헤더를 지원해요. 패턴과 일치하는 파일이 대화 컨텍스트에 있을 때만 지침이 자동으로 붙습니다.

---
applyTo: "**/*.test.ts"
description: Testing conventions
---

Use Jest with React Testing Library. Prefer userEvent over fireEvent.
Always test accessibility with getByRole.

지시 파일 적용 방식

지시 파일 콘텐츠는 각 대화 시작 시 자동으로 포함됩니다. 세션의 첫 메시지에 컨텍스트로 주입되며 수동으로 참조할 필요가 없어요.

  • 발견된 모든 지시 파일이 연결되어 컨텍스트로 포함됩니다.
  • Workspace 파일이 user 파일보다 먼저 포함됩니다.
  • 서로 다른 범위에 같은 이름의 파일이 두 개 있으면 workspace 버전이 우선합니다.
  • 결합된 총 크기는 약 100,000자로 제한됩니다. 이 한도를 초과하는 파일은 건너뜁니다.

우선 순위

여러 소스의 파일을 발견하면 다음 순서로 병합됩니다.

  • Workspace 지시 파일 — 프로젝트별, 최우선순위
  • User 수준 지시 파일 — 전역 개인 규칙
  • Profile 지시 파일 — 활성 프로필(있는 경우)

파일은 경로별로 중복 제거됩니다. workspace 파일과 user 파일의 이름이 같으면 workspace 버전이 사용되고 user 버전은 건너뜁니다.

지시 파일 보기

Agent Settings를 열고 사이드바에서 Rules를 선택한 다음 Instruction Files 탭을 클릭하세요. 이 패널은 범위(Workspace 또는 User)와 함께 발견된 모든 지시 파일을 표시해요. 어떤 파일이든 클릭해 편집기에서 열 수 있어요.

모범 사례

  • 지침을 집중해서 유지하세요. 코딩 스타일, 프로젝트 구조, 핵심 명령처럼 에이전트가 모든 대화에서 필요로 하는 정보만 포함하세요.
  • 팀 규칙에는 workspace 범위를 사용하세요. 프로젝트 수준 규칙을 프로젝트 루트의 AGENTS.md에 두고 소스 제어에 커밋하세요.
  • 개인 선호에는 user 범위를 사용하세요. 개인 스타일 선호나 전역 도구 지침을 ~/.snowflake/cortex/에 두세요.
  • 크기 한도 아래로 유지하세요. 결합된 지침 콘텐츠는 약 100k자로 제한됩니다. 파일을 간결하게 유지해 대화 컨텍스트 여지를 남기세요.
  • 조건부 규칙에는 MDC 또는 .instructions.md를 사용하세요. 특정 파일 유형에만 적용되는 규칙은 glob 기반 범위 지정이 유용해 관련 없는 대화를 어지럽히지 않아요.

더 알아보기