.intent.yml

Appearance

Quick Start ​

최소한의 필드로 .intent.yml 명세를 작성하고, 단계별로 확장하는 방법을 안내한다.

1단계: 최소 명세 ​

5개의 필수 섹션만으로 유효한 명세를 만들 수 있다:

yaml
apiVersion: v1

kind: Enhancement

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

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

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

이것만으로 명세가 완성된다. behaviors에 원하는 동작을 나열하면 구현자가 이를 기반으로 작업할 수 있다.

2단계: 메타데이터 확장 ​

필요에 따라 metadata에 선택 필드를 추가한다:

yaml
metadata:
  name: dark-mode
  title: 다크 모드
  package: ui-kit
  issue: VIGOR13-200
  status: draft
  tags:
    - accessibility
    - theme
  • package — 대상 패키지를 명시한다
  • issue — 연관된 이슈 트래커 식별자를 연결한다
  • status — 명세의 현재 상태를 표시한다 (Status Lifecycle 참조)
  • tags — 분류 태그를 추가한다

3단계: 시나리오 추가 ​

동작을 구체적인 상황으로 검증하고 싶으면 scenarios를 추가한다:

yaml
spec:
  behaviors:
    - 라이트/다크 테마를 전환할 수 있다

  scenarios:
    - name: 테마 전환
      given: 현재 라이트 모드이다
      when: 다크 모드 토글을 클릭한다
      then: 화면이 다크 모드로 전환된다

scenarios는 Given/When/Then 구조로 기대 동작을 명확히 기술한다.

4단계: 제약 조건과 미결정 사항 ​

제약 조건(constraints)과 미결정 사항(openQuestions)으로 명세를 보완한다:

yaml
constraints:
  - 테마 전환 시 페이지 새로고침 없이 적용된다
  - level: SHOULD
    text: CSS 커스텀 프로퍼티로 테마를 구현한다

openQuestions:
  - 시스템 설정 변경 시 자동으로 테마를 전환할 것인가?
  • constraints의 문자열은 MUST 수준으로 간주된다 (축약 문법 참조)
  • openQuestions는 결정이 내려지면 decidedAt과 decision을 추가한다

파일 위치 ​

프로젝트의 specs/ 디렉토리에 <name>.intent.yml 형식으로 저장한다:

specs/
  intent-map.yml              # 프로젝트 전체 spec 매니페스트
  dark-mode.intent.yml
  shopping-cart.intent.yml

파일명은 metadata.name과 일치시킨다. spec이 늘어나면 intent-map.yml로 도메인별 구조를 관리할 수 있다 (Intent Map 참조).

다음 단계 ​

  • Kind Types — 명세 유형 3가지를 이해한다