---
name: technical-design
description: 앱 개발과 기능 변경에 필요한 스택·도구, API·데이터 모델, 코드 구조와 구현 순서를 설계한다. 기술 선택, 데이터·인터페이스 변경, 여러 부분에 걸친 구현 계획이 필요할 때 사용한다. 단순 변경은 기존 구조에 맞는 짧은 작업·검증 계획으로 축소한다.
---

# 기술 설계와 구현 계획

요구사항을 기존 구조에 맞는 변경과 검증 가능한 작업으로 나눈다. 고정된 스택이나 아키텍처를 모든 프로젝트에 적용하지 않는다.

## 입력과 조사

요구사항·완료 조건, 필요한 UX 결과, 프로젝트 규칙을 확인한다. 기존 코드의 진입점·호출자·데이터 흐름, 의존성과 CI·배포 구성을 필요한 범위에서 읽는다. 미정 기술·계약·데이터·여러 모듈을 다루면 [기술 결정과 작업 계획 기준](references/design-checks.md)을 읽는다.

관련 스택이 확인되고 전문 지침을 연결할 때는 [기술별 지침 선택 기준](references/stack-guidance.md)을 읽는다. 합의한 도메인 용어·공유 결정과 실제 코드의 매핑을 계획에 반영한다.

프로젝트 정책에서 기술 선정 이후로 연기한 검증 도구·명령·CI·코드 설정을 실제 스택에 맞춰 채운다. 지금 필요한 미정 정책은 구현 전에 해소하고, 남은 연기는 결정 시점을 갱신한다. 정책 문서에는 실제 설정의 위치를 연결하고 같은 규칙을 중복 복제하지 않는다.

## 필요한 분야만 설계

- **스택·도구:** 기존 선택을 유지할 수 있는지 먼저 확인한다. 새 선택이 필요하면 실제 제약과 유지 비용에 근거해 결정한다. 버전·API·서비스 지원 여부는 구현 시점의 공식 자료로 확인한다.
- **플러그인:** 현재 사용 가능한 전문 도구·스킬을 조사하고 필요한 기능과 설정을 적는다. 설치·연결·계정 권한을 실제로 확보했는지 구분한다. 계획을 세웠다고 설치가 완료된 것으로 처리하지 않는다.
- **API·권한:** 요청·응답·오류·인증·권한과 기존 호출자 영향을 정의한다. 관련되는 경우에만 재시도·중복 처리·페이지 처리 등을 설계한다.
- **데이터:** 엔터티·관계·제약과 필요한 조회를 정한다. 변경이 있으면 기존 데이터, 마이그레이션 순서, 구·신 버전 공존 여부와 복구 가능성을 확인한다.
- **코드 구조:** 변경할 모듈과 책임·의존성을 정한다. 새로운 계층·인터페이스·범용 프레임워크는 현재 요구에 근거가 있을 때만 도입한다.
- **실행·릴리스:** 개발 실행 방법, 환경 설정과 CI 검증을 확인한다. 배포가 범위에 있으면 플랫폼·환경·배포 경로와 필요한 준비를 정한다.

## 작업 계획

요구사항과 변경 영역을 연결하고, 의존 순서대로 구현·검증 작업을 만든다. 작업마다 관련 요구와 완료 확인 방법을 연결하고, 필요한 테스트·문서는 해당 작업과 함께 다룬다. 기존 동작을 확인할 방법, 오류·권한·데이터 전환 검증을 관련 작업에 포함한다. 실제로 독립적인 작업만 병렬 가능하다고 표시하며, 이 표시는 별도 에이전트 실행 권한을 뜻하지 않는다.

결정 이유, 변경 영역, 작업 목록, 검증 기준, 미확정 외부 의존성을 전달한다. 작은 변경은 코드 위치·수정 의도·확인 방법으로 충분하다. 구현 가능한 핵심 결정이 남아 있으면 그 작업을 완료로 표시하지 않는다. 단독 설계 요청은 계획까지만 수행한다.