[5팀 진재윤] Chapter 1-2. AI와 테스트를 활용한 안정적인 기능 개발

[jy0813]

과제 체크포인트

필수 스펙

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

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

기본 과제

공통 제출

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

기본 과제(Easy)

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

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

에이전트를 설계하면서 너무 큰 그림을 한 번에 완성하려고하여 테스트를 시작하기 전 여러가지 자동화 스크립트들이 작동하지않고,
feedback-protocol.md 를 활용하여 피드백 루프를 하려했지만.. 제대로 작동하지 않아서 개선하려던 채팅 히스토리 스크린샷 입니다!

기본 과제(Hard)

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

심화 과제

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

# AI와 테스트를 활용한 안정적인 기능 개발 리포트

## 사용하는 도구를 선택한 이유가 있을까요? 각 도구의 특징에 대해 조사해본적이 있나요?

- 평소 클로드 코드를 자주 사용해왔기 때문에, 이번에도 자연스럽게 클로드 코드를 기반으로 작업을 시작했습니다.
- 클로드 코드는 SuperClaude 라는 오픈소스 프레임워크 로 업그레이드하여 사용하고, 클로드 코드를 기반으로 더 많은 명령어, 페르소나를
 사용한다. 정도로 알고있습니다.

## 테스트를 기반으로 하는 AI를 통한 기능 개발과 없을 때의 기능개발은 차이가 있었나요? 

- AI를 이용한 기능 개발은 테스트 코드가 있을 때 훨씬 안정적으로 흘러갔습니다. AI는 명세를 하고, 역할을 나누고,
테스트는 AI의 명세와 역할을 기반으로 개발하고, 확실히 처음 1주차에 AI 없이 사용했던것 보다 훨씬 편리하게 디스크립션 등 을 명시할수 있었습니다.

## AI의 응답을 개선하기 위해 추가했던 여러 정보(context)는 무엇인가요? 

1. 명세 문서 (specs/, 9개 파일, ~3,000줄)
   - Given-When-Then 패턴으로 모든 요구사항 정의
   - AI가 읽고 코드 생성 가능한 수준의 상세도
   - 예: specs/09-recurring-events.md (33KB)

2. 테스트 규칙 (rules/, 4개 파일, ~800줄)
   - Testing Library 쿼리 우선순위 (getByRole > getByLabelText > getByTestId)
   - TDD Red-Green-Refactor 원칙
   - 안티패턴 명시

3. 6 Agent 시스템 (.claude/agents/, 6개 파일, ~1,500줄)
   - Agent 1-6 역할 분담 및 전문화
   - 각 Agent의 출력물이 다음 Agent의 입력
   - 품질 게이트: Agent 1 (8개 항목), Agent 2 (5개 항목)

4. 자동화 스크립트 (.claude/scripts/, 8개, ~1,200줄)
   - 30% → 70% 자동화 수준
   - 평균 75-91% 시간 절감
   - commit-helper.sh, test-enforcer.sh, quality-gate.sh 등

5.  지식 베이스 (.claude/knowledge-base/, 4개 디렉토리, ~500줄)
   - patterns/ - TDD 패턴, 테스트 패턴
   - lessons-learned/ - Agent 협업 교훈
   - common-errors/ - 자주 발생하는 에러
   - best-practices/ - Agent 1-6별 베스트 프랙티스

6.  피드백 프로토콜 (.claude/feedback-protocol.md, ~288줄)
   - Agent 2 → Agent 1: 명세 품질 피드백 (최대 3회 재시도)
   - Agent 6 → Agent 3, 4, 5: 커밋/품질 문제 피드백 (최대 2회)
   - 3단계 근거 서술 (사실 → 평가 → 대안)

7.  마스터 문서 (CLAUDE.md, 2,600줄, v2.9.2)
   - 단일 진입점으로 전체 프로젝트 이해 가능
   - 10개 버전 진화 (v1.0.0 → v2.9.2)
   - 모든 관련 문서 상호 참조

## 이 context를 잘 활용하게 하기 위해 했던 노력이 있나요?

6가지 전략으로 Context 활용을 최적화했습니다:

전략 1: 우선순위 시스템
- 1순위: 명세 문서 (specs/) - 무엇을 구현할지
- 2순위: 테스트 규칙 (rules/) - 어떻게 테스트할지
- 3순위: CLAUDE.md - 프로젝트 구조
- 4순위: Agent 시스템 - 워크플로우

전략 2: Given-When-Then 패턴 강제
- 모든 명세와 테스트에서 일관된 형식
- AI가 자동으로 명세 → 테스트 변환 가능

전략 3: 산출물 흐름도
- Agent 1 → specs/[기능명].md → Agent 2
- Agent 2 → claudedocs/02-test-design-*.md → Agent 3
- Agent 3 → src/__tests__/unit/*.spec.ts → Agent 4
- Agent 4 → src/utils/*.ts → Agent 5
- Agent 5 → 개선된 코드 → Agent 6
- Agent 6 → claudedocs/06-orchestrator-*.md

전략 4: 템플릿 시스템
- claudedocs/templates/ (6개 템플릿, 835줄)
- 각 Agent별 산출물 템플릿 제공
- 일관된 문서 형식 보장

전략 5: 자동화 통합
- doc-generator.sh: 템플릿 기반 문서 자동 생성
- feedback-generator.sh: 지식 베이스 활용 피드백 생성

전략 6: 피드백 루프
- Agent 2 → Agent 1: 명세 품질 검증 (3회 재시도)
- Agent 6 → Agent 3, 4, 5: 커밋/품질 검증 (2회 재시도)

## 생성된 여러 결과는 만족스러웠나요? AI의 응답을 어떤 기준을 갖고 '평가(evaluation)'했나요?

3가지 평가 기준 (정량적 + 정성적 + 시스템 수준)을 사용했습니다.

A. 정량적 기준 (Quantitative Metrics)

| 항목 | 목표 | 실제 | 평가 |
|------|------|------|------|
| 테스트 통과율 | 100% | 100% (21개) | ⭐⭐⭐⭐⭐ |
| 테스트 커버리지 | 85% | 99.16% (repeatUtils.ts) | ⭐⭐⭐⭐⭐ |
| TypeScript 에러 | 0개 | 0개 | ⭐⭐⭐⭐⭐ |
| ESLint 에러 | 0개 | 0개 | ⭐⭐⭐⭐⭐ |
| Git 커밋 규칙 | 100% | 5/5개 커밋 | ⭐⭐⭐⭐⭐ |
| 자동화 효율 | 70% | 82% 절감 | ⭐⭐⭐⭐⭐ |

B. 정성적 기준 (Qualitative Metrics)

| 항목 | 평가 방법 | 결과 | 평가 |
|------|----------|------|------|
| 명세 준수도 | 요구사항 100% 구현 확인 | 4가지 반복 유형 완벽 구현 | ⭐⭐⭐⭐⭐ |
| TDD 사이클 | Red-Green-Refactor 순서 검증 | 시간 순서 완벽 준수 | ⭐⭐⭐⭐⭐ |
| 코드 품질 | Agent 5 리팩토링 의미 | 매직 넘버 상수화, JSDoc 추가 | ⭐⭐⭐⭐☆ |
| 문서화 품질 | Agent 산출물 추적성 | 11개 파일 완벽 추적 | ⭐⭐⭐⭐⭐ |
| AI 응답 품질 | 명세와 규칙 준수 | Testing Library 쿼리 100% 준수 | ⭐⭐⭐⭐⭐ |

C. 시스템 수준 평가

| 항목 | 평가 방법 | 결과 | 평가 |
|------|----------|------|------|
| Agent 협업 | 산출물 전달 원활성 | 5단계 완벽 협업 | ⭐⭐⭐⭐⭐ |
| 피드백 루프 | 품질 향상 기여 | 1회 피드백으로 개선 | ⭐⭐⭐⭐⭐ |
| 자동화 안정성 | 스크립트 성공률 | 100% 안정 동작 | ⭐⭐⭐⭐⭐ |

사실 이런 수치가 제대로 적용되지는 않았습니다. 이러한 기준을 정해도, 여러가지 컨텍스트를 사용해도 한번에 너무 큰 그림을 그리다보니,
에이전트에 제대로 적용이 안되서 꽤나 많은 리팩토링 작업이 있었고, 리팩토링 작업도 큰 그림에서 테스트 1개를 돌려보고 나서부터 시작했던지라 원하던 리팩토링을 실패하여 사용하지 않는 Context가 많아졌습니다.
결과는 만족스럽지 못했지만 그래도 이러한 경험을 통해서 앞으로는 같은 실수는 반복하지 않을겁니다! 

## AI에게 어떻게 질문하는것이 더 나은 결과를 얻을 수 있었나요? 시도했던 여러 경험을 알려주세요. 

- 큰 단위보다는 작은 단위로 쪼개는 범위로 작성했습니다.
- 참조 문서를 명시하였습니다.
- 6 Agent 시스템(BAMD)을 사용하여 TDD 를 준수하였습니다.  
- 자동화 스크립트 중 commit-helper.sh 를 사용하여 일관성을 보장했습니다.
- feedback-protocol.md 를 활용하여 피드백 루프를 활용했습니다.

하지만 아쉽게도 아래 2가지는 열심히 공들였던 부분인데 아침에 커밋을 되돌리고 작업하느라 다시..사용하지 않는 형태로 남아버렸습니다... 


## AI에게 지시하는 작업의 범위를 어떻게 잡았나요? 범위를 좁게, 넓게 해보고 결과를 적어주세요. 그리고 내가 생각하는 적절한 단위를 말해보세요.

범위를 넓게 잡으면 에이전트가 오히려 불안정하게 동작했습니다.
하나의 함수, 하나의 문단, 하나의 규칙 — 이런 작은 단위 단위의 Context를 명확히 주는 것이 최적이었습니다.
테스트도 그렇듯, “작게 쪼개고 점진적으로 확장하는 것” 이 가장 이상적인 접근이었습니다!

## 동기들에게 공유하고 싶은 좋은 참고자료나 문구가 있었나요? 마음껏 자랑해주세요.

이미 영서님께서 공유해주셨지만!

[TDD 관련 문서](https://gist.github.com/spilist/8bbf75568c0214083e4d0fbbc1f8a09c)

[RTL 관련문서](https://testing-library.com/docs/queries/about/#priority)

[BMAD 관련](https://github.com/bmad-code-org/BMAD-METHOD)

[켄트백아조씨](https://kentcdodds.com/blog/common-mistakes-with-react-testing-library)


## AI가 잘하는 것과 못하는 것에 대해 고민한 적이 있나요? 내가 생각하는 지점에 대해 작성해주세요.

AI가 잘하는 것
- 패턴 인식 및 재현
- 반복 작업 자동화

AI가 못하는 것
- 모호한 요구사항 이해
- 큰 범위 한 번에 처리
- 맥락 유지 (조금 신기할정도로..?)

AI는 패턴을 빠르게 일반화하고 반복적인 태스크에는 강하지만,  맥락을 세밀하게 유지하는 데 약했습니다.
그래서 AI가 잘하도록 만드는 건 결국 사람이 Context를 어떻게 설계하느냐의 문제임을 깨달았습니다.


## 마지막으로 느낀점에 대해 적어주세요!

이번 과제는 단순히 AI를 이용해 코드를 자동화하는 과제가 아니었던거같습니다.
오히려 테스트의 본질 작은 단위, 빠른 피드백, 점진적 개선을 배우는 과정이며 설계에 본질이라고 생각이 들었습니다.
처음에는 기능 구현에만 몰두했지만, 큰 그림으로만 보고 많은걸 한번에 하려던 제가 결국 놓치고 있던 건 점진적 완성 이었습니다.
테스트처럼 에이전트도 작게 시작해서 확장해야 한다를 정말 많은 커밋을 되돌리며 체험했습니다..ㅠㅠ
그리고 AI는 도구이지, 설계자는 여전히 사람이다 라고 느꼈습니다.

---

과제 셀프회고

사실 이번 과제는 평소에 클로드 코드를 사용 중이라서 크게 걱정하지 않았습니다. (아주 큰 오만)
에이전트를 직접 만들어본다는 것도 재밌을 거라고 생각했고, 실제로 에이전트를 생성하는 과정에서 명세를 어떻게 설계할지 고민하면서 TDD에 대해 더 깊이 공부할 수 있는 시간이었습니다.

하지만 평소에 AI를 사용해본 것과 다르게, 직접 에이전트를 만든다는 건 훨씬 더 복잡했습니다.
에이전트를 설계하면서 수많은 시행착오를 겪었는데, 지금 돌아보면 너무 큰 그림을 한 번에 완성하려고 했던 게 문제였던 것 같습니다.
처음엔 에이전트의 기본 틀을 잡고 점진적으로 개선해 나갔어야 했는데, "한 번에 완성된 형태" 를 만들겠다는 욕심이 오히려 컨텍스트를 꼬이게 만들었고, 결국 자동화 흐름도 제대로 동작하지 않았습니다.

이 과정을 통해 느낀 건, 테스트든 에이전트든 '작은 단위부터 점진적으로 쌓아가는 구조적 사고'가 중요하다 는 점입니다.
테스트 코드에서 작은 함수 단위로 검증을 시작하듯, 에이전트 설계에서도 최소한의 입력-출력 단위를 먼저 정의하고, 이를 반복적으로 확장해 나갔더라면 훨씬 안정적인 결과를 얻을 수 있었을 것입니다.
이번 경험은 단순히 '코드 자동화 실패'가 아니라, TDD의 본질이라고 생각하는 빠른 피드백과 점진적 개선을 직접 몸으로 다시 배우는 계기로 작게나마 저한테 작은 위로를 주려고 합니다. 😢

결국 전날 새벽의 커밋으로 되돌아가면서 많은 걸 잃기도 했지만, 그래도 이번 과제로 뭐든지 처음부터 설계함에 있어서 어떤식으로 접근해야할지 생각해보는 시간이 되었고, 다음에는 테스트처럼, 에이전트도 “작게 시작해서 점진적으로 확장하는 설계”로 접근해보고 싶습니다.

기술적 성장

이번 TDD 과제를 진행하면서, Red-Green-Refactor 사이클을 직접 체험하며 테스트와 더 친해지는 계기가 되었습니다. 먼저 실패하는 테스트를 먼저 작성(Red) 하며 요구사항을 구체화했고, Green 단계에서는 테스트를 통과하기 위한 최소한의 기능만 구현하며 YAGNI 원칙을 자연스럽게 적용했습니다. 이후 리팩토링 단계(Refactor) 에서는 코드를 정리하고 개선하여 코드 품질을 높이는 경험을 할 수 있었습니다.

또한 스펙 주도 개발(Specification-driven Development)**의 중요성을 실감했습니다. 기능 명세를 테스트 시나리오 단위로 분해하고, 체크리스트를 기반으로 AI에게 전달할 Context 구조를 표준화함으로써, 테스트 작성 자체가 곧 설계 과정이 될 수 있음을 경험했습니다. 명세를 기준으로 코드를 설계하니 구현 방향이 훨씬 명확해졌습니다.

이번 과제에서 가장 크게 배운 점은 작은 단위의 자동화와 점진적 확장의 중요성입니다. 에이전트를 한 번에 완성하려다 여러 번 실패하면서, 기능과 테스트를 작게 쪼개 하나씩 검증하는 bottom-up 접근법의 가치를 체득할 수 있었습니다. 작은 단위부터 검증하고 점차 기능을 확장하는 방식이, 안정적이고 예측 가능한 자동화 시스템을 설계하는 핵심임을 깨달았습니다.

코드 품질

에이전트를 활용하였지만 원하던 느낌의 에이전트로 작성된 코드가 아니고, 여러가지 충돌로 인해 6개의 에이전트를 사용하는 hard 가 아닌 일부의 agent만 사용하게되어 만족되는 코드 품질이 없습니다. 에이전트를 아주 작은 단위부터 새로 검증해서 하나씩 다시 만들어야한다고 생각하여 만족스러운 코드가 전혀 없습니다..

학습 효과 분석

기술적 성장에서도 얘기한듯, 이번 과제에서 가장 크게 배운 점은 작은 단위의 자동화와 점진적 확장의 중요성입니다. 에이전트를 한 번에 완성하려다 여러 번 실패하면서, 기능과 테스트를 작게 쪼개 하나씩 검증하는 bottom-up 접근법의 가치를 체득할 수 있었습니다. 작은 단위부터 검증하고 점차 기능을 확장하는 방식이, 안정적이고 예측 가능한 자동화 시스템을 설계하는 핵심임을 깨달았습니다.

과제 피드백

AI를 활용해서 Agent를 만드는 경험 자체가 처음이었는데, 항해를 통해서 새로운 경험을 할 수 있어서 좋았습니다.

리뷰 받고 싶은 내용

아쉽게도...ㅠㅠ 많이 미흡해서 리뷰 받고 싶은 내용이 없습니다..