[클로드 코드 완독 챌린지] - 3주차 : 프로젝트 설계

프로젝트 아키텍처 설계

아키텍처 다이어그램 생성

아키텍처 다이어그램은 시스템의 전체 구조를 한 눈에 보여주는 핵심 도구이다. 특히 마이크로서비스처럼 복잡한 환경에서는 서비스 간 관계와 데이터 흐름을 시각적으로 표현하는 것이 팀 전체의 공통적인 이해 관계를 만드는 데 필수이다.

머메이드(Mermaid) 와 같은 텍스트 기반 다이어그램 언어를 자동으로 생성해주기 때문에, 복잡한 문법을 직접 다룰 필요 없이 요구사항에만 집중할 수 있다.

> 온라인 쇼핑몰 서비스를 위한 마이크로 아키텍처를 설계해줘
주요 기능 : 사용자 인증, 상품 관리, 주문 처리, 결제, 배송 추적
Mermaid 다이어그램으로 시각화해줘

클로드 코드는 이 요청을 바탕으로 전체 시스템을 분석하고, 프로덕션 환경에서 자주 활용되는 패턴을 반영한 다이어그램을 생성한다.

이런 결과물은 https://www.mermaidchart.com/play 와 같은 도구를 활용해 시각화할 수 있다.

앞서 생성한 다이어그램에는 이미 중요한 아키텍처 패턴들이 반영되어 있다.

1. API Gateway 패턴
   • 모든 클라이언트 요청이 단일 진입점을 통과해 인증/인가, 속도 제한, 로깅 등을 중앙에서 관리할 수 있다.
2. 서비스별 데이터베이스 분리
   • 각 마이크로서비스가 자체 데이터베이스를 보유해 결합도를 낮추고 독립적으로 확장할 수 있다.
3. 메시지 큐 기반 비동기 통신
   • 주문,결제,배송 서비스가 메시지 큐를 통해 연결되어, 한 서비스 장애가 전체 시스템에 전파되지 않도록 한다.
4. 캐싱 전략
   • 인증,상품 서비스가 레디스 캐시를 공유해, 자주 조회되는 데이터에 빠르게 응답한다.

기술 스택 검증

AI 를 활용하면 단순한 장단점 나열을 넘어, 다음 사항들까지 고려한 종합적인 분석을 받아볼 수 있다.

> 다음 기술 스택의 호환성을 검토해줘.
- Frontend : Next.js 14 + TypeScript
- Backend : NestJS + TypeScript
- Database : PostgreSQL + Redis
- Devops : Docker + Kubernetes
- CI/CD : GitHub Actions

각 기술의 버전 호환성과 잠재적 이슈를 분석해줘

---

프로젝트 구조 설계

디렉터리 구조 생성

프로젝트 디렉터리 구조는 코드의 유지보수성과 확장성을 좌우하는 핵심 설계 요소이다. 클로드 코드는 프로젝트의 유형과 규모에 적합한 디렉터리 구조를 제안한다.

> pnpm workspace 를 사용한 모노레포 구조를 생성해줘.
packages : 
- web(Next.js frontend)
- api(NestJS backend)
- shared(공통 타입 정의)
- ui(공통 UI 컴포넌트)

설정 파일 자동 생성

프로젝트의 개발 환경 설정은 팀의 코드 품질과 일관성을 유지하는 데 핵심적인 역할을 한다. 프로젝트별로 최신 베스트 프랙티스를 반영한 설정 파일들을 한 번에 생성해줘서 프로젝트가 처음부터 견고한 기반 위에서 시작할 수 있도록 한다.

> 다음 설정 파일들을 생성해줘.
1. TypeScript 설정(strict mode)
2. ESLint + Prettier 설정
3. Git hooks (Husky + lint-staged)
4. VS Code 프로젝트 설정

---

WBS 작성

자동 WBS 생성

WBS(Work Breakdown Structure) 는 프로젝트의 전체 범위를 관리 가능한 단위로 나누는 기본 도구이다. 작업을 충분히 세분화하지 않으면 일정 예측이 어긋나거나 리소스 배분이 불균형해지는 문제가 발생할 수 있다.

> 온라인 쇼핑몰 MVP 개발을 위한 WBS 를 작성해줘
- 프로젝트 기간 : 3개월
- 팀 구성 : 풀스택 개발자 2명
- Markdown 테이블 형식으로 작성해줘

티켓 관리 시스템과의 연동

작성된 WBS 는 그 자체로도 유용하지만, 실제 팀 협업에서는 티켓 관리 도구와 연결되어야 비로소 효과를 발휘한다.

전통적으로는 각 작업을 일일이 티켓으로 옮겨 적어야 했지만, 클로드 코드를 활용하면 WBS 를 바탕으로 티켓 생성 요청을 자동화할 수 있다.

장점은 아래와 같다.

1. 반복 업무 감소 : 수십 개 작업을 하나씩 수동으로 입력하는 부담을 줄임
2. 일관성 확보 : 티켓 제목, 설명, 담장자 등 동일한 기준으로 생성됨
3. 연동 유연성 : 깃허브, 지라, 리니어 등 팀이 선호하는 시스템에 맞춰 적용 가능

> 위 WBS 를 기반으로 GitHub Issues 를 자동으로 생성할 수 있는
 gh CLI 명령어 스크립트를 작성해줘

> 위 WBS 를 기반으로 Jira 티켓을 생성하는 Node.js 스크립트를 작성해줘 위 WBS 를 기반으로 Jira 티켓을 생성하는 Node.js 스크립트를 작성해줘

• 지라 : 특정 프로젝트에서는 티켓 생성 시 반드시 라벨이나 컴포넌트 필드가 필요할 수 있다.
• 깃허브 이슈 : 저장소별로 미리 정해진 이슈 템플릿이 있어서 생성된 이슈가 그 양식을 따르지 않으면 리뷰과정에서 다시 수정해야 할 수 있다.

클로드 코드를 활용할 때, 공통 규칙을 CLAUDE.md 같은 설정 파일에 기록해 두면 매번 수동으로 보정할 필요가 없다.

---

리스크 분석과 대응 계획

기술적 리스크 식별

클로드 코드를 통해 우리가 놓치기 쉬운 잠재적 위험 요소를 미리 드러내고 이에 대한 대응책을 마련해야 한다.

> 현재 프로젝트 구성을 분석하여 잠재적인 기술적 리스크를 식별하고,
 각 리스크에 대한 대응 방안을 제시해줘
 프로젝트 정보:
 - 마이크로서비스 아키텍처
 - 예상 동시 접속자 10,000 명
 - 데이터베이스 : PostgreSQL
 - 캐시 : Redis
 - 배포 : 쿠버네티스

이 명령을 실행하면 시스템의 각 컴포넌트를 분석하여 병목 지점, 단일 실패 지점, 확장성 제한,보안 취약점 등 체계적으로 식별한다.

---

프로젝트 문서 템플릿 생성

README 템플릿 생성

> 프로페셔널한 README.md 템플릿을 생성해줘
포함 사항 :
- 프로젝트 개요
- 기술 스택
- 설치 가이드
- 환경 변수 설정
- API 문서 링크
- 컨트리뷰션 가이드

ADR 작성

아키텍처 결정은 프로젝트의 장기적인 방향에 큰 영향을 미친다. ADR(Architecture Decision Record) 은 프로젝트 요구사항과 기술 스택을 바탕으로 Y-Statement 형식의 ADR 을 생성한다.

• Y-Satement 형식 : X를 선택함으로써 우리는 Y를 얻는 대신 Z를 감수한다.
• 미래의 자신과 팀을 위한 기록
  • 왜 MongoDB 대신 PostgreSQL 을 썼는지 이해 가능
• 온보딩 속도 향상
  • 새 팀원이 읽기만 해도 이해
• 기술 부채 관리
  • Consequences 섹션의 부정적 결과가 곧 기술 부채 목록이 됨

> PostgreSQL vs MongoDB 선택에 대한 ADR 을 작성해줘.
Y-Statement 형식을 사용해

README 는 외부인을 위한 가이드 역할, ADR 은 내부 팀을 위한 기억과 기준점 역할이다.

---