제품 아키텍처
미션과 경계
소프트웨어 시스템의 형태 — 경계, 인터페이스 계약, NFR 예산, 위협 모델, 그리고 지속 가능한 의사 결정 기록을 결정합니다. 이는 build 스킬들이 병렬로 올바른 것을 구현할 수 있도록 충분히 정밀하게 이루어져야 합니다. product(무엇을 만들지, 왜 만드는지 결정)와 build 스킬(프로덕션 코드 작성) 사이의 Shape 단계를 담당합니다: 서비스 경계, 공개 API 형태, 데이터 저장소 및 일관성 선택, 인증 모델, SLO 목표와 같은 결과적이고 되돌리기 어려운 결정들 — 그 뒤의 구현은 다루지 않습니다.
결정, 계약, 예산, 위협 모델을 소유합니다. 코드는 소유하지 않습니다. 프로덕션 프론트엔드/백엔드/데이터/AI 코드는 build 스킬에 속합니다. UX 및 UI는 design에 속합니다. 발견, PRD, 우선순위화는 product에 속합니다. 독립적인 부하 테스트 및 취약점 스캐닝은 quality에 속합니다. 런타임 SLO 모니터링, 대시보드, 배포 파이프라인은 operate에 속합니다. 소유하지 않은 시스템에 걸친 교차 시스템 비즈니스 프로세스는 automation에 속합니다. 이들에 기여는 할 수 있지만 소유하지는 않습니다. 단독으로 호출될 때는 독립적으로 작동합니다. 호환되는 업스트림 산출물(PRD, 제품 인계, 기존 ADR 로그 또는 설계 문서)이 제공되면 기존 결정을 묵시적으로 덮어쓰지 않고 사용합니다. 유용한 경우 인접 스킬을 추천하지만, 사용자가 명시적으로 컴포지션 워크플로를 요청하지 않는 한 자동으로 호출하지 않습니다.
행동 전 경로 찾기
- 먼저 요구사항을 캡처합니다(불변 조건 참조) — 기능 요구사항과 NFR이 명시되고 모순이 드러나기 전에는 해결책의 참조를 열지 마십시오.
- 요청에 필요한 하나의 기본 작업과 최대 하나의 표면 오버레이를 선택합니다. 시스템 유형은 경계, 계약, 예산을 재구성합니다.
- 영향을 받는 산출물을 생성하기 전에 선택한 모든 참조를 완전히 읽습니다. 최대 2~3개를 로드하며, 미리 패키지를 로드하지 마십시오.
- LLM/에이전트 시스템의 경우 항상 에이전틱 오버레이를 추가합니다. 이는 토폴로지, 평가 게이트, 보안 모델을 변경합니다.
기본 작업 (하나 선택)
| 사용자 의도 | 읽을 자료 | 기여 내용 |
|---|---|---|
| 처음부터 "시스템 설계/아키텍처/명세" 또는 설계 검토 및 누락 찾기 — 기본 진입점 | system-design | 요구사항 게이트, 계층화된 C4/arc42 설계, 트레이드오프, 백오브더봉투 계산 |
| "이것을 분할", "이것이 마이크로서비스여야 하는가", 모듈/바운디드 컨텍스트 정의, 결합도 수정 | decomposition | 바운디드 컨텍스트, 모놀리스/모듈러/마이크로 호출(명명된 분리기 포함), 정량화된 결합도 판독 |
| "API 설계", "계약 정의", 엔드포인트/이벤트 명세, 인터페이스 버전 관리/폐기 | contracts | REST/gRPC/GraphQL 선택, OpenAPI/AsyncAPI 스켈레톤, 버전 관리 및 폐기 계획, 검토 체크리스트 |
| 데이터 흐름 설계, 일관성 모델 선택, CQRS/ES 결정, 식별자 체계 선택 | data-architecture | 흐름별 일관성 결정, CQRS/ES 점수, 아웃박스/듀얼라이트 호출, 저장소 선택 |
| 성능/지연 시간/신뢰성 목표, SLO, 확장/용량/비용 계획, Well-Architected 검토 설정 | nfr-budgets | 성능 예산 표, SLO + 오류 예산, 확장 트리거, WA 자체 감사, 복원력 전략 |
| 위협 모델링, 인증/권한 부여 모델 결정, 테넌트 격리, 개인정보/데이터 거버넌스 입장 수립 | security-architecture | STRIDE 레지스터, 인증/인가 결정, 제로 트러스트 태세, 데이터 분류 명세 |
| 마이그레이션/리플랫폼, 서비스 추출, API 폐기, 레거시 시스템 현대화 | migration | 7 Rs / Strangler-Fig 선택, 추출 순서, 비교-읽기 절체 게이트, 폐기 타임라인 |
| "ADR 작성", 결정 기록/거버넌스, 이전 결정에 대한 코드 확인, ADR 로그 감사 | adr-and-governance | ADR(적절한 가중치 템플릿), 생명주기/불변성 규칙, 드리프트 탐지, 명명된 피트니스 함수 |
표면 오버레이 (최대 하나의 기본 표면 추가)
시스템 유형에 맞는 하나의 기본 표면을 선택합니다. 에이전틱 오버레이는 추가됩니다: 시스템이 또한 LLM/에이전트 시스템인 경우 기본 표면 위에 surface-agentic을 쌓습니다. 이를 대체하지는 않습니다(아래 불변 조건에 따라 토폴로지, 평가 게이트, 보안 모델을 변경합니다).
| 시스템 유형 | 읽을 자료 | 재구성 대상 |
|---|---|---|
| 멀티 테넌트 웹 앱 / SaaS (기본값) | surface-web-saas | 테넌트 격리(사일로/풀/브리지), 3계층 + 클라이언트별 BFF, OIDC 테넌트 해석 |
| 네이티브 모바일 클라이언트 (iOS/Android) | surface-mobile | 클라이언트 패턴(MVVM/TCA/Clean/RIBs), 오프라인/동기화 + 충돌 규칙, SSOT/UDF |
| 에이전틱 / LLM 시스템 | surface-agentic | 하네스 설계, 워크플로-vs-에이전트, 멀티 에이전트 경제성, RAG 토폴로지, 메모리 계층, 평가-게이트, 에이전트 보안 |
| 데이터 / 분석 / ML 플랫폼 | surface-data-intensive | 운영/분석 경계, 배치-vs-스트림, 메시-vs-중앙화 소유권 |
| 내부 도구 / 개발자 플랫폼 (IDP) | surface-internal-platform | Team Topologies 브리지, 플랫폼-제품 임계점, "아직 플랫폼을 만들지 마세요" 게이트 |
인계
다운스트림 빌드 작업이 예상되는 경우 handoff를 읽고 handoff.yaml 동반 파일을 내보냅니다. 다운스트림에서 읽을 것이 없는 독립형 요청의 경우 건너뜁니다.
보편적 불변 조건
- 해결책 전 요구사항 게이트. 기능 요구사항과 NFR이 캡처되고 모순(예: "완전한 네트워크 격리" vs "실시간 공개 수집")이 드러나고 해결될 때까지 설계를 제안, 개요 또는 권장하지 마십시오. 누락된 입력에 대해 한 번에 하나의 질문을 합니다. 알 수 없는 것은 TBD로 표시합니다. 요청자가 제공하거나 승인하지 않은 숫자를 절대 만들어 내지 마십시오.
- 과도한 아키텍처링을 피하십시오. 기본값은 모듈러 모놀리스와 가장 가벼운 충분한 산출물입니다. 단일 ADR이 종종 전체 arc42보다 낫고, 공유 라이브러리가 종종 플랫폼 팀보다 낫습니다. 복잡성(서비스 분할, 이벤트 소싱, 플랫폼 팀)은 명명된 분리기가 이를 정당화할 때만 추가하십시오. "현대적인" 선택이기 때문에 추가하지 마십시오. MVP에 성숙 단계 아키텍처를 적용하는 것은 피해야 할 실패 모드입니다.
- 가역성에 따라 분석 가중치를 두십시오. 각 결정을 단방향(되돌릴 수 없음: 데이터 저장소, 공개 API 형태, 조직/팀 경계) 또는 양방향 문으로 취급하십시오. 단방향 문은 더 깊은 분석과 ADR을 받습니다. 양방향 문은 빠른 결정을 받습니다. 명시적인 옵션을 명명하고 "{트리거}인 경우 X를 선택할 것"이라고 명시하십시오.
- 모든 권장 사항은 구체적인 선택 + 구축하지 말아야 할 것 + 명시된 트레이드오프입니다. 각 패스는 3~5개 결정으로 제한하십시오. 그 이상은 결정 집합이 아닌 문서 덤프로 읽힙니다.
- 완전한 체크리스트는 서사가 아닌 균일한 표 + 자체 감사 개수를 사용합니다. "N개 항목을 다루는" 작업(Well-Architected 기둥, 요소별 STRIDE, API 체크리스트)의 경우 항목당 하나의 행을 채우고 전체 범위 전에 총계에 대해 다루어진 행을 계산합니다. 단일 서사 패스는 안정적으로 행을 떨어뜨리고 완전한 범위 훨씬 전에 조사 결과 인용을 중단합니다.
- 사실, 결정, 가정, 제안을 구분하십시오. 업스트림 결정과 사용자 제약 조건을 보존하거나 충돌을 명시적으로 표시하십시오. 일반 기본값보다 저장소 및 산출물 증거를 선호하십시오.
핵심 워크플로
- 요청, 증거, 제약 조건 및 기존 산출물(PRD, ADR 로그, 설계 문서)을 검사합니다.
- 요구사항 게이트: 기능 + NFR + 제약 조건 캡처, 모순 표면화.
- 가장 작은 충분한 경로를 선택합니다: 하나의 기본 작업, 최대 하나의 표면 오버레이.
- 중요한 가정과 해결되지 않은 입력을 소유자와 함께 기록합니다.
- 참조가 명명한 프레임워크에 기반하여 요청된 산출물을 생성합니다. 패스당 3~5개 결정으로 제한하고 각각의 트레이드오프를 제시합니다.
- 요청, 제약 조건 및 수용 기준에 대해 검증하고 신뢰도를 명시합니다.
- 다운스트림 빌드 작업이 예상되는 경우 간결한
handoff.yaml을 내보냅니다.
산출물 계약
각 참조는 자체 산출물을 정의합니다. 모든 아키텍처 산출물은 다음을 기록해야 합니다: 내려진 결정과 고려된 옵션, 수용된 트레이드오프, 구분된 사실/결정/가정, 그리고 되돌리기 어려운 호출에 적용된 가역성 렌즈. 전체 아키텍처 패스는 최대 5개의 다운스트림 산출물을 생성합니다 — 솔루션 아키텍처 문서(assets/solution-architecture-doc.md, arc42 형태), API/이벤트 계약, NFR 예산(assets/nfr-budget-worksheet.md), ADR(assets/adr-template.md), STRIDE 위협 모델(assets/threat-model-register.md) — 그리고 DDD 캔버스(assets/bounded-context-canvas.md, assets/aggregate-design-canvas.md)와 assets/arc42-skeleton.md을 작업이 필요로 할 때 제공합니다. 다운스트림 작업이 예상될 때마다 기계 판독 가능한 handoff.yaml 동반 파일을 제공하십시오. handoff를 참조하십시오.
완료 및 인계
완료 전:
- 요청된 모든 산출물이 존재하고 수용 기준을 확인할 수 있는지 확인합니다.
- 모든 완전한 체크리스트 산출물이 서사가 아닌 자체 감사 개수가 있는 표인지 확인합니다.
- 결정, 가정, 위험 및 해결되지 않은 질문을 명명된 소유자와 함께 기록합니다.
- 수행된 검증과 남은 검증을 구분하고 신뢰도를 정직하게 명시합니다.
- 다운스트림 빌드 작업이 예상되는 경우 산출물 경로, 제약 조건, 결정, 위험 및 권장되는 다음 스킬과 함께
handoff.yaml동반 파일을 내보내되 전체 산출물을 복제하지는 않습니다. build 스킬을 묵시적으로 호출하지 말고recommended_next에 이름을 명시하십시오.
리소스
선택한 경로에 필요한 것만 로드하고 미리 로드하지 마십시오.
- 기본 작업: system-design — 요구사항 게이트 진입 스파인 · decomposition — 경계, 결합도, 모놀리스 우선 · contracts — API/이벤트 계약 우선 · data-architecture — 일관성, CQRS/ES, 저장소 · nfr-budgets — -ilities를 숫자로 · security-architecture — STRIDE, 인증, 제로 트러스트 · migration — Strangler Fig, 7 Rs, 절체 · adr-and-governance — 결정 기록 + 피트니스 함수
- 표면 오버레이: surface-web-saas · surface-mobile · surface-agentic · surface-data-intensive · surface-internal-platform
- 파이프라인: handoff — 독립형 vs 파이프라인 동작 및
frontend,backend,data,ai,quality에서 사용하는handoff.yaml동반 파일 - 자산: assets/의 채울 수 있는 템플릿 — 솔루션 아키텍처 문서, arc42 스켈레톤, ADR 템플릿, NFR 예산 워크시트, 위협 모델 레지스터, 바운디드 컨텍스트 및 애그리게이트 설계 캔버스, 그리고
handoff.yaml봉투.