component-design

name	component-design
description	Inception 아티팩트(requirements, user-stories, workflow-plan)를 입력으로 받아 agentic 시스템의 컴포넌트 경계·인터페이스 계약·데이터 모델을 설계하고 `.omao/plans/construction/design.md`를 생성한다. Agent·Tool·Memory·Gateway 경계를 명확히 나누고 후속 code-generation·test-strategy skill의 단일 진실원 역할을 한다.
argument-hint	[feature or unit name]
user-invocable	true
model	claude-opus-4-7
allowed-tools	Read,Grep,Glob,Bash

언제 사용하나요

다음 상황에서 본 skill을 실행합니다.

• AIDLC Construction 단계 진입 직후 신규 feature·unit의 컴포넌트 설계가 필요할 때
• Inception이 생성한 requirements·user-stories가 모두 승인 완료된 상태에서 구현 진입을 준비할 때
• 기존 컴포넌트의 인터페이스 변경·데이터 모델 진화(schema migration)가 필요할 때
• Agent·Tool·Memory·Gateway 경계가 모호하여 팀 간 합의가 필요할 때

다음 상황에서는 사용하지 않습니다.

• Inception 아티팩트(requirements·user-stories·workflow-plan)가 아직 확정되지 않은 상태 — 먼저 aidlc (inception) skill들로 상위 단계를 완료해야 합니다.
• 단순 버그 픽스·리팩토링 — 설계 문서 갱신이 필요 없는 변경은 code-generation skill로 직접 진행합니다.

전제 조건

• aidlc-docs/inception/requirements.md 존재 및 Inception stage가 Completed 상태.
• aidlc-docs/inception/user-stories.md 존재, 각 스토리에 수락 기준(acceptance criteria) 포함.
• aidlc-docs/inception/workflow-plan.md 존재, 컴포넌트 간 호출 순서와 데이터 흐름 기술.
• .omao/plans/construction/ 디렉토리 쓰기 권한.
• 팀 내 최소 1명의 설계 리뷰어 지정(승인 gate 담당자).

실행 절차

Step 1: Inception 아티팩트 로딩 및 범위 확정

Inception 산출물을 읽고 본 설계 세션의 범위를 확정합니다.

FEATURE="$1"  # 예: rag-qa-agent
test -f aidlc-docs/inception/requirements.md || { echo "missing requirements"; exit 1; }
test -f aidlc-docs/inception/user-stories.md || { echo "missing user-stories"; exit 1; }
test -f aidlc-docs/inception/workflow-plan.md || { echo "missing workflow-plan"; exit 1; }
mkdir -p .omao/plans/construction

범위 확정 항목: 대상 feature 이름, 포함 user stories 목록, 제외 항목(out-of-scope), 외부 시스템 경계.

Step 2: 컴포넌트 경계 식별

Agentic 시스템의 4가지 표준 역할 축에 따라 컴포넌트를 분류합니다.

• Agent — LLM 호출과 결정 논리를 담당하는 컴포넌트
• Tool — Agent가 호출하는 결정적(deterministic) 함수 또는 외부 API 클라이언트
• Memory — 대화 이력·벡터 저장소·KV 캐시 등 상태 보관소
• Gateway — 라우팅·rate limit·guardrail을 수행하는 입출력 경계

각 컴포넌트의 책임·입력·출력·에러 경로를 표로 정리합니다.

Step 3: 인터페이스 계약 작성

컴포넌트 간 호출은 타입 서명·에러 모델·멱등성(idempotency) 정책을 포함한 계약으로 명세합니다. Python의 경우 Protocol 또는 dataclass, TypeScript의 경우 interface를 사용합니다.

from typing import Protocol, Sequence
from dataclasses import dataclass

@dataclass(frozen=True)
class RetrievalResult:
    doc_id: str
    score: float
    content: str

class RetrievalTool(Protocol):
    def search(self, query: str, top_k: int) -> Sequence[RetrievalResult]: ...

모든 인터페이스는 다음 4가지를 명시합니다: 입력 타입, 출력 타입, 예외 타입, 멱등성 여부.

Step 4: 데이터 모델 정의

영속 데이터는 별도 섹션으로 스키마를 정의합니다. 벡터 DB·RDB·오브젝트 스토리지·캐시를 분리하여 기술합니다.

저장소 종류	기술 스택 권장	스키마 필수 항목
벡터 DB	Milvus, pgvector	collection 이름, dimension, metric, partition 키
RDB	PostgreSQL	테이블명, PK, FK, 인덱스, 제약조건
오브젝트 스토리지	S3	bucket, prefix, 객체 lifecycle
캐시	Redis, ElastiCache	key 패턴, TTL, eviction 정책

Step 5: design.md 산출물 작성

다음 섹션 순서로 .omao/plans/construction/design.md를 작성합니다.

1. Overview — 해결할 문제, 범위, 대상 사용자
2. Architecture Diagram — Mermaid sequenceDiagram 또는 flowchart
3. Components — Step 2의 경계 표
4. Interfaces — Step 3의 타입 계약 코드 블록
5. Data Model — Step 4의 저장소 스키마
6. Non-Functional Requirements — latency SLO, 비용 상한, 보안 요구사항
7. Risks and Mitigations — 비결정성·LLM 장애·데이터 노출 3대 리스크
8. Review Checklist — 설계 리뷰어가 승인 전에 확인할 체크리스트

Step 6: 설계 리뷰 요청 및 승인 대기

design.md 작성 완료 후 리뷰어에게 검토를 요청합니다. 승인 방식은 PR 코멘트 또는 audit log 기록입니다.

Migrated from plain-text audit.md to schema-validated JSONL in v0.5:

python3 -m tools.oma_audit.append \
    --actor "$USER" --role skill-component-design \
    --action gate-pass \
    --entity-type Skill --entity-id component-design \
    --phase construction \
    --reason "design.md submitted for review"

리뷰어가 승인 전까지 code-generation·test-strategy skill 실행을 차단합니다.

Good Example vs Bad Example

Good — 인터페이스가 타입·예외·멱등성을 모두 명시합니다.

class LangfuseTracer(Protocol):
    def log_trace(self, trace_id: str, payload: dict) -> None:
        """멱등: 동일 trace_id 재호출 시 첫 호출만 저장. 네트워크 실패 시 LangfuseUnavailable 발생."""

Bad — 계약이 느슨하여 구현자가 자유 해석합니다.

def log_trace(payload):
    # 어떤 타입? 실패 시 동작? 재호출 허용?
    ...

Good — Agent와 Tool 경계가 분리되어 있어 Tool만 독립적으로 unit test 가능합니다.

Bad — LLM 호출과 DB 조회가 한 함수에 혼재되어 mock 지점이 불분명합니다.

산출물 체크리스트

본 skill 실행 종료 직전 다음을 자동 검증합니다.

• .omao/plans/construction/design.md 존재
• 8개 섹션(Overview ~ Review Checklist) 모두 채워짐
• Mermaid 다이어그램 렌더링 가능
• 모든 인터페이스에 타입·예외·멱등성 명시
• 리뷰 요청이 aidlc-docs/audit.md에 기록됨

참고 자료

공식 문서

• awslabs/aidlc-workflows — Construction stage — Construction 단계 공식 규약
• Python typing.Protocol — 구조적 서브타이핑
• Mermaid sequenceDiagram — 다이어그램 문법

관련 문서 (내부)

• aidlc plugin — 입력 아티팩트 제공자
• code-generation skill — 본 skill의 후속 실행자
• test-strategy skill — 본 skill의 병렬 소비자