Skills, Agents, Hooks 및 보안 GitHub 저장소를 활용한 Claude Code 프로젝트 설정 방법

AI 코딩 도구는 코드 주변의 프로젝트를 이해할 때 가장 잘 작동합니다.

새로운 Claude Code 세션은 질문에 답하고 파일을 편집할 수 있지만, 귀하의 아키텍처 결정(architecture decisions), 코딩 표준(coding standards), 보안 기대치(security expectations), 테스트 규칙(testing rules), 풀 리퀘스트(pull request) 형식 또는 운영 제약 사항(operational constraints)을 자동으로 알지는 못합니다. 그러한 컨텍스트(context)는 예측 가능한 어딘가에 존재해야 합니다.

이 가이드는 desertfox33이 소유한 재사용 가능한 저장소를 사용하여 Claude Code 프로젝트를 설정하는 전체 과정을 안내합니다:

참조 저장소: https://github.com/desertfox33/claude-code-project-template

목표는 단순히 폴더를 만드는 것이 아닙니다. 목표는 Claude Code가 코드 리뷰, 테스트 작성, 풀 리퀘스트 준비, 보안 문제 확인 및 프로젝트별 규칙 준수와 같은 실제 프로젝트 작업 전반에서 일관되게 동작하도록 만드는 것입니다.

이 설정을 운영 환경(production environment)에서 사용하기 전에, 최신 공식 문서를 통해 현재 Claude Code의 동작을 확인하십시오. 도구, 구성 이름 및 기능 동작은 변경될 수 있습니다.

우리가 구축하는 것

이 저장소는 다음과 같은 구조를 사용합니다:

claude-code-project-template/
├── CLAUDE.md
├── CLAUDE.local.md.example
...

이 레이아웃은 장기적인 컨텍스트(long-lived context)와 작업별 컨텍스트(task-specific context)를 분리합니다. 이를 통해 설정을 더 쉽게 유지 관리할 수 있으며, Claude가 모든 작업에 대해 관련 없는 지침을 로드할 가능성을 줄여줍니다.

멘탈 모델 (The Mental Model)

프로젝트를 여러 계층으로 생각하십시오.

CLAUDE.md는 프로젝트 브리핑(project briefing)입니다. 여기에는 Claude가 모든 세션에서 알고 있어야 하는 정보, 즉 프로젝트 목적, 기술 스택(tech stack), 아키텍처 규칙(architecture rules), 코딩 표준(coding standards), 보안 기대치(security expectations) 및 저장소의 나머지 부분을 사용하는 방법이 포함됩니다.

CLAUDE.local.md는 개인적인 재정의(personal overrides)를 위한 것입니다. 이는 로컬에 유지되어야 하며 커밋(commit)해서는 안 됩니다. 머신별 노트, 로컬 경로, 개인적 선호도 및 일시적인 실험을 위해 사용하십시오.

.claude/rules/에는 특정 규칙 파일들이 포함되어 있습니다. 지침이 여러 작업에 걸쳐 적용되지만 매번 메인 프로젝트 브리핑(briefing)에 로드될 필요는 없을 때 규칙(rules)을 사용하십시오.

.claude/skills/에는 재사용 가능한 작업 전문 지식(expertise)이 포함되어 있습니다. 코드 리뷰, 테스트 작성, 풀 리퀘스트(pull request) 설명 생성 또는 보안 검토와 같이 반복적인 작업에 대해 Claude가 특정 프로세스를 따라야 할 때 스킬(skills)을 사용하십시오.

.claude/commands/에는 프로젝트별 슬래시 명령어(slash commands)가 포함되어 있습니다. /review, /test 또는 /pr과 같이 짧고 반복 가능한 진입점이 필요할 때 명령어(commands)를 사용하십시오.

.claude/agents/에는 특화된 서브 에이전트(subagent) 정의가 포함되어 있습니다. 보안 검토, 테스트 작성 또는 조사(research)와 같이 격리된 역할(role)을 통해 이점을 얻을 수 있는 작업에는 에이전트(agents)를 사용하십시오.

.claude/hooks/에는 도구 사용(tool use) 또는 파일 변경에 따른 동작을 강제하는 스크립트가 포함되어 있습니다. 훅(hooks)은 명령어를 실행할 수 있으므로 코드(code)로 취급하십시오.

.claude/memory/에는 지속적인 프로젝트 컨텍스트(context), 결정 사항 및 진행 노트가 포함되어 있습니다.

.claude/workflows/에는 기능 빌드(feature builds), 버그 수정 및 리뷰 사이클과 같은 더 큰 규모의 작업을 위한 반복 가능한 작업 청사진(blueprints)이 포함되어 있습니다.

.mcp.example.json은 Model Context Protocol (MCP) 설정을 위해 커밋된 예시 파일입니다. 실제 .mcp.json은 로컬 경로, 명령어, 환경 참조 또는 자격 증명(credentials)을 포함할 수 있으므로 일반적으로 로컬 전용으로 유지되어야 하며 Git에서 무시(ignore)되어야 합니다. MCP는 Claude를 외부 도구 및 데이터 소스에 연결할 수 있으므로 보안에 민감한 설정으로 취급하십시오.

1단계: CLAUDE.md로 시작하기

CLAUDE.md를 저장소의 루트(root)에 배치하십시오.

Claude가 항상 가지고 있어야 할 컨텍스트(context)를 위해 이를 사용하십시오. 단순히 정보를 쏟아붓는 쓰레기통으로 만들지 마십시오. 좋은 CLAUDE.md는 다음 질문들에 답할 수 있어야 합니다:

• 이 프로젝트는 무엇을 하는가?
• 어떤 기술 스택(tech stack)을 사용하는가?
• 코드는 어떤 표준(standards)을 따라야 하는가?
• 승인 없이 절대 수정해서는 안 되는 파일은 무엇인가?
• 어떤 스킬(skills), 에이전트(agents), 명령어(commands), 훅(hooks) 및 워크플로(workflows)가 존재하는가?
• 어떤 보안 및 테스트 기대 사항이 적용되는가?

예시 내용:

Claude Code를 위한 프로젝트 지침 (Project Instructions)

이 저장소는 desertfox33에 의해 관리됩니다.
...

사용처

모든 Claude Code 프로젝트에서 CLAUDE.md를 사용하세요. 이는 프로젝트의 운영 가이드 역할을 합니다.

포함하지 말아야 할 사항

CLAUDE.md에 개인적인 비밀(secrets), 로컬 파일 시스템 경로(local filesystem paths), 임시 메모(temporary notes) 또는 방대한 규칙 문서(large rule documents)를 넣지 마세요. 로컬 전용 데이터는 CLAUDE.local.md에, 상세한 규칙은 .claude/rules/에 작성하세요.

2단계: CLAUDE.local.md를 통한 로컬 재정의(Local Overrides) 추가

예시 파일을 생성합니다:

CLAUDE.local.md.example

개발자는 이를 로컬에 복사할 수 있습니다:

cp CLAUDE.local.md.example CLAUDE.local.md

그 다음, 실제 파일을 .gitignore에 추가합니다:

CLAUDE.local.md

사용처

개인적인 선호도(personal preferences)와 로컬 컨텍스트(local context)를 위해 CLAUDE.local.md를 사용하세요:

# 로컬 Claude 메모 (Local Claude Notes)

- 나의 로컬 테스트 명령어는 `npm test`입니다.
...

중요성

로컬 재정의(Local overrides)는 유용하지만, 개인적인 세부 정보를 유출할 수 있습니다. 이를 Git에서 제외함으로써 개인적인 경로, 내부 환경 메모, 임시 지침 등을 보호할 수 있습니다.

3단계: 모듈형 규칙(Modular Rules) 추가

규칙은 여기에 위치합니다:

.claude/rules/

이 저장소에는 다음이 포함되어 있습니다:

.claude/rules/code-style.md
.claude/rules/api-conventions.md
.claude/rules/testing-standard.md
...

어떤 규칙을 사용할 것인가

Claude가 애플리케이션 코드를 편집할 때는 code-style.md를 사용하세요. 여기에는 명명 규칙(naming), 구조(structure), 가독성 기대치(readability expectations), 에러 처리(error handling) 및 유지보수 표준(maintainability standards)이 정의되어야 합니다.

Claude가 API를 작업할 때는 api-conventions.md를 사용하세요. 여기에는 경로 명명(route naming), 검증 기대치(validation expectations), 에러 응답(error responses), 인증 가정(authentication assumptions) 및 호환성 요구사항(compatibility requirements)이 정의되어야 합니다.

Claude가 테스트를 작성하거나 검토할 때는 testing-standard.md를 사용하세요. 여기에는 단위 테스트 스타일(unit test style), 통합 테스트 기대치(integration test expectations), 커버리지 우선순위(coverage priorities), 피스처(fixtures), 모킹 규칙(mocking rules) 및 실패 사례(failure cases)가 정의되어야 합니다.

Claude가 풀 리퀘스트 (Pull Request, PR)를 준비할 때는 pr.md를 사용하세요. 여기에는 PR 제목 형식, 설명 구조, 테스트 증거 (testing evidence), 보안 영향 (security impact), 그리고 롤백 고려 사항 (rollback considerations)이 정의되어야 합니다.

예시: testing-standard.md

# 테스트 표준 (Testing Standard)

테스트를 작성할 때:
...

실무 가이드

각 규칙 파일은 하나의 목적에 집중하도록 유지하세요. 특정 규칙이 코드 리뷰 (code review)에만 관련이 있다면 코드 리뷰 스킬 (code review skill)에 두세요. 만약 모든 코드 변경 사항에 적용된다면 .claude/rules/에 두세요.

4단계: 스킬 (Skills) 추가하기

스킬은 다음 위치에 존재합니다:

.claude/skills/<skill-name>/SKILL.md

각 스킬은 하나의 작업 (job)을 수행해야 합니다. 모든 것을 다 하려고 시도하는 하나의 거대한 스킬을 만들지 마세요.

이 저장소에는 네 가지 스킬이 포함되어 있습니다.

스킬 1: code-review

위치:

.claude/skills/code-review/SKILL.md
.claude/skills/code-review/review-checklist.md

사용 시점

Claude가 브랜치 (branch), 파일 (file), 폴더 (folder) 또는 풀 리퀘스트 (pull request)를 다음 항목에 대해 검토해야 할 때 code-review를 사용하세요:

• 정확성 (Correctness)
• 유지보수성 (Maintainability)
• 신뢰성 (Reliability)
• 보안 우려 사항 (Security concerns)
• 테스트 커버리지 (Test coverage)
• 에러 핸들링 (Error handling)
• 파괴적 변경 사항 (Breaking changes)
• 운영 리스크 (Operational risk)

사용 방법

Claude에게 다음과 같이 요청하세요:

Use the code-review skill to review the changes in this branch.

또는:

Use the code-review skill to review src/auth for correctness, security, and test coverage.

스킬이 수행해야 할 작업

스킬은 Claude에게 다음을 지시해야 합니다:

1. 변경 된 파일 식별.
2. 의도된 동작 이해.
3. 정확성 및 엣지 케이스 (edge cases) 검토.
4. 보안에 민감한 변경 사항 확인.
5. 테스트 영향도 확인.
6. 발견된 사항을 심각도 (severity)에 따라 분류.
7. 유지보수성이나 리스크에 영향을 주지 않는 사소한 지적 (nitpicks)은 피할 것.

출력 예시 형식

## 요약 (Summary)

검토된 내용에 대한 짧은 설명.
...

가장 도움이 되는 상황

코드를 병합 (merge) 하기 전, 풀 리퀘스트 (pull request)를 열기 전, 또는 대규모 AI 지원 편집 (AI-assisted edit)을 수행한 후에 이 스킬을 사용하세요.

스킬 2: testing-patterns

위치:

.claude/skills/testing-patterns/SKILL.md
.claude/skills/testing-patterns/test-strategy.md

사용 시점

Claude가 다음과 같은 작업을 수행해야 할 때 testing-patterns를 사용하세요:

• 단위 테스트 (unit tests) 작성
• 기존 테스트 개선
• 회귀 테스트 (regression tests) 추가
• 누락된 테스트 케이스 (test cases) 식별
• 새로운 기능에 대한 테스트 전략 (test strategy) 설계
• 모호한 수락 기준 (acceptance criteria)을 테스트 케이스로 변환

사용 방법

새로운 검증 로직에 대한 테스트를 작성하기 위해 testing-patterns 스킬을 사용하세요.

또는:

이 버그 수정에 대해 누락된 테스트를 식별하기 위해 testing-patterns 스킬을 사용하세요.

스킬이 수행해야 할 역할

이 스킬은 Claude가 다음과 같은 특성을 가진 테스트를 생성하도록 안내해야 합니다:

• 결정론적 (Deterministic)
• 집중된 (Focused)
• 유지보수 가능한 (Maintainable)
• 설정(setup), 실행(action), 단언(assertion)이 명확한
• 엣지 케이스 (edge cases) 및 실패 모드 (failure modes)에 민감한

가장 도움이 되는 상황

기능 구현 후, 버그 수정 중, 또는 풀 리퀘스트 (pull request)를 생성하기 전에 사용하세요.

실용적인 패턴은 다음과 같습니다:

기능 구현 → testing-patterns 사용 → code-review 사용 → PR 준비

스킬 3: pr-description

위치:

.claude/skills/pr-description/SKILL.md
.claude/skills/pr-description/template.md

사용 시점

Claude가 명확한 풀 리퀘스트 (pull request) 요약을 준비해야 할 때 pr-description을 사용하세요.

요약에는 다음 내용이 포함되어야 합니다:

• 변경 사항
• 변경 이유
• 테스트 방법
• 보안 영향 (Security impact)
• 배포 또는 롤백 (rollback) 고려 사항
• 관련 있는 경우 스크린샷 또는 로그
• 후속 작업

사용 방법

이 브랜치에 대한 PR 요약을 생성하기 위해 pr-description 스킬을 사용하세요.

또는:

pr-description 스킬을 사용하고 최신 테스트 실행 결과에서 얻은 테스트 증거를 포함하세요.

가장 도움이 되는 상황

풀 리퀘스트 (pull request)를 열기 직전에 사용하세요. 여러 개의 작은 커밋 (commits)을 하나의 일관된 변경 사항으로 설명해야 할 때 특히 유용합니다.

스킬 4: security-review

위치:

.claude/skills/security-review/SKILL.md

사용 시점

변경 사항이 다음 사항에 영향을 미칠 때 security-review를 사용하세요:

• 인증 (Authentication)
• 권한 부여 (Authorization)
• 세션 처리 (Session handling)
• 입력값 검증 (Input validation)
• 비밀 정보 (Secrets)
• 로깅 (Logging)
• 데이터 액세스 (Data access)
• API 엔드포인트 (API endpoints)
• 파일 업로드 또는 다운로드 (File upload or download)
• 의존성 (Dependencies)
• CI/CD
• 훅 (Hooks)
• MCP 설정 (MCP configuration)
• GitHub Actions
• Claude Code 자동화 (Claude Code automation)

사용 방법

Use the security-review skill to review this change for public repository safety.

또는:

Use the security-review skill to inspect .claude/hooks and .mcp.json before I push this repository public.

해당 스킬이 점검해야 할 사항

스킬은 다음과 같은 질문을 던져야 합니다:

• 어떤 자산 (asset)을 보호하고 있는가?
• 공격자가 무엇에 영향을 미칠 수 있는가?
• 이것이 비밀 정보 (secrets)나 개인 데이터를 노출할 수 있는가?
• 훅 (hook)이 안전하지 않은 명령을 실행할 수 있는가?
• MCP가 예상치 못한 외부 시스템에 연결될 수 있는가?
• 공개 기여자 (public contributors)가 자동화를 악용할 수 있는가?
• 로그 (logs)가 안전한가?
• 권한 (permissions)이 너무 광범위하지 않은가?
• 더 안전한 설계 (design)가 있는가?

가장 도움이 되는 시점

저장소를 공개하기 전, 외부 기여분을 병합(merge)하기 전, 그리고 자동화를 활성화하기 전에 이 스킬을 사용하세요.

단계 5: 프로젝트 슬래시 명령어 (Slash Commands) 추가

명령어는 여기에 위치합니다:

.claude/commands/

이 저장소에는 다음이 포함되어 있습니다:

.claude/commands/review.md
.claude/commands/deploy.md
.claude/commands/scaffold.md
...

스킬 대신 명령어를 사용하는 경우

반복 가능한 워크플로 (workflow)를 위한 짧은 트리거가 필요할 때는 명령어를 사용하세요.

Claude가 작업에 적용할 수 있는 재사용 가능한 전문 지식 (expertise)이 필요할 때는 스킬을 사용하세요.

예를 들어:

/review src/auth

은 Claude에게 리뷰 워크플로를 실행하고 code-review 스킬을 적용하도록 지시할 수 있습니다.

/test src/services

은 Claude에게 testing-patterns 스킬을 적용하도록 지시할 수 있습니다.

/pr

은 Claude에게 pr-description 스킬을 적용하도록 지시할 수 있습니다.

권장되는 명령어 동작

명령어는 다음과 같아야 합니다:

• 인자 (arguments)를 수용할 것
• 무엇을 점검할지 명시할 것
• 위험한 동작을 수행하기 전에 물어볼 것
• 관련 스킬 또는 규칙을 참조할 것
• 일관된 출력을 생성할 것

단계 6: 에이전트 (Agents) 추가

에이전트는 여기에 위치합니다:

.claude/agents/

이 저장소에는 다음이 포함되어 있습니다:

.claude/agents/security-reviewer.md
.claude/agents/test-writer.md
.claude/agents/research.md

에이전트 (Agents) 사용 시점

작업이 특화된 역할이나 격리된 컨텍스트 (Isolated context)를 통해 이점을 얻을 수 있을 때 에이전트를 사용하십시오.

보안에 민감한 작업에는 security-reviewer.md를 사용하십시오.

테스트 설계 및 테스트 구현에는 test-writer.md를 사용하십시오.

문서 검토, 미지의 동작 (Unknown behavior), 또는 기술 검증에는 research.md를 사용하십시오.

프롬프트 예시

머지 (Merge) 전, 이 풀 리퀘스트 (Pull request)의 리스크를 점검하기 위해 보안 리뷰어 에이전트 (Security reviewer agent)를 사용해줘.

실무적 주의사항

에이전트는 유용하지만, 인간의 검토를 피하기 위한 수단이 되어서는 안 됩니다. 에이전트의 결과물은 권장 사항으로 취급하십시오. 머지 (Merge), 배포 (Deploy), 또는 게시 (Publish)에 대한 결정권은 여전히 사용자에게 있습니다.

단계 7: 훅 (Hooks) 주의해서 추가하기

훅 (Hooks)은 여기에 위치합니다:

.claude/hooks/

이 저장소에는 다음과 같은 내용이 포함되어 있습니다: