rtaffe28/arch-plan

아키텍처 우선 계획

계획은 무엇보다도 두 가지 질문에 답합니다: 구성 요소는 무엇이고 어떻게 연결되는가(다이어그램), 그리고 구성 요소 간의 정확한 계약은 무엇인가(인터페이스). 작업 목록은 부차적입니다. 유능한 구현자는 좋은 인터페이스로부터 작업을 도출할 수 있습니다.

계획은 로컬 및 개인 파일입니다: ~/plans/<YYYY-MM-DD>-<slug>/. 마크다운 파일이 진실의 원천입니다. 아티팩트는 이 파일의 뷰입니다.

1. 요청 이해

• 목표를 한두 문장으로 다시 설명하고, 명시적으로 범위를 벗어난 항목을 추가하세요.
• 요구 사항이 모호하면 질문하세요(아래 질문하기 참조). 설계를 변경할 수 있는 질문만 하세요. 답변이 새로운 분기를 열면 한 번 더 질문하세요.
• 좋은 기본값이 코드의 현재 상태에 따라 달라지는 경우, 먼저 2단계를 빠르게 수행하여 추천 사항이 추측이 아닌 저장소를 기반으로 하도록 하세요.

질문하기

이 단계, 토론 후, 반복 중에 사용자에게 하는 모든 질문은 AskUserQuestion 도구를 통해 이루어져야 하며, 채팅에서 목록으로 제시하지 마세요. 사용자는 대부분의 질문에 한 번의 클릭으로 답변할 수 있어야 합니다:

• 추천 사항을 미리 채우세요. 선택할 옵션을 첫 번째 옵션으로 만들고, 레이블 끝에 (Recommended)를 추가하세요. 코드베이스의 기존 패턴, AGENTS.md, 그리고 설계를 가장 단순하게 유지하는 방법을 기반으로 하세요.
• 질문당 2~4개의 구체적인 옵션, 각각 실제 선택지이며, 설계에 미치는 의미를 설명하는 설명을 포함하세요(예: "마이그레이션 추가", "useCursorFeed 재사용"). "기타" 옵션은 추가하지 마세요. 도구가 자유 텍스트를 위한 옵션을 추가합니다.
• 자체 완결적. 사용자는 대화상자만 볼 수 있으므로, 각 질문은 기능과 결정 중인 항목의 이름을 지정하고, 질문의 근거가 되는 내용을 간략히 설명하세요.
• 호출당 최대 4개의 질문, 각각 짧은 header 칩(≤12자, 예: "Storage", "Auth", "Scope")을 포함하세요. 관련 질문을 묶고, 나머지는 다른 호출에서 처리하세요.
• 옵션이 상호 배타적이지 않은 경우에만 multiSelect를 사용하세요(예: "이 기능을 적용할 표면은?"). 구체적인 아티팩트(인터페이스 스케치, 스키마, ASCII 레이아웃)를 비교할 때는 preview를 사용하세요.
• 명확한 답변이 있고 롤백 비용이 저렴한 선택이라면 묻지 말고 결정하여 결정 테이블에 기록하세요.

2. 컨텍스트 수집

작업 중인 저장소(메인 체크아웃 또는 스택의 작업 트리):

• 먼저 CLAUDE.md, AGENTS.md, .claude/rules/*를 읽으세요. 이 파일들은 모순되어서는 안 되는 결정을 인코딩합니다.
• 기능이 접촉하거나 재사용할 수 있는 기존 항목(타입, 서비스, 라우트, 테이블, 작업, 컴포넌트)을 찾으세요. 광범위한 검토가 필요한 경우, 영역별로 병렬 Explore 에이전트를 실행하고 결론만 유지하세요.
• 확장할 모든 기존 인터페이스를 path:line과 함께 기록하세요.

3. 규모 평가

	소규모	대규모
신호	코드베이스의 한 영역, 대략 하나의 PR(~400줄 미만), 마이그레이션 없음 또는 간단한 마이그레이션	여러 영역, 스키마 변경, 새로운 백그라운드 작업, 둘 이상의 PR, 여러 사람 또는 세션
출력	plan.md만	plan.md 및 slices/01-<name>.md, slices/02-<name>.md, ...

소규모 작업을 분할하지 마세요. 하나의 PR 변경에 절차를 추가하는 것은 낭비입니다.

대규모 작업의 경우 수직 슬라이스로 자르세요: 각 슬라이스는 자체적으로 병합 가능하고, 메인 브랜치를 작동 상태로 유지하며, 테스트 가능한 무언가를 제공합니다. 스키마 전용 "슬라이스" 또는 "프론트엔드 슬라이스"는 슬라이스가 아닙니다. 슬라이스를 종속성 순서로 정렬하고 각각 대략 하나의 PR 크기로 유지하세요.

4. 계획 작성

~/plans/<date>-<slug>/plan.md:

# <제목>

**상태:** 초안 | 승인됨 | 진행 중 | 완료
**규모:** 소규모 | 대규모 (N 슬라이스)
**저장소 / 베이스:** phave-ng @ <커밋>

## 목표
<2~3문장> · **범위 외:** <항목>

## 아키텍처
### 구성 요소
<Mermaid 순서도: 기존 항목은 일반 스타일, 새 항목은 강조, 변경된 항목은 표시>
### 주요 흐름
<각 주요 흐름에 대한 Mermaid 시퀀스 다이어그램, 주요 오류 경로 포함>
### 데이터 모델
<테이블이나 컬럼이 변경되면 Mermaid erDiagram; 라이프사이클이 있으면 stateDiagram>

## 인터페이스
<기능이 추가하거나 변경하는 모든 계약을 저장소 언어의 실제 코드로 작성.
 각각을 NEW 또는 CHANGED로 표시하고, 대상 파일 경로를 포함.>
- 타입 / 도메인 모델
- 함수 및 서비스: 전체 시그니처와 throw하는 항목
- HTTP / 서버 액션: 메서드, 경로, 요청 및 응답 타입, 인증, 오류 코드
- 데이터베이스: 테이블, 컬럼, 인덱스, RLS 정책, 마이그레이션 이름
- 작업 / 이벤트: 이름, 페이로드 타입, 멱등성, 재시도
- UI 컴포넌트: props 및 렌더링하는 페이지

## 주요 설계 결정
| 결정 | 고려된 옵션 | 선택 | 이유 |

## 미결 질문
- [ ] <질문> — 답변할 수 있는 사람과 답변에 따라 변경되는 사항

## 슬라이스        (대규모만)
| # | 슬라이스 | 제공 사항 | 종속성 | 상태 |

## 계획 (소규모만)
<순서가 있는 단계; 각 단계: 구현하는 인터페이스, 파일, 테스트 방법>

## 테스트 전략
<단위 테스트 및 스택에 대해 테스트할 항목 (`ai-test` / `manual-test` 참조)>

## 위험

각 slices/0N-<name>.md는 다음을 포함합니다: 목표, plan.md에서 구현하는 인터페이스(링크, 복사 금지), 파일, 순서가 있는 단계, 승인 기준, 테스트, 그리고 구현 노트(비어 있음, implement-plan이 채움).

규칙:

• 다이어그램은 Mermaid를 사용하며, 다이어그램당 하나의 아이디어를 담습니다. 하나의 다이어그램에 ~12개 이상의 노드가 필요하면 분할하세요.
• 인터페이스는 코드이며, 산문이 아닙니다. 실제 파일 이름을 지정하세요. 가능한 경우 기존 타입을 재사용하고, 그렇게 했음을 명시하세요.
• 합리적인 엔지니어가 다르게 결정할 수 있는 모든 결정은 결정 테이블에 포함하세요.
• 알 수 없는 사항은 미결 질문에 포함하고, 각 질문에 대해 추천하는 답변을 제시하세요. 조용히 추측하지 마세요.

5. 비판자 / 옹호자 토론

Agent 도구를 사용하여 두 에이전트를 병렬로 실행하세요. 각 에이전트에게 계획 경로와 읽을 주요 저장소 파일을 제공하고, 당신의 결론은 제공하지 마세요:

• 비판자: "무엇이 잘못되었는지 찾으세요. 설계가 목표를 충족합니까? 인터페이스가 누락되었거나, 누출이 있거나, 코드베이스 패턴과 일치하지 않습니까? 슬라이스가 진정한 수직 슬라이스가 아닙니까? 과도하게 설계되었거나 과소 지정된 부분, 놓친 재사용, 실패 모드, 마이그레이션 위험, 권한 격차가 있습니까? 각 문제를 구체적인 수정 사항과 함께 보고하세요."
• 옹호자: "명백한 대안이 기각된 부분에서 특히, 계획 선택에 대한 가장 강력한 주장을 펴세요. 비판자가 공격할 가능성이 있는 부분과 현재 설계가 유지되는 이유를 언급하세요."

그런 다음 반박 라운드를 진행하세요: 각 에이전트에게 다른 에이전트의 출력을 보내고(SendMessage), 각 지점에 대해 양보하거나 유지할 것을 요청하세요.

당신이 판사입니다. 각 논쟁 지점에 대해:

• 합의된 변경: plan.md / 슬라이스 파일에 적용하세요.
• 해결되지 않았고 사용자의 의견이 필요한 경우: 추천 옵션과 함께 미결 질문으로 이동하세요.
• 기각: 결정을 유지하고, 결정 테이블에 이유를 기록하세요.

plan.md에 ## 토론 요약을 추가하세요: 지점 → 비판자 → 옹호자 → 해결.

6. 아티팩트로 제시

artifact-design 및 다이어그램용 artifact-diagramming을 로드하세요. 검토를 위해 한 페이지를 게시하되, 다음 순서로 게시하세요:

1. 제목, 상태, 규모 및 한 문단 요약
2. 주요 설계 결정(테이블)
3. 미결 질문: 사용자에게 필요한 사항, 중요하고 쉽게 찾을 수 있도록
4. 아키텍처 다이어그램: 원시 Mermaid 텍스트가 아닌 렌더링된 형태
5. 인터페이스: 강조 표시된 코드, 계층별로 그룹화, NEW / CHANGED 배지 포함
6. 슬라이스(대규모) 또는 단계(소규모)
7. 토론 하이라이트: 계획을 변경했거나 여전히 열려 있는 지점만
8. plan.md의 로컬 경로

채팅에서 링크를 제공하세요. 그런 다음 AskUserQuestion을 사용하여 미결 질문을 하세요(위의 질문하기 참조). 각 질문에는 비판자와 옹호자의 입장을 옵션으로 포함하고, 권장 사항을 첫 번째로 제시하세요.

7. 승인될 때까지 반복

사용자의 답변과 의견은 먼저 plan.md에 적용됩니다: 답변된 질문은 미결 질문에서 결정 테이블로 이동합니다. 반복 중에 제기된 새로운 질문도 동일한 방식으로 AskUserQuestion과 권장 옵션을 사용하여 질문합니다. 그런 다음 동일한 아티팩트(동일한 파일 경로이므로 URL은 동일하게 유지)를 다시 게시합니다. 사용자가 승인하면 상태: 승인됨으로 설정하고 implement-plan을 가리키세요.

이 스킬은 제품 코드를 작성하지 않습니다.