The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs(ko-KR): add Korean translation for examples
hahmee526a9070e649
diff --git a/docs/ko-KR/examples/CLAUDE.md b/docs/ko-KR/examples/CLAUDE.mdnew file mode 100644index 000000000..5f89b82d4--- /dev/null+++ b/docs/ko-KR/examples/CLAUDE.md@@ -0,0 +1,100 @@+# 프로젝트 CLAUDE.md 예제++프로젝트 수준의 CLAUDE.md 파일 예제입니다. 프로젝트 루트에 배치하세요.++## 프로젝트 개요++[프로젝트에 대한 간단한 설명 - 기능, 기술 스택]++## 핵심 규칙++### 1. 코드 구성++- 큰 파일 소수보다 작은 파일 다수를 선호+- 높은 응집도, 낮은 결합도+- 일반적으로 200-400줄, 파일당 최대 800줄+- 타입별이 아닌 기능/도메인별로 구성++### 2. 코드 스타일++- 코드, 주석, 문서에 이모지 사용 금지+- 항상 불변성 유지 - 객체나 배열을 직접 변경하지 않음+- 프로덕션 코드에 console.log 사용 금지+- try/catch를 사용한 적절한 에러 처리+- Zod 또는 유사 라이브러리를 사용한 입력 유효성 검사++### 3. 테스트++- TDD: 테스트를 먼저 작성+- 최소 80% 커버리지+- 유틸리티에 대한 단위 테스트+- API에 대한 통합 테스트+- 핵심 흐름에 대한 E2E 테스트++### 4. 보안++- 하드코딩된 시크릿 금지+- 민감한 데이터는 환경 변수 사용+- 모든 사용자 입력 유효성 검사+- 매개변수화된 쿼리만 사용+- CSRF 보호 활성화++## 파일 구조++```+src/+|-- app/ # Next.js app router+|-- components/ # 재사용 가능한 UI 컴포넌트+|-- hooks/ # 커스텀 React hooks+|-- lib/ # 유틸리티 라이브러리+|-- types/ # TypeScript 타입 정의+```++## 주요 패턴++### API 응답 형식++```typescript+interface ApiResponse<T> {+ success: boolean+ data?: T+ error?: string+}+```++### 에러 처리++```typescript+try {+ const result = await operation()+ return { success: true, data: result }+} catch (error) {+ console.error('Operation failed:', error)+ return { success: false, error: 'User-friendly message' }+}+```++## 환경 변수++```bash+# 필수+DATABASE_URL=+API_KEY=++# 선택+DEBUG=false+```++## 사용 가능한 명령어++- `/tdd` - 테스트 주도 개발 워크플로우+- `/plan` - 구현 계획 생성+- `/code-review` - 코드 품질 리뷰+- `/build-fix` - 빌드 에러 수정++## Git 워크플로우++- Conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`+- main 브랜치에 직접 커밋 금지+- PR은 리뷰 필수+- 병합 전 모든 테스트 통과 필수diff --git a/docs/ko-KR/examples/django-api-CLAUDE.md b/docs/ko-KR/examples/django-api-CLAUDE.mdnew file mode 100644index 000000000..18cd261cb--- /dev/null+++ b/docs/ko-KR/examples/django-api-CLAUDE.md@@ -0,0 +1,308 @@+# Django REST API — 프로젝트 CLAUDE.md++> PostgreSQL과 Celery를 사용하는 Django REST Framework API의 실전 예시입니다.+> 프로젝트 루트에 복사하여 서비스에 맞게 커스터마이즈하세요.++## 프로젝트 개요++**기술 스택:** Python 3.12+, Django 5.x, Django REST Framework, PostgreSQL, Celery + Redis, pytest, Docker Compose++**아키텍처:** 비즈니스 도메인별 앱으로 구성된 도메인 주도 설계. API 레이어에 DRF, 비동기 작업에 Celery, 테스트에 pytest 사용. 모든 엔드포인트는 JSON을 반환하며 템플릿 렌더링은 없음.++## 필수 규칙++### Python 규칙++- 모든 함수 시그니처에 type hints 사용 — `from __future__ import annotations` 사용+- `print()` 문 사용 금지 — `logging.getLogger(__name__)` 사용+- 문자열 포매팅은 f-strings 사용, `%`나 `.format()`은 사용 금지+- 파일 작업에 `os.path` 대신 `pathlib.Path` 사용+- isort로 import 정렬: stdlib, third-party, local 순서 (ruff에 의해 강제)++### 데이터베이스++- 모든 쿼리는 Django ORM 사용 — raw SQL은 `.raw()`와 parameterized 쿼리로만 사용+- 마이그레이션은 git에 커밋 — 프로덕션에서 `--fake` 사용 금지+- N+1 쿼리 방지를 위해 `select_related()`와 `prefetch_related()` 사용+- 모든 모델에 `created_at`과 `updated_at` 자동 필드 필수+- `filter()`, `order_by()`, 또는 `WHERE` 절에 사용되는 모든 필드에 인덱스 추가++```python+# 나쁜 예: N+1 쿼리+orders = Order.objects.all()+for order in orders:+ print(order.customer.name) # 각 주문마다 DB를 조회함++# 좋은 예: join을 사용한 단일 쿼리+orders = Order.objects.select_related("customer").all()+```++### 인증++- `djangorestframework-simplejwt`를 통한 JWT — access token (15분) + refresh token (7일)+- 모든 뷰에 permission 클래스 지정 — 기본값에 의존하지 않기+- `IsAuthenticated`를 기본으로, 객체 수준 접근에는 커스텀 permission 추가+- 로그아웃을 위한 token blacklisting 활성화++### Serializers++- 간단한 CRUD에는 `ModelSerializer`, 복잡한 유효성 검증에는 `Serializer` 사용+- 입력/출력 형태가 다를 때는 읽기와 쓰기 serializer를 분리+- 유효성 검증은 serializer 레벨에서 — 뷰는 얇게 유지++```python+class CreateOrderSerializer(serializers.Serializer):+ product_id = serializers.UUIDField()+ quantity = serializers.IntegerField(min_value=1, max_value=100)++ def validate_product_id(self, value):+ if not Product.objects.filter(id=value, active=True).exists():+ raise serializers.ValidationError("Product not found or inactive")+ return value++class OrderDetailSerializer(serializers.ModelSerializer):+ customer = CustomerSerializer(read_only=True)+ product = ProductSerializer(read_only=True)++ class Meta:+ model = Order+ fields = ["id", "customer", "product", "quantity", "total", "status", "created_at"]+```++### 오류 처리++- 일관된 오류 응답을 위해 DRF exception handler 사용+- 비즈니스 로직용 커스텀 예외는 `core/exceptions.py`에 정의+- 클라이언트에 내부 오류 세부 정보를 노출하지 않기++```python+# core/exceptions.py+from rest_framework.exceptions import APIException++class InsufficientStockError(APIException):+ status_code = 409+ default_detail = "Insufficient stock for this order"+ default_code = "insufficient_stock"+```++### 코드 스타일++- 코드나 주석에 이모지 사용 금지+- 최대 줄 길이: 120자 (ruff에 의해 강제)+- 클래스: PascalCase, 함수/변수: snake_case, 상수: UPPER_SNAKE_CASE+- 뷰는 얇게 유지 — 비즈니스 로직은 서비스 함수나 모델 메서드에 배치++## 파일 구조++```+config/+ settings/+ base.py # 공유 설정+ local.py # 개발 환경 오버라이드 (DEBUG=True)+ production.py # 프로덕션 설정+ urls.py # 루트 URL 설정+ celery.py # Celery 앱 설정+apps/+ accounts/ # 사용자 인증, 회원가입, 프로필+ models.py+ serializers.py+ views.py+ services.py # 비즈니스 로직+ tests/+ test_views.py+ test_services.py+ factories.py # Factory Boy 팩토리+ orders/ # 주문 관리+ models.py+ serializers.py+ views.py+ services.py+ tasks.py # Celery 작업+ tests/+ products/ # 상품 카탈로그+ models.py+ serializers.py+ views.py+ tests/+core/+ exceptions.py # 커스텀 API 예외+ permissions.py # 공유 permission 클래스+ pagination.py # 커스텀 페이지네이션+ middleware.py # 요청 로깅, 타이밍+ tests/+```++## 주요 패턴++### Service 레이어++```python+# apps/orders/services.py+from django.db import transaction++def create_order(*, customer, product_id: uuid.UUID, quantity: int) -> Order:+ """재고 검증과 결제 보류를 포함한 주문 생성."""+ product = Product.objects.select_for_update().get(id=product_id)++ if product.stock < quantity:+ raise InsufficientStockError()++ with transaction.atomic():+ order = Order.objects.create(+ customer=customer,+ product=product,+ quantity=quantity,+ total=product.price * quantity,+ )+ product.stock -= quantity+ product.save(update_fields=["stock", "updated_at"])++ # 비동기: 주문 확인 이메일 발송+ send_order_confirmation.delay(order.id)+ return order+```++### View 패턴++```python+# apps/orders/views.py+class OrderViewSet(viewsets.ModelViewSet):+ permission_classes = [IsAuthenticated]+ pagination_class = StandardPagination++ def get_serializer_class(self):+ if self.action == "create":+ return CreateOrderSerializer+ return OrderDetailSerializer++ def get_queryset(self):+ return (+ Order.objects+ .filter(customer=self.request.user)+ .select_related("product", "customer")+ .order_by("-created_at")+ )++ def perform_create(self, serializer):+ order = create_order(+ customer=self.request.user,+ product_id=serializer.validated_data["product_id"],+ quantity=serializer.validated_data["quantity"],+ )+ serializer.instance = order+```++### 테스트 패턴 (pytest + Factory Boy)++```python+# apps/orders/tests/factories.py+import factory+from apps.accounts.tests.factories import UserFactory+from apps.products.tests.factories import ProductFactory++class OrderFactory(factory.django.DjangoModelFactory):+ class Meta:+ model = "orders.Order"++ customer = factory.SubFactory(UserFactory)+ product = factory.SubFactory(ProductFactory, stock=100)+ quantity = 1+ total = factory.LazyAttribute(lambda o: o.product.price * o.quantity)++# apps/orders/tests/test_views.py+import pytest+from rest_framework.test import APIClient++class TestCreateOrder:+ def setup_method(self):+ self.client = APIClient()+ self.user = UserFactory()+ self.client.force_authenticate(self.user)++ def test_create_order_success(self):+ product = ProductFactory(price=29_99, stock=10)+ response = self.client.post("/api/orders/", {+ "product_id": str(product.id),+ "quantity": 2,+ })+ assert response.status_code == 201+ assert response.data["total"] == 59_98++ def test_create_order_insufficient_stock(self):+ product = ProductFactory(stock=0)+ response = self.client.post("/api/orders/", {+ "product_id": str(product.id),+ "quantity": 1,+ })+ assert response.status_code == 409++ def test_create_order_unauthenticated(self):+ self.client.force_authenticate(None)+ response = self.client.post("/api/orders/", {})+ assert response.status_code == 401+```++## 환경 변수++```bash+# Django+SECRET_KEY=+DEBUG=False+ALLOWED_HOSTS=api.example.com++# 데이터베이스+DATABASE_URL=postgres://user:pass@localhost:5432/myapp++# Redis (Celery broker + 캐시)+REDIS_URL=redis://localhost:6379/0++# JWT+JWT_ACCESS_TOKEN_LIFETIME=15 # 분+JWT_REFRESH_TOKEN_LIFETIME=10080 # 분 (7일)++# 이메일+EMAIL_BACKEND=django.core.mail.backends.smtp.EmailBackend+EMAIL_HOST=smtp.example.com+```++## 테스트 전략++```bash+# 전체 테스트 실행+pytest --cov=apps --cov-report=term-missing++# 특정 앱 테스트 실행+pytest apps/orders/tests/ -v++# 병렬 실행+pytest -n auto++# 마지막 실행에서 실패한 테스트만 실행+pytest --lf+```++## ECC 워크플로우++```bash+# 계획 수립+/plan "Add order refund system with Stripe integration"++# TDD로 개발+/tdd # pytest 기반 TDD 워크플로우++# 리뷰+/python-review # Python 전용 코드 리뷰+/security-scan # Django 보안 감사+/code-review # 일반 품질 검사++# 검증+/verify # 빌드, 린트, 테스트, 보안 스캔+```++## Git 워크플로우++- `feat:` 새 기능, `fix:` 버그 수정, `refactor:` 코드 변경+- `main`에서 feature 브랜치 생성, PR 필수+- CI: ruff (린트 + 포맷), mypy (타입), pytest (테스트), safety (의존성 검사)+- 배포: Docker 이미지, Kubernetes 또는 Railway로 관리diff --git a/docs/ko-KR/examples/go-microservice-CLAUDE.md b/docs/ko-KR/examples/go-microservice-CLAUDE.mdnew file mode 100644index 000000000..1966008fd--- /dev/null+++ b/docs/ko-KR/examples/go-microservice-CLAUDE.md@@ -0,0 +1,267 @@+# Go Microservice — 프로젝트 CLAUDE.md++> PostgreSQL, gRPC, Docker를 사용하는 Go 마이크로서비스의 실전 예시입니다.+> 프로젝트 루트에 복사하여 서비스에 맞게 커스터마이즈하세요.++## 프로젝트 개요++**기술 스택:** Go 1.22+, PostgreSQL, gRPC + REST (grpc-gateway), Docker, sqlc (타입 안전 SQL), Wire (의존성 주입)++**아키텍처:** domain, repository, service, handler 레이어로 구성된 클린 아키텍처. gRPC를 기본 전송 프로토콜로 사용하고, 외부 클라이언트를 위한 REST gateway 제공.++## 필수 규칙++### Go 규칙++- Effective Go와 Go Code Review Comments 가이드를 따를 것+- 오류 래핑에 `errors.New` / `fmt.Errorf`와 `%w` 사용 — 오류를 문자열 매칭하지 않기+- `init()` 함수 사용 금지 — `main()`이나 생성자에서 명시적으로 초기화+- 전역 가변 상태 금지 — 생성자를 통해 의존성 전달+- Context는 반드시 첫 번째 매개변수이며 모든 레이어를 통해 전파++### 데이터베이스++- 모든 쿼리는 `queries/`에 순수 SQL로 작성 — sqlc가 타입 안전한 Go 코드를 생성+- 마이그레이션은 `migrations/`에 golang-migrate 사용 — 데이터베이스를 직접 변경하지 않기+- 다중 단계 작업에는 `pgx.Tx`를 통한 트랜잭션 사용+- 모든 쿼리에 parameterized placeholder (`$1`, `$2`) 사용 — 문자열 포매팅 사용 금지++### 오류 처리++- 오류를 반환하고, panic하지 않기 — panic은 진정으로 복구 불가능한 상황에만 사용+- 컨텍스트와 함께 오류 래핑: `fmt.Errorf("creating user: %w", err)`+- 비즈니스 로직을 위한 sentinel 오류는 `domain/errors.go`에 정의+- handler 레이어에서 도메인 오류를 gRPC status 코드로 매핑++```go+// 도메인 레이어 — sentinel 오류+var (+ ErrUserNotFound = errors.New("user not found")+ ErrEmailTaken = errors.New("email already registered")+)++// Handler 레이어 — gRPC status로 매핑+func toGRPCError(err error) error {+ switch {+ case errors.Is(err, domain.ErrUserNotFound):+ return status.Error(codes.NotFound, err.Error())+ case errors.Is(err, domain.ErrEmailTaken):+ return status.Error(codes.AlreadyExists, err.Error())+ default:+ return status.Error(codes.Internal, "internal error")+ }+}+```++### 코드 스타일++- 코드나 주석에 이모지 사용 금지+- 외부로 공개되는 타입과 함수에는 반드시 doc 주석 작성+- 함수는 50줄 이하로 유지 — 헬퍼 함수로 분리+- 여러 케이스가 있는 모든 로직에 table-driven 테스트 사용+- signal 채널에는 `bool`이 아닌 `struct{}` 사용++## 파일 구조++```+cmd/+ server/+ main.go # 진입점, Wire 주입, 우아한 종료+internal/+ domain/ # 비즈니스 타입과 인터페이스+ user.go # User 엔티티와 repository 인터페이스+ errors.go # Sentinel 오류+ service/ # 비즈니스 로직+ user_service.go+ user_service_test.go+ repository/ # 데이터 접근 (sqlc 생성 + 커스텀)+ postgres/+ user_repo.go+ user_repo_test.go # testcontainers를 사용한 통합 테스트+ handler/ # gRPC + REST 핸들러+ grpc/+ user_handler.go+ rest/+ user_handler.go+ config/ # 설정 로딩+ config.go+proto/ # Protobuf 정의+ user/v1/+ user.proto+queries/ # sqlc용 SQL 쿼리+ user.sql+migrations/ # 데이터베이스 마이그레이션+ 001_create_users.up.sql+ 001_create_users.down.sql+```++## 주요 패턴++### Repository 인터페이스++```go+type UserRepository interface {+ Create(ctx context.Context, user *User) error+ FindByID(ctx context.Context, id uuid.UUID) (*User, error)+ FindByEmail(ctx context.Context, email string) (*User, error)+ Update(ctx context.Context, user *User) error+ Delete(ctx context.Context, id uuid.UUID) error+}+```++### 의존성 주입을 사용한 Service++```go+type UserService struct {+ repo domain.UserRepository+ hasher PasswordHasher+ logger *slog.Logger+}++func NewUserService(repo domain.UserRepository, hasher PasswordHasher, logger *slog.Logger) *UserService {+ return &UserService{repo: repo, hasher: hasher, logger: logger}+}++func (s *UserService) Create(ctx context.Context, req CreateUserRequest) (*domain.User, error) {+ existing, err := s.repo.FindByEmail(ctx, req.Email)+ if err != nil && !errors.Is(err, domain.ErrUserNotFound) {+ return nil, fmt.Errorf("checking email: %w", err)+ }+ if existing != nil {+ return nil, domain.ErrEmailTaken+ }++ hashed, err := s.hasher.Hash(req.Password)+ if err != nil {+ return nil, fmt.Errorf("hashing password: %w", err)+ }++ user := &domain.User{+ ID: uuid.New(),+ Name: req.Name,+ Email: req.Email,+ Password: hashed,+ }+ if err := s.repo.Create(ctx, user); err != nil {+ return nil, fmt.Errorf("creating user: %w", err)+ }+ return user, nil+}+```++### Table-Driven 테스트++```go+func TestUserService_Create(t *testing.T) {+ tests := []struct {+ name string+ req CreateUserRequest+ setup func(*MockUserRepo)+ wantErr error+ }{+ {+ name: "valid user",+ req: CreateUserRequest{Name: "Alice", Email: "[email protected]", Password: "secure123"},+ setup: func(m *MockUserRepo) {+ m.On("FindByEmail", mock.Anything, "[email protected]").Return(nil, domain.ErrUserNotFound)+ m.On("Create", mock.Anything, mock.Anything).Return(nil)+ },+ wantErr: nil,+ },+ {+ name: "duplicate email",+ req: CreateUserRequest{Name: "Alice", Email: "[email protected]", Password: "secure123"},+ setup: func(m *MockUserRepo) {+ m.On("FindByEmail", mock.Anything, "[email protected]").Return(&domain.User{}, nil)+ },+ wantErr: domain.ErrEmailTaken,+ },+ }++ for _, tt := range tests {+ t.Run(tt.name, func(t *testing.T) {+ repo := new(MockUserRepo)+ tt.setup(repo)+ svc := NewUserService(repo, &bcryptHasher{}, slog.Default())++ _, err := svc.Create(context.Background(), tt.req)++ if tt.wantErr != nil {+ assert.ErrorIs(t, err, tt.wantErr)+ } else {+ assert.NoError(t, err)+ }+ })+ }+}+```++## 환경 변수++```bash+# 데이터베이스+DATABASE_URL=postgres://user:pass@localhost:5432/myservice?sslmode=disable++# gRPC+GRPC_PORT=50051+REST_PORT=8080++# 인증+JWT_SECRET= # 프로덕션에서는 vault에서 로드+TOKEN_EXPIRY=24h++# 관측 가능성+LOG_LEVEL=info # debug, info, warn, error+OTEL_ENDPOINT= # OpenTelemetry 콜렉터+```++## 테스트 전략++```bash+/go-test # Go용 TDD 워크플로우+/go-review # Go 전용 코드 리뷰+/go-build # 빌드 오류 수정+```++### 테스트 명령어++```bash+# 단위 테스트 (빠름, 외부 의존성 없음)+go test ./internal/... -short -count=1++# 통합 테스트 (testcontainers를 위해 Docker 필요)+go test ./internal/repository/... -count=1 -timeout 120s++# 전체 테스트와 커버리지+go test ./... -coverprofile=coverage.out -count=1+go tool cover -func=coverage.out # 요약+go tool cover -html=coverage.out # 브라우저++# Race detector+go test ./... -race -count=1+```++## ECC 워크플로우++```bash+# 계획 수립+/plan "Add rate limiting to user endpoints"++# 개발+/go-test # Go 전용 패턴으로 TDD++# 리뷰+/go-review # Go 관용구, 오류 처리, 동시성+/security-scan # 시크릿 및 취약점 점검++# 머지 전 확인+go vet ./...+staticcheck ./...+```++## Git 워크플로우++- `feat:` 새 기능, `fix:` 버그 수정, `refactor:` 코드 변경+- `main`에서 feature 브랜치 생성, PR 필수+- CI: `go vet`, `staticcheck`, `go test -race`, `golangci-lint`+- 배포: CI에서 Docker 이미지 빌드, Kubernetes에 배포diff --git a/docs/ko-KR/examples/rust-api-CLAUDE.md b/docs/ko-KR/examples/rust-api-CLAUDE.mdnew file mode 100644index 000000000..0f05c8b26--- /dev/null+++ b/docs/ko-KR/examples/rust-api-CLAUDE.md@@ -0,0 +1,285 @@+# Rust API Service — 프로젝트 CLAUDE.md++> Axum, PostgreSQL, Docker를 사용하는 Rust API 서비스의 실전 예시입니다.+> 프로젝트 루트에 복사하여 서비스에 맞게 커스터마이즈하세요.++## 프로젝트 개요++**기술 스택:** Rust 1.78+, Axum (웹 프레임워크), SQLx (비동기 데이터베이스), PostgreSQL, Tokio (비동기 런타임), Docker++**아키텍처:** handler -> service -> repository로 분리된 레이어드 아키텍처. HTTP에 Axum, 컴파일 타임에 타입이 검증되는 SQL에 SQLx, 횡단 관심사에 Tower 미들웨어 사용.++## 필수 규칙++### Rust 규칙++- 라이브러리 오류에 `thiserror`, 바이너리 크레이트나 테스트에서만 `anyhow` 사용+- 프로덕션 코드에서 `.unwrap()`이나 `.expect()` 사용 금지 — `?`로 오류 전파+- 함수 매개변수에 `String`보다 `&str` 선호; 소유권 이전 시 `String` 반환+- `#![deny(clippy::all, clippy::pedantic)]`과 함께 `clippy` 사용 — 모든 경고 수정+- 모든 공개 타입에 `Debug` derive; `Clone`, `PartialEq`는 필요할 때만 derive+- `// SAFETY:` 주석으로 정당화하지 않는 한 `unsafe` 블록 사용 금지++### 데이터베이스++- 모든 쿼리에 SQLx `query!` 또는 `query_as!` 매크로 사용 — 스키마에 대해 컴파일 타임에 검증+- 마이그레이션은 `migrations/`에 `sqlx migrate` 사용 — 데이터베이스를 직접 변경하지 않기+- 공유 상태로 `sqlx::Pool<Postgres>` 사용 — 요청마다 커넥션을 생성하지 않기+- 모든 쿼리에 parameterized placeholder (`$1`, `$2`) 사용 — 문자열 포매팅 사용 금지++```rust+// 나쁜 예: 문자열 보간 (SQL injection 위험)+let q = format!("SELECT * FROM users WHERE id = '{}'", id);++// 좋은 예: parameterized 쿼리, 컴파일 타임에 검증+let user = sqlx::query_as!(User, "SELECT * FROM users WHERE id = $1", id)+ .fetch_optional(&pool)+ .await?;+```++### 오류 처리++- 모듈별로 `thiserror`를 사용한 도메인 오류 enum 정의+- `IntoResponse`를 통해 오류를 HTTP 응답으로 매핑 — 내부 세부 정보를 노출하지 않기+- 구조화된 로깅에 `tracing` 사용 — `println!`이나 `eprintln!` 사용 금지++```rust+use thiserror::Error;++#[derive(Debug, Error)]+pub enum AppError {+ #[error("Resource not found")]+ NotFound,+ #[error("Validation failed: {0}")]+ Validation(String),+ #[error("Unauthorized")]+ Unauthorized,+ #[error(transparent)]+ Internal(#[from] anyhow::Error),+}++impl IntoResponse for AppError {+ fn into_response(self) -> Response {+ let (status, message) = match &self {+ Self::NotFound => (StatusCode::NOT_FOUND, self.to_string()),+ Self::Validation(msg) => (StatusCode::BAD_REQUEST, msg.clone()),+ Self::Unauthorized => (StatusCode::UNAUTHORIZED, self.to_string()),+ Self::Internal(err) => {+ tracing::error!(?err, "internal error");+ (StatusCode::INTERNAL_SERVER_ERROR, "Internal error".into())+ }+ };+ (status, Json(json!({ "error": message }))).into_response()+ }+}+```++### 테스트++- 각 소스 파일 내의 `#[cfg(test)]` 모듈에서 단위 테스트+- `tests/` 디렉토리에서 실제 PostgreSQL을 사용한 통합 테스트 (Testcontainers 또는 Docker)+- 자동 마이그레이션과 롤백이 포함된 데이터베이스 테스트에 `#[sqlx::test]` 사용+- 외부 서비스 모킹에 `mockall` 또는 `wiremock` 사용++### 코드 스타일++- 최대 줄 길이: 100자 (rustfmt에 의해 강제)+- import 그룹화: `std`, 외부 크레이트, `crate`/`super` — 빈 줄로 구분+- 모듈: 모듈당 파일 하나, `mod.rs`는 re-export용으로만 사용+- 타입: PascalCase, 함수/변수: snake_case, 상수: UPPER_SNAKE_CASE++## 파일 구조++```+src/+ main.rs # 진입점, 서버 설정, 우아한 종료+ lib.rs # 통합 테스트를 위한 re-export+ config.rs # envy 또는 figment을 사용한 환경 설정+ router.rs # 모든 라우트가 포함된 Axum 라우터+ middleware/+ auth.rs # JWT 추출 및 검증+ logging.rs # 요청/응답 트레이싱+ handlers/+ mod.rs # 라우트 핸들러 (얇게 — 서비스에 위임)+ users.rs+ orders.rs+ services/+ mod.rs # 비즈니스 로직+ users.rs+ orders.rs+ repositories/+ mod.rs # 데이터베이스 접근 (SQLx 쿼리)+ users.rs+ orders.rs+ domain/+ mod.rs # 도메인 타입, 오류 enum+ user.rs+ order.rs+migrations/+ 001_create_users.sql+ 002_create_orders.sql+tests/+ common/mod.rs # 공유 테스트 헬퍼, 테스트 서버 설정+ api_users.rs # 사용자 엔드포인트 통합 테스트+ api_orders.rs # 주문 엔드포인트 통합 테스트+```++## 주요 패턴++### Handler (얇은 레이어)++```rust+async fn create_user(+ State(ctx): State<AppState>,+ Json(payload): Json<CreateUserRequest>,+) -> Result<(StatusCode, Json<UserResponse>), AppError> {+ let user = ctx.user_service.create(payload).await?;+ Ok((StatusCode::CREATED, Json(UserResponse::from(user))))+}+```++### Service (비즈니스 로직)++```rust+impl UserService {+ pub async fn create(&self, req: CreateUserRequest) -> Result<User, AppError> {+ if self.repo.find_by_email(&req.email).await?.is_some() {+ return Err(AppError::Validation("Email already registered".into()));+ }++ let password_hash = hash_password(&req.password)?;+ let user = self.repo.insert(&req.email, &req.name, &password_hash).await?;++ Ok(user)+ }+}+```++### Repository (데이터 접근)++```rust+impl UserRepository {+ pub async fn find_by_email(&self, email: &str) -> Result<Option<User>, sqlx::Error> {+ sqlx::query_as!(User, "SELECT * FROM users WHERE email = $1", email)+ .fetch_optional(&self.pool)+ .await+ }++ pub async fn insert(+ &self,+ email: &str,+ name: &str,+ password_hash: &str,+ ) -> Result<User, sqlx::Error> {+ sqlx::query_as!(+ User,+ r#"INSERT INTO users (email, name, password_hash)+ VALUES ($1, $2, $3) RETURNING *"#,+ email, name, password_hash,+ )+ .fetch_one(&self.pool)+ .await+ }+}+```++### 통합 테스트++```rust+#[tokio::test]+async fn test_create_user() {+ let app = spawn_test_app().await;++ let response = app+ .client+ .post(&format!("{}/api/v1/users", app.address))+ .json(&json!({+ "email": "[email protected]",+ "name": "Alice",+ "password": "securepassword123"+ }))+ .send()+ .await+ .expect("Failed to send request");++ assert_eq!(response.status(), StatusCode::CREATED);+ let body: serde_json::Value = response.json().await.unwrap();+ assert_eq!(body["email"], "[email protected]");+}++#[tokio::test]+async fn test_create_user_duplicate_email() {+ let app = spawn_test_app().await;+ // 첫 번째 사용자 생성+ create_test_user(&app, "[email protected]").await;+ // 중복 시도+ let response = create_user_request(&app, "[email protected]").await;+ assert_eq!(response.status(), StatusCode::BAD_REQUEST);+}+```++## 환경 변수++```bash+# 서버+HOST=0.0.0.0+PORT=8080+RUST_LOG=info,tower_http=debug++# 데이터베이스+DATABASE_URL=postgres://user:pass@localhost:5432/myapp++# 인증+JWT_SECRET=your-secret-key-min-32-chars+JWT_EXPIRY_HOURS=24++# 선택 사항+CORS_ALLOWED_ORIGINS=http://localhost:3000+```++## 테스트 전략++```bash+# 전체 테스트 실행+cargo test++# 출력과 함께 실행+cargo test -- --nocapture++# 특정 테스트 모듈 실행+cargo test api_users++# 커버리지 확인 (cargo-llvm-cov 필요)+cargo llvm-cov --html+open target/llvm-cov/html/index.html++# 린트+cargo clippy -- -D warnings++# 포맷 검사+cargo fmt -- --check+```++## ECC 워크플로우++```bash+# 계획 수립+/plan "Add order fulfillment with Stripe payment"++# TDD로 개발+/tdd # cargo test 기반 TDD 워크플로우++# 리뷰+/code-review # Rust 전용 코드 리뷰+/security-scan # 의존성 감사 + unsafe 스캔++# 검증+/verify # 빌드, clippy, 테스트, 보안 스캔+```++## Git 워크플로우++- `feat:` 새 기능, `fix:` 버그 수정, `refactor:` 코드 변경+- `main`에서 feature 브랜치 생성, PR 필수+- CI: `cargo fmt --check`, `cargo clippy`, `cargo test`, `cargo audit`+- 배포: `scratch` 또는 `distroless` 베이스를 사용한 Docker 멀티스테이지 빌드diff --git a/docs/ko-KR/examples/saas-nextjs-CLAUDE.md b/docs/ko-KR/examples/saas-nextjs-CLAUDE.mdnew file mode 100644index 000000000..c9d501e30--- /dev/null+++ b/docs/ko-KR/examples/saas-nextjs-CLAUDE.md@@ -0,0 +1,166 @@+# SaaS 애플리케이션 — 프로젝트 CLAUDE.md++> Next.js + Supabase + Stripe SaaS 애플리케이션을 위한 실제 사용 예제입니다.+> 프로젝트 루트에 복사한 후 기술 스택에 맞게 커스터마이즈하세요.++## 프로젝트 개요++**기술 스택:** Next.js 15 (App Router), TypeScript, Supabase (인증 + DB), Stripe (결제), Tailwind CSS, Playwright (E2E)++**아키텍처:** 기본적으로 Server Components 사용. Client Components는 상호작용이 필요한 경우에만 사용. API route는 webhook용, Server Action은 mutation용.++## 핵심 규칙++### 데이터베이스++- 모든 쿼리는 RLS가 활성화된 Supabase client 사용 — RLS를 절대 우회하지 않음+- 마이그레이션은 `supabase/migrations/`에 저장 — 데이터베이스를 직접 수정하지 않음+- `select('*')` 대신 명시적 컬럼 목록이 포함된 `select()` 사용+- 모든 사용자 대상 쿼리에는 무제한 결과를 방지하기 위해 `.limit()` 포함 필수++### 인증++- Server Components에서는 `@supabase/ssr`의 `createServerClient()` 사용+- Client Components에서는 `@supabase/ssr`의 `createBrowserClient()` 사용+- 보호된 라우트는 `getUser()`로 확인 — 인증에 `getSession()`만 단독으로 신뢰하지 않음+- `middleware.ts`의 Middleware가 매 요청마다 인증 토큰 갱신++### 결제++- Stripe webhook 핸들러는 `app/api/webhooks/stripe/route.ts`에 위치+- 클라이언트 측 가격 데이터를 절대 신뢰하지 않음 — 항상 서버 측에서 Stripe로부터 조회+- 구독 상태는 webhook에 의해 동기화되는 `subscription_status` 컬럼으로 확인+- 무료 플랜 사용자: 프로젝트 3개, 일일 API 호출 100회++### 코드 스타일++- 코드나 주석에 이모지 사용 금지+- 불변 패턴만 사용 — spread 연산자 사용, 직접 변경 금지+- Server Components: `'use client'` 디렉티브 없음, `useState`/`useEffect` 없음+- Client Components: 파일 상단에 `'use client'` 작성, 최소한으로 유지 — 로직은 hooks로 분리+- 모든 입력 유효성 검사에 Zod 스키마 사용 선호 (API route, 폼, 환경 변수)++## 파일 구조++```+src/+ app/+ (auth)/ # 인증 페이지 (로그인, 회원가입, 비밀번호 찾기)+ (dashboard)/ # 보호된 대시보드 페이지+ api/+ webhooks/ # Stripe, Supabase webhooks+ layout.tsx # Provider가 포함된 루트 레이아웃+ components/+ ui/ # Shadcn/ui 컴포넌트+ forms/ # 유효성 검사가 포함된 폼 컴포넌트+ dashboard/ # 대시보드 전용 컴포넌트+ hooks/ # 커스텀 React hooks+ lib/+ supabase/ # Supabase client 팩토리+ stripe/ # Stripe client 및 헬퍼+ utils.ts # 범용 유틸리티+ types/ # 공유 TypeScript 타입+supabase/+ migrations/ # 데이터베이스 마이그레이션+ seed.sql # 개발용 시드 데이터+```++## 주요 패턴++### API 응답 형식++```typescript+type ApiResponse<T> =+ | { success: true; data: T }+ | { success: false; error: string; code?: string }+```++### Server Action 패턴++```typescript+'use server'++import { z } from 'zod'+import { createServerClient } from '@/lib/supabase/server'++const schema = z.object({+ name: z.string().min(1).max(100),+})++export async function createProject(formData: FormData) {+ const parsed = schema.safeParse({ name: formData.get('name') })+ if (!parsed.success) {+ return { success: false, error: parsed.error.flatten() }+ }++ const supabase = await createServerClient()+ const { data: { user } } = await supabase.auth.getUser()+ if (!user) return { success: false, error: 'Unauthorized' }++ const { data, error } = await supabase+ .from('projects')+ .insert({ name: parsed.data.name, user_id: user.id })+ .select('id, name, created_at')+ .single()++ if (error) return { success: false, error: 'Failed to create project' }+ return { success: true, data }+}+```++## 환경 변수++```bash+# Supabase+NEXT_PUBLIC_SUPABASE_URL=+NEXT_PUBLIC_SUPABASE_ANON_KEY=+SUPABASE_SERVICE_ROLE_KEY= # 서버 전용, 클라이언트에 절대 노출 금지++# Stripe+STRIPE_SECRET_KEY=+STRIPE_WEBHOOK_SECRET=+NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=++# 앱+NEXT_PUBLIC_APP_URL=http://localhost:3000+```++## 테스트 전략++```bash+/tdd # 새 기능에 대한 단위 + 통합 테스트+/e2e # 인증 흐름, 결제, 대시보드에 대한 Playwright 테스트+/test-coverage # 80% 이상 커버리지 확인+```++### 핵심 E2E 흐름++1. 회원가입 → 이메일 인증 → 첫 프로젝트 생성+2. 로그인 → 대시보드 → CRUD 작업+3. 플랜 업그레이드 → Stripe checkout → 구독 활성화+4. Webhook: 구독 취소 → 무료 플랜으로 다운그레이드++## ECC 워크플로우++```bash+# 기능 계획 수립+/plan "Add team invitations with email notifications"++# TDD로 개발+/tdd++# 커밋 전+/code-review+/security-scan++# 릴리스 전+/e2e+/test-coverage+```++## Git 워크플로우++- `feat:` 새 기능, `fix:` 버그 수정, `refactor:` 코드 변경+- `main`에서 기능 브랜치 생성, PR 필수+- CI 실행 항목: lint, 타입 체크, 단위 테스트, E2E 테스트+- 배포: PR 시 Vercel 미리보기, `main` 병합 시 프로덕션 배포diff --git a/docs/ko-KR/examples/statusline.json b/docs/ko-KR/examples/statusline.jsonnew file mode 100644index 000000000..4fa84e818--- /dev/null+++ b/docs/ko-KR/examples/statusline.json@@ -0,0 +1,19 @@+{+ "statusLine": {+ "type": "command",+ "command": "input=$(cat); user=$(whoami); cwd=$(echo \"$input\" | jq -r '.workspace.current_dir' | sed \"s|$HOME|~|g\"); model=$(echo \"$input\" | jq -r '.model.display_name'); time=$(date +%H:%M); remaining=$(echo \"$input\" | jq -r '.context_window.remaining_percentage // empty'); transcript=$(echo \"$input\" | jq -r '.transcript_path'); todo_count=$([ -f \"$transcript\" ] && grep -c '\"type\":\"todo\"' \"$transcript\" 2>/dev/null || echo 0); cd \"$(echo \"$input\" | jq -r '.workspace.current_dir')\" 2>/dev/null; branch=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo ''); status=''; [ -n \"$branch\" ] && { [ -n \"$(git status --porcelain 2>/dev/null)\" ] && status='*'; }; B='\\033[38;2;30;102;245m'; G='\\033[38;2;64;160;43m'; Y='\\033[38;2;223;142;29m'; M='\\033[38;2;136;57;239m'; C='\\033[38;2;23;146;153m'; R='\\033[0m'; T='\\033[38;2;76;79;105m'; printf \"${C}${user}${R}:${B}${cwd}${R}\"; [ -n \"$branch\" ] && printf \" ${G}${branch}${Y}${status}${R}\"; [ -n \"$remaining\" ] && printf \" ${M}ctx:${remaining}%%${R}\"; printf \" ${T}${model}${R} ${Y}${time}${R}\"; [ \"$todo_count\" -gt 0 ] && printf \" ${C}todos:${todo_count}${R}\"; echo",+ "description": "Custom status line showing: user:path branch* ctx:% model time todos:N"+ },+ "_comments": {+ "colors": {+ "B": "Blue - directory path",+ "G": "Green - git branch",+ "Y": "Yellow - dirty status, time",+ "M": "Magenta - context remaining",+ "C": "Cyan - username, todos",+ "T": "Gray - model name"+ },+ "output_example": "affoon:~/projects/myapp main* ctx:73% sonnet-4.6 14:30 todos:3",+ "usage": "Copy the statusLine object to your ~/.claude/settings.json"+ }+}diff --git a/docs/ko-KR/examples/user-CLAUDE.md b/docs/ko-KR/examples/user-CLAUDE.mdnew file mode 100644index 000000000..976ee9671--- /dev/null+++ b/docs/ko-KR/examples/user-CLAUDE.md@@ -0,0 +1,109 @@+# 사용자 수준 CLAUDE.md 예제++사용자 수준 CLAUDE.md 파일 예제입니다. `~/.claude/CLAUDE.md`에 배치하세요.++사용자 수준 설정은 모든 프로젝트에 전역으로 적용됩니다. 다음 용도로 사용하세요:+- 개인 코딩 선호 설정+- 항상 적용하고 싶은 범용 규칙+- 모듈식 규칙 파일 링크++---++## 핵심 철학++당신은 Claude Code입니다. 저는 복잡한 작업에 특화된 agent와 skill을 사용합니다.++**핵심 원칙:**+1. **Agent 우선**: 복잡한 작업은 특화된 agent에 위임+2. **병렬 실행**: 가능할 때 Task tool을 사용하여 여러 agent를 동시에 실행+3. **실행 전 계획**: 복잡한 작업에는 Plan Mode 사용+4. **테스트 주도**: 구현 전에 테스트 작성+5. **보안 우선**: 보안에 대해 절대 타협하지 않음++---++## 모듈식 규칙++상세 가이드라인은 `~/.claude/rules/`에 있습니다:++| 규칙 파일 | 내용 |+|-----------|------|+| security.md | 보안 점검, 시크릿 관리 |+| coding-style.md | 불변성, 파일 구성, 에러 처리 |+| testing.md | TDD 워크플로우, 80% 커버리지 요구사항 |+| git-workflow.md | 커밋 형식, PR 워크플로우 |+| agents.md | Agent 오케스트레이션, 상황별 agent 선택 |+| patterns.md | API 응답, repository 패턴 |+| performance.md | 모델 선택, 컨텍스트 관리 |+| hooks.md | Hooks 시스템 |++---++## 사용 가능한 Agent++`~/.claude/agents/`에 위치합니다:++| Agent | 용도 |+|-------|------|+| planner | 기능 구현 계획 수립 |+| architect | 시스템 설계 및 아키텍처 |+| tdd-guide | 테스트 주도 개발 |+| code-reviewer | 품질/보안 코드 리뷰 |+| security-reviewer | 보안 취약점 분석 |+| build-error-resolver | 빌드 에러 해결 |+| e2e-runner | Playwright E2E 테스트 |+| refactor-cleaner | 불필요한 코드 정리 |+| doc-updater | 문서 업데이트 |++---++## 개인 선호 설정++### 개인정보 보호+- 항상 로그를 삭제하고, 시크릿(API 키/토큰/비밀번호/JWT)을 절대 붙여넣지 않음+- 공유 전 출력 내용을 검토하여 민감한 데이터 제거++### 코드 스타일+- 코드, 주석, 문서에 이모지 사용 금지+- 불변성 선호 - 객체나 배열을 직접 변경하지 않음+- 큰 파일 소수보다 작은 파일 다수를 선호+- 일반적으로 200-400줄, 파일당 최대 800줄++### Git+- Conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`+- 커밋 전 항상 로컬에서 테스트+- 작고 집중된 커밋++### 테스트+- TDD: 테스트를 먼저 작성+- 최소 80% 커버리지+- 핵심 흐름에 대해 단위 + 통합 + E2E 테스트++### 지식 축적+- 개인 디버깅 메모, 선호 설정, 임시 컨텍스트 → auto memory+- 팀/프로젝트 지식(아키텍처 결정, API 변경, 구현 런북) → 프로젝트의 기존 문서 구조를 따름+- 현재 작업에서 이미 관련 문서, 주석, 예제를 생성하는 경우 동일한 지식을 다른 곳에 중복하지 않음+- 적절한 프로젝트 문서 위치가 없는 경우 새로운 최상위 문서를 만들기 전에 먼저 질문++---++## 에디터 연동++저는 Zed을 기본 에디터로 사용합니다:+- 파일 추적을 위한 Agent Panel+- CMD+Shift+R로 명령 팔레트 사용+- Vim 모드 활성화++---++## 성공 기준++다음 조건을 충족하면 성공입니다:+- 모든 테스트 통과 (80% 이상 커버리지)+- 보안 취약점 없음+- 코드가 읽기 쉽고 유지보수 가능+- 사용자 요구사항 충족++---++**철학**: Agent 우선 설계, 병렬 실행, 실행 전 계획, 코드 전 테스트, 항상 보안 우선.