{"content_id":"9bufu7fxqw","slug":"claude-code-rules-skills-agents-guide","locale":"ko","schema_type":"HowTo","category":"tutorial","category_name":"튜토리얼","title":"Claude Code Rules·Skills·Agents 실전 가이드","summary":"Claude Code의 Rules, Skills, Agents는 각각 지속 지침, 재사용 절차, 격리된 작업 위임을 담당합니다. 정확한 파일 구조와 호출 방식, 보안 및 컨텍스트 관리 원칙을 실전 예제로 설명합니다.","sponsorship_disclosure":null,"author":{"name":"인조이스 편집팀","url":"https://injoys.com/ko/about"},"key_points":["프로젝트 루트에 `.claude` 디렉터리를 만들고 공유 설정과 개인 설정의 범위를 구분합니다.","항상 지킬 기준은 `.claude/rules`의 Markdown 파일로 분리하고 필요하면 적용 경로를 제한합니다.","반복 절차는 `.claude/skills/\u003c이름\u003e/SKILL.md`에 작성하고 자동 또는 명시적 호출 방식을 설정합니다.","독립된 컨텍스트와 역할이 필요한 작업은 `.claude/agents/\u003c이름\u003e.md` 서브에이전트로 위임합니다.","작은 검증 작업으로 로딩, 도구 권한, 결과 품질을 확인한 뒤 팀 저장소에 반영합니다."],"content_markdown":"Claude Code의 확장 기능은 모두 같은 종류의 프롬프트가 아니다. **Rules는 지속적으로 적용할 지침**, **Skills는 반복해서 재사용할 작업 절차**, **Agents는 별도 컨텍스트에서 일하는 역할별 실행자**다. 세 기능을 정확히 구분하면 프롬프트 반복을 줄이면서도 메인 대화의 컨텍스트를 효율적으로 관리할 수 있다.\n\n이 문서는 프로젝트 단위 설정을 기준으로 설명한다. Claude Code 버전에 따라 지원되는 메타데이터나 화면이 달라질 수 있으므로, 동작하지 않는 필드는 설치된 버전의 공식 문서에서 다시 확인해야 한다.\n\n## 1단계: `.claude` 디렉터리와 설정 범위 정하기\n\n프로젝트에서 공유할 Rules, Skills, Agents는 일반적으로 저장소 루트의 `.claude` 아래에 둔다.\n\n```text\nmy-project/\n├── .claude/\n│   ├── rules/\n│   │   ├── code-style.md\n│   │   └── api.md\n│   ├── skills/\n│   │   └── fix-issue/\n│   │       └── SKILL.md\n│   └── agents/\n│       ├── code-reviewer.md\n│       └── test-runner.md\n├── src/\n└── package.json\n```\n\n디렉터리는 다음과 같이 만들 수 있다.\n\n```bash\nmkdir -p .claude/rules\nmkdir -p .claude/skills/fix-issue\nmkdir -p .claude/agents\n```\n\n### `.claude`에 관한 두 가지 오해\n\n1. `.claude`가 Claude Code의 모든 지침에 반드시 필요한 것은 아니다. 프로젝트 지침은 루트의 `CLAUDE.md` 또는 `.claude/CLAUDE.md`로도 관리할 수 있고, 사용자 개인 설정은 홈 디렉터리의 `~/.claude` 아래에 둘 수 있다.\n2. 파일명은 운영체제에 따라 대소문자가 구분된다. Skill 진입 파일은 공식 형식에 맞춰 대문자 `SKILL.md`로 작성하는 것이 안전하다. `skill.md`로 저장하면 인식되지 않을 수 있다.\n\n### 프로젝트 설정과 개인 설정의 선택 기준\n\n| 범위 | 적합한 내용 | 예시 |\n|---|---|---|\n| 프로젝트 공유 | 모든 기여자가 동일하게 따라야 하는 규칙과 자동화 | 테스트 명령, 디렉터리 구조, API 규약 |\n| 사용자 개인 | 개인 취향이나 저장소에 공개하면 안 되는 설정 | 개인 작업 방식, 로컬 도구 선택 |\n| 로컬 전용 | 특정 컴퓨터에서만 유효한 경로나 실험 설정 | 로컬 데이터 경로, 임시 디버깅 절차 |\n\n팀에서 함께 사용할 파일만 Git에 커밋한다. 비밀 키, 토큰, 내부 서버 비밀번호는 Rules나 Skills에 기록하지 않는다.\n\n## 2단계: Rules로 지속 지침 만들기\n\nRules는 Claude가 작업할 때 참고해야 하는 프로젝트 지침을 여러 Markdown 파일로 나누어 관리하는 기능이다. `.claude/rules` 아래에 있는 규칙 가운데 `paths` 조건이 없는 파일은 프로젝트 지침으로 로드되며, 경로 조건을 지정한 파일은 관련 파일을 다룰 때 적용된다.\n\n### 기본 Rule 예제\n\n`.claude/rules/code-style.md`를 다음처럼 작성할 수 있다.\n\n```markdown\n# 코드 작성 원칙\n\n- 새 애플리케이션 코드는 TypeScript로 작성한다.\n- 공개 함수에는 입력값, 반환값, 실패 조건을 설명한다.\n- 기존 테스트를 삭제해서 실패를 숨기지 않는다.\n- 변경 후 관련 테스트와 타입 검사를 실행한다.\n- 설명은 한국어로 작성하되 코드 식별자는 기존 명명 규칙을 따른다.\n```\n\n좋은 Rule은 검증할 수 있다. “코드를 멋지게 작성한다”보다 “변경 후 `npm test`와 `npm run typecheck`를 실행한다”가 명확하다.\n\n### 특정 경로에만 적용하는 Rule\n\n프런트엔드와 백엔드의 규칙이 다르면 YAML front matter의 `paths`로 범위를 좁힐 수 있다.\n\n```markdown\n---\npaths:\n  - \"src/api/**/*.ts\"\n  - \"tests/api/**/*.ts\"\n---\n\n# API 규칙\n\n- 모든 API 입력은 스키마로 검증한다.\n- 인증 실패와 권한 부족을 서로 다른 오류로 처리한다.\n- 엔드포인트를 변경하면 대응하는 API 테스트도 갱신한다.\n```\n\n경로별 규칙은 불필요한 지침이 모든 작업의 컨텍스트를 차지하는 문제를 줄여준다.\n\n### Rules에 넣지 말아야 할 내용\n\n- 한 번만 수행할 마이그레이션 절차\n- 특정 이슈에만 필요한 상세 요구사항\n- 서로 충돌하는 절대 지시\n- 이미 코드나 린터 설정으로 강제되는 내용을 길게 반복한 문장\n- 비밀번호, API 키, 고객 정보 등 민감한 데이터\n\nRules는 “무조건 따르는 마법의 보장 장치”가 아니다. 모호하거나 상충하는 지침이 있으면 결과가 달라질 수 있으므로 테스트, 린터, 권한 통제 같은 결정적 검증 수단을 함께 사용해야 한다.\n\n## 3단계: Skills로 반복 절차 자동화하기\n\nSkill은 설명, 작업 절차, 필요 도구, 보조 자료를 하나의 재사용 가능한 단위로 묶는다. 프로젝트 Skill의 기본 구조는 `.claude/skills/\u003cskill-name\u003e/SKILL.md`이며, 필요하면 같은 디렉터리에 템플릿이나 스크립트를 추가할 수 있다.\n\nRules와 달리 Skill은 특정 작업에 필요할 때 사용된다. Claude가 Skill의 설명을 보고 자동으로 선택할 수도 있고, 사용자가 `/\u003cskill-name\u003e` 형식으로 명시적으로 호출할 수도 있다. 반드시 수동으로만 작동하는 것은 아니다.\n\n### 이슈 수정 Skill 예제\n\n`.claude/skills/fix-issue/SKILL.md` 예시는 다음과 같다.\n\n```markdown\n---\nname: fix-issue\ndescription: 버그를 재현하고 원인을 좁힌 뒤 최소 수정과 회귀 테스트를 수행한다.\ndisable-model-invocation: true\nallowed-tools: Read, Grep, Glob, Edit, Bash(npm test:*)\n---\n\n# 이슈 수정 절차\n\n대상 이슈: $ARGUMENTS\n\n1. 관련 코드와 기존 테스트를 조사한다.\n2. 수정 전에 재현 방법과 예상 동작을 정리한다.\n3. 근본 원인을 한 문단으로 설명한다.\n4. 영향 범위가 가장 작은 수정을 적용한다.\n5. 회귀 테스트를 추가하거나 기존 테스트가 문제를 검증하는지 확인한다.\n6. 허용된 테스트를 실행하고 결과를 요약한다.\n7. 변경 파일, 남은 위험, 수동 확인 항목을 보고한다.\n```\n\n이 Skill은 다음처럼 호출할 수 있다.\n\n```text\n/fix-issue 로그인 후 프로필 사진이 갱신되지 않는 문제\n```\n\n`disable-model-invocation: true`는 Claude가 임의로 이 Skill을 실행하지 않고 사용자가 직접 호출하도록 제한할 때 유용하다. 지원되는 front matter 필드는 Claude Code 버전에 따라 달라질 수 있다.\n\n### 설계 우선 Skill 예제\n\n바로 코딩하는 대신 설계 문서를 먼저 만들게 하려면 다음 흐름을 Skill에 넣을 수 있다.\n\n1. 요구사항과 모호한 부분을 분리한다.\n2. 기존 구조와 재사용 가능한 모듈을 조사한다.\n3. 데이터 흐름, 인터페이스, 실패 조건을 설계한다.\n4. `docs/design/` 아래에 설계 문서를 작성한다.\n5. 사용자의 승인 또는 명시된 승인 조건을 확인한 후 구현한다.\n6. 테스트와 롤백 방법을 제시한다.\n\n### 좋은 Skill의 조건\n\n- 입력과 최종 산출물이 분명하다.\n- 절차의 순서와 중단 조건이 명시돼 있다.\n- 필요한 도구만 허용한다.\n- 긴 참고 자료는 별도 파일로 분리한다.\n- 실패했을 때 임의로 계속 진행하지 않고 보고하도록 한다.\n- 한 Skill이 지나치게 많은 목적을 갖지 않는다.\n\n커밋 작성, 코드 리뷰, 릴리스 점검, API 설계처럼 반복되면서 시작과 끝이 분명한 작업이 Skill에 적합하다.\n\n## 4단계: Agents로 역할과 컨텍스트 분리하기\n\nClaude Code의 서브에이전트는 별도의 컨텍스트에서 특정 역할을 수행하고 결과를 메인 대화로 돌려준다. 메인 컨텍스트에 대량의 검색 결과나 테스트 로그를 모두 누적하고 싶지 않을 때 유용하다.\n\n프로젝트 에이전트는 일반적으로 `.claude/agents/\u003cagent-name\u003e.md`에 정의한다. `/agents` 명령을 통해 에이전트를 확인하거나 관리할 수 있으며, 자연어로 특정 에이전트에게 위임하도록 요청할 수도 있다.\n\n### 코드 리뷰 에이전트 예제\n\n`.claude/agents/code-reviewer.md`를 다음과 같이 작성할 수 있다.\n\n```markdown\n---\nname: code-reviewer\ndescription: 변경된 코드에서 결함, 보안 위험, 테스트 누락을 검토하는 읽기 중심 리뷰어\ntools: Read, Grep, Glob, Bash\nmodel: sonnet\n---\n\n당신은 코드 리뷰 전담 에이전트다.\n\n다음 우선순위로 검토한다.\n\n1. 실제 장애나 데이터 손실을 일으킬 수 있는 결함\n2. 인증, 권한, 입력 검증과 관련된 보안 문제\n3. 동시성, 트랜잭션, 오류 처리 문제\n4. 요구사항을 검증하지 못하는 테스트 누락\n5. 유지보수성을 크게 떨어뜨리는 구조\n\n각 발견 사항에는 파일 경로, 근거, 발생 조건, 최소 수정 방향을 포함한다.\n근거 없는 스타일 취향은 결함으로 보고하지 않는다.\n코드를 직접 수정하지 말고 리뷰 결과만 반환한다.\n```\n\n다음과 같이 요청할 수 있다.\n\n```text\ncode-reviewer 에이전트에게 현재 브랜치의 변경 사항을 검토하게 해줘.\n```\n\n### Skill과 Agent의 차이\n\n| 기준 | Rules | Skills | Agents |\n|---|---|---|---|\n| 핵심 목적 | 지속 지침 제공 | 반복 절차 재사용 | 역할별 작업 위임 |\n| 적용 시점 | 항상 또는 경로 조건에 따라 | 자동 선택 또는 명시적 호출 | Claude의 위임 또는 사용자 요청 |\n| 컨텍스트 | 메인 작업에 지침으로 포함 | 주로 현재 작업 흐름에서 실행 | 별도 컨텍스트에서 수행 후 결과 반환 |\n| 대표 예 | 코딩 표준 | 이슈 수정 절차 | 코드 리뷰어 |\n| 저장 위치 | `.claude/rules/*.md` | `.claude/skills/\u003c이름\u003e/SKILL.md` | `.claude/agents/*.md` |\n\n### Agents와 Agent Teams는 다르다\n\n일반 서브에이전트가 별도 컨텍스트를 쓴다는 사실이 곧 에이전트끼리 자유롭게 대화한다는 뜻은 아니다. 일반적인 서브에이전트는 맡은 일을 수행하고 결과를 메인 에이전트에 반환하는 위임 구조다. 여러 독립 세션이 서로 메시지를 주고받는 Agent Teams 기능은 별도의 기능이며, 지원 상태와 활성화 조건을 공식 문서에서 확인해야 한다.\n\n에이전트가 다른 에이전트를 연쇄적으로 계속 생성한다고 전제해 워크플로를 설계하면 버전이나 권한 제약 때문에 실패할 수 있다. 먼저 메인 에이전트가 역할별 서브에이전트에 일을 나누고 결과를 종합하는 단순한 구조로 시작하는 편이 안전하다.\n\n## 5단계: 로딩·권한·품질 검증하기\n\n설정 파일을 만들었다고 해서 의도대로 작동한다고 가정하면 안 된다. 작은 작업으로 각 구성요소를 따로 검증한다.\n\n### 권장 검증 순서\n\n1. **Rules 확인:** 규칙이 적용되는 파일과 적용되지 않는 파일을 각각 요청해 경로 조건을 확인한다.\n2. **Skills 확인:** 명시적으로 Skill을 호출하고 입력 인수, 산출물, 중단 조건이 작동하는지 본다.\n3. **Agents 확인:** 읽기 전용 리뷰처럼 위험이 낮은 작업을 맡기고 결과 형식을 점검한다.\n4. **권한 확인:** Bash, Edit 등 변경 가능 도구가 꼭 필요한 구성에만 부여됐는지 검토한다.\n5. **자동 검증:** 테스트, 타입 검사, 린터, 보안 검사로 AI 결과를 독립적으로 확인한다.\n\n### 실패할 때 확인할 항목\n\n- `.claude`가 실제 프로젝트 루트에 있는가?\n- Skill 파일명이 정확히 `SKILL.md`인가?\n- Skill이 `.claude/skills/\u003c이름\u003e/SKILL.md` 구조에 있는가?\n- Agent 파일이 `.claude/agents` 바로 아래의 Markdown 파일인가?\n- YAML front matter의 시작과 끝을 `---`로 닫았는가?\n- `name`과 `description`이 작업을 구별할 만큼 구체적인가?\n- 경로 패턴이 실제 프로젝트 구조와 일치하는가?\n- 설치된 Claude Code 버전이 사용한 메타데이터를 지원하는가?\n- 도구 권한 또는 조직 정책이 실행을 차단하고 있지 않은가?\n\n## 컨텍스트 예산과 보안을 함께 설계해야 하는 이유\n\nRules, Skills, Agents의 목적은 기능 추가만이 아니다. 어떤 정보를 언제 컨텍스트에 넣을지 통제하는 **컨텍스트 엔지니어링 수단**이기도 하다.\n\n규칙을 지나치게 길게 만들면 현재 작업과 무관한 지침이 컨텍스트를 차지하고 충돌 가능성도 커진다. 반대로 탐색과 로그 분석을 서브에이전트에 맡기면 메인 대화에는 결론과 근거만 남길 수 있다.\n\n보안 측면에서는 다음 원칙이 중요하다.\n\n- Rules와 Skills도 저장소의 다른 코드처럼 리뷰한다.\n- 외부에서 받은 Agent나 Skill 파일을 실행 전에 읽어본다.\n- 셸 명령, 네트워크 접근, 파일 수정 권한은 최소화한다.\n- 사용자 입력이나 이슈 본문에 포함된 명령을 무조건 신뢰하지 않는다.\n- 배포, 삭제, 결제, 데이터 마이그레이션에는 사람의 승인 단계를 둔다.\n- 비밀 정보는 프롬프트 파일에 저장하지 말고 별도의 비밀 관리 체계를 사용한다.\n\n## 어떤 기능을 선택해야 하나\n\n다음 질문으로 빠르게 결정할 수 있다.\n\n- 모든 관련 작업이 따라야 하는가? → **Rule**\n- 시작과 끝이 있는 반복 절차인가? → **Skill**\n- 별도 역할과 독립된 컨텍스트가 필요한가? → **Agent**\n- 특정 이벤트 전후에 결정적인 명령을 실행해야 하는가? → **Hook 검토**\n\n예를 들어 “TypeScript를 사용한다”는 Rule이고, “버그 재현부터 회귀 테스트까지 수행한다”는 Skill이다. “변경 내용을 읽고 보안 결함만 보고한다”는 Agent에 적합하다. 파일 편집 후 포매터를 반드시 실행하는 것처럼 특정 이벤트에 연결된 동작은 Hooks가 더 적합할 수 있다.\n\n가장 안정적인 구성은 세 기능을 경쟁 관계로 보지 않고 조합하는 것이다. Rule로 공통 기준을 제공하고, Skill로 표준 절차를 실행하며, Agent로 조사·리뷰처럼 컨텍스트가 큰 작업을 분리한 뒤 테스트와 Hooks로 결정적 검증을 보완한다.","content_html":"\u003cp\u003eClaude Code의 확장 기능은 모두 같은 종류의 프롬프트가 아니다. \u003cstrong\u003eRules는 지속적으로 적용할 지침\u003c/strong\u003e, \u003cstrong\u003eSkills는 반복해서 재사용할 작업 절차\u003c/strong\u003e, \u003cstrong\u003eAgents는 별도 컨텍스트에서 일하는 역할별 실행자\u003c/strong\u003e다. 세 기능을 정확히 구분하면 프롬프트 반복을 줄이면서도 메인 대화의 컨텍스트를 효율적으로 관리할 수 있다.\u003c/p\u003e\n\u003cp\u003e이 문서는 프로젝트 단위 설정을 기준으로 설명한다. Claude Code 버전에 따라 지원되는 메타데이터나 화면이 달라질 수 있으므로, 동작하지 않는 필드는 설치된 버전의 공식 문서에서 다시 확인해야 한다.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#1%EB%8B%A8%EA%B3%84-claude-%EB%94%94%EB%A0%89%ED%84%B0%EB%A6%AC%EC%99%80-%EC%84%A4%EC%A0%95-%EB%B2%94%EC%9C%84-%EC%A0%95%ED%95%98%EA%B8%B0\" class=\"anchor\" id=\"1단계-claude-디렉터리와-설정-범위-정하기\"\u003e\u003c/a\u003e1단계: \u003ccode\u003e.claude\u003c/code\u003e 디렉터리와 설정 범위 정하기\u003c/h2\u003e\n\u003cp\u003e프로젝트에서 공유할 Rules, Skills, Agents는 일반적으로 저장소 루트의 \u003ccode\u003e.claude\u003c/code\u003e 아래에 둔다.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003emy-project/\n\u003c/span\u003e\u003cspan\u003e├── .claude/\n\u003c/span\u003e\u003cspan\u003e│   ├── rules/\n\u003c/span\u003e\u003cspan\u003e│   │   ├── code-style.md\n\u003c/span\u003e\u003cspan\u003e│   │   └── api.md\n\u003c/span\u003e\u003cspan\u003e│   ├── skills/\n\u003c/span\u003e\u003cspan\u003e│   │   └── fix-issue/\n\u003c/span\u003e\u003cspan\u003e│   │       └── SKILL.md\n\u003c/span\u003e\u003cspan\u003e│   └── agents/\n\u003c/span\u003e\u003cspan\u003e│       ├── code-reviewer.md\n\u003c/span\u003e\u003cspan\u003e│       └── test-runner.md\n\u003c/span\u003e\u003cspan\u003e├── src/\n\u003c/span\u003e\u003cspan\u003e└── package.json\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e디렉터리는 다음과 같이 만들 수 있다.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003emkdir\u003c/span\u003e\u003cspan\u003e -p\u003c/span\u003e\u003cspan\u003e .claude/rules\n\u003c/span\u003e\u003cspan\u003emkdir\u003c/span\u003e\u003cspan\u003e -p\u003c/span\u003e\u003cspan\u003e .claude/skills/fix-issue\n\u003c/span\u003e\u003cspan\u003emkdir\u003c/span\u003e\u003cspan\u003e -p\u003c/span\u003e\u003cspan\u003e .claude/agents\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#claude%EC%97%90-%EA%B4%80%ED%95%9C-%EB%91%90-%EA%B0%80%EC%A7%80-%EC%98%A4%ED%95%B4\" class=\"anchor\" id=\"claude에-관한-두-가지-오해\"\u003e\u003c/a\u003e\u003ccode\u003e.claude\u003c/code\u003e에 관한 두 가지 오해\u003c/h3\u003e\n\u003col\u003e\n\u003cli\u003e\n\u003ccode\u003e.claude\u003c/code\u003e가 Claude Code의 모든 지침에 반드시 필요한 것은 아니다. 프로젝트 지침은 루트의 \u003ccode\u003eCLAUDE.md\u003c/code\u003e 또는 \u003ccode\u003e.claude/CLAUDE.md\u003c/code\u003e로도 관리할 수 있고, 사용자 개인 설정은 홈 디렉터리의 \u003ccode\u003e~/.claude\u003c/code\u003e 아래에 둘 수 있다.\u003c/li\u003e\n\u003cli\u003e파일명은 운영체제에 따라 대소문자가 구분된다. Skill 진입 파일은 공식 형식에 맞춰 대문자 \u003ccode\u003eSKILL.md\u003c/code\u003e로 작성하는 것이 안전하다. \u003ccode\u003eskill.md\u003c/code\u003e로 저장하면 인식되지 않을 수 있다.\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch3\u003e\n\u003ca href=\"#%ED%94%84%EB%A1%9C%EC%A0%9D%ED%8A%B8-%EC%84%A4%EC%A0%95%EA%B3%BC-%EA%B0%9C%EC%9D%B8-%EC%84%A4%EC%A0%95%EC%9D%98-%EC%84%A0%ED%83%9D-%EA%B8%B0%EC%A4%80\" class=\"anchor\" id=\"프로젝트-설정과-개인-설정의-선택-기준\"\u003e\u003c/a\u003e프로젝트 설정과 개인 설정의 선택 기준\u003c/h3\u003e\n\u003cdiv class=\"overflow-x-auto\"\u003e\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003e범위\u003c/th\u003e\n\u003cth\u003e적합한 내용\u003c/th\u003e\n\u003cth\u003e예시\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"범위\"\u003e프로젝트 공유\u003c/td\u003e\n\u003ctd data-label=\"적합한 내용\"\u003e모든 기여자가 동일하게 따라야 하는 규칙과 자동화\u003c/td\u003e\n\u003ctd data-label=\"예시\"\u003e테스트 명령, 디렉터리 구조, API 규약\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"범위\"\u003e사용자 개인\u003c/td\u003e\n\u003ctd data-label=\"적합한 내용\"\u003e개인 취향이나 저장소에 공개하면 안 되는 설정\u003c/td\u003e\n\u003ctd data-label=\"예시\"\u003e개인 작업 방식, 로컬 도구 선택\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"범위\"\u003e로컬 전용\u003c/td\u003e\n\u003ctd data-label=\"적합한 내용\"\u003e특정 컴퓨터에서만 유효한 경로나 실험 설정\u003c/td\u003e\n\u003ctd data-label=\"예시\"\u003e로컬 데이터 경로, 임시 디버깅 절차\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\u003c/div\u003e\n\u003cp\u003e팀에서 함께 사용할 파일만 Git에 커밋한다. 비밀 키, 토큰, 내부 서버 비밀번호는 Rules나 Skills에 기록하지 않는다.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#2%EB%8B%A8%EA%B3%84-rules%EB%A1%9C-%EC%A7%80%EC%86%8D-%EC%A7%80%EC%B9%A8-%EB%A7%8C%EB%93%A4%EA%B8%B0\" class=\"anchor\" id=\"2단계-rules로-지속-지침-만들기\"\u003e\u003c/a\u003e2단계: Rules로 지속 지침 만들기\u003c/h2\u003e\n\u003cp\u003eRules는 Claude가 작업할 때 참고해야 하는 프로젝트 지침을 여러 Markdown 파일로 나누어 관리하는 기능이다. \u003ccode\u003e.claude/rules\u003c/code\u003e 아래에 있는 규칙 가운데 \u003ccode\u003epaths\u003c/code\u003e 조건이 없는 파일은 프로젝트 지침으로 로드되며, 경로 조건을 지정한 파일은 관련 파일을 다룰 때 적용된다.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EA%B8%B0%EB%B3%B8-rule-%EC%98%88%EC%A0%9C\" class=\"anchor\" id=\"기본-rule-예제\"\u003e\u003c/a\u003e기본 Rule 예제\u003c/h3\u003e\n\u003cp\u003e\u003ccode\u003e.claude/rules/code-style.md\u003c/code\u003e를 다음처럼 작성할 수 있다.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e# 코드 작성 원칙\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e- 새 애플리케이션 코드는 TypeScript로 작성한다.\n\u003c/span\u003e\u003cspan\u003e- 공개 함수에는 입력값, 반환값, 실패 조건을 설명한다.\n\u003c/span\u003e\u003cspan\u003e- 기존 테스트를 삭제해서 실패를 숨기지 않는다.\n\u003c/span\u003e\u003cspan\u003e- 변경 후 관련 테스트와 타입 검사를 실행한다.\n\u003c/span\u003e\u003cspan\u003e- 설명은 한국어로 작성하되 코드 식별자는 기존 명명 규칙을 따른다.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e좋은 Rule은 검증할 수 있다. “코드를 멋지게 작성한다”보다 “변경 후 \u003ccode\u003enpm test\u003c/code\u003e와 \u003ccode\u003enpm run typecheck\u003c/code\u003e를 실행한다”가 명확하다.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#%ED%8A%B9%EC%A0%95-%EA%B2%BD%EB%A1%9C%EC%97%90%EB%A7%8C-%EC%A0%81%EC%9A%A9%ED%95%98%EB%8A%94-rule\" class=\"anchor\" id=\"특정-경로에만-적용하는-rule\"\u003e\u003c/a\u003e특정 경로에만 적용하는 Rule\u003c/h3\u003e\n\u003cp\u003e프런트엔드와 백엔드의 규칙이 다르면 YAML front matter의 \u003ccode\u003epaths\u003c/code\u003e로 범위를 좁힐 수 있다.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003cspan\u003epaths:\n\u003c/span\u003e\u003cspan\u003e  - \"src/api/\u003c/span\u003e\u003cspan\u003e**/\u003c/span\u003e\u003cspan\u003e*.ts\"\n\u003c/span\u003e\u003cspan\u003e  - \"tests/api/\u003c/span\u003e\u003cspan\u003e**/\u003c/span\u003e\u003cspan\u003e*.ts\"\n\u003c/span\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e# API 규칙\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e- 모든 API 입력은 스키마로 검증한다.\n\u003c/span\u003e\u003cspan\u003e- 인증 실패와 권한 부족을 서로 다른 오류로 처리한다.\n\u003c/span\u003e\u003cspan\u003e- 엔드포인트를 변경하면 대응하는 API 테스트도 갱신한다.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e경로별 규칙은 불필요한 지침이 모든 작업의 컨텍스트를 차지하는 문제를 줄여준다.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#rules%EC%97%90-%EB%84%A3%EC%A7%80-%EB%A7%90%EC%95%84%EC%95%BC-%ED%95%A0-%EB%82%B4%EC%9A%A9\" class=\"anchor\" id=\"rules에-넣지-말아야-할-내용\"\u003e\u003c/a\u003eRules에 넣지 말아야 할 내용\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e한 번만 수행할 마이그레이션 절차\u003c/li\u003e\n\u003cli\u003e특정 이슈에만 필요한 상세 요구사항\u003c/li\u003e\n\u003cli\u003e서로 충돌하는 절대 지시\u003c/li\u003e\n\u003cli\u003e이미 코드나 린터 설정으로 강제되는 내용을 길게 반복한 문장\u003c/li\u003e\n\u003cli\u003e비밀번호, API 키, 고객 정보 등 민감한 데이터\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003eRules는 “무조건 따르는 마법의 보장 장치”가 아니다. 모호하거나 상충하는 지침이 있으면 결과가 달라질 수 있으므로 테스트, 린터, 권한 통제 같은 결정적 검증 수단을 함께 사용해야 한다.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#3%EB%8B%A8%EA%B3%84-skills%EB%A1%9C-%EB%B0%98%EB%B3%B5-%EC%A0%88%EC%B0%A8-%EC%9E%90%EB%8F%99%ED%99%94%ED%95%98%EA%B8%B0\" class=\"anchor\" id=\"3단계-skills로-반복-절차-자동화하기\"\u003e\u003c/a\u003e3단계: Skills로 반복 절차 자동화하기\u003c/h2\u003e\n\u003cp\u003eSkill은 설명, 작업 절차, 필요 도구, 보조 자료를 하나의 재사용 가능한 단위로 묶는다. 프로젝트 Skill의 기본 구조는 \u003ccode\u003e.claude/skills/\u0026lt;skill-name\u0026gt;/SKILL.md\u003c/code\u003e이며, 필요하면 같은 디렉터리에 템플릿이나 스크립트를 추가할 수 있다.\u003c/p\u003e\n\u003cp\u003eRules와 달리 Skill은 특정 작업에 필요할 때 사용된다. Claude가 Skill의 설명을 보고 자동으로 선택할 수도 있고, 사용자가 \u003ccode\u003e/\u0026lt;skill-name\u0026gt;\u003c/code\u003e 형식으로 명시적으로 호출할 수도 있다. 반드시 수동으로만 작동하는 것은 아니다.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EC%9D%B4%EC%8A%88-%EC%88%98%EC%A0%95-skill-%EC%98%88%EC%A0%9C\" class=\"anchor\" id=\"이슈-수정-skill-예제\"\u003e\u003c/a\u003e이슈 수정 Skill 예제\u003c/h3\u003e\n\u003cp\u003e\u003ccode\u003e.claude/skills/fix-issue/SKILL.md\u003c/code\u003e 예시는 다음과 같다.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003cspan\u003ename: fix-issue\n\u003c/span\u003e\u003cspan\u003edescription: 버그를 재현하고 원인을 좁힌 뒤 최소 수정과 회귀 테스트를 수행한다.\n\u003c/span\u003e\u003cspan\u003edisable-model-invocation: true\n\u003c/span\u003e\u003cspan\u003eallowed-tools: Read, Grep, Glob, Edit, Bash(npm test:\u003c/span\u003e\u003cspan\u003e*)\n\u003c/span\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e# 이슈 수정 절차\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e대상 이슈: $ARGUMENTS\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e1. 관련 코드와 기존 테스트를 조사한다.\n\u003c/span\u003e\u003cspan\u003e2. 수정 전에 재현 방법과 예상 동작을 정리한다.\n\u003c/span\u003e\u003cspan\u003e3. 근본 원인을 한 문단으로 설명한다.\n\u003c/span\u003e\u003cspan\u003e4. 영향 범위가 가장 작은 수정을 적용한다.\n\u003c/span\u003e\u003cspan\u003e5. 회귀 테스트를 추가하거나 기존 테스트가 문제를 검증하는지 확인한다.\n\u003c/span\u003e\u003cspan\u003e6. 허용된 테스트를 실행하고 결과를 요약한다.\n\u003c/span\u003e\u003cspan\u003e7. 변경 파일, 남은 위험, 수동 확인 항목을 보고한다.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e이 Skill은 다음처럼 호출할 수 있다.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e/fix-issue 로그인 후 프로필 사진이 갱신되지 않는 문제\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e\u003ccode\u003edisable-model-invocation: true\u003c/code\u003e는 Claude가 임의로 이 Skill을 실행하지 않고 사용자가 직접 호출하도록 제한할 때 유용하다. 지원되는 front matter 필드는 Claude Code 버전에 따라 달라질 수 있다.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EC%84%A4%EA%B3%84-%EC%9A%B0%EC%84%A0-skill-%EC%98%88%EC%A0%9C\" class=\"anchor\" id=\"설계-우선-skill-예제\"\u003e\u003c/a\u003e설계 우선 Skill 예제\u003c/h3\u003e\n\u003cp\u003e바로 코딩하는 대신 설계 문서를 먼저 만들게 하려면 다음 흐름을 Skill에 넣을 수 있다.\u003c/p\u003e\n\u003col\u003e\n\u003cli\u003e요구사항과 모호한 부분을 분리한다.\u003c/li\u003e\n\u003cli\u003e기존 구조와 재사용 가능한 모듈을 조사한다.\u003c/li\u003e\n\u003cli\u003e데이터 흐름, 인터페이스, 실패 조건을 설계한다.\u003c/li\u003e\n\u003cli\u003e\n\u003ccode\u003edocs/design/\u003c/code\u003e 아래에 설계 문서를 작성한다.\u003c/li\u003e\n\u003cli\u003e사용자의 승인 또는 명시된 승인 조건을 확인한 후 구현한다.\u003c/li\u003e\n\u003cli\u003e테스트와 롤백 방법을 제시한다.\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EC%A2%8B%EC%9D%80-skill%EC%9D%98-%EC%A1%B0%EA%B1%B4\" class=\"anchor\" id=\"좋은-skill의-조건\"\u003e\u003c/a\u003e좋은 Skill의 조건\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e입력과 최종 산출물이 분명하다.\u003c/li\u003e\n\u003cli\u003e절차의 순서와 중단 조건이 명시돼 있다.\u003c/li\u003e\n\u003cli\u003e필요한 도구만 허용한다.\u003c/li\u003e\n\u003cli\u003e긴 참고 자료는 별도 파일로 분리한다.\u003c/li\u003e\n\u003cli\u003e실패했을 때 임의로 계속 진행하지 않고 보고하도록 한다.\u003c/li\u003e\n\u003cli\u003e한 Skill이 지나치게 많은 목적을 갖지 않는다.\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003e커밋 작성, 코드 리뷰, 릴리스 점검, API 설계처럼 반복되면서 시작과 끝이 분명한 작업이 Skill에 적합하다.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#4%EB%8B%A8%EA%B3%84-agents%EB%A1%9C-%EC%97%AD%ED%95%A0%EA%B3%BC-%EC%BB%A8%ED%85%8D%EC%8A%A4%ED%8A%B8-%EB%B6%84%EB%A6%AC%ED%95%98%EA%B8%B0\" class=\"anchor\" id=\"4단계-agents로-역할과-컨텍스트-분리하기\"\u003e\u003c/a\u003e4단계: Agents로 역할과 컨텍스트 분리하기\u003c/h2\u003e\n\u003cp\u003eClaude Code의 서브에이전트는 별도의 컨텍스트에서 특정 역할을 수행하고 결과를 메인 대화로 돌려준다. 메인 컨텍스트에 대량의 검색 결과나 테스트 로그를 모두 누적하고 싶지 않을 때 유용하다.\u003c/p\u003e\n\u003cp\u003e프로젝트 에이전트는 일반적으로 \u003ccode\u003e.claude/agents/\u0026lt;agent-name\u0026gt;.md\u003c/code\u003e에 정의한다. \u003ccode\u003e/agents\u003c/code\u003e 명령을 통해 에이전트를 확인하거나 관리할 수 있으며, 자연어로 특정 에이전트에게 위임하도록 요청할 수도 있다.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EC%BD%94%EB%93%9C-%EB%A6%AC%EB%B7%B0-%EC%97%90%EC%9D%B4%EC%A0%84%ED%8A%B8-%EC%98%88%EC%A0%9C\" class=\"anchor\" id=\"코드-리뷰-에이전트-예제\"\u003e\u003c/a\u003e코드 리뷰 에이전트 예제\u003c/h3\u003e\n\u003cp\u003e\u003ccode\u003e.claude/agents/code-reviewer.md\u003c/code\u003e를 다음과 같이 작성할 수 있다.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003cspan\u003ename: code-reviewer\n\u003c/span\u003e\u003cspan\u003edescription: 변경된 코드에서 결함, 보안 위험, 테스트 누락을 검토하는 읽기 중심 리뷰어\n\u003c/span\u003e\u003cspan\u003etools: Read, Grep, Glob, Bash\n\u003c/span\u003e\u003cspan\u003emodel: sonnet\n\u003c/span\u003e\u003cspan\u003e---\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e당신은 코드 리뷰 전담 에이전트다.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e다음 우선순위로 검토한다.\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e1. 실제 장애나 데이터 손실을 일으킬 수 있는 결함\n\u003c/span\u003e\u003cspan\u003e2. 인증, 권한, 입력 검증과 관련된 보안 문제\n\u003c/span\u003e\u003cspan\u003e3. 동시성, 트랜잭션, 오류 처리 문제\n\u003c/span\u003e\u003cspan\u003e4. 요구사항을 검증하지 못하는 테스트 누락\n\u003c/span\u003e\u003cspan\u003e5. 유지보수성을 크게 떨어뜨리는 구조\n\u003c/span\u003e\u003cspan\u003e\n\u003c/span\u003e\u003cspan\u003e각 발견 사항에는 파일 경로, 근거, 발생 조건, 최소 수정 방향을 포함한다.\n\u003c/span\u003e\u003cspan\u003e근거 없는 스타일 취향은 결함으로 보고하지 않는다.\n\u003c/span\u003e\u003cspan\u003e코드를 직접 수정하지 말고 리뷰 결과만 반환한다.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003cp\u003e다음과 같이 요청할 수 있다.\u003c/p\u003e\n\u003cpre\u003e\u003ccode\u003e\u003cspan\u003ecode-reviewer 에이전트에게 현재 브랜치의 변경 사항을 검토하게 해줘.\n\u003c/span\u003e\u003c/code\u003e\u003c/pre\u003e\n\u003ch3\u003e\n\u003ca href=\"#skill%EA%B3%BC-agent%EC%9D%98-%EC%B0%A8%EC%9D%B4\" class=\"anchor\" id=\"skill과-agent의-차이\"\u003e\u003c/a\u003eSkill과 Agent의 차이\u003c/h3\u003e\n\u003cdiv class=\"overflow-x-auto\"\u003e\u003ctable\u003e\n\u003cthead\u003e\n\u003ctr\u003e\n\u003cth\u003e기준\u003c/th\u003e\n\u003cth\u003eRules\u003c/th\u003e\n\u003cth\u003eSkills\u003c/th\u003e\n\u003cth\u003eAgents\u003c/th\u003e\n\u003c/tr\u003e\n\u003c/thead\u003e\n\u003ctbody\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"기준\"\u003e핵심 목적\u003c/td\u003e\n\u003ctd data-label=\"Rules\"\u003e지속 지침 제공\u003c/td\u003e\n\u003ctd data-label=\"Skills\"\u003e반복 절차 재사용\u003c/td\u003e\n\u003ctd data-label=\"Agents\"\u003e역할별 작업 위임\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"기준\"\u003e적용 시점\u003c/td\u003e\n\u003ctd data-label=\"Rules\"\u003e항상 또는 경로 조건에 따라\u003c/td\u003e\n\u003ctd data-label=\"Skills\"\u003e자동 선택 또는 명시적 호출\u003c/td\u003e\n\u003ctd data-label=\"Agents\"\u003eClaude의 위임 또는 사용자 요청\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"기준\"\u003e컨텍스트\u003c/td\u003e\n\u003ctd data-label=\"Rules\"\u003e메인 작업에 지침으로 포함\u003c/td\u003e\n\u003ctd data-label=\"Skills\"\u003e주로 현재 작업 흐름에서 실행\u003c/td\u003e\n\u003ctd data-label=\"Agents\"\u003e별도 컨텍스트에서 수행 후 결과 반환\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"기준\"\u003e대표 예\u003c/td\u003e\n\u003ctd data-label=\"Rules\"\u003e코딩 표준\u003c/td\u003e\n\u003ctd data-label=\"Skills\"\u003e이슈 수정 절차\u003c/td\u003e\n\u003ctd data-label=\"Agents\"\u003e코드 리뷰어\u003c/td\u003e\n\u003c/tr\u003e\n\u003ctr\u003e\n\u003ctd data-label=\"기준\"\u003e저장 위치\u003c/td\u003e\n\u003ctd data-label=\"Rules\"\u003e\u003ccode\u003e.claude/rules/*.md\u003c/code\u003e\u003c/td\u003e\n\u003ctd data-label=\"Skills\"\u003e\u003ccode\u003e.claude/skills/\u0026lt;이름\u0026gt;/SKILL.md\u003c/code\u003e\u003c/td\u003e\n\u003ctd data-label=\"Agents\"\u003e\u003ccode\u003e.claude/agents/*.md\u003c/code\u003e\u003c/td\u003e\n\u003c/tr\u003e\n\u003c/tbody\u003e\n\u003c/table\u003e\u003c/div\u003e\n\u003ch3\u003e\n\u003ca href=\"#agents%EC%99%80-agent-teams%EB%8A%94-%EB%8B%A4%EB%A5%B4%EB%8B%A4\" class=\"anchor\" id=\"agents와-agent-teams는-다르다\"\u003e\u003c/a\u003eAgents와 Agent Teams는 다르다\u003c/h3\u003e\n\u003cp\u003e일반 서브에이전트가 별도 컨텍스트를 쓴다는 사실이 곧 에이전트끼리 자유롭게 대화한다는 뜻은 아니다. 일반적인 서브에이전트는 맡은 일을 수행하고 결과를 메인 에이전트에 반환하는 위임 구조다. 여러 독립 세션이 서로 메시지를 주고받는 Agent Teams 기능은 별도의 기능이며, 지원 상태와 활성화 조건을 공식 문서에서 확인해야 한다.\u003c/p\u003e\n\u003cp\u003e에이전트가 다른 에이전트를 연쇄적으로 계속 생성한다고 전제해 워크플로를 설계하면 버전이나 권한 제약 때문에 실패할 수 있다. 먼저 메인 에이전트가 역할별 서브에이전트에 일을 나누고 결과를 종합하는 단순한 구조로 시작하는 편이 안전하다.\u003c/p\u003e\n\u003ch2\u003e\n\u003ca href=\"#5%EB%8B%A8%EA%B3%84-%EB%A1%9C%EB%94%A9%EA%B6%8C%ED%95%9C%ED%92%88%EC%A7%88-%EA%B2%80%EC%A6%9D%ED%95%98%EA%B8%B0\" class=\"anchor\" id=\"5단계-로딩권한품질-검증하기\"\u003e\u003c/a\u003e5단계: 로딩·권한·품질 검증하기\u003c/h2\u003e\n\u003cp\u003e설정 파일을 만들었다고 해서 의도대로 작동한다고 가정하면 안 된다. 작은 작업으로 각 구성요소를 따로 검증한다.\u003c/p\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EA%B6%8C%EC%9E%A5-%EA%B2%80%EC%A6%9D-%EC%88%9C%EC%84%9C\" class=\"anchor\" id=\"권장-검증-순서\"\u003e\u003c/a\u003e권장 검증 순서\u003c/h3\u003e\n\u003col\u003e\n\u003cli\u003e\n\u003cstrong\u003eRules 확인:\u003c/strong\u003e 규칙이 적용되는 파일과 적용되지 않는 파일을 각각 요청해 경로 조건을 확인한다.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eSkills 확인:\u003c/strong\u003e 명시적으로 Skill을 호출하고 입력 인수, 산출물, 중단 조건이 작동하는지 본다.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003eAgents 확인:\u003c/strong\u003e 읽기 전용 리뷰처럼 위험이 낮은 작업을 맡기고 결과 형식을 점검한다.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003e권한 확인:\u003c/strong\u003e Bash, Edit 등 변경 가능 도구가 꼭 필요한 구성에만 부여됐는지 검토한다.\u003c/li\u003e\n\u003cli\u003e\n\u003cstrong\u003e자동 검증:\u003c/strong\u003e 테스트, 타입 검사, 린터, 보안 검사로 AI 결과를 독립적으로 확인한다.\u003c/li\u003e\n\u003c/ol\u003e\n\u003ch3\u003e\n\u003ca href=\"#%EC%8B%A4%ED%8C%A8%ED%95%A0-%EB%95%8C-%ED%99%95%EC%9D%B8%ED%95%A0-%ED%95%AD%EB%AA%A9\" class=\"anchor\" id=\"실패할-때-확인할-항목\"\u003e\u003c/a\u003e실패할 때 확인할 항목\u003c/h3\u003e\n\u003cul\u003e\n\u003cli\u003e\n\u003ccode\u003e.claude\u003c/code\u003e가 실제 프로젝트 루트에 있는가?\u003c/li\u003e\n\u003cli\u003eSkill 파일명이 정확히 \u003ccode\u003eSKILL.md\u003c/code\u003e인가?\u003c/li\u003e\n\u003cli\u003eSkill이 \u003ccode\u003e.claude/skills/\u0026lt;이름\u0026gt;/SKILL.md\u003c/code\u003e 구조에 있는가?\u003c/li\u003e\n\u003cli\u003eAgent 파일이 \u003ccode\u003e.claude/agents\u003c/code\u003e 바로 아래의 Markdown 파일인가?\u003c/li\u003e\n\u003cli\u003eYAML front matter의 시작과 끝을 \u003ccode\u003e---\u003c/code\u003e로 닫았는가?\u003c/li\u003e\n\u003cli\u003e\n\u003ccode\u003ename\u003c/code\u003e과 \u003ccode\u003edescription\u003c/code\u003e이 작업을 구별할 만큼 구체적인가?\u003c/li\u003e\n\u003cli\u003e경로 패턴이 실제 프로젝트 구조와 일치하는가?\u003c/li\u003e\n\u003cli\u003e설치된 Claude Code 버전이 사용한 메타데이터를 지원하는가?\u003c/li\u003e\n\u003cli\u003e도구 권한 또는 조직 정책이 실행을 차단하고 있지 않은가?\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003e\n\u003ca href=\"#%EC%BB%A8%ED%85%8D%EC%8A%A4%ED%8A%B8-%EC%98%88%EC%82%B0%EA%B3%BC-%EB%B3%B4%EC%95%88%EC%9D%84-%ED%95%A8%EA%BB%98-%EC%84%A4%EA%B3%84%ED%95%B4%EC%95%BC-%ED%95%98%EB%8A%94-%EC%9D%B4%EC%9C%A0\" class=\"anchor\" id=\"컨텍스트-예산과-보안을-함께-설계해야-하는-이유\"\u003e\u003c/a\u003e컨텍스트 예산과 보안을 함께 설계해야 하는 이유\u003c/h2\u003e\n\u003cp\u003eRules, Skills, Agents의 목적은 기능 추가만이 아니다. 어떤 정보를 언제 컨텍스트에 넣을지 통제하는 \u003cstrong\u003e컨텍스트 엔지니어링 수단\u003c/strong\u003e이기도 하다.\u003c/p\u003e\n\u003cp\u003e규칙을 지나치게 길게 만들면 현재 작업과 무관한 지침이 컨텍스트를 차지하고 충돌 가능성도 커진다. 반대로 탐색과 로그 분석을 서브에이전트에 맡기면 메인 대화에는 결론과 근거만 남길 수 있다.\u003c/p\u003e\n\u003cp\u003e보안 측면에서는 다음 원칙이 중요하다.\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003eRules와 Skills도 저장소의 다른 코드처럼 리뷰한다.\u003c/li\u003e\n\u003cli\u003e외부에서 받은 Agent나 Skill 파일을 실행 전에 읽어본다.\u003c/li\u003e\n\u003cli\u003e셸 명령, 네트워크 접근, 파일 수정 권한은 최소화한다.\u003c/li\u003e\n\u003cli\u003e사용자 입력이나 이슈 본문에 포함된 명령을 무조건 신뢰하지 않는다.\u003c/li\u003e\n\u003cli\u003e배포, 삭제, 결제, 데이터 마이그레이션에는 사람의 승인 단계를 둔다.\u003c/li\u003e\n\u003cli\u003e비밀 정보는 프롬프트 파일에 저장하지 말고 별도의 비밀 관리 체계를 사용한다.\u003c/li\u003e\n\u003c/ul\u003e\n\u003ch2\u003e\n\u003ca href=\"#%EC%96%B4%EB%96%A4-%EA%B8%B0%EB%8A%A5%EC%9D%84-%EC%84%A0%ED%83%9D%ED%95%B4%EC%95%BC-%ED%95%98%EB%82%98\" class=\"anchor\" id=\"어떤-기능을-선택해야-하나\"\u003e\u003c/a\u003e어떤 기능을 선택해야 하나\u003c/h2\u003e\n\u003cp\u003e다음 질문으로 빠르게 결정할 수 있다.\u003c/p\u003e\n\u003cul\u003e\n\u003cli\u003e모든 관련 작업이 따라야 하는가? → \u003cstrong\u003eRule\u003c/strong\u003e\n\u003c/li\u003e\n\u003cli\u003e시작과 끝이 있는 반복 절차인가? → \u003cstrong\u003eSkill\u003c/strong\u003e\n\u003c/li\u003e\n\u003cli\u003e별도 역할과 독립된 컨텍스트가 필요한가? → \u003cstrong\u003eAgent\u003c/strong\u003e\n\u003c/li\u003e\n\u003cli\u003e특정 이벤트 전후에 결정적인 명령을 실행해야 하는가? → \u003cstrong\u003eHook 검토\u003c/strong\u003e\n\u003c/li\u003e\n\u003c/ul\u003e\n\u003cp\u003e예를 들어 “TypeScript를 사용한다”는 Rule이고, “버그 재현부터 회귀 테스트까지 수행한다”는 Skill이다. “변경 내용을 읽고 보안 결함만 보고한다”는 Agent에 적합하다. 파일 편집 후 포매터를 반드시 실행하는 것처럼 특정 이벤트에 연결된 동작은 Hooks가 더 적합할 수 있다.\u003c/p\u003e\n\u003cp\u003e가장 안정적인 구성은 세 기능을 경쟁 관계로 보지 않고 조합하는 것이다. Rule로 공통 기준을 제공하고, Skill로 표준 절차를 실행하며, Agent로 조사·리뷰처럼 컨텍스트가 큰 작업을 분리한 뒤 테스트와 Hooks로 결정적 검증을 보완한다.\u003c/p\u003e\n","tags":["컨텍스트 엔지니어링","Claude Code","AI 코딩","Agent Skills","코딩 에이전트"],"faqs":[{"question":"Claude Code에서 `.claude` 폴더는 반드시 필요한가요?","answer":"프로젝트용 Rules, Skills, Agents를 표준 구조로 관리할 때 사용하지만 모든 지침에 반드시 필요한 것은 아닙니다. 프로젝트 지침은 루트의 `CLAUDE.md` 또는 `.claude/CLAUDE.md`에도 둘 수 있고, 개인 설정은 `~/.claude` 아래에서 관리할 수 있습니다."},{"question":"Rules와 `CLAUDE.md`는 어떤 차이가 있나요?","answer":"`CLAUDE.md`는 프로젝트의 핵심 지침을 한 문서로 제공하기에 적합합니다. `.claude/rules`는 주제별 파일 분리와 경로별 조건 적용에 유리하므로 프로젝트가 커질수록 규칙을 모듈화하는 데 도움이 됩니다."},{"question":"Skill 파일명은 `skill.md`인가요, `SKILL.md`인가요?","answer":"공식 Agent Skills 구조에 맞춘 진입 파일명은 대문자 `SKILL.md`입니다. 프로젝트 Skill은 `.claude/skills/\u003cskill-name\u003e/SKILL.md`에 두는 것이 안전하며, 대소문자를 구분하는 운영체제에서는 `skill.md`가 다른 파일로 처리됩니다."},{"question":"Claude Code Skill은 사용자가 호출할 때만 실행되나요?","answer":"항상 그런 것은 아닙니다. Claude가 Skill의 설명을 보고 적합한 작업에서 자동으로 선택할 수 있으며, 사용자가 `/\u003cskill-name\u003e`으로 호출할 수도 있습니다. 자동 호출을 막아야 한다면 지원되는 버전에서 `disable-model-invocation` 설정을 검토할 수 있습니다."},{"question":"Skill과 Agent 중 무엇을 사용해야 하나요?","answer":"현재 작업 흐름에서 반복 절차를 실행하려면 Skill이 적합합니다. 대량 조사, 테스트 분석, 코드 리뷰처럼 별도 역할과 격리된 컨텍스트가 필요하면 Agent가 적합합니다. 공통 코딩 기준처럼 지속적으로 적용할 내용은 Rule로 분리합니다."},{"question":"서브에이전트끼리 직접 대화하거나 다른 에이전트를 호출할 수 있나요?","answer":"일반적인 Claude Code 서브에이전트는 별도 컨텍스트에서 작업한 뒤 결과를 메인 에이전트에 반환하는 구조입니다. 여러 독립 세션의 직접 협업은 별도의 Agent Teams 기능과 구분해야 하며, 사용 중인 버전의 지원 상태와 제한을 확인해야 합니다."},{"question":"Rules를 작성하면 Claude가 지침을 항상 완벽하게 지키나요?","answer":"아닙니다. Rules는 지속적으로 제공되는 지침이지만 결정적인 강제 장치는 아닙니다. 지침 충돌이나 모호성 때문에 누락될 수 있으므로 린터, 타입 검사, 테스트, Hooks, 코드 리뷰와 함께 사용해야 합니다."},{"question":"외부에서 받은 Skill이나 Agent를 바로 사용해도 안전한가요?","answer":"바로 실행하지 않는 것이 좋습니다. 파일에 포함된 지침, 셸 명령, 허용 도구, 네트워크 및 파일 접근 범위를 먼저 검토하고 최소 권한으로 시험해야 합니다. 비밀 정보 전송이나 위험한 파일 변경을 유도하는 내용이 없는지도 확인해야 합니다."}],"sources":[{"url":"https://code.claude.com/docs/en/memory","title":"Claude Code documentation: Manage Claude's memory","type":"source"},{"url":"https://code.claude.com/docs/en/skills","title":"Claude Code documentation: Extend Claude with skills","type":"source"},{"url":"https://code.claude.com/docs/en/sub-agents","title":"Claude Code documentation: Create custom subagents","type":"source"},{"url":"https://code.claude.com/docs/en/settings","title":"Claude Code documentation: Claude Code settings","type":"source"}],"images":[{"id":767,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6OTgyOSwicHVyIjoiYmxvYl9pZCJ9fQ==--8ba3d33d24232863ea1d744998bca1e2dbb088c6/ai-7c680af1.webp","is_representative":true,"generation_method":"ai_photo","license":"ai_generated","mime_type":"image/webp","translations":{"ko":{"alt":"책상에서 노트북의 개발 워크플로 대시보드를 살펴보는 사람","caption":"개발자가 노트북에서 프로젝트 파일과 자동화 작업 상태를 확인하고 있다.","description":null},"en":{"alt":"Person viewing a development workflow dashboard on a laptop at a desk","caption":"A developer reviews project files and automation task statuses on a laptop.","description":null},"ja":{"alt":"デスクでノートパソコンの開発ワークフローダッシュボードを見る人","caption":"開発者がノートパソコンでプロジェクトファイルと自動化タスクの状態を確認している。","description":null},"es":{"alt":"Persona viendo un panel de flujo de desarrollo en un portátil sobre un escritorio","caption":"Un desarrollador revisa archivos del proyecto y estados de tareas automatizadas en un portátil.","description":null},"id":{"alt":"Seseorang melihat dasbor alur kerja pengembangan di laptop pada meja","caption":"Seorang pengembang memeriksa berkas proyek dan status tugas otomatis di laptop.","description":null},"pt":{"alt":"Pessoa visualizando um painel de fluxo de desenvolvimento em um notebook","caption":"Um desenvolvedor verifica arquivos do projeto e o status de tarefas automatizadas no notebook.","description":null},"zh-hant":{"alt":"坐在書桌前查看筆電開發工作流程儀表板的人","caption":"開發者正在筆電上檢查專案檔案與自動化任務狀態。","description":null},"de":{"alt":"Person betrachtet ein Dashboard für Entwicklungsabläufe auf einem Laptop am Schreibtisch","caption":"Ein Entwickler prüft Projektdateien und den Status automatisierter Aufgaben auf einem Laptop.","description":null}}},{"id":768,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6OTgzNSwicHVyIjoiYmxvYl9pZCJ9fQ==--458d876e5a3cb0d4581f0909c6198e47789eda8b/ai-54d6eb4e.webp","is_representative":false,"generation_method":"ai_image","license":"ai_generated","mime_type":"image/webp","translations":{"ko":{"alt":"폴더, 필터, 자동화 단계, AI 작업 공간, 보안 및 검증 흐름을 연결한 워크플로 다이어그램","caption":"규칙과 자동화 단계가 보안 계층을 거쳐 테스트와 검증으로 이어지는 구조를 보여준다.","description":null},"en":{"alt":"Workflow diagram linking folders, filters, automation steps, an AI workspace, security, and validation","caption":"Rules and automated steps flow through a security layer into testing and validation.","description":null},"ja":{"alt":"フォルダー、フィルター、自動化工程、AI作業環境、セキュリティ、検証を結ぶワークフロー図","caption":"ルールと自動化工程がセキュリティ層を経てテストと検証へ進む構成を示している。","description":null},"es":{"alt":"Diagrama de flujo con carpetas, filtros, automatización, espacio de IA, seguridad y validación","caption":"Las reglas y los pasos automatizados pasan por una capa de seguridad hasta las pruebas y la validación.","description":null},"id":{"alt":"Diagram alur folder, filter, tahap otomatisasi, ruang kerja AI, keamanan, dan validasi","caption":"Aturan dan tahapan otomatis mengalir melalui lapisan keamanan menuju pengujian dan validasi.","description":null},"pt":{"alt":"Diagrama de fluxo com pastas, filtros, automação, ambiente de IA, segurança e validação","caption":"Regras e etapas automatizadas passam por uma camada de segurança até os testes e a validação.","description":null},"zh-hant":{"alt":"連結資料夾、篩選器、自動化步驟、AI 工作區、安全與驗證的流程圖","caption":"規則與自動化步驟經過安全層後，進入測試與驗證流程。","description":null},"de":{"alt":"Workflow mit Ordnern, Filtern, Automatisierung, KI-Arbeitsplatz, Sicherheit und Validierung","caption":"Regeln und automatisierte Schritte führen über eine Sicherheitsebene zu Tests und Validierung.","description":null}}},{"id":769,"url":"https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6OTg0MSwicHVyIjoiYmxvYl9pZCJ9fQ==--0a7726350fd343b4a1ec772d59017213a4a6d71d/ai-c239f290.webp","is_representative":false,"generation_method":"ai_infographic","license":"ai_generated","mime_type":"image/webp","visible_locales":["ko"],"translations":{"ko":{"alt":"Claude Code의 Rules·Skills·Agents 구조, 워크플로, 권한 및 컨텍스트를 설명하는 인포그래픽","caption":"프로젝트 구조부터 규칙 재사용, 에이전트 위임, 결과 검증까지의 실전 흐름을 정리합니다.","description":null},"en":{"alt":"Infographic explaining Claude Code Rules, Skills, Agents, workflow, permissions, and contexts","caption":"It outlines the practical flow from project structure and reusable rules to agent delegation and result validation.","description":null},"ja":{"alt":"Claude CodeのRules・Skills・Agentsの構成、ワークフロー、権限、コンテキストを示す図","caption":"プロジェクト構成からルールの再利用、エージェントへの委任、結果検証までの流れをまとめています。","description":null},"es":{"alt":"Infografía sobre Rules, Skills y Agents de Claude Code, con flujo, permisos y contextos","caption":"Resume el flujo desde la estructura del proyecto y la reutilización de reglas hasta la delegación y validación.","description":null},"id":{"alt":"Infografik struktur Rules, Skills, Agents Claude Code beserta alur kerja, izin, dan konteks","caption":"Diagram ini merangkum alur dari struktur proyek dan penggunaan ulang aturan hingga delegasi agen dan validasi hasil.","description":null},"pt":{"alt":"Infográfico de Rules, Skills e Agents do Claude Code, com fluxo, permissões e contextos","caption":"O diagrama resume o fluxo da estrutura do projeto e reutilização de regras à delegação e validação dos resultados.","description":null},"zh-hant":{"alt":"說明 Claude Code Rules、Skills、Agents 結構、工作流程、權限與情境的資訊圖","caption":"此圖整理從專案結構、規則重用到代理委派與結果驗證的實務流程。","description":null},"de":{"alt":"Infografik zu Claude Code Rules, Skills und Agents mit Workflow, Berechtigungen und Kontexten","caption":"Sie zeigt den Ablauf von Projektstruktur und Regelwiederverwendung bis zur Agentendelegation und Ergebnisprüfung.","description":null}}}],"published_at":"2026-08-19T16:14:05+09:00","updated_at":"2026-08-19T16:14:05+09:00","license":"cc_by","translation_status":"original","available_locales":["ko","en","ja","es"],"data_locales":["ko","en","ja","es","id","pt","zh-hant","de"],"url":"https://injoys.com/ko/articles/claude-code-rules-skills-agents-guide"}