everything-claude-code/docs/ko-KR/CONTRIBUTING.md

Everything Claude Code에 기여하기

기여에 관심을 가져주셔서 감사합니다! 이 저장소는 Claude Code 사용자를 위한 커뮤니티 리소스입니다.

목차

• 우리가 찾는 것
• 빠른 시작
• 스킬 기여하기
• 에이전트 기여하기
• 훅 기여하기
• 커맨드 기여하기
• Pull Request 프로세스

---

우리가 찾는 것

에이전트

특정 작업을 잘 처리하는 새로운 에이전트:

• 언어별 리뷰어 (Python, Go, Rust)
• 프레임워크 전문가 (Django, Rails, Laravel, Spring)
• DevOps 전문가 (Kubernetes, Terraform, CI/CD)
• 도메인 전문가 (ML 파이프라인, 데이터 엔지니어링, 모바일)

스킬

워크플로우 정의와 도메인 지식:

• 언어 모범 사례
• 프레임워크 패턴
• 테스팅 전략
• 아키텍처 가이드

훅

유용한 자동화:

• 린팅/포매팅 훅
• 보안 검사
• 유효성 검증 훅
• 알림 훅

커맨드

유용한 워크플로우를 호출하는 슬래시 커맨드:

• 배포 커맨드
• 테스팅 커맨드
• 코드 생성 커맨드

---

빠른 시작

# 1. 포크 및 클론
gh repo fork affaan-m/everything-claude-code --clone
cd everything-claude-code

# 2. 브랜치 생성
git checkout -b feat/my-contribution

# 3. 기여 항목 추가 (아래 섹션 참고)

# 4. 로컬 테스트
cp -r skills/my-skill ~/.claude/skills/  # 스킬의 경우
# 그런 다음 Claude Code로 테스트

# 5. PR 제출
git add . && git commit -m "feat: add my-skill" && git push -u origin feat/my-contribution

---

스킬 기여하기

스킬은 Claude Code가 컨텍스트에 따라 로드하는 지식 모듈입니다.

디렉토리 구조

skills/
└── your-skill-name/
    └── SKILL.md

SKILL.md 템플릿

---
name: your-skill-name
description: 스킬 목록에 표시되는 간단한 설명
origin: ECC
---

# 스킬 제목

이 스킬이 다루는 내용에 대한 간단한 개요.

## 핵심 개념

주요 패턴과 가이드라인 설명.

## 코드 예제

\`\`\`typescript
// 실용적이고 테스트된 예제 포함
function example() {
  // 잘 주석 처리된 코드
}
\`\`\`

## 모범 사례

- 실행 가능한 가이드라인
- 해야 할 것과 하지 말아야 할 것
- 흔한 실수 방지

## 사용 시점

이 스킬이 적용되는 시나리오 설명.

스킬 체크리스트

• 하나의 도메인/기술에 집중
• 실용적인 코드 예제 포함
• 500줄 미만
• 명확한 섹션 헤더 사용
• Claude Code에서 테스트 완료

스킬 예시

스킬	용도
coding-standards/	TypeScript/JavaScript 패턴
frontend-patterns/	React와 Next.js 모범 사례
backend-patterns/	API와 데이터베이스 패턴
security-review/	보안 체크리스트

---

에이전트 기여하기

에이전트는 Task 도구를 통해 호출되는 전문 어시스턴트입니다.

파일 위치

agents/your-agent-name.md

에이전트 템플릿

---
name: your-agent-name
description: 이 에이전트가 하는 일과 Claude가 언제 호출해야 하는지. 구체적으로 작성!
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: sonnet
---

당신은 [역할] 전문가입니다.

## 역할

- 주요 책임
- 부차적 책임
- 하지 않는 것 (경계)

## 워크플로우

### 1단계: 이해
작업에 접근하는 방법.

### 2단계: 실행
작업을 수행하는 방법.

### 3단계: 검증
결과를 검증하는 방법.

## 출력 형식

사용자에게 반환하는 것.

## 예제

### 예제: [시나리오]
입력: [사용자가 제공하는 것]
행동: [수행하는 것]
출력: [반환하는 것]

에이전트 필드

필드	설명	옵션
name	소문자, 하이픈 연결	code-reviewer
description	호출 시점 결정에 사용	구체적으로 작성!
tools	필요한 것만 포함	Read, Write, Edit, Bash, Grep, Glob, WebFetch, Task
model	복잡도 수준	haiku (단순), sonnet (코딩), opus (복잡)

예시 에이전트

에이전트	용도
tdd-guide.md	테스트 주도 개발
code-reviewer.md	코드 리뷰
security-reviewer.md	보안 점검
build-error-resolver.md	빌드 오류 수정

---

훅 기여하기

훅은 Claude Code 이벤트에 의해 트리거되는 자동 동작입니다.

파일 위치

hooks/hooks.json

훅 유형

유형	트리거 시점	사용 사례
PreToolUse	도구 실행 전	유효성 검증, 경고, 차단
PostToolUse	도구 실행 후	포매팅, 검사, 알림
SessionStart	세션 시작 시	컨텍스트 로딩
Stop	세션 종료 시	정리, 감사

훅 형식

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "tool == \"Bash\" && tool_input.command matches \"rm -rf /\"",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[Hook] BLOCKED: Dangerous command' && exit 1"
          }
        ],
        "description": "위험한 rm 명령 차단"
      }
    ]
  }
}

Matcher 문법

// 특정 도구 매칭
tool == "Bash"
tool == "Edit"
tool == "Write"

// 입력 패턴 매칭
tool_input.command matches "npm install"
tool_input.file_path matches "\\.tsx?$"

// 조건 결합
tool == "Bash" && tool_input.command matches "git push"

훅 예시

// tmux 밖 dev 서버 차단
{
  "matcher": "tool == \"Bash\" && tool_input.command matches \"npm run dev\"",
  "hooks": [{"type": "command", "command": "echo '개발 서버는 tmux에서 실행하세요' && exit 1"}],
  "description": "dev 서버를 tmux에서 실행하도록 강제"
}

// TypeScript 편집 후 자동 포맷
{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\.tsx?$\"",
  "hooks": [{"type": "command", "command": "npx prettier --write \"$file_path\""}],
  "description": "TypeScript 파일 편집 후 포맷"
}

// git push 전 경고
{
  "matcher": "tool == \"Bash\" && tool_input.command matches \"git push\"",
  "hooks": [{"type": "command", "command": "echo '[Hook] push 전에 변경사항을 다시 검토하세요'"}],
  "description": "push 전 검토 리마인더"
}

훅 체크리스트

• Matcher가 구체적 (너무 광범위하지 않게)
• 명확한 오류/정보 메시지 포함
• 올바른 종료 코드 사용 (exit 1은 차단, exit 0은 허용)
• 충분한 테스트 완료
• 설명 포함

---

커맨드 기여하기

커맨드는 /command-name으로 사용자가 호출하는 액션입니다.

파일 위치

commands/your-command.md

커맨드 템플릿

---
description: /help에 표시되는 간단한 설명
---

# 커맨드 이름

## 목적

이 커맨드가 수행하는 작업.

## 사용법

\`\`\`
/your-command [args]
\`\`\`

## 워크플로우

1. 첫 번째 단계
2. 두 번째 단계
3. 마지막 단계

## 출력

사용자가 받는 결과.

커맨드 예시

커맨드	용도
commit.md	Git 커밋 생성
code-review.md	코드 변경사항 리뷰
tdd.md	TDD 워크플로우
e2e.md	E2E 테스팅

---

크로스-하네스 및 번역

스킬 서브셋 (Codex 및 Cursor)

ECC는 다른 하네스를 위한 스킬 서브셋도 제공합니다:

• Codex: .agents/skills/ — agents/openai.yaml에 나열된 스킬이 Codex에서 로드됩니다.
• Cursor: .cursor/skills/ — Cursor용 스킬 서브셋이 별도로 포함됩니다.

Codex 또는 Cursor에서도 제공해야 하는 새 스킬을 추가한다면:

1. 먼저 skills/your-skill-name/ 아래에 일반적인 ECC 스킬로 추가합니다.
2. Codex에서도 제공해야 하면 .agents/skills/에 반영하고, 필요하면 agents/openai.yaml에도 참조를 추가합니다.
3. Cursor에서도 제공해야 하면 Cursor 레이아웃에 맞게 .cursor/skills/ 아래에 추가합니다.

기존 디렉터리의 구조를 확인한 뒤 같은 패턴을 따르세요. 이 서브셋 동기화는 수동이므로 PR 설명에 반영 여부를 적어 두는 것이 좋습니다.

번역

번역 문서는 docs/ 아래에 있습니다. 예: docs/zh-CN, docs/zh-TW, docs/ja-JP.

번역된 에이전트, 커맨드, 스킬을 변경한다면:

• 대응하는 번역 파일도 함께 업데이트하거나
• 유지보수자/번역자가 후속 작업을 할 수 있도록 이슈를 열어 주세요.

---

Pull Request 프로세스

1. PR 제목 형식

feat(skills): add rust-patterns skill
feat(agents): add api-designer agent
feat(hooks): add auto-format hook
fix(skills): update React patterns
docs: improve contributing guide

2. PR 설명

## 요약
무엇을 추가했고 왜 필요한지.

## 유형
- [ ] 스킬
- [ ] 에이전트
- [ ] 훅
- [ ] 커맨드

## 테스트
어떻게 테스트했는지.

## 체크리스트
- [ ] 형식 가이드라인 준수
- [ ] Claude Code에서 테스트 완료
- [ ] 민감한 정보 없음 (API 키, 경로)
- [ ] 명확한 설명 포함

3. 리뷰 프로세스

1. 메인테이너가 48시간 이내에 리뷰
2. 피드백이 있으면 수정 반영
3. 승인되면 main에 머지

---

가이드라인

해야 할 것

• 기여를 집중적이고 모듈화되게 유지
• 명확한 설명 포함
• 제출 전 테스트
• 기존 패턴 따르기
• 의존성 문서화

하지 말아야 할 것

• 민감한 데이터 포함 (API 키, 토큰, 경로)
• 지나치게 복잡하거나 특수한 설정 추가
• 테스트하지 않은 기여 제출
• 기존 기능과 중복되는 것 생성

---

파일 이름 규칙

• 소문자에 하이픈 사용: python-reviewer.md
• 설명적으로 작성: workflow.md가 아닌 tdd-workflow.md
• name과 파일명을 일치시키기

---

질문이 있으신가요?

• 이슈: github.com/affaan-m/everything-claude-code/issues
• X/Twitter: @affaanmustafa

---

기여해 주셔서 감사합니다! 함께 훌륭한 리소스를 만들어 갑시다.