Introduction

.intent.yml은 개발 의도를 명세하는 YAML 기반 형식이다. 무엇을 만들어야 하는가를 코드베이스 안에 선언적으로 기술한다.

왜 필요한가

개발 워크플로우에서 "의도"는 이슈 설명이나 구두 논의에만 존재하는 경우가 많다. 코드가 작성된 후에는 원래 의도를 추적하기 어렵고, AI 에이전트가 구현을 담당할 때는 명확한 명세가 더욱 중요하다.

.intent.yml은 이 간극을 메운다:

• 사용자가 의도를 명세한다 (무엇을, 왜)
• 구현자(사람 또는 AI)가 이를 기반으로 테스트와 코드를 작성한다

왜 YAML인가

• 들여쓰기로 계층을 표현하여 별도 문법 학습이 불필요하다
• 주석을 지원하여 명세 내에 부가 설명을 남길 수 있다
• 대부분의 에디터와 도구에서 기본 지원된다

핵심 구조

.intent.yml은 5개의 최상위 섹션으로 구성된다:

apiVersion: v1          # 형식 버전

kind: Feature                 # 명세 유형

metadata:                     # 메타 정보
  name: my-feature
  title: 기능 제목

context: |                    # 배경과 목적
  왜 이 기능이 필요한지 서술한다.

spec:                         # 의도 선언
  behaviors:
    - 원하는 동작을 서술한다

섹션	역할	차용한 형식
apiVersion / kind	이 명세가 무엇인지	Kubernetes
metadata	식별과 분류	Kubernetes
context	왜 필요한지	ADR
spec	원하는 상태가 무엇인지	Kubernetes, Gherkin

apiVersion, kind, metadata, context, spec.behaviors만 있으면 유효한 명세다. 나머지 필드는 모두 선택이다.

프로젝트 수준 관리

개별 .intent.yml 파일이 늘어나면 intent-map.yml로 전체 구조를 관리한다. 도메인별로 spec을 분류하여 프로젝트의 전체 범위를 한눈에 파악할 수 있다.

# intent-map.yml
apiVersion: v1
metadata:
  name: my-project
  title: 프로젝트 제목
domains:
  auth:
    title: 인증
    specs:
      - signup
      - login

자세한 내용은 Intent Map 가이드에서 다룬다.

다음 단계

• Quick Start — 최소 명세를 작성해본다