Examples

기존 .intent.yml 예제를 해설한다.

최소 명세: dark-mode

필수 필드만 사용하는 가장 간단한 형태다.

apiVersion: v1

kind: Enhancement

metadata: 
  name: dark-mode
  title: 다크 모드

context: |
  장시간 화면을 보는 사용자의 눈 피로를 줄이기 위해 # [!code highlight]
  다크 모드를 지원한다. # [!code highlight]

spec: 
  behaviors: 
    - 라이트/다크 테마를 전환할 수 있다
    - 시스템 설정에 따라 초기 테마가 결정된다
    - 선택한 테마는 재방문 시에도 유지된다

주목할 점:

• kind: Enhancement — 새 기능이 아니라 기존 앱에 테마 지원을 추가하는 개선이다
• 선택 필드(drivers, constraints, scenarios 등)를 모두 생략했다
• metadata.status를 생략하면 draft로 간주된다
• behaviors 3개로 핵심 의도를 충분히 전달한다

전체 명세: shopping-cart

모든 선택 필드를 활용하는 상세한 명세다.

메타 정보

apiVersion: v1

kind: Feature

metadata:
  name: shopping-cart
  title: 장바구니
  package: store              # 대상 패키지
  issue: VIGOR13-100          # Linear 이슈 연결
  status: draft               # 현재 상태
  tags:                       # 분류 태그
    - e-commerce
    - core-feature

metadata의 선택 필드를 모두 활용하여 패키지, 이슈 트래커, 상태, 태그를 기록한다.

배경과 동인

context: |
  사용자가 상품을 탐색하면서 구매할 항목을 모아두는 장바구니가 필요하다.
  장바구니는 구매 전환율에 직접적인 영향을 미치는 핵심 기능이다.

drivers:
  - 상품 상세 페이지에서 바로 구매로 이어지는 흐름이 없다
  - text: 여러 상품을 한 번에 주문하고 싶다는 사용자 피드백
    source: 2026-01 사용자 설문

drivers에서 문자열 축약형과 객체 전체형을 혼용하고 있다. 두 번째 항목은 source로 근거를 명시한다.

동작과 시나리오

spec:
  behaviors:
    - 상품을 장바구니에 추가할 수 있다
    - 장바구니에서 상품 수량을 변경할 수 있다
    - 장바구니에서 상품을 제거할 수 있다
    - 장바구니의 총 금액을 확인할 수 있다
    - 장바구니에서 주문 페이지로 이동할 수 있다

  scenarios:
    - name: 상품 추가
      given: 재고가 있는 상품 상세 페이지에 있다
      when: 장바구니 담기 버튼을 클릭한다
      then: 해당 상품이 수량 1로 장바구니에 추가된다

    - name: 동일 상품 재추가
      given: 장바구니에 상품 A가 2개 있다
      when: 상품 A를 다시 장바구니에 담는다
      then: 상품 A의 수량이 3으로 증가한다

    - name: 재고 초과 방지
      given: 상품 B의 재고가 5개이고 장바구니에 5개가 담겨 있다
      when: 상품 B를 다시 장바구니에 담는다
      then: 재고 부족 안내가 표시되고 수량은 5로 유지된다

    - name: 빈 장바구니
      given: 장바구니가 비어 있다
      when: 장바구니 페이지에 진입한다
      then: 빈 장바구니 안내와 상품 탐색 링크가 표시된다

behaviors는 높은 수준의 동작을 나열하고, scenarios는 구체적인 상황을 Given/When/Then으로 기술한다.

제약 조건

constraints:
  - 재고가 0인 상품은 장바구니에 담을 수 없다
  - 상품 수량은 해당 상품의 재고 수를 초과할 수 없다
  - level: SHOULD
    text: 장바구니는 브라우저를 닫아도 유지된다
  - level: MAY
    text: 비회원도 장바구니를 사용할 수 있다

처음 두 항목은 문자열이므로 MUST 수준이다. 나머지는 level을 명시하여 SHOULD와 MAY를 구분한다.

데이터 예시

examples:
  - name: 기본 장바구니
    input:
      items:
        - productId: P001
          name: TypeScript 입문서
          price: 25000
          quantity: 2
        - productId: P002
          name: 무선 키보드
          price: 89000
          quantity: 1
    expected:
      totalItems: 3
      totalPrice: 139000

  - name: 수량 변경
    input:
      cartItemId: P001
      newQuantity: 5
    expected:
      updatedQuantity: 5
      totalPrice: 214000

examples는 구체적인 입출력 데이터를 제공하여 behaviors와 scenarios를 보완한다. 테스트 데이터로 직접 활용할 수 있다.

미결정 사항

openQuestions:
  - 장바구니 항목 수 제한이 필요한가?
  - text: 비회원 장바구니의 만료 기간은?
    decidedAt: 2026-02-01
    decision: 7일 후 자동 삭제

첫 번째 질문은 아직 미결정이다. 두 번째 질문은 결정이 내려져 decidedAt과 decision이 기록되었다. 모든 질문이 결정되면 status를 review로 전환할 수 있다.