Initial commit

.trae/skills/brainstorming/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: "brainstorming"
+description: "구현 전에 아이디어를 질문과 설계안으로 구체화합니다. 기능 추가, 동작 변경, 신규 개발처럼 창의적 작업을 시작하기 전에 반드시 호출합니다."
+---
+
+# 아이디어를 설계로 구체화하기
+
+자연스러운 협업형 대화를 통해 아이디어를 완성도 높은 설계와 명세로 바꿉니다.
+
+먼저 현재 프로젝트 문맥을 이해한 뒤, 질문을 한 번에 하나씩 하면서 아이디어를 구체화합니다. 무엇을 만들지 충분히 이해했다면 설계를 제시하고 사용자 승인을 받습니다.
+
+<HARD-GATE>
+설계를 제시하고 사용자 승인을 받기 전까지는 구현 스킬 호출, 코드 작성, 프로젝트 스캐폴딩, 기타 구현 행동을 해서는 안 됩니다. 이 규칙은 작업이 얼마나 단순해 보이든 항상 적용됩니다.
+</HARD-GATE>
+
+## 안티 패턴: "이건 너무 단순해서 설계가 필요 없다"
+
+모든 작업은 이 과정을 거쳐야 합니다. 할 일 목록, 단일 함수 유틸리티, 설정 변경도 예외가 아닙니다. "단순한" 작업일수록 검증되지 않은 가정 때문에 불필요한 재작업이 생기기 쉽습니다. 설계는 짧아도 되지만, 반드시 제시하고 승인을 받아야 합니다.
+
+## 체크리스트
+
+아래 항목별로 작업을 만들고, 순서대로 완료해야 합니다.
+
+1. **프로젝트 문맥 탐색** - 파일, 문서, 최근 커밋 확인
+2. **시각 보조 도구 제안** - 시각적 질문이 예상되면 별도 메시지로 제안
+3. **명확화 질문 진행** - 한 번에 하나씩 질문하며 목적, 제약, 성공 기준 파악
+4. **2~3개 접근법 제안** - 트레이드오프와 추천안 포함
+5. **설계 제시** - 복잡도에 맞춰 섹션별로 설명하고 승인 받기
+6. **설계 문서 작성** - `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`에 저장
+7. **명세 자체 점검** - placeholder, 모순, 모호성, 범위 확인
+8. **사용자 문서 검토** - 구현 전 설계 문서 검토 요청
+9. **구현 단계 전환** - 다음 단계로 `writing-plans` 스킬 호출
+
+## 프로세스 흐름
+
+기본 흐름은 아래와 같습니다.
+
+1. 현재 프로젝트 문맥을 탐색합니다.
+2. 필요한 경우 시각 보조 도구를 별도 메시지로 제안합니다.
+3. 질문을 한 번에 하나씩 하며 요구를 구체화합니다.
+4. 2~3개의 접근법을 비교하고 추천안을 제시합니다.
+5. 설계를 섹션 단위로 설명하며 단계적으로 승인을 받습니다.
+6. 승인된 설계를 문서로 저장합니다.
+7. 문서를 스스로 점검해 빈칸, 모순, 모호함을 제거합니다.
+8. 사용자에게 문서 검토를 요청합니다.
+9. 승인이 끝나면 다음 단계로 `writing-plans`를 호출합니다.
+
+## 프로세스
+
+**아이디어 이해**
+
+- 먼저 현재 프로젝트 상태를 확인합니다.
+- 요청이 여러 독립 하위 시스템을 포함하면, 세부 질문 전에 먼저 분해가 필요한지 판단합니다.
+- 하나의 명세로 다루기 너무 크다면 하위 프로젝트로 나누고, 첫 번째 하위 프로젝트만 일반 설계 흐름으로 진행합니다.
+- 적절한 범위라면 질문을 한 번에 하나씩 하며 구체화합니다.
+- 가능하면 객관식 질문을 우선 사용하되, 필요하면 서술형도 사용합니다.
+- 각 메시지에는 질문 하나만 포함합니다.
+- 목적, 제약 조건, 성공 기준을 이해하는 데 집중합니다.
+- 너무 일찍 구현 방향으로 뛰어들지 말고, 범위와 기대 결과를 먼저 고정합니다.
+- "간단해 보인다"는 이유로 질문 단계를 생략하지 않습니다.
+
+**접근법 탐색**
+
+- 서로 다른 2~3개의 접근법을 제안합니다.
+- 각 접근법의 장단점과 추천 이유를 함께 설명합니다.
+- 추천안을 먼저 제시하고, 왜 그 선택이 적합한지 설명합니다.
+- 접근법은 기능 관점뿐 아니라 유지보수, 테스트 용이성, 사용자 경험까지 함께 비교합니다.
+
+**설계 제시**
+
+- 무엇을 만들지 충분히 이해했다면 설계를 제시합니다.
+- 각 섹션은 복잡도에 맞게 짧게 또는 자세히 설명합니다.
+- 각 섹션 뒤에는 지금까지 맞는지 확인을 요청합니다.
+- 아키텍처, 구성요소, 데이터 흐름, 오류 처리, 테스트를 다룹니다.
+- 이해되지 않는 부분이 있으면 다시 질문하고 명확히 합니다.
+- 한 번에 모든 내용을 밀어 넣기보다, 사용자가 따라올 수 있는 단위로 나눠 검증합니다.
+
+**격리와 명확성을 고려한 설계**
+
+- 시스템을 명확한 목적을 가진 작은 단위로 나눕니다.
+- 각 단위는 잘 정의된 인터페이스로 통신하고, 독립적으로 이해 및 테스트 가능해야 합니다.
+- 각 단위에 대해 "무엇을 하는가, 어떻게 사용하는가, 무엇에 의존하는가"를 설명할 수 있어야 합니다.
+- 내부 구현을 몰라도 역할을 이해할 수 있어야 하며, 내부를 바꿔도 소비자가 깨지지 않아야 합니다.
+- 파일이 지나치게 커지면 책임이 과도하게 섞였다는 신호로 봅니다.
+
+**기존 코드베이스에서 작업할 때**
+
+- 변경 제안 전에 현재 구조와 패턴을 먼저 탐색합니다.
+- 현재 작업에 영향을 주는 구조적 문제는 설계에 포함해 개선할 수 있습니다.
+- 현재 목표와 무관한 리팩터링은 제안하지 않습니다.
+
+## 설계 제시 규칙
+
+- 섹션별로 끊어서 설명하고, 각 섹션 뒤에 확인을 받습니다.
+- 설계는 복잡도에 맞춰 짧게 또는 자세히 조절합니다.
+- 구조, 데이터 흐름, 오류 처리, 테스트 전략을 빠뜨리지 않습니다.
+- 사용자가 "지금까지 맞다"고 확인하기 전까지 다음 단계로 밀어붙이지 않습니다.
+
+## 금지 사항
+
+- 설계 승인 전에 구현 스킬 호출
+- 설계 승인 전에 코드 작성
+- 질문 여러 개를 한 번에 던지는 방식
+- 대안 비교 없이 단일 해법만 제시하는 방식
+- 현재 목표와 무관한 대형 리팩터링 제안
+- 사용자 검토 없이 바로 구현 계획 또는 구현으로 넘어가는 방식
+
+## 설계 후 단계
+
+**문서화**
+
+- 승인된 설계를 `docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md`에 작성합니다.
+- 사용자가 다른 문서 위치를 선호하면 그 경로를 우선합니다.
+- 가능하면 명확하고 간결한 문체를 유지합니다.
+
+**명세 자체 점검**
+
+설계 문서를 작성한 뒤 아래 항목을 빠르게 확인합니다.
+
+1. **Placeholder 점검** - `TBD`, `TODO`, 미완성 섹션, 모호한 요구사항이 있는지 확인
+2. **내부 일관성 점검** - 섹션끼리 모순되지 않는지 확인
+3. **범위 점검** - 단일 구현 계획으로 충분한 범위인지 확인
+4. **모호성 점검** - 여러 해석이 가능한 요구사항을 하나로 명확히 고정
+
+문제가 있으면 문서 안에서 바로 수정하고 진행합니다.
+
+**사용자 검토 게이트**
+
+설계 검토가 끝나면, 구현 계획으로 넘어가기 전에 사용자에게 작성된 명세 문서를 검토해 달라고 요청합니다.
+
+예시 문구:
+
+> 명세를 `<path>` 에 작성했습니다. 구현 계획을 쓰기 전에 변경하고 싶은 점이 있는지 검토해 주세요.
+
+사용자가 승인할 때까지 기다립니다. 변경 요청이 있으면 수정하고 다시 점검합니다.
+
+**구현 전환**
+
+- 다음 단계에서는 `writing-plans` 스킬을 호출합니다.
+- 다른 구현 스킬을 먼저 호출하지 않습니다.
+
+## 기대 결과
+
+이 스킬의 결과물은 다음을 만족해야 합니다.
+
+- 사용자 의도가 구조화된 설계 문장으로 정리되어 있어야 합니다.
+- 구현 전에 범위와 성공 기준이 합의되어 있어야 합니다.
+- 설계 문서만 읽어도 다음 단계에서 무엇을 구현할지 알 수 있어야 합니다.
+- 설계 문서는 placeholder 없이 구체적이어야 합니다.
+
+## 핵심 원칙
+
+- **한 번에 한 질문** - 여러 질문을 한꺼번에 던지지 않습니다.
+- **객관식 우선** - 답하기 쉬운 형식을 우선합니다.
+- **YAGNI 준수** - 불필요한 기능은 설계에서 제거합니다.
+- **대안 비교** - 항상 2~3개의 접근법을 제시합니다.
+- **점진적 검증** - 설계를 제시하고 승인받은 뒤 다음으로 진행합니다.
+- **유연한 명확화** - 이해가 부족하면 다시 질문합니다.
+
+## 안티 패턴 신호
+
+다음 생각이 들면 흐름을 다시 점검합니다.
+
+- 이건 너무 간단해서 설계가 필요 없다
+- 구현하면서 알아가도 된다
+- 사용자 의도는 아마 이럴 것이다
+- 설계 문서는 나중에 써도 된다
+- 구현 스킬부터 불러도 큰 문제는 없다
+
+이런 생각은 대부분 브레인스토밍 단계를 건너뛰려는 신호입니다.
+
+## 시각 보조 도구
+
+목업, 다이어그램, 시각 옵션을 보여주는 브라우저 기반 보조 수단입니다. 이는 별도 모드가 아니라 필요할 때 사용하는 도구입니다.
+
+**제안 시점**
+
+앞으로의 질문이 시각 요소를 포함할 가능성이 높다면, 아래 문구를 반드시 **단독 메시지**로 제안합니다.
+
+> 지금 논의하는 내용 중 일부는 웹 브라우저에서 직접 보여드리면 더 이해하기 쉬울 수 있습니다. 진행하면서 목업, 다이어그램, 비교안 같은 시각 자료를 준비할 수 있습니다. 아직 새 기능이라 토큰 사용량이 많을 수 있는데, 사용해 보시겠어요? (로컬 URL 열기 필요)
+
+이 제안 메시지에는 다른 질문, 요약, 설명을 섞지 않습니다. 사용자의 답변을 기다린 뒤 계속 진행합니다.
+
+**질문별 판단**
+
+사용자가 수락했더라도 모든 질문을 브라우저로 처리하지는 않습니다. 매 질문마다 "읽는 것보다 보는 것이 더 이해하기 쉬운가?"를 기준으로 판단합니다.
+
+- 브라우저 사용: 목업, 와이어프레임, 레이아웃 비교, 아키텍처 다이어그램 같은 시각 중심 내용
+- 터미널 사용: 요구사항 질문, 개념적 선택지, 트레이드오프 설명, 범위 결정 같은 텍스트 중심 내용
+
+자세한 사용법은 [visual-companion.md](./visual-companion.md)를 참고합니다.

.trae/skills/brainstorming/visual-companion.md

@@ -0,0 +1,68 @@
+# 시각 보조 도구 가이드
+
+브레인스토밍 중 목업, 다이어그램, 비교안을 보여주기 위한 브라우저 기반 시각 보조 가이드입니다.
+
+## 언제 사용할지
+
+세션 단위가 아니라 질문 단위로 판단합니다. 기준은 하나입니다. **읽는 것보다 보는 것이 더 이해하기 쉬운가?**
+
+**브라우저를 사용할 때**
+
+- UI 목업, 와이어프레임, 레이아웃, 내비게이션 구조
+- 시스템 구성도, 데이터 흐름도, 관계도
+- 레이아웃이나 스타일의 시각적 비교
+- 간격, 시각적 위계, 분위기 같은 디자인 완성도 논의
+- 상태 전이, 흐름도, 엔터티 관계처럼 공간적 관계가 중요한 설명
+
+**터미널을 사용할 때**
+
+- 요구사항과 범위 질문
+- 개념적 A/B/C 선택
+- 장단점 비교와 트레이드오프 정리
+- API 설계, 데이터 모델링, 구조 선택 같은 기술 의사결정
+- 시각 취향이 아니라 언어 설명이 필요한 명확화 질문
+
+UI 주제에 대한 질문이라고 해서 자동으로 시각 질문이 되는 것은 아닙니다. "어떤 종류의 위저드를 원하나요?"는 개념 질문이고, "이 위저드 레이아웃 중 무엇이 더 맞나요?"는 시각 질문입니다.
+
+## 진행 방식
+
+서버는 HTML 파일이 저장되는 디렉터리를 감시하고 가장 최근 파일을 브라우저에 제공합니다. 화면 내용은 `screen_dir`에 기록하고, 사용자의 클릭/선택 결과는 `state_dir/events`에 저장됩니다.
+
+**콘텐츠 조각과 전체 문서**
+
+- HTML이 `<!DOCTYPE` 또는 `<html`로 시작하면 전체 문서로 그대로 제공합니다.
+- 그렇지 않으면 서버가 기본 프레임 템플릿으로 감싸서 보여줍니다.
+- 기본적으로는 전체 HTML 문서보다 **콘텐츠 조각** 작성 방식을 사용합니다.
+
+## 세션 시작
+
+- 서버를 시작하고 응답에서 `url`, `screen_dir`, `state_dir`를 저장합니다.
+- 사용자에게 URL을 열어 달라고 안내합니다.
+- 가능하면 프로젝트 루트를 기준으로 실행해 결과물이 프로젝트 안에 유지되게 합니다.
+- 환경상 URL 접근이 어렵다면 호스트 설정을 조정합니다.
+
+## 반복 루프
+
+1. 서버가 살아 있는지 확인하고 `screen_dir`에 새 HTML 파일을 씁니다.
+2. 사용자에게 URL과 현재 화면에 무엇이 보이는지 짧게 설명합니다.
+3. 사용자가 터미널에서 응답하면 `state_dir/events`를 읽어 브라우저 상호작용을 확인합니다.
+4. 피드백에 따라 현재 화면을 수정하거나 다음 질문으로 넘어갑니다.
+5. 다음 단계가 시각 자료가 아니라면 대기 화면을 밀어 넣어 오래된 화면이 남지 않게 합니다.
+
+## 작성 원칙
+
+- 파일명은 의미 있게 짓습니다. 예: `layout.html`, `visual-style.html`
+- 같은 파일명을 재사용하지 않습니다.
+- 한 화면에는 2~4개 선택지만 둡니다.
+- 질문 자체를 화면에 명확히 적습니다.
+- 레이아웃 검토에는 와이어프레임, 완성도 검토에는 더 실제적인 시안을 사용합니다.
+- 필요한 경우 실제 콘텐츠를 사용하고, 불필요한 정교함은 피합니다.
+
+## 이벤트 해석
+
+브라우저 클릭 이벤트는 `state_dir/events`에 JSON Lines 형식으로 기록됩니다. 마지막 선택이 최종 선택인 경우가 많지만, 선택 흐름 전체가 사용자의 망설임이나 선호를 보여줄 수 있습니다.
+
+## 정리
+
+- 세션 종료 시 서버를 중지합니다.
+- 프로젝트 기반 세션이라면 결과물은 이후 참고를 위해 남겨둘 수 있습니다.