비전 — 제품이 무엇이며, 무엇이 되기를 거부하는가
super-ux의 일부 — 전체 파이프라인은 system-map.md 참조. 문서를 작성한 후
python3 docs/ux/lint.py를 실행하세요.
ux-foundation 위의 계층입니다. 파운데이션은 누가 제품을 사용하고 왜 사용하는지에 답합니다;
비전은 제품이 무엇인지와 무엇이 되기를 거부하는지에 답합니다. 이것이 없으면 "이것을 구축해야 할까?"라는 질문에 마지막으로 의견을 가진 사람보다 오래 지속되는 답이 없습니다.
이름에 "무엇"이 포함된 다른 계층인 scenarios.md와 혼동하지 마십시오:
시나리오는 제품이 단계별로 무엇을 하는지를 말합니다. 기능이 완벽하게 시나리오화되어도 안티-비전을 위반할 수 있습니다.
이 스킬은 두 가지를 생성하며, 두 번째가 핵심입니다.
docs/ux/vision.md— 문서.- 프로젝트 자체 지시 파일에 있는 비전-정렬 규칙으로, 이후의 모든 기능이 비전에 대해 확인되며 비전이 한 번 작성되고 다시는 읽히지 않는 상황을 방지합니다.
아무도 읽지 않는 비전은 문서일 뿐, 제약 조건이 아닙니다.
체인에 맞춤: 비전 → 파운데이션 (페르소나, JTBD, 여정, 스토리) → 흐름 → 시나리오 → 감사. 각 계층은 그 위의 계층을 추적합니다.
단계 0 — README가 아닌 프로젝트를 읽으세요
한 글자를 쓰기 전에:
README.md,ARCHITECTURE.md,ROADMAP.md,CHANGELOG.md,docs/의 모든 파일.- 주요 소스: 진입점, 주요 서비스, 스키마, 라우팅 테이블.
- 존재하는 경우 마케팅 표면 — 랜딩 페이지, 가격, 기능.
package.json/pyproject.toml/Cargo.toml— 실제 의존성을 확인.- 라이브 UI. 제품이 말하는 대로가 아니라 실제로 하는 것.
docs/ux/foundation.md가 존재하면 읽으세요 — 비전은 이미 합의된 페르소나와 직무와 모순되지 않아야 합니다.
README만으로 작성된 비전은 README를 설명합니다. 프로젝트가 말하는 것과 코드가 실제로 하는 것 사이의 간격은 대개 진짜 비전이 숨어 있는 곳이며, 그 간격을 명확히 말하는 것이 이 스킬이 하는 가장 가치 있는 일인 경우가 많습니다.
단계 1 — 변환
쓰기 전에 내부적으로 답하세요:
이 제품이 존재하기 전 사용자 → [혼란 / 복잡성 / 고통]
이 제품이 존재한 후 사용자 → [명확성 / 단순성 / 힘]
아래의 모든 것은 이것에서 흐릅니다. 이것을 명시할 수 없다면, 아직 제품을 비전을 쓸 만큼 충분히 알지 못한 것입니다 — 단계 0으로 돌아가세요.
단계 2 — docs/ux/vision.md를 아홉 계층으로 작성하세요
모든 계층은 필수입니다. 프로젝트의 문서 언어로 작성하세요.
1. 본질. 한 문장. [제품]은 [사용자]가 [X]를 하는 방식을 바꾸는 [시스템 유형]입니다.
기능 이름, UI, 기술 없음. 테스트: 제품이 다른 스택에서 처음부터 다시 구축된다면 이 문장이 여전히 참일까요?
그렇지 않다면, 구현을 지칭하는 것이지 본질이 아닙니다.
2. 핵심 아이디어. 문제 진술이 아닌 — 세상에 대한 관찰.
[X]는 풍부합니다.
[Y]는 희소합니다.
→ 이 제품이 그 격차를 연결합니다.
하나의 관찰, 목록이 아닙니다. "정보는 풍부하고, 명확성은 희소합니다."
3. 시스템이 하는 일. 지속적인 행동, 명사가 아닌 동사: 관찰한다 … 이해한다 … 변환한다 … 표면화한다 …. 기능 이름 없음. "대시보드가 있다"는 행동이 아닙니다; "소스 간의 모순을 표면화한다"가 행동입니다.
4. 사용자의 역할. 사용할 때 사용자가 되는 것. "사용자가 클릭한다"가 아니라 — 사용자는 지시하고, 판단하고, 결정합니다. 사용자의 역할이 다른 도구를 작동시키는 것과 구별할 수 없다면 비전이 아직 구체적이지 않습니다.
5. 원칙. 세 가지에서 다섯 가지, 각각 우리는 X를 하고, Y는 하지 않는다 형태로, 여기서 Y는 합리적인 팀이 실제로 선택할 만한 것입니다. 거부된 대안이 없는 원칙은 슬로건입니다.
6. 안티-비전. 이 제품이 무엇이 되기를 거부하는지 명시적으로. 팀이 건너뛰는 계층이며 논쟁을 해결하는 유일한 계층입니다. 표류할 수 있는 인접 제품을 지목하고 각각에 대해 아니오라고 말하세요.
7. 지평선. 2~3년 후의 방향, 로드맵이 아닌 방향. 로드맵은 트래커에 속하며 분기마다 썩습니다.
8. 한 문장. 누군가 정확히 한 가지만 기억한다면 이것입니다.
9. 정렬 테스트. 제안된 모든 기능이 통과해야 하는 세 가지에서 다섯 가지 질문. 이것들이 4단계의 규칙이 실제로 실행할 내용입니다.
단계 3 — 배송 전에 검증하세요
모든 항목을 확인하고, 합리화하지 말고 수정하세요:
- 본질이 다른 기술로 완전히 재작성되어도 유지됨
- 어떤 계층도 기능, 화면 또는 공급업체를 지칭하지 않음
- 안티-비전이 실제 대안을 지목하며, 허수아비가 아님
- 원칙에는 누군가가 실제로 선택했을 법한 거부된 측면이 있음
-
docs/ux/foundation.md와 모순되지 않음 — 모순된다면 조용히 덮지 말고 발견 사항으로 제기 - 모르는 사람이 정렬 테스트를 사용하여 그럴듯한 기능을 거부할 수 있음
단계 4 — 정렬 규칙 설치
규칙을 프로젝트 자체 지시 파일에 작성하세요. ux-rule이 사용하는 것과 동일한 파일:
Claude Code의 경우 CLAUDE.md, Codex와 opencode의 경우 AGENTS.md,
Gemini의 경우 GEMINI.md. 프로젝트에 이미 있는 것을 감지하고, 아무것도 없을 때만 CLAUDE.md를 생성하세요.
절대 하나의 에이전트 경로를 하드코딩하지 마세요 — 실행 중인 에이전트가 볼 수 없는 곳에 규칙을 설치하는 것은
규칙이 없는 것보다 나쁩니다. 모든 사람이 그것이 다루어졌다고 믿기 때문입니다.
멱등성: 헤딩이 이미 있으면 두 번째 복사본을 추가하지 않고 그 자리에서 블록을 업데이트하세요.
## 비전 정렬 — 강제 규칙 (super-ux)
새로운 기능, 기능 또는 중요한 변경을 계획하기 전에 `docs/ux/vision.md`에 대해 확인하세요 —
특히 **안티-비전**과 **정렬 테스트**를.
**정렬됨** → 진행하고, 한 줄로 비전의 어느 부분을 제공하는지 말하세요.
**정렬되지 않음** → 코드를 작성하기 전에 멈추고 말하세요:
1. 갈등 지점을 명시하세요 — 해당 계층을 인용하여 어떤 계층과 모순되는지.
2. 두 가지 경로를 제시하세요: (a) 특정 변경과 함께 기능을 맞추도록 재구성; (b) 어떤 계층이 변경되고 그 비용이 무엇인지 말하며 비전을 수정.
3. 결정을 기다리세요. 조용히 하나를 선택하지 마세요.
**다음의 경우 트리거하지 마세요:** 버그 수정, 리팩터링, 의존성 작업, 테스트, 문서화, 또는 사용자 대면 표면이 없는 모든 것. 오타 수정에 대한 비전 확인은 팀이 중요한 확인을 건너뛰도록 배우는 방법입니다.
단계 5 — README가 이를 가리키도록 하세요
프로젝트 개요 아래에 docs/ux/vision.md를 링크하는 한 줄을 추가하세요.
앞문에서 찾을 수 없는 비전은 아무도 읽지 않는 비전입니다.
일반적인 실수
| 실수 | 왜 깨지는가 |
|---|---|
| 본질이 기술을 지칭함 | 첫 번째 재작성에서 더 이상 참이 아님 |
| 거부된 측면이 없는 원칙 | "우리는 품질을 중시합니다"는 어떤 논쟁도 해결하지 못함 |
| 안티-비전 없음 | 범위 질문을 결정하는 유일한 계층이 누락됨 |
| 로드맵으로 작성된 지평선 | 분기 내에 썩고, 문서 전체가 낡은 것으로 읽힘 |
비전이 foundation.md와 모순됨 | 두 개의 진실 출처, 팀은 마지막으로 읽은 것을 따름 |
| 규칙이 하나의 에이전트 하드코딩된 경로에 설치됨 | 실제로 실행 중인 에이전트에게 보이지 않음; 아무도 알아채지 못함, 부재가 준수와 동일하게 보이기 때문 |
| README에서 작성됨 | README를 설명함 |