Component Design

언제 사용하나요

다음 상황에서 본 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·오브젝트 스토리지·캐시를 분리하여 기술합니다.

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의 병렬 소비자