의도 기반 개발

의도 기반 개발 (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 형식.
가정: 최대 행 수는 10,000 미만, 내보내는 필드에 PII 없음.

AC-001: 내보내기가 올바른 헤더로 파일 생성
- 시나리오: 인증된 사용자, 하나 이상의 데이터 행 표시됨
- 동작: "Export 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: 내보내기가 올바르게 작동하고 안전합니다.

실패 — "올바르게 작동"과 "안전"은 관찰 가능하지 않으며, 시나리오, 트리거, 예상 결과, 금지된 부작용, 검증 방법 또는 우선순위가 없습니다.

통과하는 수용 기준

AC-001: 인증된 사용자가 대시보드 CSV를 받습니다.
- 시나리오: 세션에 사용자 ID를 가진 인증된 사용자, 대시보드에 하나 이상의 행이 표시됨, CSV 데이터 없음.
- 동작: "내보내기" 버튼 클릭.
- 예상: Content-Type이 text/csv인 HTTP 응답, 본문은 현재 페이지의 행과 일치하는 행 포함, 첫 번째 행은 헤더 행, 파일 이름은 report-yyyy-mm-dd.csv임.
- 금지: 500 오류, 빈 파일(행이 있음에도), 응답에 다른 사용자의 행 포함.
- 검증: Cypress 테스트: 로그인, 행이 있는 대시보드 방문, 캡처된 응답의 헤더 및 행 수를 어설션, curl을 통한 수동 스키마 점검.
- 환경/안전: Cy.only로 격리된 테스트, 프로덕션 DB 연결 없음.
- 우선순위: 필수.

통과 — 동작은 관찰 가능하고(받음, 포함, 포함하지 않음), 시나리오, 트리거, 금지, 검증 방법 및 우선순위가 지정되어 있습니다.

부록: 일반적인 오해

• "시스템이 사용자에게 친숙해야 함" — 가정일 뿐, 기준이 아닙니다. 관찰 가능한 UX 기준(예: "오류 메시지에 해결 단계가 포함됨", "탭 순서가 시각적 레이아웃을 따름")을 선호하거나 UX 검토를 검증 방법으로 나열합니다.
• "API가 올바른 상태 코드를 반환해야 함" — 모호함: "올바름"을 정의해야 합니다. 스펙에 대한 참조가 필요합니다.
• 기준을 충족하기 위해 "자동화된 테스트를 추가함" — 구현에 대한 설명일 뿐, 기준이 아닙니다. 기준은 동작을 설명하고 검증 방법을 나열합니다.