ChrisWiles/claude-code-showcase

대부분의 소프트웨어 엔지니어들은 현재 LLM 에이전트(LLM agents)가 얼마나 뛰어난지, 특히 Claude Code와 같은 도구들이 얼마나 강력한지 심각하게 간과하고 있습니다.

Claude Code를 한 번 설정해 두면, 여러분의 코드베이스(codebase)를 가리키게 하여 컨벤션(conventions)을 학습시키고, 베스트 프랙티스(best practices)를 가져오며, 기본적으로 초강력 팀원처럼 작동할 때까지 모든 것을 정교하게 다듬을 수 있습니다. 진정한 돌파구는 재사용 가능한 일련의 견고한 "기술(skills)"과 여러분이 항상 수행하는 작업들을 위한 몇 가지 "에이전트(agents)"를 구축하는 것입니다.

커스텀 UI 라이브러리(Custom UI Library)? 우리는 그것을 정확히 어떻게 사용하는지 설명하는 기술을 보유하고 있습니다. 테스트를 작성하는 방식, GraphQL을 구조화하는 방식, 그리고 기본적으로 우리 레포지토리(repo)에서 모든 작업이 수행되기를 원하는 방식도 마찬가지입니다. 따라서 Claude가 코드를 생성할 때, 별도의 설정 없이도 이미 우리의 패턴과 표준에 부합하게 됩니다.

자동화된 품질 게이트(Automated Quality Gates)? 우리는 코드를 자동 포맷팅하고, 테스트 파일이 변경될 때 테스트를 실행하며, TypeScript의 타입을 체크하고, 심지어 메인 브랜치(main branch)에서의 수정을 차단하는 훅(hooks)을 사용합니다. Claude Code는 또한 커스텀 규칙과 리뷰 단계에 도달하기 전에 문제를 포착하는 린트 체크(lint checks)를 포함하여 다양한 ESLint 자동화 기능을 생성했습니다.

심층 코드 리뷰(Deep Code Review)? 우리는 변경 사항이 적용된 후 Claude가 실행하는 코드 리뷰 에이전트를 보유하고 있습니다. 이 에이전트는 TypeScript 엄격 모드(strict mode), 에러 핸들링(error handling), 로딩 상태(loading states), 뮤테이션 패턴(mutation patterns) 등을 다루는 상세한 체크리스트를 따릅니다. PR(Pull Request)이 올라오면, GitHub Action을 통해 자동으로 전체 PR 리뷰를 수행합니다.

예약된 유지보수(Scheduled Maintenance)? 우리는 정해진 일정에 따라 실행되는 GitHub 워크플로(workflow) 에이전트를 운영하고 있습니다:

• 월간 문서 동기화(Monthly docs sync) - 지난 한 달간의 커밋(commits)을 읽어 문서가 여전히 일치하는지 확인합니다.
• 주간 코드 품질(Weekly code quality) - 무작위 디렉토리를 검토하고 문제를 자동으로 수정합니다.
• 격주 의존성 감사(Biweekly dependency audit) - 테스트 검증을 통한 안전한 의존성(dependency) 업데이트를 수행합니다.

지능형 기술 제안(Intelligent Skill Suggestions)? 우리는 모든 프롬프트(prompt)를 분석하여 키워드, 파일 경로 및 의도 패턴(intent patterns)을 기반으로 Claude가 어떤 기술을 활성화해야 하는지 자동으로 제안하는 기술 평가 시스템을 구축했습니다.

수많은 유지보수 및 품질 작업이 그저... 자동화되었습니다. 믿기지 않을 정도로 매끄럽게 작동합니다.

JIRA/Linear 연동? 우리는 MCP (Model Context Protocol) 서버를 통해 Claude Code를 티켓 시스템에 연결합니다. 이제 Claude는 티켓을 읽고, 요구 사항을 이해하며, 기능을 구현하고, 티켓 상태를 업데이트하며, 진행 과정에서 버그를 발견하면 새로운 티켓을 생성하기까지 합니다. /ticket 명령어가 수락 기준 (Acceptance Criteria) 읽기부터 PR (Pull Request)을 티켓에 다시 연결하는 것까지 전체 워크플로우를 처리합니다.

우리는 티켓 분류 (Triage) 작업에도 Claude Code를 사용합니다. Claude가 티켓을 읽고, 코드베이스를 조사한 뒤, 무엇을 해야 하는지에 대한 의견을 댓글로 남깁니다. 따라서 엔지니어가 해당 작업을 맡게 되면, 이미 절반은 진행된 상태에서 시작하는 것과 다름없습니다.

이 분야에는 즉각적인 효과를 볼 수 있는 요소 (Low-hanging fruit)가 너무나 많아서, 사람들이 왜 아직 다들 달려들지 않는지 솔직히 이해가 안 될 정도입니다.

• 디렉토리 구조 (Directory Structure)
• 빠른 시작 (Quick Start)
• 설정 참조 (Configuration Reference)
• GitHub Actions 워크플로우 (Workflows)
• 모범 사례 (Best Practices)
• 이 리포지토리의 예시 (Examples in This Repository)

your-project/
├── CLAUDE.md # 프로젝트 메모리 (대체 위치)
├── .mcp.json # MCP 서버 설정 (JIRA, GitHub 등)
...

mkdir -p .claude/{agents,commands,hooks,skills}

프로젝트 루트에 프로젝트의 핵심 정보가 담긴 CLAUDE.md를 생성하세요. 전체 예시는 CLAUDE.md를 참조하십시오.

# 프로젝트 이름
## 주요 정보
- **스택 (Stack)**: React, TypeScript, Node.js
...

.claude/settings.json을 생성하세요. 자동 포맷팅, 테스트 등이 포함된 전체 예시는 settings.json을 참조하십시오.

{
"hooks": {
"PreToolUse": [
...

.claude/skills/testing-patterns/SKILL.md를 생성하세요. 포괄적인 예시는 testing-patterns/SKILL.md를 참조하십시오.

---
name: testing-patterns
description: 이 프로젝트를 위한 Jest 테스트 패턴입니다. 테스트 작성, 모킹 (Mocking) 생성, 또는 TDD (Test-Driven Development) 워크플로우를 따를 때 사용하세요.
...

팁: description 필드는 매우 중요합니다. Claude는 이 필드를 사용하여 언제 해당 기술 (Skill)을 적용할지 결정합니다. 사용자가 자연스럽게 언급할 만한 키워드를 포함하세요.

CLAUDE.md는 세션 시작 시 자동으로 로드되는 Claude의 지속성 메모리 (Persistent Memory)입니다.

위치 (우선순위 순):

.claude/CLAUDE.md

(프로젝트, .claude 폴더 내) ./CLAUDE.md

(프로젝트 루트) ~/.claude/CLAUDE.md

(사용자 수준, 모든 프로젝트)

포함할 내용:

• 프로젝트 스택 및 아키텍처 개요
• 주요 명령어 (test, build, lint, deploy)
• 코드 스타일 가이드라인
• 중요한 디렉토리 및 그 용도
• 핵심 규칙 및 제약 사항

📄 예시: CLAUDE.md

훅 (hooks), 환경 변수 (environment variables), 그리고 권한 (permissions)을 위한 메인 설정 파일입니다.

위치: .claude/settings.json

📄 예시: settings.json | 사람이 읽을 수 있는 문서

이벤트	발생 시점	사용 사례
PreToolUse	도구 실행 전	main 브랜치 수정 차단, 명령어 검증
PostToolUse	도구 완료 후	자동 포맷팅 (Auto-format), 테스트 실행, 린트 (lint)
UserPromptSubmit	사용자가 프롬프트 제출 시	컨텍스트 추가, 기술 제안
Stop	에이전트 종료 시	Claude의 계속 진행 여부 결정

{
"block": true, // 동작 차단 (PreToolUse에서만 해당)
"message": "사유", // 사용자에게 보여줄 메시지
...

0

• 성공2

• 차단 오류 (PreToolUse에서만 해당, 도구 차단)- 기타 - 비차단 오류

MCP (Model Context Protocol) 서버를 통해 Claude Code는 JIRA, GitHub, Slack, 데이터베이스 등과 같은 외부 도구에 연결할 수 있습니다. 이를 통해 "티켓을 읽고, 구현한 뒤, 티켓 상태를 업데이트하는" 것과 같은 워크플로우를 활성화할 수 있습니다.

위치: .mcp.json

(프로젝트 루트, 팀 공유를 위해 git에 커밋됨)

📄 예시: .mcp.json

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Claude Code │────▶│ MCP Server │────▶│ External API │
│ │◀────│ (로컬 브리지) │◀────│ (JIRA, GitHub) │
...

MCP 서버는 로컬에서 실행되며 Claude에게 외부 서비스와 상호작용할 수 있는 도구를 제공합니다. JIRA MCP 서버를 구성하면 Claude는 jira_get_issue, jira_update_issue, jira_create_issue 등의 도구를 갖게 됩니다.

{
"mcpServers": {
"server-name": {
...

필드 (Fields):

필드 (Field)	필수 여부 (Required)	설명 (Description)
type	예	서버 유형: stdio (로컬 프로세스) 또는 http (원격)
command	stdio의 경우 필수	실행할 실행 파일 (예: npx, python)
args	아니요	명령줄 인자 (Command-line arguments)
env	아니요	환경 변수 (Environment variables) (${VAR} 확장을 지원)
url	http의 경우 필수	원격 서버 URL
headers	http의 경우 필수	인증을 위한 HTTP 헤더

{
"mcpServers": {
"jira": {
...

이를 통해 가능한 작업:

• 티켓 상세 정보, 수락 기준 (Acceptance criteria) 및 댓글 읽기
• 티켓 상태 업데이트 (To Do → In Progress → In Review)
• 진행 상황 업데이트가 포함된 댓글 추가
• 개발 중 발견된 버그에 대한 새 티켓 생성
• PR (Pull Request)을 티켓에 연결

/ticket 명령어를 사용한 예시 워크플로우:

사용자: /ticket PROJ-123
Claude:
1. JIRA에서 PROJ-123을 가져오는 중...
...

이슈 트래킹 (Issue Tracking):

{
"jira": {
"type": "stdio",
...

코드 및 DevOps:

{
"github": {
"type": "stdio",
...

커뮤니케이션:

{
"slack": {
"type": "stdio",
...

데이터베이스:

{
"postgres": {
"type": "stdio",
...

MCP 설정은 변수 확장 (Variable expansion)을 지원합니다:

${VAR}

• 환경 변수로 확장됩니다 (설정되어 있지 않으면 실패함)

${VAR:-default}

• VAR가 설정되어 있지 않으면 기본값(default)을 사용합니다

이 값들을 셸 프로필(Shell profile)이나 .env 파일에 설정하세요 (비밀 정보는 커밋하지 마세요!):

export JIRA_HOST="https://yourcompany.atlassian.net"
export JIRA_EMAIL="you@company.com"
export JIRA_API_TOKEN="your-api-token"

settings.json에서 MCP 서버를 자동 승인할 수 있습니다:

{
"enableAllProjectMcpServers": true
}

또는 특정 서버만 승인할 수 있습니다:

{
"enabledMcpjsonServers": ["jira", "github", "slack"]
}

LSP (Language Server Protocol)는 Claude에게 코드 유형 정보, 오류, 완성(Completions) 및 탐색(Navigation)과 같은 실시간 코드 이해 능력을 제공합니다. 단순히 텍스트를 읽는 대신, Claude는 사용자의 IDE가 코드를 보는 것과 동일한 방식으로 코드를 "볼" 수 있습니다.

이것이 중요한 이유: TypeScript를 편집할 때, Claude는 사용자가 타입 오류(type error)를 발생시켰는지 즉시 파악합니다. 함수를 참조할 때, Claude는 해당 함수의 정의(definition)로 바로 이동할 수 있습니다. 이는 코드 생성(code generation) 품질을 극적으로 향상시킵니다.

LSP 지원은 settings.json 내의 플러그인을 통해 활성화됩니다:

{
"enabledPlugins": {
"typescript-lsp@claude-plugins-official": true,
...

기능	설명
진단 (Diagnostics)	모든 편집 후 실시간 오류 및 경고
타입 정보 (Type Information)	호버(Hover) 정보, 함수 시그니처 (function signatures), 타입 정의
코드 탐색 (Code Navigation)	정의로 이동 (Go to definition), 참조 찾기 (find references)
완성 (Completions)	문맥을 인식하는 심볼 제안 (Context-aware symbol suggestions)

플러그인	언어	바이너리 우선 설치
typescript-lsp	TypeScript/JavaScript	npm install -g typescript-language-server typescript
pyright-lsp	Python	pip install pyright
rust-lsp	Rust	rustup component add rust-analyzer

고급 설정을 위해 .lsp.json을 생성하세요:

{
"typescript": {
"command": "typescript-language-server",
...

LSP가 작동하지 않는 경우:

• 바이너리가 설치되었는지 확인: which typescript-language-server # 경로가 반환되어야 함
• 디버그 로깅 활성화: claude --enable-lsp-logging
• 플러그인 상태 확인: claude /plugin # Errors 탭 확인

우리의 가장 강력한 자동화 기능 중 하나는 **기술 평가 시스템 (skill evaluation system)**입니다. 이 시스템은 모든 프롬프트 제출 시 실행되며, Claude가 어떤 기술을 활성화해야 하는지 지능적으로 제안합니다.

📄 파일: skill-eval.sh | skill-eval.js | skill-rules.json

프롬프트를 제출하면 UserPromptSubmit 훅(hook)이 기술 평가 엔진을 트리거합니다:

• 프롬프트 분석 (Prompt Analysis) - 엔진은 다음 항목을 기준으로 프롬프트를 분석합니다:

  • 키워드 (Keywords): 단순 단어 매칭 (test, form, graphql, bug)
  • 패턴 (Patterns): 정규 표현식 (Regex) 매칭 (\btest(?:s|ing)?\b, \.stories\.)
  • 파일 경로 (File Paths): 언급된 파일 추출 (src/components/Button.tsx)
  • 의도 (Intent): 수행하려는 작업 감지 (create.*test, fix.*bug)

디렉토리 매핑 (Directory Mapping)

• 파일 경로가 관련 기술 (Skills)에 매핑됩니다:
  { "src/components/core": "core-components", "src/graphql": "graphql-schema", ".github/workflows": "github-actions", "src/hooks": "react-ui-patterns" }

신뢰도 점수 산정 (Confidence Scoring)

• 각 트리거 (Trigger) 유형은 점수 값을 가집니다:
  { "keyword": 2, "keywordPattern": 3, "pathPattern": 4, "directoryMatch": 5, "intentPattern": 4 }

기술 제안 (Skill Suggestion)

• 신뢰도 임계값 (Confidence threshold)을 초과하는 기술이 이유와 함께 제안됩니다:
  SKILL ACTIVATION REQUIRED Detected file paths: src/components/UserForm.tsx Matched skills (ranked by relevance): 1. formik-patterns (HIGH confidence) Matched: keyword "form", path "src/components/UserForm.tsx" 2. react-ui-patterns (MEDIUM confidence) Matched: directory mapping, keyword "component"

기술 (Skills)은 skill-rules.json에 정의됩니다:

{
"testing-patterns": {
"description": "Jest testing patterns and TDD workflow",
...

훅 (Hooks)을 프로젝트로 복사하세요:

cp -r .claude/hooks/ your-project/.claude/hooks/

settings.json에 훅을 추가하세요:

:{ "hooks": { "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": ""$CLAUDE_PROJECT_DIR"/.claude/hooks/skill-eval.sh", "timeout": 5 } ] } ] } }

프로젝트의 기술 (Skills)과 트리거 (Triggers)에 맞춰 skill-rules.json을 커스텀하세요.

기술 (Skills)은 Claude에게 프로젝트 특화 패턴과 컨벤션 (Conventions)을 가르치는 마크다운 (Markdown) 문서입니다.

위치: .claude/skills/{skill-name}/SKILL.md

📄 예시:

• testing-patterns - TDD, 팩토리 함수 (factory functions), 모킹 (mocking)
• systematic-debugging - 4단계 디버깅 방법론 (Four-phase debugging methodology)
• react-ui-patterns - 로딩 상태 (Loading states), 에러 핸들링 (error handling)
• graphql-schema - 쿼리 (Queries), 뮤테이션 (mutations), 코드 생성 (codegen)
• core-components - 디자인 시스템 (Design system), 토큰 (tokens)
• formik-patterns - 폼 핸들링 (Form handling), 유효성 검사 (validation)

필드 (Field)	필수 여부 (Required)	최대 길이 (Max Length)	설명 (Description)
name	예 (Yes)	64자 (chars)	소문자, 숫자, 하이픈만 허용됩니다. 디렉토리 이름과 일치해야 합니다.
description	예 (Yes)	1024자 (chars)	해당 스킬이 무엇을 하는지, 그리고 언제 사용하는지에 대한 내용입니다. Claude는 이 설명을 바탕으로 언제 스킬을 적용할지 결정합니다.
allowed-tools	아니오 (No)	-	Claude가 사용할 수 있는 도구들의 쉼표로 구분된 목록입니다 (예: Read, Grep, Bash(npm:*)).
model	아니오 (No)	-	사용할 특정 모델입니다 (예: claude-sonnet-4-20250514).

---
name: skill-name
description: 이 스킬이 무엇을 하는지, 그리고 언제 사용하는지에 대한 내용입니다. 사용자가 언급할 만한 키워드를 포함하세요.
...
```typescript
// 예시 코드 (Example code)

// 잘못된 예시 (Bad example)