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

[rlacodud]

과제 체크포인트

필수 스펙

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

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

기본 과제

공통 제출

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

기본 과제(Easy)

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

심화과제

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

AI agent를 생성하고 SPEC => RED 단계까지 진행되도록 구현했습니다.

심화 과제

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

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

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

이번 과제에서는 AI의 강점을 단일 도구에 의존하기보다, 각 모델의 특화된 역할을 구분해 협업 구조로 설계했습니다.

- GPT-5: 테스트 명세 초안 작성, 코드 리뷰, 품질 평가 자동화  
- Claude 3.5: 구조화된 문서 및 가이드 작성 (`TEST_GUIDE.md`, `patterns.md` 등)  
- Cursor: TDD 사이클 실행 환경 (RED → GREEN → REFACTOR 자동화)  
- Vitest: 테스트 검증 및 리포트 생성  

이 구조를 통해 GPT가 명세 초안을 작성하고, Claude가 이를 구체화하며, Cursor가 실제 프로젝트 구조에 맞게 테스트를 실행하는 협업형 에이전트 워크플로우를 구현했습니다.

---

## 테스트를 기반으로 하는 AI 개발과 그렇지 않을 때의 차이점은 무엇이었나요?

일반적인 개발에서는 보통 기능 구현 → 테스트 작성 → 검증 순으로 진행됩니다.  
이 경우 테스트는 단순한 검증 도구에 그치며, 예상치 못한 오류나 설계 불일치가 뒤늦게 드러날 수 있습니다.

반면 테스트 기반 개발(TDD)은 테스트 명세가 개발의 출발점이 됩니다.  
즉, 기능 구현 이전에 이미 “무엇을 만들어야 하는지”가 명확히 정의되며,  
그에 따라 코드가 테스트를 ‘만족시키기 위한 방향’으로 작성됩니다.

이 차이는 단순한 순서의 변화가 아니라, 사고의 전환이었습니다.  
TDD는 명세 중심의 설계를 유도하여, 일관되고 예측 가능한 결과물을 만들 수 있게 했습니다!! (이 점에서 매우 긍정적인 인사이트를 얻었습니다)

---

## AI의 응답 품질을 높이기 위해 추가했던 여러 정보(context)는 무엇인가요?

AI가 단순한 도구가 아니라, 일관된 기준을 가진 팀원처럼 동작하도록 하기 위해  
문서 기반의 지식 레이어(Context Layer)를 구축했습니다.

- `TEST_GUIDE.md`: 테스트 작성 원칙과 패턴 정의  
- `patterns.md` / `antipatterns.md`: 좋은 테스트 구조와 피해야 할 구조 정의  
- `workflow-agents.md`: 각 Agent의 역할과 실행 순서 정의  
- `test-metrics.md`: 테스트 품질 평가 지표  
- `prompt-templates.md`: 일관된 프롬프트 포맷  

이 문서들을 통해 AI가 맥락을 잃지 않고, 명세에 기반한 판단을 내릴 수 있도록 가이드했습니다.

---

## AI가 이 context를 잘 활용하도록 하기 위해 어떤 노력을 했나요?

1. 에이전트 간 상태 동기화 체계 구축
   - `workflow-status.json`을 통해 각 Agent의 실행 상태를 공유했습니다.  
2. 명확한 역할 분리
   - `SpecAgent → TestAgent → CodeAgent → RefactorAgent → GitAgent` 순으로 단계별 책임을 분리했습니다.  
3. OrchestratorAgent를 통한 자동 제어
   - 전체 워크플로우를 자동으로 제어하여, 명세–테스트–코드–리팩토링이 순차적으로 이루어지도록 구성했습니다.

이를 통해 AI가 단순히 “코드를 짜는 도구”가 아니라, 명세를 이해하고 협업하는 개발자처럼 동작하도록 유도했습니다.

---

## 생성된 결과는 만족스러웠나요? 그리고 어떤 기준으로 평가(evaluation)했나요?

AI의 결과는 단순한 성공 여부보다 품질 메트릭으로 평가했습니다.

| 구분 | 지표 | 기준 |
|------|------|------|
| 정량 | 테스트 커버리지 | 80% 이상 |
| 정량 | 변이 테스트 점수 | 70% 이상 |
| 정성 | 명세 충실도 | 요구사항 완전 반영 |
| 정성 | 코드 품질 | 함수/변수 네이밍 규칙 준수, 중복 최소화 |

즉, “테스트를 통과하는 코드”보다는  
“품질을 보장하는 테스트와 코드 구조”를 목표로 평가했습니다.  
이로써 AI 결과물의 신뢰성과 일관성을 확보할 수 있을 것이라고 생각했습니다.
(실제로 REFACTOR까지 가보지 못해서 결과는 확실하지 않네요..ㅜㅜ)

---

## AI에게 어떤 식으로 질문했을 때 더 나은 결과를 얻을 수 있었나요?

- ❌ `테스트 코드 만들어줘` → 모호한 결과  
- ✅ `너는 TestAgent야. spec.md 기반 RED 단계를 생성해.`  
- ✅ `TEST_GUIDE.md의 AAA 규칙을 따르고, 함수명은 generateRepeats로.`  

명확한 역할과 맥락을 제공했을 때, AI의 응답 품질이 눈에 띄게 향상되었습니다.  
모호하게 지시했을 때는 오히려 질문의 수가 늘어나고 결과 품질이 불안정해졌습니다.  
따라서 “한 번의 지시로 충분히 구체적인 명령”을 내리는 것을 목표로 했습니다.

---

## AI에게 지시하는 작업의 범위를 어떻게 설정했나요?

처음에는 전체 프로세스를 한 번에 설명하고 순차적으로 실행시키려 했지만,  
그럴 경우 각 단계의 결과가 흐려지고, 초기에 정의한 기준이 손실되는 문제를 경험했습니다.

이후에는 범위를 좁히고,  
큰 개요는 유지하되 현재 수행할 단계(예: RED, GREEN 등)에 대한 세부 지침만 전달했습니다.  
이렇게 하니 각 단계의 완성도가 높아지고, 테스트–코드 간 일관성도 유지되었습니다.

> 결론: 적절한 단위는  
> “하나의 기능(feature) = 하나의 TDD 사이클(RED → GREEN → REFACTOR)” 이었습니다.

---

## 동기들에게 공유하고 싶은 자료나 문구가 있나요?

**추천 참고자료**
- [BMAD-METHOD (AI + TDD 문서 구조 예시)](https://github.com/bmad-code-org/BMAD-METHOD)  
- [Google Testing Blog – Testing Pyramid](https://testing.googleblog.com/)  
- [Martin Fowler – Test Anti-patterns](https://martinfowler.com/)

> “명세는 코드보다 앞서 존재해야 하며, 테스트는 그 명세의 거울이다.”  
> 이 문장을 이번 과제를 진행하며 실감했습니다.

---

## AI가 잘하는 것과 못하는 것에 대해 어떻게 생각하나요?

AI는 명확한 기준과 구조가 주어졌을 때 탁월한 성능을 발휘합니다.  
예를 들어, 테스트 명세 기반의 구조화나 코드 정리는 매우 안정적입니다.  
반면 맥락이 길거나 모호한 지시가 포함되면, 판단력이 흔들리고 일관성이 떨어집니다...

따라서 “명확한 조건과 목적”을 제시하는 것은 사람의 역할,  
“그 안에서 최적의 해법을 찾는 것”은 AI의 역할이라고 생각합니다.

---

## 마지막으로 느낀 점

이번 과제를 통해 AI를 단순한 도구가 아니라,  
테스트 기반 개발의 동료이자 협업 파트너로 다루는 방법을 배웠습니다.  

TDD의 원칙과 명세 중심 사고는 앞으로 개발자로서의 제 코드 철학의 중심이 될 것 같습니다.  
AI가 만들어주는 결과보다, AI와 함께 사고하며 문제를 정의하는 과정이 가장 인상적인 경험이었습니다.

---

과제 셀프회고

기술적 성장

1. TDD에 대한 이해와 적용

TDD(Test-Driven Development)는 단순히 테스트를 먼저 작성하는 개발 방식이 아니라
개발의 방향을 명확히 하는 사고 체계라는 점을 이번 과제를 통해 체감했습니다.

실패하는 테스트를 먼저 작성한다 = 무엇을 만들지부터 정확히 정의한다

단계	설명	목적
RED	실패하는 테스트 작성	문제 정의와 요구사항 구체화
GREEN	테스트를 통과하는 최소한의 코드 작성	불필요한 구현 최소화
REFACTOR	코드 품질 개선 및 중복 제거	유연하고 유지보수 가능한 코드

테스트를 먼저 작성함으로써,
코드를 짜기 위한 설계가 아니라, 테스트를 만족시키는 설계가 자연스럽게 만들어졌습니다.
이는 AI가 코드를 생성할 때도 마찬가지로, 테스트 명세가 명확해야만 정확한 코드를 얻을 수 있다는 사실을 증명했습니다.

---

2. AI Agent 개념 이해와 역할 설계

AI Agent는 단일 모델이 아닌, 역할이 분리된 협업형 지능 시스템입니다.
즉, “하나의 거대한 AI”가 아니라 역할이 명확한 AI 팀을 구성하는 개념입니다.

Agent	역할	예시
SpecAgent	요구사항 명세 및 테스트 시나리오 정의	반복 일정의 예외 조건 정의
TestAgent	실패하는 테스트 코드 작성	31일, 윤년 조건 테스트
CodeAgent	테스트를 통과시키는 최소한의 코드 생성	반복 로직 구현
RefactorAgent	코드 구조 개선 및 중복 제거	함수 추출, 네이밍 정리
GitAgent	버전 관리 및 커밋 메시지 생성	“✅ GREEN 단계 통과: 반복 일정 기능 추가”
Orchestrator	전체 단계 제어	RED → GREEN → REFACTOR 순환

각 에이전트는 “TDD 사이클의 한 단계”를 담당하고,
Orchestrator는 이를 순차적으로 실행해 AI 기반 자동 개발 파이프라인을 완성합니다.

---

3. 아키텍처적 이해

AI Agent 시스템은 아래 3개의 계층으로 구성된다고 이해했습니다.

1. Model Layer – GPT·Claude·Gemini 등 LLM이 “생각”하는 영역
2. Orchestration Layer – Agent 간 역할 분배 및 순서 제어
3. Tool Layer – Git, Test Runner, File I/O 등 실제 행동 수행

“AI는 말을 잘하지만, 행동을 못한다.”
=> 그래서 Tool Layer를 통해 행동력을 부여해야 한다는 점이 인상 깊었습니다.

---

4. AI와 TDD의 결합 — 자동화된 개발 사이클

AI와 TDD를 결합하여 아래와 같은 자동 사이클로 구현했습니다.
Orchestrator → “반복 일정 기능을 구현해라”
↓
SpecAgent → 명세 정의
↓
TestAgent → 실패하는 테스트 작성 (RED)
↓
CodeAgent → 테스트 통과 코드 작성 (GREEN)
↓
RefactorAgent → 중복 제거 및 품질 개선 (REFACTOR)
↓
GitAgent → 자동 커밋 및 스냅샷

결과적으로 사람의 역할은 명확한 명세 작성과 AI가 만든 결과를 비판적으로 검증하는 일로 귀결됩니다.

---

5. AI의 활용을 위해 고려한 핵심 역량

역량	설명	실제 적용
문제 정의력	AI는 모호한 지시를 이해하지 못한다.	테스트 문서(spec.md)에 예외 조건 명시
배경 지식의 깊이	AI는 도우미이지, 설계자는 아니다.	TDD, TypeScript, 반복 로직을 직접 학습
비판적 사고력	AI 결과를 그대로 수용하지 않는다.	AI 코드의 의도와 결과를 검증하며 수정

AI를 잘 쓰려면, 오히려 기본기가 더 단단해야 한다는 점을 절실히 느꼈습니다.

---

6. 학습 및 깨달음

• AI는 “대신 코드를 짜주는 존재”가 아니라, “테스트를 기준으로 함께 사고하는 존재”였다.
• 프롬프트 한 줄이 AI의 사고 구조를 완전히 바꾼다는 걸 깨달았다.
  (예: “테스트 작성해줘” ❌ → “너는 TestAgent야, RED 단계 코드를 생성해.” ✅)
• 문서가 많아질수록 작업이 느려지는 게 아니라, 오히려 일관성과 품질이 높아진다는 것을 체감했다.

---

개인적 회고

=> “AI를 무분별하게 쓰는 건 빠른 길 같지만, 결국 본질을 흐린다.”
=> “명확한 문제 정의와 기본 개념 이해가 AI 활용의 핵심이다.”
=> “AI는 도구가 아니라, 잘 설계된 팀원이다.”

처음엔 막막했지만,
TDD와 AI Agent 개념을 이해하고 나니 AI와의 협업이 하나의 구조적 사고 과정으로 느껴졌습니다.
이 과제는 단순한 기능 구현을 넘어서, ‘AI를 통한 문제 해결 사고법’을 익히는 경험이었습니다.

그에 따른 과제 진행 초반에 한 날 것의 생각을 첨부해보았습니다. (하단 블로그에도 포함된 내용입니다.)

내가 지금 제대로 이해하고 작업하고 있는지 모르겠다.
팀에서 나만 AI를 유료 결제로 사용하고 있지 않고 기본 배경지식도 제일 부족한 것 같다.

AI를 활용하다보니 제대로 이해하고 진행하는지 모르겠고 다 비슷한 AI로 비슷한 방식으로 진행할 것 같은데 그렇다면 어느 부분에서 차별화를 줄 수 있을지에 대한 생각이 많아졌다.

어떻게 보면 하루만에 끝낼 수도 있는 과제라는 생각이 들고 과제의 본질에 대해 깊이있게 생각하게 되는 것 같다.
AI를 활용하는 것의 장점은 과연 검증된 빠른 코딩만을 위한 것인가, AI를 잘 활용하기 위해서는 그에 따른 주변 배경 지식을 명확하고 깊이있게 아는 것이 중요하다고 생각했다.
무분별하고 막연하게 사용하는 것은 AI의 강점을 흐리는 것이고 그것이 과제의 본질 또한 아닐 것이다.

일단 AI에 대해 알아보고 TDD와 AI agent에 대해 명학히 알고 명령을 짜는 게 효율적으로 진행하는 방법같다.

ㄴ 지금 보니 "어떻게 보면 하루만에 끝낼 수도 있는 과제"는 참 오만한 생각이었습니다ㅜㅜ

리뷰 받고 싶은 내용

• 코치님이 작업하실 때나 실무에서는 테스트 명세(spec-agent.ts)와 실제 코드(code-agent.ts) 간 싱크를 유지할 때(AI가 명세를 일관적으로 반영할 수 있도록) 어떤 방식으로 하는지 공유해주실 수 있나요?
• RefactorAgent가 테스트 품질 기준(test-metrics.md)을 더 잘 반영하게 하려면 어떤 구조와 명세를 담으면 좋을까요?
• Hard를 진행하려다가 GREEN 단계에서 막혔는데 실무에서도 GREEN이 제일 어려운 단계일까요? 그렇다면 그 이유는 무엇이고 어떻게 설계를 하면 더 쉽게 진행할 수 있을까요?

마지막으로 과제를 진행하며 작성한 블로그 링크 공유드립니다!
AI를 활용한 TDD(Test-Driven-Development)