[6팀 노유리] Chapter 1-2. AI와 테스트를 활용한 안정적인 기능 개발

[nohyr]

과제 체크포인트

필수 스펙

• 1. 반복 유형 선택
  • 일정 생성 또는 수정 시 반복 유형을 선택할 수 있다.
  • 반복 유형은 다음과 같다: 매일, 매주, 매월, 매년
    • 31일에 매월을 선택한다면 → 매월 마지막이 아닌, 31일에만 생성하세요.
    • 윤년 29일에 매년을 선택한다면 → 29일에만 생성하세요!
  • 반복일정은 일정 겹침을 고려하지 않는다.

2. 반복 일정 표시
   • 캘린더 뷰에서 반복 일정을 아이콘을 넣어 구분하여 표시한다.
3. 반복 종료
   • 반복 종료 조건을 지정할 수 있다.
   • 옵션: 특정 날짜까지
     • 예제 특성상, 2025-12-31까지 최대 일자를 만들어 주세요.
4. 반복 일정 수정
   1. ‘해당 일정만 수정하시겠어요?’ 라는 텍스트에서 ‘예’라고 누르는 경우 단일 수정
      • 반복일정을 수정하면 단일 일정으로 변경됩니다.
      • 반복일정 아이콘도 사라집니다.
   2. ‘해당 일정만 수정하시겠어요?’ 라는 텍스트에서 ‘아니오’라고 누르는 경우 전체 수정
      • 이 경우 반복 일정은 유지됩니다.
      • 반복일정 아이콘도 유지됩니다.
5. 반복 일정 삭제
   1. ‘해당 일정만 삭제하시겠어요?’ 라는 텍스트에서 ‘예’라고 누르는 경우 단일 수정
      1. 해당 일정만 삭제합니다.
   2. ‘해당 일정만 삭제하시겠어요?’ 라는 텍스트에서 ‘아니오’라고 누르는 경우 전체 수정
      1. 반복 일정의 모든 일정을 삭제할 수 있다.

기본 과제

공통 제출

• 테스트를 잘 작성할 수 있는 규칙 명세
• 명세에 있는 기능을 구현하기 위한 테스트를 모두 작성하고 올바르게 구현했는지
• 명세에 있는 기능을 모두 올바르게 구현하고 잘 동작하는지

기본 과제(Easy)

• AI 코드를 잘 작성하기 위해 추가로 작성했던 지침
• 커밋별 올바르게 단계에 대한 작업
• AI 도구 활용을 개선하기 위해 노력한 점 PR에 작성

기본 과제(Hard)

• Agent 구현 명세 문서 또는 코드
• 커밋별 올바르게 단계에 대한 작업
• 결과를 올바로 얻기위한 history 또는 log
• AI 도구 활용을 개선하기 위해 노력한 점 PR에 작성

심화 과제

• 모든 질문에 대해 꼼꼼하게 정리했는지

---

🤖 AI 도구 활용을 개선하기 위해 노력한 점

1. 프로젝트별 맞춤 지침 작성 (CLAUDE.md)

• 프로젝트 개요: React 19 + TypeScript 기술 스택, 커스텀 훅 패턴 명시
• 아키텍처 패턴: Redux/Zustand 대신 커스텀 훅 사용, 데이터 흐름 다이어그램 제공
• 파일 구조: 모든 디렉토리 구조를 트리 형태로 명확하게 문서화
• 코딩 컨벤션: 파일 명명 규칙, 주석 작성 규칙, 에러 처리 패턴, Import 순서 명시
• 비자명한 구현 세부사항: 알림 폴링 시스템, ISO 주 표준, 반복 기능 UI 주석 처리 등 코드만으로는 알기 어려운 맥락 제공

2. TDD 워크플로우 자동화를 위한 Agent 시스템 구축

6개의 전문화된 AI Agent를 설계하여 TDD 사이클을 체계적으로 관리:

• Feature Architect: 요구사항 분석 및 설계 문서 작성
• Test Designer (RED): 실패하는 테스트 코드 작성
• Implementation Engineer (GREEN): 테스트를 통과하는 최소 구현
• Refactor Specialist (REFACTOR): 코드 품질 개선
• Quality Validator: 품질 검증 및 리뷰
• Documentation Writer: 커밋 메시지 및 문서 작성

각 Agent는 명확한 입력/출력과 책임을 가지며, .claude/agents/ 폴더에 markdown 형태로 정의

3. 상세한 명세 문서 작성 (specs/)

AI가 정확하게 구현할 수 있도록 명세를 5개 파일로 분리:

• 00-tdd-workflow.md: TDD 사이클 및 커밋 규칙
• 01-repeat-api-spec.md: API 엔드포인트 명세
• 02-repeat-generation-algorithm.md: 반복 일정 생성 알고리즘
• 03-special-cases.md: 31일 매월 반복, 윤년 2/29 처리 등 엣지 케이스
• 04-single-all-operations.md: 단일/전체 수정 및 삭제 로직

각 명세는 Given-When-Then 형식의 예제 포함

4. 컨텍스트 계층화

.claude/
├── agents/          # Agent 역할 정의 (6개 파일)
└── docs/            # 프로젝트 문서 (분리)
    ├── CODE_REVIEW_RULES.md
    ├── GIT_BRANCH_STRATEGY.md
    ├── PERFORMANCE_OPTIMIZATION.md
    └── README.md

역할(agents)과 문서(docs)를 분리하여 AI가 필요한 정보를 빠르게 찾을 수 있도록 구조화

5. 구체적이고 단계적인 프롬프트 설계

• ❌ "반복 일정 기능을 구현해줘" (모호함)
• ✅ "Test Designer 역할로, specs/02-repeat-generation-algorithm.md를 바탕으로 hard.repeatUtils.spec.ts 테스트 파일을 작성해줘" (구체적)

각 단계마다 역할을 명시하고, 참조할 문서를 지정하여 AI의 혼란 최소화

6. 테스트 파일 난이도별 명명 규칙

__tests__/
├── unit/
│   ├── easy.dateUtils.spec.ts
│   ├── easy.eventOverlap.spec.ts
│   ├── hard.repeatUtils.spec.ts          # 반복 생성 알고리즘
│   └── hard.repeatOperations.spec.ts     # 단일/전체 수정 삭제

파일명에 난이도를 표시하여 AI가 테스트 복잡도를 인지하고 적절한 수준의 테스트 작성

7. 커밋 메시지에 TDD 단계 표시

[RED] test(repeat): 반복 일정 생성 테스트 작성
[GREEN] feat(repeat): 반복 일정 생성 알고리즘 구현
[REFACTOR] refactor(repeat): 코드 구조 개선

커밋 히스토리만 봐도 TDD 사이클을 명확하게 추적 가능

---

과제 셀프회고

회사에서 AI를 적극적으로 활용하라고 했을 때, 필요성을 잘 느끼지 못했을 뿐만 아니라 AI를 어떻게 활용해야 할지 감이 잡히지 않았습니다. AI를 활용하는 방법에 대해서도 따로 공부하지 않았기 때문에 처음에는 어떻게 접근해야 할지 난감했습니다. 과제 내용을 파악하는 데 어려움이 있었고, 에이전트나 오케스트레이터 같은 낯선 용어를 접했을 때는 '과제를 1주일 안에 다 할 수 있을까?' 하는 걱정도 많았습니다. 다행히 참고 자료가 풍부해서 하루 종일 그것만 보며 학습할 수 있었습니다. 또한 회사에서 Claude AI를 사용해 보라고 결제해 주셔서, 그동안 사용해보지 못했던 AI를 이번 기회에 직접 경험할 수 있었습니다.

기술적 성장

1. TDD 실전 적용 경험

학습 내용:

• RED-GREEN-REFACTOR 사이클을 실제 기능 개발에 적용
• 테스트를 먼저 작성하니 요구사항이 명확해지고, 엣지 케이스를 사전에 발견
• 리팩토링 시 테스트가 있어 자신감 있게 코드 개선 가능

구체적 사례:

• 31일 매월 반복: 테스트 케이스 작성 중 "31일이 없는 달은 건너뛴다"는 요구사항 명확화
• 윤년 2/29: 테스트에서 isLeapYear 유틸리티 필요성을 발견하고 추가

2. 복잡한 날짜 로직 구현

학습 내용:

• new Date()의 월 인덱스가 0부터 시작하는 것을 고려한 안전한 날짜 계산
• 윤년 판별 알고리즘 (4의 배수, 100의 배수, 400의 배수 규칙)
• ISO 주 표준 (목요일 기준) 적용

구현 예시:

// 특정 월의 일수 계산
const getDaysInMonth = (year: number, month: number): number => {
  return new Date(year, month, 0).getDate();
};

// 윤년 판별
const isLeapYear = (year: number): boolean => {
  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
};

3. API 설계 패턴 학습

학습 내용:

• RESTful API 설계: /api/events/:id (단일), /api/recurring-events/:repeatId (전체)
• 의미있는 엔드포인트 분리로 단일/전체 수정 구분
• HTTP 상태 코드 적절한 사용 (200 OK, 204 No Content)

4. React Hook 최적화

학습 내용:

• useCallback으로 함수 메모이제이션하여 불필요한 리렌더링 방지
• useMemo로 비싼 계산 결과 캐싱
• React Hook exhaustive-deps 경고 해결 경험

개선 사례:

// Before: 매 렌더링마다 새 함수 생성
const checkUpcomingEvents = () => { /* ... */ };

// After: useCallback으로 메모이제이션
const checkUpcomingEvents = useCallback(() => { /* ... */ }, [events, notifiedEvents]);

코드 품질

특히 만족스러운 구현

1. 명세 기반 테스트 구조

   • 각 명세 파일마다 대응하는 테스트 파일 작성
   • 테스트 이름에 명세 ID 포함 ([SE-001], [AE-001])으로 추적성 확보

2. 반복 일정 생성 알고리즘의 확장성

   export function generateRecurringEvents(baseEvent: EventForm): Event[] {
     if (baseEvent.repeat.type === 'none') {
       return [createSingleEvent(baseEvent)];
     }
   
     const repeatId = crypto.randomUUID();
     const endDate = baseEvent.repeat.endDate || '2025-12-31';
     const events: Event[] = [];
   
     // 반복 타입별 처리가 명확하게 분리됨
     switch (baseEvent.repeat.type) {
       case 'daily': /* ... */
       case 'weekly': /* ... */
       case 'monthly': /* ... */
       case 'yearly': /* ... */
     }
   
     return events;
   }

   • 각 반복 타입의 로직이 독립적으로 분리되어 유지보수 용이
   • 새로운 반복 타입 추가 시 확장 가능

3. MSW를 활용한 API 모킹

   • 실제 API 서버 없이 테스트 가능
   • setupMockHandlerCreation, setupMockHandlerUpdating 등 헬퍼 함수로 중복 제거

리팩토링이 필요한 부분

1. App.tsx의 컴포넌트 분리

   • 현재 단일 파일에 모든 UI 로직이 집중됨 (약 800줄)
   • 개선 방향: EventForm, CalendarView, EventList 등으로 분리 필요

2. 에러 처리 일관성

   • 일부 함수는 throw, 일부는 에러 객체 반환
   • 개선 방향: Result<T, E> 타입으로 통일하거나, 전역 에러 핸들러 도입

3. 반복 일정 UI 활성화 후 통합 테스트

   • 현재 App.tsx에서 반복 UI가 주석 처리됨
   • 개선 방향: 주석 해제 후 E2E 테스트 추가 필요

코드 설계 관련 고민과 결정

고민 1: 단일/전체 수정 시 API 설계

• Option A: 쿼리 파라미터 사용 (/api/events/:id?mode=single)
• Option B: 엔드포인트 분리 (/api/events/:id, /api/recurring-events/:repeatId)
• 결정: Option B 선택
• 이유: RESTful하고 의미가 명확함, 권한 관리 시 엔드포인트별로 제어 가능

고민 2: repeat.id 생성 시점

• Option A: 프론트엔드에서 생성
• Option B: 백엔드에서 생성
• 결정: Option A 선택 (현재 구현)
• 이유: 서버가 없는 예제 특성상 클라이언트에서 UUID 생성

고민 3: 반복 일정 데이터 저장 방식

• Option A: 반복 규칙만 저장하고 필요할 때마다 생성
• Option B: 모든 개별 일정을 미리 생성하여 저장
• 결정: Option B 선택
• 이유:
  • 단일 수정 시 해당 일정만 변경 가능
  • 검색 및 필터링 성능 향상
  • 일정 겹침 감지 용이

학습 효과 분석

가장 큰 배움이 있었던 부분

1. AI와의 협업 방법론

   • AI는 "도구"가 아니라 "협업자"로 접근해야 효과적
   • 명확한 컨텍스트와 역할 부여가 핵심
   • Agent 시스템으로 복잡한 작업을 단계별로 분해하니 품질 향상

2. TDD의 실용성

   • "테스트 먼저 작성"이 비효율적이라고 생각했으나, 실제로는:
     • 요구사항 이해도 향상
     • 버그 조기 발견
     • 리팩토링 시 안전망 제공
   • 특히 날짜 로직처럼 엣지 케이스가 많은 경우 TDD가 필수

3. 명세의 중요성

   • 상세한 명세가 있으니 AI가 정확하게 구현
   • Given-When-Then 형식이 AI에게 특히 효과적
   • 명세 작성 시간이 아깝지 않음 (구현 시간 단축)

추가 학습이 필요한 영역

1. 성능 최적화

   • 현재 반복 일정을 모두 메모리에 로드하는 방식
   • 대용량 데이터 처리를 위한 가상 스크롤, 페이지네이션 학습 필요

2. 타입 안전성 강화

   • 현재 일부 as 타입 단언 사용
   • Branded Type, Template Literal Type 등으로 더 안전한 타입 설계

3. 접근성 (a11y)

   • 키보드 네비게이션 개선
   • 스크린 리더 지원
   • ARIA 레이블 추가

실무 적용 가능성

1. Agent 기반 TDD 워크플로우

   • 실무 프로젝트에도 동일하게 적용 가능
   • 팀 컨벤션을 Agent 문서에 반영하면 일관성 유지
   • 신입 개발자 온보딩 시 Agent 활용 가능

2. 명세 문서 작성 습관

   • 기획서를 specs 형태로 정리하는 습관
   • AI와의 협업뿐 아니라 팀 커뮤니케이션에도 유용

3. 테스트 우선 개발

   • 복잡한 비즈니스 로직은 TDD로 접근
   • 단순 UI는 Storybook 등 다른 도구 활용

과제 피드백

과제에서 좋았던 부분

1. 단계별 난이도 설계

   • Easy(기본 기능) → Hard(반복 일정) 순서가 적절
   • 각 단계가 이전 단계의 지식을 활용하도록 설계됨

2. 실용적인 요구사항

   • 31일 매월 반복, 윤년 2/29 등 실제 캘린더 앱에서 마주하는 문제
   • 단순한 CRUD를 넘어선 복잡한 비즈니스 로직 경험

3. TDD + AI Agent 조합

   • 최신 개발 트렌드를 반영한 과제 설계
   • 단순히 "AI 써보기"가 아니라 "AI와 협업하는 방법론" 학습

과제에서 모호하거나 애매했던 부분

1. "31일 매월 반복"의 정확한 의미

   • 처음에는 "각 달의 마지막 날"인지 "31일이 있는 달의 31일"인지 불명확
   • 명세서에 "31일에만 생성"이라고 명시되어 있어 해결
   • 개선 제안: 예시를 1~2개 더 추가하면 더 명확할 듯

2. 반복 일정 UI 주석 처리

   • App.tsx의 441~478줄이 주석 처리되어 있음
   • "8주차 과제"라는 설명이 있지만, 현재 과제에서 UI를 활성화해야 하는지 애매
   • 실제로는 주석을 해제하지 않아도 API와 로직만으로 테스트 통과

3. 테스트 데이터 파일 분리

   • realEvents.json과 e2e.json의 역할 구분이 처음에 헷갈림
   • 개선 제안: README에 테스트 데이터 관리 방법 추가

---

리뷰 받고 싶은 내용

1. 반복 일정 생성 알고리즘의 효율성

현재 구현:

// src/utils/repeatUtils.ts
export function generateRecurringEvents(baseEvent: EventForm): Event[] {
  // ...
  let currentDate = new Date(startDateObj);

  while (currentDate <= endDateObj) {
    // 각 반복 타입별로 날짜 계산 및 검증
    if (repeat.type === 'monthly') {
      const day = startDateObj.getDate();
      const daysInMonth = getDaysInMonth(currentDate.getFullYear(), currentDate.getMonth() + 1);

      if (day <= daysInMonth) {
        // 일정 생성
      }
    }
    // ...
    currentDate = getNextDate(currentDate, repeat.type);
  }
}

질문:

• 실무에서는 이런 알고리즘을 어떻게 최적화하시나요? (예: 캐싱, 사전 계산 등)

2. 단일/전체 수정 시 데이터 일관성 보장

현재 구현:

// 단일 수정: repeat.type을 'none'으로 변경
PUT /api/events/:id
{
  ...event,
  repeat: { type: 'none', interval: 1 }
}

// 전체 수정: repeat.id로 모든 일정 찾아서 수정
PUT /api/recurring-events/:repeatId
{
  startTime: '14:00',
  endTime: '15:00'
}

우려사항:

• 단일 수정 후 같은 repeat.id를 가진 다른 일정이 남아있을 때, "orphan repeat group"이 생길 수 있습니다.
• 예: 4개 중 2개를 단일 수정하면, 남은 2개만 repeat.id를 공유하게 됨

질문:

• 이런 경우 repeat.id를 유지하는 것이 맞을까요, 아니면 새로운 repeat.id를 부여해야 할까요?

3. MSW 핸들러의 상태 관리

현재 구현:

// src/__mocks__/handlers.ts
let eventsData: Event[] = [...initialEvents];

export const handlers = [
  http.get('/api/events', () => {
    return HttpResponse.json(eventsData);
  }),

  http.post('/api/events', async ({ request }) => {
    const newEvent = await request.json();
    eventsData.push(newEvent);
    return HttpResponse.json(newEvent);
  }),
];

우려사항:

• 전역 변수 eventsData를 사용하여 상태 관리
• 테스트 간 격리가 제대로 되지 않을 수 있음 (beforeEach에서 리셋하긴 함)

질문:

• MSW 핸들러의 상태 관리 베스트 프랙티스가 궁금합니다.
• 각 테스트마다 독립적인 MSW 인스턴스를 사용하는 방법도 있을까요?
• 또는 server.use()로 테스트마다 핸들러를 오버라이드하는 방식이 더 나을까요?

4. Agent 시스템의 실무 적용 가능성

현재 설계:

.claude/agents/
├── 1-feature-architect.md
├── 2-test-designer.md
├── 3-implementation-engineer.md
├── 4-refactor-specialist.md
├── 5-quality-validator.md
└── 6-documentation-writer.md

질문:

• 이런 Agent 기반 워크플로우를 실제 팀 프로젝트에 적용해보신 경험이 있으신가요?

5. 타입 안전성 개선 방향

현재 문제:

// src/types.ts
export interface RepeatInfo {
  type: 'none' | 'daily' | 'weekly' | 'monthly' | 'yearly';
  interval: number;
  endDate?: string;
  id?: string;  // 반복 그룹 ID
}

• repeat.type이 'none'일 때 id가 있으면 안 되는데, 현재 타입으로는 방지 불가
• repeat.type이 'none'이 아닐 때 id가 필수인데, optional로 정의됨

개선 방향 고민:

// Option 1: Discriminated Union
type RepeatInfo =
  | { type: 'none'; interval: 1 }
  | { type: 'daily' | 'weekly' | 'monthly' | 'yearly'; interval: number; endDate?: string; id: string };

// Option 2: Branded Type
type RepeatId = string & { readonly brand: unique symbol };

질문:

• 어떤 방식이 더 유지보수하기 좋을까요?

---

커밋 히스토리:

• TDD 사이클 준수: [RED] → [GREEN] → [REFACTOR]
• 총 144개 테스트 통과
• ESLint, TypeScript 컴파일 에러 없음

테스트 커버리지:

• 반복 일정 생성 알고리즘: 매일/매주/매월/매년 + 엣지 케이스
• 단일/전체 수정 및 삭제 API
• 윤년 및 31일 특수 케이스 처리