프롬프트는 설계 언어다

파일 업로드 만들어줘.

// AI 결과: 기본적이지만 빈약한 구현
export async function uploadFile(file: File) {
  const formData = new FormData();
  formData.append('file', file);
  const res = await fetch('/api/upload', { method: 'POST', body: formData });
  return res.json();
}

[Context]
Next.js 16 App Router 프로젝트. 프로필 이미지 업로드.
AWS S3 버킷 설정 완료. 인증은 middleware.ts에서 세션 기반 처리.

[Intent]
인증된 사용자가 프로필 이미지를 업로드하면 S3에 저장하고,
users 테이블의 avatarUrl을 업데이트한다.

[Constraints]
- 최대 5MB, image/jpeg, image/png, image/webp만 허용
- 파일명은 UUID로 변환
- 기존 이미지 있으면 S3에서 삭제
- 업로드 실패 시 DB 미반영 (트랜잭션)
- presigned URL 방식

[Validation]
- 5MB 초과 시 400 에러
- 비허용 타입 시 400 에러
- 비인증 시 401 에러
- S3 실패 시 DB에 빈 URL 미저장

// AI 결과: 제약조건이 모두 반영된 구현
import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
import { PutObjectCommand, DeleteObjectCommand } from '@aws-sdk/client-s3';

const ALLOWED_TYPES = ['image/jpeg', 'image/png', 'image/webp'];
const MAX_SIZE = 5 * 1024 * 1024; // 5MB

export async function POST(req: NextRequest) {
  const session = await getSession(req);
  if (!session) return NextResponse.json({ error: '인증 필요' }, { status: 401 });

  const { fileType, fileSize } = await req.json();

  if (!ALLOWED_TYPES.includes(fileType)) {
    return NextResponse.json({ error: '허용되지 않은 파일 형식' }, { status: 400 });
  }
  if (fileSize > MAX_SIZE) {
    return NextResponse.json({ error: '파일 크기 5MB 초과' }, { status: 400 });
  }

  const fileKey = `avatars/${crypto.randomUUID()}.${fileType.split('/')[1]}`;

  // presigned URL 발급
  const uploadUrl = await getSignedUrl(s3Client, new PutObjectCommand({
    Bucket: process.env.S3_BUCKET,
    Key: fileKey,
    ContentType: fileType,
  }), { expiresIn: 300 });

  // 트랜잭션: 이전 이미지 삭제 + DB 업데이트
  const prevAvatar = await db.user.findUnique({
    where: { id: session.userId },
    select: { avatarUrl: true },
  });

  await db.$transaction(async (tx) => {
    await tx.user.update({
      where: { id: session.userId },
      data: { avatarUrl: `${process.env.CDN_URL}/${fileKey}` },
    });
    if (prevAvatar?.avatarUrl) {
      const prevKey = prevAvatar.avatarUrl.replace(`${process.env.CDN_URL}/`, '');
      await s3Client.send(new DeleteObjectCommand({
        Bucket: process.env.S3_BUCKET, Key: prevKey,
      }));
    }
  });

  return NextResponse.json({ uploadUrl, fileKey });
}

제약조건:
- 알림 전송이 결제 응답을 블로킹하면 안 된다
- 전송 실패 시 최대 3회 재시도
- 각 알림 채널은 독립적으로 실패할 수 있다
- 모든 전송 시도는 로깅되어야 한다

피할 것:
- 외부 메시지 큐는 현재 인프라에 없으므로 사용하지 않는다
- 알림 템플릿 시스템은 이 단계에서 필요 없다

검증기준:
- 결제 API 응답 시간이 알림 전송으로 인해 증가하지 않음
- 이메일 전송 실패 시 슬랙 알림은 정상 전송됨
- 새 채널 추가 시 기존 코드 변경 없이 파일 추가만으로 가능
- 재시도 로직이 지수 백오프로 동작함

# CLAUDE.md

## 프로젝트 개요
<!-- AI에게 "왜 이 프로젝트가 존재하는지" 알려준다.
     이것이 없으면 AI는 범용적 솔루션을 제안한다. -->
B2B SaaS로 중소기업 회계 자동화를 제공한다.
핵심 가치: 정확성 > 속도. 회계 데이터는 오류 허용 불가.

## 아키텍처
<!-- 디렉토리 구조를 명시하면 AI가 파일을 올바른 위치에 생성한다. -->
- app/: Next.js App Router
- lib/: 비즈니스 로직 (순수 함수 중심)
- services/: 외부 API 연동
- prisma/: DB 스키마와 마이그레이션

## 개발 규칙
<!-- MUST/MUST NOT/SHOULD 구분이 핵심.
     AI는 "해도 되고 안 해도 되는 것"을 잘 판단하지 못한다. -->

### MUST (반드시)
- 모든 금액 계산은 Decimal.js 사용 (부동소수점 금지)
- API 응답은 반드시 AppResponse 타입으로 래핑
- DB 쿼리에 반드시 인덱스 힌트 주석 포함

### MUST NOT (절대 금지)
- moment.js 사용 금지 (dayjs 사용)
- any 타입 사용 금지
- console.log 금지 (logger 모듈 사용)

### SHOULD (권장)
- 함수는 20줄 이내 권장
- 복잡한 조건문은 early return 패턴

## 기술 스택과 선택 이유
<!-- "왜"를 적어야 AI가 다른 기술을 제안하지 않는다. -->
- Prisma: 타입 안전한 ORM. Drizzle 대비 팀 숙련도 높음
- Redis: 세션 + 캐시. Memcached 대비 데이터 구조 다양성
- Decimal.js: 회계 정확도. BigInt 대비 소수점 연산 용이

## 알려진 기술 부채
<!-- AI가 이 영역을 건드릴 때 주의하도록 경고한다. -->
- legacy/reports/: 리팩토링 예정. 건드리지 말 것
- utils/date.ts: moment.js 의존. dayjs 마이그레이션 진행중

---
effort: high
---
# CLAUDE.md

이 프로젝트에서는 보안 관련 코드에 최대한 신중하게 접근합니다.

project-root/
  .prompts/
    api-endpoint.md      # API 생성 패턴
    db-migration.md      # DB 마이그레이션 패턴
    test-template.md     # 테스트 작성 패턴
    CHANGELOG.md         # 프롬프트 변경 이력

<!-- .prompts/CHANGELOG.md -->
## 2025-03-15
- api-endpoint.md v3: 인증 미들웨어 참조 규칙 추가
- 원인: AI가 보호된 라우트에서 인증 체크를 누락하는 패턴 3회 반복

## 2025-03-08
- api-endpoint.md v2: 응답 형식 통일 규칙 추가
- 원인: AI가 매번 다른 응답 구조를 생성

## 역방향 분석 기록

### 2025-03-14 - 결제 웹훅 처리기
- 결과: 한 번에 프로덕션 수준의 코드 생성
- 성공 요인 분석:
  1. 기존 웹훅 처리기 코드를 컨텍스트로 제공
  2. 멱등성 요구사항을 명시
  3. 실패 시나리오 5개를 구체적으로 나열
- 학습: "기존 코드 예시 + 실패 시나리오 나열"이 이 팀의 핵심 패턴

## 팀 프롬프트 패턴

### API 엔드포인트 생성
[Context] 기술 스택, 인증 방식, 관련 모델
[Intent] 어떤 데이터를 어떻게 처리
[Constraints] 페이지네이션, 필터링, 권한, 응답 형식
[Validation] 엣지 케이스 목록

### DB 마이그레이션
[Context] 현재 스키마, 관련 쿼리, 데이터 규모
[Intent] 어떤 변경을 왜 하는지
[Constraints] 무중단 배포, 롤백 가능, 기존 데이터 보존
[Validation] 마이그레이션 전후 데이터 정합성

### 버그 수정
[Context] 증상, 재현 조건, 관련 로그
[Intent] 어떤 동작이 정상인지
[Constraints] 다른 기능에 영향 없을 것, 테스트 추가 필수
[Validation] 재현 시나리오에서 정상 동작 확인