dev-architecture

기능 개발의 두 번째 단계로, 시스템 구조와 기술 방향을 설계한다. AI가 기술 옵션과 트레이드오프를 분석하고, 사용자가 최종 기술 결정을 내린다.

Workflow

1. 선행 문서 및 코드베이스 분석

다음을 순서대로 확인한다:

1. docs/dev-process/PRD.md가 존재하면 읽어서 요구사항을 파악한다
2. 프로젝트 구조를 Glob으로 탐색한다 (package.json, go.mod, requirements.txt, Cargo.toml 등으로 기술 스택 파악)
3. 기존 아키텍처 패턴을 코드에서 파악한다 (디렉토리 구조, 모듈 구성, 의존성 흐름)

PRD가 없으면 사용자에게 기능 개요를 직접 물어본다.

2. 정보 수집 — 1차 질문 (기술 맥락)

• 현재 사용 중인 기술 스택과 유지해야 할 제약은?
• 이 기능의 예상 트래픽/데이터 규모는? (해당 시)
• 특별히 고려해야 할 비기능 요구사항(성능, 보안, 확장성)은?

3. 정보 수집 — 2차 질문 (설계 방향)

1차 답변과 코드베이스 분석을 바탕으로:

• 기존 시스템에서 재사용하거나 확장할 부분은?
• 새로 도입을 검토 중인 기술이나 패턴이 있는가?
• 외부 시스템 연동이 필요한가? (API, 메시지 큐, 외부 서비스 등)

4. 기술 옵션 분석

주요 설계 결정 포인트별로 기술 옵션을 분석한다:

각 결정 포인트마다:

• 2~3개 옵션 제시
• 옵션별 장단점(Pros/Cons) 정리
• 현재 프로젝트 맥락에서의 추천과 근거

AI는 추천안을 제시하되, 최종 결정은 사용자에게 맡긴다.

5. 아키텍처 문서 작성

사용자의 결정을 반영하여 references/architecture-template.md 형식으로 문서를 작성한다.

작성 원칙:

• 구현 코드가 아닌 구조에 집중한다
• 컴포넌트 간 의존성과 데이터 흐름을 명확히 한다
• 기존 코드베이스와의 통합 지점을 구체적으로 명시한다
• 결정의 근거(ADR)를 반드시 기록한다

6. 리뷰 및 확정

초안을 사용자에게 보여주고:

• 기술 결정에 대한 최종 확인
• 누락된 컴포넌트나 연동 포인트 확인
• 시스템 영향 범위 검증

피드백을 반영하여 확정한다.

7. Output

docs/dev-process/ARCHITECTURE.md에 저장한다. 파일 저장 후 한 줄 요약과 함께 다음 단계(/dev-spec)를 안내한다.