specshape-plan은(는) 무엇을 하나요?
코드가 존재하기 전에 코드 리뷰: 변경 사항의 형태를 스케치로 보여주고, 모든 결정을 보존합니다.
계획을 작성합니다: 작업의 개략적이고 코드에 기반한 그림으로, .specshape/<id>.md에 저장됩니다.
사용자가 이를 검토하고, 방향을 조정하며 승인합니다. 코드는 나중에 /specshape-build에 의해 한 번에 하나의 작업씩 작성됩니다.
이 스킬은 절대 코드를 작성하지 않습니다.
변경할 수 있는 것
.specshape/아래의 파일: 계획, 승인 시.specshape/context.md- 사용자의 명시적 동의와 승인 시에만: 트래커의 티켓, 리포지토리의
AGENTS.md에 한 줄
그 외에는 아무것도 변경할 수 없습니다. 소스 파일, 브랜치, 커밋, 티켓 댓글 또는 상태를 변경하는 명령은 금지됩니다. 사용자가 계획된 작업을 구현하도록 요청하면, 7단계의 가용성 규칙을 따르고 절대 여기서 구현하지 마십시오. Tweak은 이 스킬을 종료하고 일반 에이전트 작업(3단계)으로 전환합니다.
0. 오리엔테이션
- 컨텍스트를 읽습니다.
.specshape/context.md가 있으면 읽고, 링크된 용어집도 읽습니다. 용어집, 계약 및 규칙은 작성하는 모든 것에 적용됩니다.AGENTS.md및 프로젝트 자체 규칙(CLAUDE.md,CONTEXT.md, ADR, 기여 가이드)을 읽습니다. - 입력이 무엇인지 파악합니다. 먼저
.specshape/의 기존 계획을 확인합니다: - 새 작업의 ID를 선택합니다: 티켓 키가 있으면 그것을 사용하고, 없으면 짧은 케밥-케이스 슬러그를 사용합니다.
1. 요청 읽기
티켓이나 스펙을 전체적으로 읽습니다: 설명, 수락 기준, 댓글, 연결된 및 상위 티켓, 연결된 머지 리퀘스트. 수락 기준을 적어둡니다. 계획은 각 기준을 다루거나 범위 외로 나열해야 합니다. 입력이 너무 모호해서 크기를 측정할 수 없으면, 크기 측정을 가능하게 하는 한 가지 질문만 하고 더 이상 묻지 않습니다.
2. 코드 조사
사실이 당신의 임무입니다. 코드, 티켓 또는 사용 가능한 도구에서 찾을 수 있는 것을 사용자에게 묻지 마십시오. 탐색을 헬퍼에게 넘길 수 있으면 넘기고, 그렇지 않으면 직접 수행하십시오.
조사 깊이는 크기에 따라 다릅니다. 먼저 빠르게 살펴보고 크기를 측정(3단계)한 후, 필요한 만큼 깊이 들어갑니다:
| 크기 | 조사 |
|---|---|
| 변경, 기능 | 영향을 받는 전체 코드: 구축할 기반, 빠진 것, 오늘날의 연결 방식(진입점, 호출 경로, 설정), 주변 테스트 및 작성 방식 |
| 이니셔티브 | 영향을 받는 영역만: 진입점과 주요 타입, 각각 path:line으로 표시. 각 스토리를 계획할 때 깊이 읽음 |
| 프로젝트 | 없음: 코드 없음 |
의존할 모든 사실에 대해 path:line을 기록합니다. 코드가 사용하는 도메인 용어와 티켓과 코드가 동일한 것을 다르게 표현하는 부분을 기록합니다.
Git 상태나 파일 목록에서 변경되지 않은 내용을 유추하지 말고, 영향을 받는 파일을 다시 읽거나 확인된 콘텐츠 기준과 비교하십시오.
3. 크기 측정
sizing.md로 작업 크기를 측정합니다. 크기와 이를 결정한 신호를 답변 시작 부분에 적고 계속 진행합니다. 확인을 기다리지 마십시오. 사용자는 언제든지 재정의할 수 있습니다("변경으로 처리"). 재정의는 요청 라운드와 계획 세부 사항을 변경하지, 계획 검토나 승인은 변경하지 않습니다.
Tweak → 여기서 중단합니다. 1-3줄로 무엇을 어디서 변경해야 하는지 설명하고, 계획이 필요하지 않다고 말합니다.
"에이전트에게 이 편집을 직접 요청하거나, 여기서 '수정'이라고 말하여 Specshape 외부에서 계속하세요."로 마칩니다.
아무것도 저장하지 않고 소스 변경을 하지 마십시오. 이후의 수정 요청은 이 스킬 밖의 일반 에이전트 작업이며, /specshape-build가 필요하지 않습니다.
4. 질문
계획의 형태를 바꾸고 사용자만이 답할 수 있는 질문을 합니다: 의도, 우선순위, 의미, 코드가 해결할 수 없는 트레이드오프.
| 크기 | 라운드 |
|---|---|
| 변경 | 없음 |
| 기능 | 한 번. 답변이 새로운 질문을 열 경우에만 두 번째 |
| 이니셔티브, 프로젝트 | 결정되지 않은 것이 없을 때까지 라운드 |
- 지금 답할 수 있는 모든 것을 한 라운드에 물어보세요. 아직 없는 답변에 의존하는 질문은 나중 라운드를 기다립니다.
- 프로젝트의 경우 첫 번째 라운드는 용어집에 관한 것입니다: 각 핵심 용어의 의미와 용어 간의 관계("계정이란 무엇인가? 사용자가 두 개에 속할 수 있는가?")를 스택이나 형태보다 먼저 질문합니다.
- 티켓과 코드가 동일한 것을 다른 단어로 사용하는 경우 어느 것이 올바른지 질문합니다.
- 실제 질문이 없으면 라운드를 진행하지 마십시오. 라운드를 채우기 위해 질문을 만들어내지 마십시오. 이니셔티브/프로젝트의 경우, 답변이 중요한 경계를 해결하지 못했는지 확인하십시오. 스택이나 호스팅 선택이 노출, 등록 또는 전송 정책을 해결하지는 않습니다. 발견이 완료되었다고 주장하기 전에 종속 질문을 먼저 하십시오(review.md 참조).
- 계획 자체에서 볼 수 있는 선택(네이밍, 모듈 소유권)은 질문이 아닙니다. 이는 계획의 결정이며, 기본적으로 당신의 권장 사항으로 설정됩니다.
모든 질문을 다음 형식으로 작성하고 답변을 기다립니다:
❓ **Q1 - <제목>**: <질문, 옵션이 있다면 포함>
➡️ <권장 답변과 이유>
5. 계획 작성
plan-format.md의 형식으로 .specshape/<id>.md를 작성합니다. 계획의 내용은 크기에 따라 다릅니다:
| 크기 | 포함 내용 |
|---|---|
| 변경 | 요약, 결정, 변경 지도, 1-4개의 작업 평평한 목록 |
| 기능 | 요약, 결정, 코드 스케치가 있는 디자인 형태, 변경 지도, 작업 |
| 이니셔티브 | 요약, 결정, 영향을 받는 영역, 스토리(목표와 수락 기준, 작업 없음) |
| 프로젝트 | 요약, 결정, 형태(폴더, 모듈, 데이터 모델, 주요 흐름), 스토리; 첫 번째 스토리는 워킹 스켈레톤 |
모든 계획은 용어, 계약 또는 규칙을 추가하거나 변경할 때 컨텍스트 변경 섹션도 포함합니다(context-format.md 참조).
규칙:
- 증거. 기존 코드에 대한 모든 주장은
path:line을 인용합니다. 확인할 수 없는 것은assumption:으로 표시합니다. 인용이 주장을 뒷받침하는지 확인하고 기존 테스트 커버리지도 확인합니다. 권장 사항을 정당화하기 위해 프로젝트 이력이나 과거 실패를 절대 지어내지 마십시오. - 개략적이지 상세하지 않음. 코드 스케치는 시그니처, 타입 및 아이디어를 전달하는 라인을 보여주며, 최대 약 15줄입니다. 공개 경계에서 잘못된 입력 동작을 명시합니다. 검증된 CLI가 직접 서비스 호출자에게 유효하지 않은 인수를 도달 불가능하게 만들지는 않습니다. 각 작업의 상세 스케치는 작업을 빌드하기 직전 프리뷰에서 제공됩니다.
- 결정. 디자인이나 동작에 영향을 미치는 의미 있는 대안이 있는 선택을 포함합니다.
일상적인 작업(플래그 문서화, 확립된 검증 규칙 따르기)은 재료 트레이드오프가 없는 한 형태나 작업에서 직접 처리합니다.
표준 파서 검증이 사용자 정의 검증이 가능하다는 이유만으로 결정이 필요하지는 않습니다. 일상적인 작업은 범위 내에 유지합니다: 변경된 공개 인터페이스에 대한 기존 사용 설명서 업데이트; 관련 없는 정리는 제외합니다.
결정에 D1, D2 … 번호를 매기고 스토리를 포함한 전체 계획에 걸쳐 사용합니다. 각 결정에는 옵션, 권장 사항 및 사용자가 신경 쓸 결과("기본값이
true이므로 ad-hoc 실행이groupBy와 함께 실패함")가 포함됩니다. 상태:open은 답변 대기 중;decided는 사용자가 선택함;assumed는 사용자가 선택 없이 승인함. "모든 권장 사항 사용"은 명시적 선택입니다. - 작업. 각 작업은 빌드와 테스트를 녹색으로 유지하고, 작업할 파일, 수행할 결정, 필요한 작업, 추가되거나 변경된 동작을 실행하는 **완료 확인(done-check)**을 명시합니다. 동작과 그 테스트를 동일한 작업에 유지하고, 검증을 이후 작업으로 미루지 마십시오. testing.md를 사용하여 레드-그린-리팩터 슬라이스, 공개 테스트 경계, 결과 및 명령을 계획합니다. 변경되지 않은 녹색 스위트만으로는 새로운 동작을 증명하지 않습니다.
- 위험. 관찰 가능한 실패와 그 영향에 대한 증거를 명시합니다. 실행 순서를 보여주는 인용이 그 순서를 필수로 만들지는 않습니다. 순서가 중요한 경우 관련 부작용을 설명합니다.
- 스토리. 각 스토리는 자체 티켓 및 머지 리퀘스트로 독립적으로 출시 가능하며, 목표와 수락 기준이 있습니다.
스켈레톤은 모든 기본 기능이 아닌 가장 작은 유용한 엔드-투-엔드 경로로 유지합니다.
스토리 ID는 티켓이 존재할 때까지
<id>.<n>입니다. 번호를 재사용하지 마십시오. - 용어집의 단어를 사용하고 사용하지 말라고 지정된 단어는 사용하지 마십시오.
- 표현 presentation.md를 따릅니다: 비교 가능한 레코드에는 표를, 스토리/작업에는 의존성 트리를, 흐름이나 관계를 설명할 때는 Mermaid를 사용합니다.
- 누군가 다시 읽을 내용만 작성합니다. 완전성을 위해 섹션을 포함하지 마십시오. 적용되지 않는 섹션은 채우는 대신
n/a: <이유>로 작성합니다.
보여주기 전에 확인합니다. 이니셔티브/프로젝트의 경우 review.md도 읽고 스토리 간 일관성과 가정을 검토합니다. 피드백 후와 승인 전에 다시 확인합니다. 실패를 수정합니다:
- 모든 수락 기준이 다루어졌거나 범위 외로 나열됨
- 변경 지도의 모든 파일에 작업이 있고, 모든 작업의 파일이 변경 지도에 있음
- 모든 결정에 의미 있는 대안, 권장 사항 및 결과가 있음
- 기존 코드에 대한 모든 주장에
path:line또는assumption:레이블이 있음 - 선택된 모든 계약에 검증(허용적 기본값 또는 폴백 포함)이 있음
- 모든 동작 작업에 테스트, 공개 테스트 경계 및 레드-그린-리팩터 검사가 포함됨; 모든 스토리에 목표와 수락 기준이 있음
- 결정, 스토리/작업, 컨텍스트 및 범위 외 주장이 관찰 가능한 동작에 대해 일치함
- 컨텍스트의 용어, 계약 또는 규칙이 모순되지 않음
-
base_commit이 현재HEAD임; 커밋을 사용할 수 없으면 생략하고 이유 설명
6. 보여주기 및 검토
보여주기:
- 항상 전체: 요약과 열린 결정(사용자가 작업하는 부분)
- 변경, 기능: 실제 코드 스케치, 변경 지도, 작업 및 완료 확인을 포함한 전체 계획 본문. 요약, 형태 설명 또는 저장된 파일 링크는 대체물이 아님
- 이니셔티브, 프로젝트: 의존성 및 의존성 트리를 포함한 스토리 개요 표, 나머지에 대한 계획 파일 경로
- 계획된 스토리 검토: 요약, 수락 기준, 열린 결정, 형태, 전체 변경 지도, 작업 테이블 및 의존성 트리. 모든 작업의 파일, 경계, 결과 및 확인 명령을 보여줌; 공유 스위트 명령이나 산문 작업 목록은 대체물이 아님
사용자에게 필요한 것으로 마칩니다:
D1a 또는 D1b를 선택하거나, 피드백을 주거나, 승인이라고 말해주세요.
실제 열린 결정 ID를 사용하십시오. 열린 결정이 없으면 피드백 또는 승인만 요청하십시오.
피드백 시:
- 계획 수정,
version증가,Changed since라인을 변경된 내용으로 교체 - 답변된 결정을
decided로 표시 - 사용자가 지속적인 선호도("클래스 이름에 버전 번호를 절대 넣지 마") 또는 프로젝트 전체 진실을 명시하면 컨텍스트 변경에 추가; 승인 시 적용됨
7. 승인 시
- 명시적 선택을
decided로, 선택되지 않은 권장 사항을assumed로 기록합니다. 계획의 일관성을 다시 확인한 후status: approved및approved: <날짜>를 설정하고, 커밋이 존재하면base_commit을 갱신합니다. 선택 사항이 계획 내용을 변경할 때 버전을 증가시킵니다. - 컨텍스트 변경을
.specshape/context.md에 적용하고, 필요하면 생성합니다. 리포지토리에 이미 용어집이 있으면 링크하고 누락된 부분만 추가합니다. 스토리를 계획할 때 상위의 표준 용어집을 사용합니다. 프로젝트 문서에 중복 정의를 예약하지 마십시오. 그런 다음 계획의 컨텍스트 변경 섹션을 비웁니다. - 이니셔티브 또는 프로젝트: 티켓 제공. 생성할 티켓을 나열합니다: 스토리당 하나씩, 입력 티켓(에픽)의 하위로 또는 프로젝트의 경우 새 에픽 아래에. 각 티켓에는 제목, 목표, 수락 기준 및 계획 링크가 포함되며, 작업은 포함되지 않습니다. 사용자가 예라고 말한 후에만, 사용 가능한 트래커 액세스를 사용하여 생성합니다. 각 로컬 스토리 ID를 계획에서 해당 티켓 키로 대체합니다. 사용 가능한 트래커 통합 및 입력 티켓 소스를 확인합니다. Git 리모트가 없다고 트래커 액세스가 없는 것은 아닙니다. 액세스가 불가능하면 그렇게 말하고 로컬 ID를 유지합니다. 목적지만 알 수 없으면 사용할 트래커/프로젝트를 묻습니다.
- 이 리포지토리의 첫 번째 계획:
AGENTS.md에 한 줄을 추가하겠다고 제안하고, 예라고 한 후에만 추가합니다: "이 코드를 작업하기 전에.specshape/context.md가 있으면 읽으세요. 계획은.specshape/에 있습니다." 해당 스킬을 사용할 수 있는 경우에만 "계획된 작업에는/specshape-build를 사용하세요."를 추가합니다. 이 제안과 다음 단계에 동일한 가용성 조회를 사용합니다. 제안된 라인을 보여주기 전에 확인합니다. - 다음 단계를 말합니다:
- 변경 또는 기능: 해당 스킬을 사용할 수 있는 경우
/specshape-build <id> T1. 그렇지 않으면 계획이 구현 준비가 되었지만/specshape-build를 사용할 수 없다고 말합니다. 코드를 작성하지 않고 중단합니다. - 이니셔티브 또는 프로젝트:
/specshape-plan <첫 번째 스토리 ID>. 다른 스토리를 제안하기 전에 그 전제 조건을 확인합니다. 아직 구축되지 않은 경우, 사전 계획이 가정에 의존할 것이며 빌드 전에 구현된 인터페이스에 대해 재검증해야 한다고 설명합니다. 핸드오프는 저장된 작업 정의와 완료 확인에 충실해야 합니다. 새로운 수동 검사나 요구 사항을 추가하지 마십시오. 다른 검사가 필요하면 먼저 계획을 수정하고 검토하십시오.
- 변경 또는 기능: 해당 스킬을 사용할 수 있는 경우
스토리 계획
입력: 승인된 계획의 스토리 ID.
- 상위 계획이 승인되지 않았으면 그렇게 말하고 중단합니다.
- 스토리의 의존성을 읽고 현재 상태에서 영향을 받는 코드를 전체적으로 조사합니다. 전제 조건 코드가 없으면 가정된 인터페이스에 레이블을 붙이고 빌드 전에 재검증해야 할 사항을 지정합니다. 프로젝트의 워킹 스켈레톤의 경우 상위 계획의 결정과 형태에 기반합니다. 상태나 파일 목록에서 변경되지 않은 코드를 유추하지 마십시오. 새로운 경계 선택에 review.md를 적용합니다.
- 스토리가 사용자만 답할 수 있는 질문을 제기하면 질문합니다(기능 규칙).
- 스토리의 세...
… (번역을 위해 잘림)