의도 기반 개발

의도 기반 개발(Intent-Driven Development)

명세를 형식적인 절차로 만들지 않으면서 유용한 승인 기준을 생성합니다. 먼저 사용 가능한 컨텍스트를 검사하고, 진정한 모호성을 드러내며, 작업과 그 위험에 적합한 검증 방법을 선택합니다.

활성화 시점

• 사용자가 구현 전에 기능을 명확히 하거나, 승인 기준을 정의하거나, 변경의 위험을 줄이려고 요청할 때
• 요청이 보안, 인증, 영구 데이터, 마이그레이션, 외부 API 또는 규정 준수와 관련될 때
• 사용자가 다른 에이전트나 팀에 전달할 산출물을 준비하려고 할 때
• 요청이 너무 모호하여 예상 결과를 아직 관찰하거나 테스트할 수 없을 때
• 사용자가 /intent-driven-development를 명시적으로 호출할 때

사소한 편집, 간단한 한 줄짜리 수정, 활성 디버깅 세션, 코드 리뷰 요청, 또는 승인 조건이 이미 명확한 구현 요청에는 활성화하지 마세요.

작동 방식

1. 먼저 컨텍스트 검사 — 질문을 하기 전에 저장소, 문서, 스키마, 테스트 인프라를 읽어 기술적 사실을 파악하며, 제품/비즈니스 제약 조건은 사용자나 제품 문서만이 제공할 수 있는 것으로 간주합니다.
2. 깊이 선택 — 위험 프로필에 따라 빠른 캡처(Quick Capture, 3~7개 기준, 낮음/중간 위험) 또는 전체 승인 브리핑(Full Acceptance Brief, 보안, 데이터, 마이그레이션, 시스템 간 변경)을 선택합니다.
3. 최소한으로 질문 — 추론할 수 없고 범위나 동작을 실질적으로 변경하는 질문만 합니다.
4. 관찰 가능한 기준 작성 — 각 AC-NNN은 시작 조건, 트리거, 예상 결과, 금지된 부작용, 검증 방법, 우선순위를 설명합니다. 증거 없이 '올바르게' 또는 '안전하게'와 같은 모호한 단어는 사용하지 않습니다.
5. 진행 또는 전달 — 차단 위험이 없는 명확한 요청의 경우 기준을 기록하고 계속 진행합니다. 위험한 변경의 경우 차단 요소를 제시하고 확인을 기다립니다.
6. 개정 처리 — 구현 중 아키텍처 제약으로 인해 AC를 충족할 수 없는 경우 [revised]로 표시하고, 범위 또는 검증 방법을 업데이트하며, 수정 번호를 증가시키고, 변경된 기준만 다시 제시합니다.

예시

빠른 캡처 — "대시보드에 CSV 내보내기 추가"

목표: 인증된 사용자가 대시보드 데이터를 CSV 파일로 다운로드할 수 있습니다.
범위 내: 현재 필터링된 행 내보내기; 파일 이름에 날짜 포함.
범위 외: 예약된 내보내기, 이메일 전송, Excel 형식.
가정: 최대 행 수는 10k 미만; 내보낸 필드에 개인 식별 정보(PII) 없음.

AC-001: 내보내기가 올바른 헤더로 파일을 생성합니다.
- 시나리오: 인증된 사용자, 최소 하나의 데이터 행 표시됨
- 작업: "CSV 내보내기" 클릭
- 예상: 브라우저가 [id, name, created_at] 열이 있는 파일을 다운로드함
- 금지 사항: 내부 필드나 다른 사용자에 속한 행 노출 금지
- 검증: 자동화된 통합 테스트 + 수동 스키마 점검
- 우선순위: 필수

전체 승인 브리핑 트리거 — "사용자 인증을 OAuth로 마이그레이션"

인증 변경 + 외부 의존성 + 기존 세션 데이터 → 위험 검토 테이블, 세션 무효화 전략에 대한 차단 결정, 명시적인 롤백 AC가 포함된 전체 브리핑.

기존 명세 검토 — 사용자가 PRD를 붙여넣음

스킬이 누락된 범위 경계, 검증 불가능한 요구사항("시스템이 빨라야 함"), 묵시적 가정을 검토한 후, 발견 작업을 다시 시작하지 않고 수정되거나 보충된 기준을 반환합니다.

운영 규칙

1. 로컬에서 찾을 수 있는 기술적 사실에 대해 질문하기 전에 사용 가능한 저장소, 문서, 이슈, 디자인, 테스트 컨텍스트를 검사합니다.
2. 코드로부터 제품 또는 비즈니스 제약 조건을 추론하지 마십시오. 비즈니스 규칙, 규정 준수 및 법적 의무, 계약상의 SLA, 가격, 데이터 보존 정책, 우선순위, 대상 사용자는 저장소에서 읽을 수 없습니다. 사용자가 제공하거나 권위 있는 제품 문서(PRD, 계약서, 정책 문서)에 명시될 때까지 알 수 없는 것으로 간주합니다. 이를 발견된 사실이 아닌 확인을 위해 표시된 가정으로 기록합니다. 저장소는 시스템이 오늘 어떻게 동작하는지 알려줄 뿐, 비즈니스가 요구하는 사항을 알려주지 않습니다.
3. 안전하게 추론할 수 없고 필수적인 질문만 합니다. 필요할 때 짧고 관련된 질문을 그룹화하여 불필요한 턴을 줄입니다.
4. 기본적으로 구현을 차단하지 마십시오. 사용자가 충분히 명확한 변경을 요청한 경우, 주요 가정과 승인 기준을 간략히 기록한 후 진행하거나 구현 워크플로에 전달합니다.
5. 해결되지 않은 결정이 심각한 보안 노출, 데이터 손실, 되돌릴 수 없는 마이그레이션, 계약/API 위반, 의미 있는 비용, 또는 파괴적인 외부 작업을 초래할 수 있는 경우에만 명시적인 사용자 확인을 요구합니다.
6. 사용자가 요청하거나 활성 저장소 워크플로에서 명시적으로 요구하지 않는 한, 저장소에 승인 문서를 작성하거나, 프로젝트 파일을 변경하거나, 브랜치를 생성하거나, 커밋하거나, 다른 스킬을 호출하지 마십시오.
7. 자동화된 테스트를 증거로 취급하되 진리로 취급하지 마십시오. 신뢰할 수 있고 적절할 때 자동화를 선호하되, 자동화가 결과를 확립할 수 없는 경우 수동 UX, 접근성, 보안, 법률 또는 운영 검증을 허용합니다.
8. 승인 기준, 픽스처, 예시 또는 저장된 산출물에 실제 비밀, 자격 증명, 토큰, 개인 키, 개인 데이터 또는 민감한 프로덕션 페이로드를 절대 포함하지 마십시오. 수정되거나 합성된 값을 사용하십시오.
9. 명시적인 승인과 식별된 안전한 환경 없이 프로덕션/라이브 데이터에 대해 파괴적인 테스트, 마이그레이션, 보안 프로브, 부하 테스트, 유료 외부 호출 또는 작업을 실행하지 마십시오.
10. 구현 중 발견된 아키텍처, 플랫폼 또는 외부 제약 조건으로 인해 승인 기준을 충족할 수 없는 경우, 조용히 삭제하거나 우회하지 마십시오. 영향을 받은 기준을 업데이트하고([revised]로 표시하고, 제약 조건을 명시하며, 범위 또는 검증 방법을 조정), 수정 번호를 증가시키고, 변경된 기준만 사용자에게 다시 제시한 후 계속 진행합니다. 수정이 차단 결정을 변경하거나 안전 또는 정확성 보장을 실질적으로 저하시키는 경우에만 명시적인 확인을 요구합니다.

깊이 선택

가장 작은 유용한 출력을 사용하십시오.

빠른 캡처(Quick Capture)

낮거나 중간 위험의 명확하지만 사소하지 않은 변경에 사용합니다. 다음을 생성합니다:

• 목표
• 범위 내 / 범위 외
• 가정
• 3-7개의 검증 방법이 포함된 승인 기준
• 차단 질문(있는 경우)

운영 규칙의 차단 위험이 있거나 사용자가 명시적으로 명세를 먼저 요청하지 않는 한, 승인을 위해 구현을 지연시키지 마십시오.

전체 승인 브리핑(Full Acceptance Brief)

모호하거나, 시스템 간에 걸쳐 있거나, 보안에 민감하거나, 데이터를 변경하거나, 마이그레이션, 규정 준수, 또는 고비용 변경에 사용하거나, 사용자가 전달 산출물을 요청할 때 사용합니다. 아래 전체 템플릿을 생성하고, 위험한 구현 전에 해결되지 않은 차단 결정에 대한 확인을 요청합니다.

기존 명세 검토(Existing Specification Review)

사용자가 이미 PRD, 이슈, 계획 또는 승인 기준을 제공한 경우:

1. 발견 작업을 다시 시작하는 대신 이를 검토합니다.
2. 누락된 범위 경계, 안전하지 않은 가정, 모순 및 검증 불가능한 요구사항을 식별합니다.
3. 수정되거나 보충된 기준을 반환합니다.

워크플로

1. 목표 및 위험 설정

다음을 추출하거나 묻습니다:

• 사용자 또는 시스템에 대한 관찰 가능한 결과.
• 영향을 받는 행위자.
• 주요 실패 결과.
• 실제로 적용되는 위험 차원: 보안/개인정보, 영구 데이터, 호환성/API, 마이그레이션, 외부 종속성, 비용, 동시성, 성능, 사용성/접근성.

관련 없는 위험에 대한 일반적인 질문은 피하십시오.

2. 컨텍스트 발견

로컬 또는 연결된 문서를 사용할 수 있는 경우, 필요한 것만 검사합니다:

• 기존 동작 및 직접 관련된 파일 또는 인터페이스.
• 저장소 규칙, 제품 문서, API 계약, 데이터 스키마 또는 마이그레이션 기록.
• 기존 검증 인프라 및 현실적인 명령어.
• 외부 종속성 및 격리하여 테스트할 수 있는지 여부.

발견된 사실은 사용자 제공 가정과 별도로 기록합니다. 컨텍스트를 검사할 수 없는 경우, 알 수 없는 것을 말하고 집중된 질문을 합니다.

저장소는 기술적 사실(시스템이 오늘 어떻게 동작하는지, 규칙, 계약)을 드러냅니다. 제품 또는 비즈니스 제약 조건(비즈니스 규칙, 규정 준수 및 법적 의무, 계약상의 SLA, 가격, 데이터 보존 정책, 우선순위 및 대상 사용자)을 드러내지 않습니다. 코드나 명명 규칙에서 이를 재구성하지 마십시오. 사용자나 권위 있는 제품 문서에서만 캡처하고, 확인할 때까지 가정으로 나열합니다.

3. 범위 정의

명시:

• 목표: 의도된 결과를 설명하는 한 문장.
• 범위 내: 이 변경이 제공해야 하는 동작.
• 범위 외: 명시적으로 제외되는 유혹적인 관련 작업.
• 가정: 아직 입증되지 않은 주장.
• 차단 결정: 안전성이나 동작에 실질적으로 영향을 미치는 해결되지 않은 선택.

4. 승인 기준 작성

AC-001, AC-002 등을 사용합니다. 각 기준은 관찰 가능한 동작과 적절한 검증 방법을 설명해야 합니다. 기준과 테스트가 일대일로 매핑될 필요는 없습니다.

각 해당 기준에 대해 다음을 포함합니다:

• 시나리오 또는 시작 조건.
• 작업 또는 트리거.
• 예상되는 관찰 가능한 동작.
• 의미 있는 경우 금지된 부작용.
• 검증 방법: 자동화된 테스트, 통합 검사, 수동 UX 검토, 접근성 검사, 보안 검토, 운영 검사 또는 이해관계자 승인.
• 검증이 데이터, 서비스, 비용 또는 비밀에 영향을 미칠 수 있는 경우 환경/안전 제약 조건.
• 우선순위: 필수, 중요 또는 선택.

'올바르게', '안전하게', '빠르게', '직관적으로' 또는 '견고하게'와 같은 단어는 관찰 가능한 증거를 정의하거나 인간 검토 판단으로 기록하지 않고 사용하지 마십시오.

5. 관련 경계만 다루기

다음 범주를 고려하되, 적용되는 범주만 포함합니다:

범주	포함 시점	일반적인 증거
정상 경로	새롭거나 변경된 사용자 가시 동작	성공적인 워크플로 또는 상태 전환
유효성 검사	변경이 입력을 받아들임	변이 없이 잘못된 형식 또는 경계 값 거부
인증/개인정보	데이터 또는 작업에 액세스 경계가 있음	액세스 거부 및 민감한 정보 노출 없음
영속성/마이그레이션	저장된 데이터 또는 스키마 변경	이전 읽기, 마이그레이션, 롤백 또는 백업 동작
호환성	공개 API, 파일, 이벤트 또는 클라이언트 중단 가능	기존 계약 또는 픽스처가 유효함
장애 복구	네트워크, 서비스 또는 비동기 장애 존재	부분 상태 없음 또는 명확한 재시도/저하된 동작
멱등성/동시성	반복 또는 동시 쓰기가 가능함	중복 부작용 또는 잘못된 최종 상태 없음
성능	사용자 또는 서비스 임계값이 중요함	정의된 측정 조건 및 임계값
UX/접근성	사람이 결과와 상호 작용함	키보드, 피드백, 오류 복구, 시각/수동 검토

6. 제시 및 계속

• 명확화/명세 요청의 경우, 브리핑을 제시하고 나열된 차단 요소에 대해서만 결정을 요청합니다.
• 차단 요소가 없는 구현 요청의 경우, 간결한 기준 요약을 작업의 일부로 제시하고 구현을 계속합니다.
• 다른 에이전트나 팀으로 전달하는 경우, 요구사항을 발명하지 않고 행동할 수 있는 충분한 컨텍스트와 검증 세부 정보를 포함합니다.
• 요청된 경우에만 파일에 브리핑을 저장합니다. 승인된 경로가 있는 경우 사용하고, 그렇지 않으면 쓰기 전에 선택한 대상을 묻거나 명시합니다.

출력 템플릿

전체 승인 브리핑에 이 템플릿을 사용합니다. 빠른 캡처의 경우 관련 없는 섹션은 생략합니다.

# 승인 브리핑: <변경 이름>

**상태:** 초안 | 승인됨 | 구현됨 | 검증됨
**개정:** <번호>
**대상:** <사용자/팀/에이전트, 알 때>
**위험 작업 전 승인 필요:** 예 | 아니오 - <이유>

## 개정 기록

| 개정 | 날짜 | 변경된 기준 | 이유 |
| --- | --- | --- | --- |
| 1 | <날짜> | — | 초안 |

## 목표

<하나의 관찰 가능한 결과 문장.>

## 범위

**범위 내**
- <포함된 동작>

**범위 외**
- <제외된 관련 작업>

## 컨텍스트

**발견된 사실**(저장소 또는 문서에서 확인된 기술적 사실)
- <시스템의 현재 동작, 규칙, 계약>

**제품/비즈니스 제약 조건**(사용자 또는 제품 문서에서 제공, 코드에서 추론하지 않음)
- <비즈니스 규칙, 규정 준수/SLA 의무, 보존 정책, 우선순위, 대상 사용자 — 또는 "아직 제공되지 않음">

**가정**
- <확인 또는 검증할 검증되지 않은 주장>

**종속성 및 제약 조건**
- <외부 서비스, 로컬 규칙, 호환성 의무, 환경 제한>

## 위험 검토

| 위험 영역 | 적용 여부 | 필요한 처리 |
| --- | --- | --- |
| 보안/개인정보 | 예/아니오 | <수정, 권한 부여, 검토 등> |
| 영구 데이터/마이그레이션 | 예/아니오 | <호환성, 백업, 롤백 등> |
| 외부 효과/비용 | 예/아니오 | <샌드박스/테스트 환경/권한 부여> |
| 호환성/API | 예/아니오 | <유지하거나 버전을 지정할 계약> |
| UX/접근성 | 예/아니오 | <수동 또는 자동 증거> |

## 승인 기준

### AC-001: <관찰 가능한 동작>
- **시나리오:** <시작 조건>
- **작업:** <단일 트리거>
- **예상:** <관찰 가능한 결과>
- **금지 사항:** <해당되는 경우 금지된 부작용>
- **검증:** <방법 및 의도된 증거>
- **환경/안전:** <해당되는 경우 제약 조건>
- **우선순위:** 필수 | 중요 | 선택

## 차단 결정

- [ ] <안전하거나 올바른 진행을 방해하는 결정만>

## 검증 계획

| 기준 | 검증 증거 | 상태 |
| --- | --- | --- |
| AC-001 | <테스트/확인/검토 명령 또는 증거 유형> | 보류 중 |

합격/불합격 예시

이 예시를 사용하여 스킬이 실제로 검증 가능한 브리핑을 생성했는지, 계획적인 서술이 아닌지 판단합니다.

실패하는 승인 기준

AC-001: 내보내기가 올바르게 작동하고 안전합니다.

실패 — "올바르게 작동" 및 "안전"은 관찰 가능하지 않으며, 시나리오, 트리거, 예상되는...