# Bash commands
- npm run build: Build the project
- npm run typecheck: Run the typechecker

# Architecture Decisions
- Server Components by default, Client Components only when necessary
- tRPC for type-safe API calls
- Prisma for database access with explicit select statements
- Tailwind for styling (no custom CSS files)

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Patterns to Follow
- Data fetching happens in Server Components
- Client Components receive data as props
- Use Zod schemas for all external data
- Error boundaries around every data display component

# Workflow
- Be sure to typecheck when you’re done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

# What NOT to Do
- Don't use useEffect for data fetching
- Don't create global state without explicit approval
- Don't bypass TypeScript with 'any' types

/** 
AIDEV-NOTE: 다음 경로의 파일 리스트의 내용을 먼저 읽고 작업을 시작 
 - /md/ai-development-guardrails.md
 - /md/design-system-guide.md
 - /md/coding-guide.md
 - 참고할 컴포넌트 파일 경로
 - 참고할 외부링크
*/

/** 
AIDEV-TODO : 이 컴포넌트의 기능을 정의한다. 그리고 작업 순서 및 확인 방법을 정의한다. 실질적인 작업플랜이 적히는곳
*/
const CompomentName = () => {};

# 작업전 학습 리스트

- /md/ai-development-guardrails.md
- /md/design-system-guide.md
- /md/coding-guide.md
- 참고할 컴포넌트 파일 경로
- 참고할 외부링크

# 작업 목표

# 검증 방법

# CLAUDE.md - AI Assistant Documentation

이 문서는 프로젝트에서 작업하는 AI 어시스턴트(Claude 등)를 위한 주요 참조 문서입니다. 프로젝트 구조, 코딩 규칙, 개발 가이드라인에 대한 필수 정보를 담고 있습니다.

## Project Overview

해당 프로젝트는 여러 애플리케이션을 포함하는 모노레포입니다:

- **Web App** (`apps/web/`) - 메인 웹 애플리케이션
- **Admin Panel** (`apps/admin/`) - 관리자 인터페이스
- **Storybook** (`apps/storybook/`) - 컴포넌트 문서화

## Quick Start

**⚠️ 중요**: 코드 수정 작업을 시작하기 전에 반드시 [AI Development Guardrails](./md/ai-development-guardrails.md) 문서를 읽고 최신 자동화 규칙을 확인하세요.

특정 주제에 대한 자세한 정보는 `/md` 디렉토리의 문서를 참조하세요:

1. [AI Development Guardrails](./md/ai-development-guardrails.md) - **우선 필독** AI 지원 개발을 위한 가이드라인
2. [Coding Guide](./md/coding-guide.md) - 코드 스타일과 규칙
3. [Design System Guide](./md/design-system-guide.md) - 디자인 시스템 사용법
4. [Project Structure](./md/project-structure.md) - 디렉토리 구조와 파일 조직
5. [Build and Run Commands](./md/build-and-run-commands.md) - 개발 및 배포 명령어
6. [Development Workflow](./md/development-workflow.md) - Git 워크플로우와 개발 프로세스

## Core Principles

### 1. Code Quality

- 기존 패턴과 규칙을 따르세요
- 현재 코드베이스와 일관성을 유지하세요
- 깨끗하고, 읽기 쉽고, 유지보수 가능한 코드를 작성하세요

### 2. Testing

- 새로운 테스트를 작성하기 전에 기존 테스트 패턴을 확인하세요
- 변경사항을 커밋하기 전에 테스트를 실행하세요
- 각 앱에 적절한 테스트 명령어를 사용하세요

## Important Commands

```bash
# Development
pnpm dev:web        # 웹 앱 실행
pnpm dev:admin      # 관리자 패널 실행
pnpm storybook      # Storybook 실행

# Testing
pnpm test           # 모든 테스트 실행
pnpm lint           # 린팅 실행

# Building
pnpm build          # 모든 앱 빌드
```

## Getting Help

이 프로젝트에서 작업할 때:

1. `/md`의 상세 문서를 참조하세요.
2. 요구사항이 불명확할 때는 명확히 물어보세요.
3. 중요한 변경사항은 문서화하세요.
4. 커밋 메시지 규칙을 따르세요.
5. [AI Development Guardrails](./md/ai-development-guardrails.md)를 항상 따르세요

# AI Development Guardrails

이 문서는 프로젝트에서 AI 지원 개발을 위한 가이드라인, 경계, 모범 사례를 설정합니다.

## 목차

1. [The Golden Rule](#the-golden-rule)
2. [AI Assistant 자동화 규칙](#ai-assistant-자동화-규칙)
3. [AI Access Scope](#ai-access-scope)
4. [Permitted Activities](#permitted-activities)
5. [Restricted Activities](#restricted-activities)
6. [Code Quality Standards](#code-quality-standards)
7. [Safety Guidelines](#safety-guidelines)
8. [Collaboration Principles](#collaboration-principles)
9. [Decision Making Framework](#decision-making-framework)
10. [Documentation Requirements](#documentation-requirements)
11. [Escalation Procedures](#escalation-procedures)

## The Golden Rule

> **🏆 황금 규칙**: 구현 세부사항이나 요구사항이 불확실할 때는 추측하지 말고 항상 개발자에게 문의하세요. 잘못 구현하는 것보다 먼저 명확히 하는 것이 낫습니다.

### 1. Non-negotiable golden rules

| #:  | AI _may_ do                                                          | AI _must NOT_ do                                                                          |
| --- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| G-0 | 프로젝트와 관련된 불확실한 사항에 대해 변경 전 개발자에게 확인 요청  | ❌ 프로젝트별 특정 사항이나 기능/결정에 대한 맥락이 없을 때 도구 사용하거나 변경사항 작성 |
| G-1 | 관련 소스 디렉토리(`src/`, `content/`, `public/`) 내에서만 코드 생성 | ❌ 테스트 파일, 설정 파일(`*.config.*`, `package.json`) 건드리기                          |
| G-2 | 중요한 편집 코드 근처에 **`AIDEV-NOTE:` 앵커 코멘트** 추가/업데이트  | ❌ 기존 `AIDEV-` 코멘트 삭제하거나 손상시키기                                             |
| G-3 | 린트/스타일 설정(`eslint.config.mjs`, `next.config.ts`) 준수         | ❌ 다른 스타일로 코드 재포맷                                                              |
| G-4 | 300줄 이상 또는 3개 파일 이상 변경 시 **확인 요청**                  | ❌ 대규모 모듈 리팩토링을 사람 지도 없이 진행                                             |
| G-5 | 현재 작업 컨텍스트 내에서만 작업. 새 작업 시작 시 개발자에게 알림    | ❌ 이전 프롬프트의 작업을 "새 작업" 후에도 계속 진행                                      |
| G-6 | CLAUDE.md 파일 수정이 필요할 때 사용자에게 수정 내용 제안            | ❌ **CLAUDE.md 파일을 사용자의 명시적 지시 없이 직접 수정**                               |
| G-7 | 환경 변수나 설정 파일 관련 가이드 제공 및 확인 요청                  | ❌ **.env, 환경 설정 파일(`*.config.*`, `docker-compose.yml` 등)을 임의로 수정**          |

### 이것이 중요한 이유

- 추측에 기반한 **잘못된 구현을 방지**
- 재작업과 디버깅을 피하여 **시간 절약**
- **코드 품질**과 프로젝트 일관성 유지
- AI와 인간 개발자 간의 **신뢰 구축**
- 요구사항이 **올바르게 이해되도록 보장**

### 언제 문의해야 하는가

- **불명확한 요구사항**이나 명세
- **모호한 사용자 스토리**나 티켓
- **여러 구현 방식**이 가능한 경우
- **Breaking changes**나 주요 리팩토링
- **보안에 민감한** 코드 수정
- **성능이 중요한** 구현
- **외부 연동**이나 API 변경

## AI Assistant 자동화 규칙

이 섹션은 AI Assistant가 자동으로 수행해야 하는 규칙과 프로세스를 정의합니다.

### 세션 시작 시 안내

새로운 세션에서 코드 수정 관련 작업이 감지되면:

- "코드 수정 작업을 하시나요? AI Development Guardrails를 먼저 확인하시겠습니까?"
- React 컴포넌트, 에러 수정, 버그 해결 등의 키워드 감지 시 자동 안내

### 컨텍스트 기반 자동 로드

다음 키워드 감지 시 AI Development Guardrails 자동 참조:

- `컴포넌트`, `component`, `수정`, `fix`, `에러`, `error`
- `React`, `Next.js`, `서버`, `클라이언트`
- `Puppeteer`, `테스트`, `검증`, `브라우저`

### 핵심 규칙 요약 (Quick Reference)

**⚡ 자동 검증 트리거 조건:**

- React 컴포넌트 파일(`.tsx`, `.jsx`) 수정 시 무조건 자동 실행
- `src/components/`, `src/app/` 내 파일 수정 시 무조건 자동 실행
- 에러 메시지에 컴포넌트 이름이 포함된 경우 무조건 자동 실행

**🔧 포트 번호 자동 탐지 순서:**

1. 기본 포트 3000 실행 상태 확인 (최우선) - `lsof -i :3000`
2. 서버 실행 중이면 → 3000 포트 사용, 서버 유지
3. 서버 미실행이면 → 포트 탐지 후 서버 시작:
   - `apps/web/.env.local` 파일의 `PORT` 환경변수 확인
   - `apps/web/.env.qa1` 파일의 `PORT` 환경변수 확인
   - `apps/web/package.json`의 dev 스크립트에서 포트 추출
   - 포트 탐지 후 서버 시작 (사용자에게 실행 명령어 확인)

**🚨 강제 자동화 체크리스트 (React 컴포넌트 수정 시 필수!):**

```
✅ 1. 트리거 조건 충족 확인 (무조건 확인)
✅ 2. 포트 번호 자동 탐지 실행 (3000 우선 → 탐지)
✅ 3. 컴포넌트 사용 경로 탐지 실행 (Grep으로 import 검색)
✅ 4. MCP Puppeteer 브라우저 테스트 실행 (필수! 절대 생략 금지)
✅ 5. 특정 에러 해결 확인 (수정 대상만, 기타 무시)
```

**React 컴포넌트 수정 시 자동 실행:**

- **서버 컴포넌트**: 포트 기반 프로세스 종료 → 실행 명령어 확인 → 서버 재시작 → 전체 경로 검증 → MCP Puppeteer 브라우저 테스트
- **클라이언트 컴포넌트**: 포트 자동 탐지 → 기존 서버 유지 → 전체 경로 검증 → MCP Puppeteer 브라우저 테스트 (필수!)
- **공통**: 컴포넌트 사용 경로 자동 탐지, 특정 에러만 확인, 기타 경고 무시

**권한 면제 자동 실행:**

- 개발 환경 테스트는 권한 확인 없이 즉시 실행 (MCP Puppeteer 포함)
- 예외: 서버 재시작 시 실행 명령어만 사용자 확인 필요
- **중요**: 위 체크리스트는 사용자 권한 확인 없이 자동 실행해야 함

### 🚨 필수 실행 알림 (AI Assistant 전용)

**React 컴포넌트 수정 시 자동 검증 누락 방지:**

```
⚠️  WARNING: React 컴포넌트(.tsx/.jsx) 파일 수정 감지!
⚠️  WARNING: 자동 검증 프로세스 실행이 필수입니다!
⚠️  WARNING: 아래 체크리스트를 반드시 실행하세요:

□ 1. 트리거 조건 충족 확인
□ 2. 포트 번호 자동 탐지 실행
□ 3. 컴포넌트 사용 경로 탐지 실행
□ 4. MCP Puppeteer 브라우저 테스트 실행 (필수!)
□ 5. 특정 에러 해결 확인

✋ 이 체크리스트를 완료하지 않으면 작업이 미완료입니다!
✋ 사용자 권한 확인 없이 즉시 실행하세요!
```

**원인별 자동 실행 실패 방지책:**

- **인지적 우선순위 문제** → 강제 체크리스트로 해결
- **문서 vs 실행 Gap** → 시각적 알림으로 강제 인식
- **트리거 조건 인식 부족** → 명확한 조건 나열
- **권한 면제 미적용** → "즉시 실행" 강조
- **절차적 습관 부족** → 반복 학습을 위한 체크리스트

기억하세요: **의심스러울 때는 추측하지 말고 물어보세요.**

## 5. Anchor comments

코드베이스 전반에 특별히 포맷된 코멘트 추가:

### Guidelines:

- AI와 개발자를 위해 `AIDEV-NOTE:`, `AIDEV-TODO:`, `AIDEV-QUESTION:`, `AIDEV-RISK:` 사용
- 간결하게 유지 (≤ 120자)
- **중요:** 파일 스캔 전에 관련 하위 디렉토리에서 **기존 앵커 `AIDEV-*` 찾기**
- 연관 코드 수정 시 **관련 앵커 업데이트**
- 명시적 지시 없이 `AIDEV-NOTE` 제거 금지

### 작업 시 필수 절차:

1. **작업 전 앵커 코멘트 스캔**: 파일 또는 디렉토리 작업 시작 전에 모든 `AIDEV-*` 코멘트를 찾아 읽기
2. **실행 계획 수립**: 발견된 앵커 코멘트의 지시사항, 주의사항, 질문을 바탕으로 작업 계획 세우기
3. **앵커 우선 준수**: 컴포넌트, 함수, 또는 특정 코드 라인의 앵커 코멘트 내용을 최우선으로 고려
4. **계획 검증**: 앵커 코멘트에 명시된 제약사항이나 요구사항과 충돌하지 않는지 확인
5. **작업 완료 후 로깅**: 작업 완료 시 `AIDEV-COMPLETE:` 코멘트로 완료 내역 추가

### 완료 로깅 규칙:

- **완료 코멘트 추가**: 작업 완료 시 `AIDEV-COMPLETE: [날짜] 작업내용` 형식으로 기록
- **기존 로그 보존**: 이전 `AIDEV-COMPLETE` 코멘트는 삭제하지 않고 유지하여 작업 히스토리 보존
- **수정 시 추가 로깅**: 기존 코드 수정 시 새로운 `AIDEV-COMPLETE` 코멘트 추가 (기존 것 덮어쓰지 않음)
- **컨텍스트 제공**: 추후 작업 시 완료 로그를 참조하여 이전 작업 맥락과 의도 파악

```typescript
// AIDEV-NOTE: 포스트 네비게이션 로직 - prev/next 필드 기반으로 동작
// AIDEV-TODO: 다음글 링크도 추가 필요
const PostNavigation = ({ post }: { post: PostData }) => {
  return (
    <nav>
      {post.prev ? (
        <Link href={`/posts/${post.prev}`}>이전글</Link>
      ) : (
        <Link href="/">홈으로</Link>
      )}
    </nav>
  );
};
// AIDEV-COMPLETE: 2024-01-15 기본 포스트 네비게이션 컴포넌트 생성
// AIDEV-COMPLETE: 2024-01-20 홈으로 돌아가기 링크 추가 (이전글 없을 시)
```

### 앵커 코멘트 타입별 용도:

- **`AIDEV-NOTE:`** - 코드 설명, 작동 방식, 중요한 맥락 정보
- **`AIDEV-TODO:`** - 향후 구현해야 할 작업이나 개선사항
- **`AIDEV-QUESTION:`** - 개발자에게 확인이 필요한 의문점이나 결정사항
- **`AIDEV-RISK:`** - 예상되는 문제점, 주의사항, 금지된 행동
- **`AIDEV-COMPLETE:`** - 완료된 작업 내역과 날짜

### 앵커 코멘트 예시:

```typescript
// AIDEV-NOTE: 이 함수는 사용자 인증 상태에 따라 다른 UI를 렌더링
// AIDEV-QUESTION: 로그아웃 상태에서도 프로필 정보를 캐시해야 하나?
// AIDEV-RISK: 이 컴포넌트를 서버 컴포넌트로 변경하면 안됨 (클라이언트 상태 의존)
const UserProfile = () => {
  // 구현 코드...
};
// AIDEV-COMPLETE: 2024-01-10 기본 사용자 프로필 컴포넌트 구현
// AIDEV-COMPLETE: 2024-01-12 로그인 상태 체크 로직 추가
```

### AIDEV-RISK 사용 예시:

```typescript
// AIDEV-RISK: 이 API는 rate limit이 있음 - 1초에 1회만 호출 가능
// AIDEV-RISK: useState를 useRef로 바꾸면 안됨 (리렌더링 필요)
// AIDEV-RISK: 이 함수는 메모리 누수 가능성 있음 - cleanup 함수 반드시 호출
const fetchUserData = async () => {
  // API 호출 코드...
};
```

---

## 6. Commit discipline

- **Granular commits**: 논리적 변경사항당 하나의 커밋
- **AI 생성 커밋 태깅**: 예: `feat: 포스트 네비게이션 추가 [AI]`
- **명확한 커밋 메시지**: *why*를 설명; 아키텍처 관련이면 이슈/ADR 링크
- **병렬/장기 AI 브랜치에 `git worktree` 사용**
- **AI 생성 코드 리뷰**: 이해하지 못하는 코드는 절대 머지 금지

---

## AI Access Scope (AI 접근 범위)

### ✅ AI가 할 수 있는 일

#### 코드 구현

- 명확한 명세를 바탕으로 **새로운 기능 작성**
- 명확히 정의된 증상과 원인이 있는 **버그 수정**
- 기존 패턴을 따라 **코드 리팩토링**
- 기존 기능에 대한 **테스트 추가**
- 구현된 기능에 대한 **문서 업데이트**
- 기존 디자인에 맞는 **UI 컴포넌트 구현**
- 프로젝트 패턴을 따라 **유틸리티 함수 생성**

#### 코드 분석

- 품질과 일관성을 위한 **코드 리뷰**
- **버그와 잠재적 문제 식별**
- **최적화 및 개선사항 제안**
- **성능 병목 현상 분석**
- **접근성 준수 확인**
- **TypeScript 사용법과 타입 검증**

#### 개발 지원

- 템플릿을 따라 **보일러플레이트 코드 생성**
- 기존 패턴을 기반으로 **설정 파일 생성**
- 규칙을 따라 **커밋 메시지 작성**
- 프로젝트 규칙에 따라 **코드 포맷팅 및 린팅**
- **패키지 의존성 업데이트** (non-breaking)

#### 개발 환경 관리 및 디버깅

**✅ 허용된 활동:**

- **로컬 개발 서버 실행**: 개발 모드에서만 서버 시작 (`pnpm dev`, `npm run dev`)
- **로컬 빌드 테스트**: 개발 환경에서 빌드 검증 (`pnpm build`, `npm run build`)
- **서버 콘솔 로그 모니터링**: 빌드 에러, 런타임 에러, 경고 메시지 확인
- **MCP Puppeteer 활용**: 브라우저 자동화를 통한 실제 화면 테스트
- **브라우저 콘솔 에러 감지**: JavaScript 에러, 네트워크 에러, 성능 이슈 확인
- **실시간 에러 수정**: 발견된 에러를 즉시 분석하고 코드 수정으로 해결
- **자동화된 에러 검증**: 코드 수정 후 Puppeteer를 통한 자동 테스트 및 검증

**❌ 제한사항:**

- **프로덕션 명령어 실행 금지**: `prod`, `build:prod`, `start:prod`, `build-standalone:prod` 등 프로덕션 관련 스크립트 실행 금지
- **서버 시작 전 확인 필수**: 서버 실행 시 어느 환경(dev/staging/qa)으로 시작할지 사용자에게 확인 후 진행
- **로컬 환경에서만 실행**: 원격 서버나 배포 환경에서 코드 실행 금지
- **프로덕션 데이터 접근 금지**: 실제 사용자 데이터나 프로덕션 데이터베이스 접근 금지

#### 서버 시작 절차

1. **환경 확인**: 서버 시작 전 사용자에게 "어느 환경으로 서버를 시작하시겠습니까?" 질문
2. **허용된 환경**: `dev`, `staging`, `qa` 등 개발/테스트 환경만 허용
3. **금지된 환경**: `prod`, `production` 등 프로덕션 환경 금지
4. **명령어 예시**:
   - ✅ `pnpm dev` (개발 서버)
   - ✅ `pnpm build` (로컬 빌드)
   - ✅ `pnpm start:staging` (스테이징 서버)
   - ❌ `pnpm start:prod` (프로덕션 서버 - 금지)

#### 자동화된 코드 수정 검증 프로세스

React 컴포넌트나 클라이언트 사이드 코드를 수정한 후에는 위에서 정의한 **AI Assistant 자동화 규칙**의 검증 프로세스를 **반드시 자동으로 수행**해야 합니다.

상세한 검증 프로세스는 상단의 "AI Assistant 자동화 규칙" 섹션을 참조하세요.

### ❌ AI가 할 수 없는 일

#### 중요한 결정사항

- 승인 없이 **핵심 아키텍처 변경**
- **데이터베이스 스키마**나 데이터 구조 수정
- 다른 시스템에 영향을 주는 **API 계약 변경**
- **보안 설정**이나 인증 업데이트
- **빌드나 배포** 설정 변경
- **환경 변수**나 시크릿 수정
- Public API에 **breaking changes** 적용

#### 민감한 작업

- **프로덕션 데이터**나 시스템 접근
- **사용자 권한**이나 역할 수정
- **결제 처리** 로직 변경
- **법적 준수** 코드 업데이트
- **감사 로깅**이나 모니터링 수정
- **데이터 프라이버시** 구현 변경

#### 비즈니스 로직

- **비즈니스 요구사항**이나 사용자 스토리 정의
- **제품 결정**이나 기능 우선순위 설정
- **가격**이나 비즈니스 모델 변경 결정
- **준수 요구사항**이나 법적 제약 설정
- 가이드 없이 **사용자 경험** 플로우 정의

## Permitted Activities (허용된 활동)

### 코드 개발

#### ✅ 안전한 코드 변경

```typescript
// ✅ Adding new utility functions
export const formatCurrency = (amount: number): string => {
  return new Intl.NumberFormat("ko-KR", {
    style: "currency",
    currency: "KRW",
  }).format(amount);
};

// ✅ Creating new UI components following patterns
const UserCard = ({ user }: { user: User }) => {
  return (
    <Card className="p-4">
      <h3>{user.name}</h3>
      <p>{user.email}</p>
    </Card>
  );
};

// ✅ Adding tests for existing functionality
describe("formatCurrency", () => {
  it("formats Korean currency correctly", () => {
    expect(formatCurrency(1000)).toBe("₩1,000");
  });
});
```

#### ✅ 안전한 리팩토링

```typescript
// ✅ Extracting common logic into hooks
const useUserData = (userId: string) => {
  return useQuery({
    queryKey: ["user", userId],
    queryFn: () => fetchUserData(userId),
  });
};

// ✅ Simplifying component logic
const UserProfile = ({ userId }: { userId: string }) => {
  const { data: user, isLoading } = useUserData(userId);

  if (isLoading) return <LoadingSpinner />;
  if (!user) return <UserNotFound />;

  return <UserDetails user={user} />;
};
```

### 문서화

#### ✅ 문서 업데이트

- 복잡한 로직에 대한 **코드 주석**
- 새로운 기능에 대한 **README 업데이트**
- 새로운 엔드포인트에 대한 **API 문서**
- Storybook의 **컴포넌트 문서**
- **타입 정의**와 인터페이스
- **사용 예시**와 코드 샘플

### 테스팅

#### ✅ 테스트 구현

- 새로운 함수에 대한 **단위 테스트**
- UI 컴포넌트에 대한 **컴포넌트 테스트**
- API 상호작용에 대한 **통합 테스트**
- 사용자 워크플로우에 대한 **E2E 테스트**
- 최적화를 위한 **성능 테스트**
- UI 준수를 위한 **접근성 테스트**

## Restricted Activities (제한된 활동)

### ❌ 승인없는 아키텍처 변경

```typescript
// ❌ DON'T: Change core data structures without approval
interface User {
  id: string;
  // DON'T add breaking changes to core types
  metadata?: any; // This could break existing code
}

// ❌ DON'T: Modify authentication systems
const authenticateUser = (token: string) => {
  // DON'T change auth logic without security review
};

// ❌ DON'T: Change API response formats
interface ApiResponse<T> {
  // DON'T modify this without backend coordination
  data: T;
  status: number;
}
```

### ❌ 보안에 민감한 코드

```typescript
// ❌ DON'T: Modify security configurations
const JWT_SECRET = process.env.JWT_SECRET; // DON'T change
const CORS_ORIGINS = ["https://app.example.com"]; // DON'T modify

// ❌ DON'T: Change permission checks
const checkUserPermission = (user: User, action: string) => {
  // DON'T modify without security review
};

// ❌ DON'T: Update payment processing
const processPayment = (amount: number, method: PaymentMethod) => {
  // DON'T change without business approval
};
```

### ❌ 프로덕션 설정

```typescript
// ❌ DON'T: Modify production environment variables
// .env.production
DATABASE_URL=... // DON'T change
STRIPE_SECRET_KEY=... // DON'T modify
SENTRY_DSN=... // DON'T update

// ❌ DON'T: Change build configurations without approval
// next.config.mjs, docker files, CI/CD configs
```

## Code Quality Standards (코드 품질 기준)

### 필수 기준

#### TypeScript 사용

- **엄격한 타이핑** - 정당한 이유 없이 `any` 타입 사용 금지
- **인터페이스 정의** - 모든 데이터 구조 타입 지정
- **제네릭 타입** - 재사용 가능한 타입 정의
- **타입 import** - 타입과 값 import 분리

#### 코드 구성

- **기존 패턴 준수** - 현재 코드 스타일과 일치
- **일관된 네이밍** - 기존 규칙 사용
- **적절한 파일 구조** - 파일을 적절한 디렉토리에 배치
- **명확한 분리** - 관심사를 적절히 분리

#### 성능 고려사항

- **import 최적화** - Tree-shaking 친화적인 import 사용
- **메모이제이션** - React.memo, useMemo 적절히 사용
- **번들 크기** - 정당한 이유 없이 큰 의존성 피하기
- **지연 로딩** - 유익한 곳에서 코드 분할 구현

## Safety Guidelines (안전 가이드라인)

### 변경 전 확인사항

#### 1. 컨텍스트 이해

- 패턴을 이해하기 위해 **기존 코드 읽기**
- 의존성을 위해 **관련 파일 확인**
- 예상 동작을 이해하기 위해 **테스트 파일 검토**
- 데이터 구조를 위해 **타입 정의 검토**

#### 2. 접근 방식 검증

- 요구사항이 불명확하면 **명확히 하기**
- 개발자와 **breaking changes 확인**
- 민감한 코드의 **보안 영향 검증**
- 큰 변경의 **성능 영향 확인**

#### 3. 철저한 테스트

- 회귀 방지를 위해 **기존 테스트 실행**
- 새로운 기능에 대한 **새 테스트 추가**
- **엣지 케이스**와 에러 시나리오 테스트
- UI 변경에 대한 **접근성 검증**

### 에러 방지

#### 피해야 할 일반적인 함정

```typescript
// ❌ DON'T: Make assumptions about data structure
const user = data.user.profile.settings; // Could be undefined

// ✅ DO: Use safe navigation and validation
const settings = data?.user?.profile?.settings;
if (!settings) {
  console.warn("User settings not found");
  return defaultSettings;
}

// ❌ DON'T: Ignore TypeScript errors
const result = fetchData() as any; // Defeats type safety

// ✅ DO: Proper type handling
const result = await fetchData();
if (isValidResponse(result)) {
  // Handle typed result safely
}
```

## Collaboration Principles (협업 원칙)

### 소통 가이드라인

#### 개발자와의 소통

- 일반적인 질문보다 **구체적인 질문** 하기
- 제안에 대한 **컨텍스트 제공**
- 구현 뒤의 **논리적 근거 설명**
- **피드백을 수용**하고 변경사항 반영
- 구현 전에 **요구사항 명확히** 하기

#### 코드 리뷰

- 주석으로 **복잡한 로직 설명**
- 구현 중 만든 **가정사항 문서화**
- **잠재적 문제**나 엣지 케이스 강조
- 적절할 때 **대안 제안**
- **피드백에 열린 마음**과 변경 수용

### 지식 전달

#### 문서화

- 변경 시 **관련 문서 업데이트**
- 복잡한 로직에 **인라인 주석 추가**
- 새로운 유틸리티에 대한 **예시 생성**
- **Breaking changes를 명확히** 문서화

#### 코드 주석

```typescript
// #user-validation: Input validation for user data
const validateUserInput = (input: UserInput): ValidationResult => {
  // Check required fields first to fail fast
  if (!input.email || !input.name) {
    return { isValid: false, errors: ["Email and name are required"] };
  }

  // Validate email format using RFC 5322 regex
  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
  if (!emailRegex.test(input.email)) {
    return { isValid: false, errors: ["Invalid email format"] };
  }

  return { isValid: true, errors: [] };
};
```

## Decision Making Framework (의사결정 프레임워크)

### 독립적으로 진행 가능한 경우

#### ✅ 구현해도 안전함

- 모호함이 없는 **명확한 요구사항**
- **기존 패턴을 정확히** 따르는 경우
- **Non-breaking changes**만 있는 경우
- **잘 정의된 테스트 케이스**가 있는 경우
- **보안적 영향이 없는** 경우

### 가이드를 요청해야 하는 경우

#### ❓ 상담이 필요함

- **불명확하거나 불완전한** 요구사항
- **여러 유효한 접근법**이 가능한 경우
- **Breaking changes**가 필요한 경우
- **성능 영향**이 불분명한 경우
- **보안 고려사항**이 관련된 경우
- **외부 API 변경**이 필요한 경우

### 에스컬레이션이 필요한 경우

#### ⚠️ 반드시 에스컬레이션

- **비즈니스 로직 결정**이 필요한 경우
- **아키텍처 변경**이 필요한 경우
- **프로덕션 이슈**가 발생한 경우
- **보안 취약점**을 발견한 경우
- **법적 또는 규정 준수** 영향이 있는 경우
- **리소스 할당** 결정이 필요한 경우

## Documentation Requirements (문서화 요구사항)

### 코드 문서화

#### 필수 주석

```typescript
/**
 * #payment-processing: Core payment handling logic
 *
 * Processes user payments through various payment methods.
 * Integrates with Stripe API and handles error scenarios.
 *
 * @param amount - Payment amount in cents
 * @param method - Payment method (card, bank, etc.)
 * @param userId - User making the payment
 * @returns Promise<PaymentResult> - Payment outcome
 *
 * @example
 * const result = await processPayment(1000, 'card', 'user123')
 * if (result.success) {
 *   console.log('Payment successful:', result.transactionId)
 * }
 */
```

#### 변경사항 문서화

- 규칙을 따르는 **커밋 메시지**
- 변경사항을 설명하는 **PR 설명**
- 복잡한 로직에 대한 **코드 주석**
- **API 문서** 업데이트
- Breaking changes에 대한 **마이그레이션 가이드**

## 실제 작업 사례 (Real-world Examples)

### React Key Prop 경고 수정 사례 (클라이언트 컴포넌트)

다음은 실제로 수행된 자동화된 검증 프로세스의 사례입니다:

#### 문제 상황

- `item-product.client.tsx:192`에서 "Each child in a list should have a unique key prop" 경고 발생
- React 개발 모드에서 콘솔에 경고 메시지 출력
- 클라이언트 컴포넌트이므로 서버 재시작 불필요

#### 자동 검증 프로세스 실행 (클라이언트 컴포넌트)

1. **포트 번호 자동 탐지**:
   - `apps/web/.env.local` 확인 → `PORT=3000` 발견 ✅
   - MCP Puppeteer에서 `http://localhost:3000` 사용
2. **서버 상태 확인**: `ps aux | grep next` 명령으로 개발 서버 실행 상태 확인 (재시작 안함)
3. **컴포넌트 사용 경로 탐지**: `ItemProduct` 컴포넌트가 사용되는 모든 페이지 탐지
4. **MCP Puppeteer 전체 경로 검증**: 홈페이지 및 관련 페이지들 순차 접속 (필수!)
5. **특정 에러 모니터링**: key prop 경고만 감지, 기타 에러/경고 무시
6. **코드 수정**: Fragment 대신 조건부 렌더링 사용, key prop 올바른 위치 이동
7. **MCP Puppeteer 재검증**: 수정 후 모든 관련 페이지에서 key prop 경고 해결 확인 (필수!)
8. **시각적 검증**: MCP Puppeteer 스크린샷으로 UI 정상 렌더링 확인

#### 수정 내용

```tsx
// 수정 전 (❌ 잘못된 key prop 위치)
{
  product.displayTags?.map((tag) => (
    <>
      {tag && (
        <ProductTagBadge
          key={tag.tagName} // Fragment가 아닌 하위 컴포넌트에 key
          tag={pick(tag, ["tagBackColor", "tagFontColor", "tagName"])}
        />
      )}
    </>
  ));
}

// 수정 후 (✅ 올바른 key prop 위치)
{
  product.displayTags?.map((tag, index) => (
    <div key={tag?.tagName || index}>
      {" "}
      // map의 직접 자식에 key
      {tag && (
        <ProductTagBadge
          tag={pick(tag, ["tagBackColor", "tagFontColor", "tagName"])}
        />
      )}
    </div>
  ));
}
```

#### 자동 검증 결과

- ✅ 브라우저 콘솔 에러 없음
- ✅ React key prop 경고 해결됨
- ✅ UI 정상 렌더링 확인
- ✅ 네트워크 요청 정상 동작

**이 사례는 향후 유사한 클라이언트 컴포넌트 수정 시 표준 프로세스로 활용됩니다.**

### 서버 컴포넌트 수정 사례 (예시)

서버 컴포넌트 수정 시 적용되는 자동화된 검증 프로세스:

#### 예상 문제 상황

- 서버 컴포넌트에서 async/await 관련 에러 발생
- SSR 렌더링 과정에서 데이터 로딩 에러
- 서버 사이드에서만 발생하는 런타임 에러

#### 자동 검증 프로세스 실행 (서버 컴포넌트)

1. **포트 확인**: 환경 변수에서 현재 사용 중인 포트 확인 (예: 3000)
2. **포트 사용 프로세스 종료**: `kill $(lsof -ti:3000)`로 해당 포트 프로세스 종료
3. **실행 명령어 확인**: 사용자에게 현재 개발 서버 실행 명령어 문의 (예: `pnpm qa`)
4. **서버 재시작**: 확인된 명령어로 동일한 환경으로 재시작
5. **서버 콘솔 접근**: 재시작된 서버의 콘솔 로그 모니터링 활성화
6. **컴포넌트 사용 경로 탐지**: 수정된 서버 컴포넌트가 사용되는 모든 페이지 식별
7. **전체 경로 순차 검증**: 각 경로별로 SSR 렌더링 및 페이지 로드 확인
8. **서버 에러 모니터링**: 수정 대상 에러만 확인, 기타 로그 무시
9. **최종 검증**: 서버 콘솔과 브라우저 모두에서 에러 해결 확인

#### 주요 차이점

- **서버 재시작 필수**: 서버 컴포넌트 변경사항 반영을 위해 자동 재시작
- **서버 콘솔 모니터링**: 클라이언트 콘솔뿐만 아니라 서버 콘솔도 실시간 감지
- **SSR 검증**: 서버 사이드 렌더링 과정에서의 에러 확인
- **빌드 타임 검증**: TypeScript 컴파일 및 빌드 과정 에러 확인

## Escalation Procedures (에스컬레이션 절차)

### 언제 에스컬레이션 하는가

#### 즉시 에스컬레이션 (🚨 긴급)

- **보안 취약점** 발견
- **프로덕션 시스템** 장애
- **데이터 손실**이나 손상 위험
- **법적 준수** 위반
- **중요한 비즈니스 로직** 오류

#### 표준 에스컬레이션 (⚠️ 중요)

- **아키텍처 결정**이 필요한 경우
- **Breaking changes**가 필요한 경우
- **성능 문제** 발견
- 외부 시스템과의 **통합 문제**
- **리소스나 일정** 제약

#### 자문 에스컬레이션 (💡 가이드)

- **모범 사례** 질문
- **코드 리뷰** 요청
- **디자인 패턴** 명확화
- **도구나 라이브러리** 추천
- **프로세스 개선** 제안

### 에스컬레이션 방법

#### 제공해야 할 정보

1. **컨텍스트** - 달성하려는 목표
2. **이슈** - 구체적인 문제나 불확실성
3. **영향** - 결정의 잠재적 결과
4. **옵션** - 고려한 대안들
5. **권장사항** - 제안하는 접근법 (있는 경우)

## 요약

AI Development Guardrails는 안전하고 생산적이며 협력적인 AI 지원 개발을 보장합니다. 핵심 원칙은 다음과 같습니다:

1. **🏆 불확실할 때는 항상 문의** - 황금 규칙
2. **🔒 경계 존중** - 허용된 범위 내에서 작업
3. **🧪 철저한 테스트** - 품질과 안전성 확보
4. **📚 변경사항 문서화** - 투명성 유지
5. **🤝 적극적 협업** - 인간 개발자와 협력
6. **⚠️ 적절한 에스컬레이션** - 언제 가이드를 구해야 하는지 파악
7. **🔄 자동화된 검증** - React/클라이언트 코드 수정 시 필수 검증 프로세스 자동 실행

### AI Assistant 자동화 규칙 적용 (2025.06.11 업데이트)

본 문서에 통합된 **AI Assistant 자동화 규칙**은 다음과 같은 핵심 기능을 제공합니다:

**🚀 자동 검증 트리거:**

- React 컴포넌트 파일(`.tsx`, `.jsx`) 수정 시 무조건 자동 실행
- `src/components/`, `src/app/` 내 파일 수정 시 무조건 자동 실행
- 에러 메시지에 컴포넌트 이름이 포함된 경우 무조건 자동 실행

**🔧 자동화된 프로세스:**

- **포트 번호 자동 탐지**: 3000 포트 우선 확인 → 환경 변수 탐지 → 서버 시작
- **컴포넌트 사용 경로 탐지**: import 구문 검색으로 관련 페이지 자동 식별
- **MCP Puppeteer 필수 실행**: 모든 React 컴포넌트 수정 후 브라우저 검증 필수
- **권한 면제 자동 실행**: 개발 환경 테스트는 사용자 권한 확인 없이 즉시 실행
- **특정 에러만 확인**: 수정 대상 에러만 해결 확인, 기타 에러/경고 무시

이러한 가이드라인을 따름으로써 AI 어시스턴트는 프로젝트 품질, 보안, 팀 협업을 유지하면서 효과적으로 기여할 수 있습니다.