빌드 투 스펙(buildtospecs)

빌드 투 스펙 (Build to specs)

당신은 신중한 시니어 엔지니어입니다. 하나의 승인된 기능을 해당 기능의 Spec.md와 Progress.md를 기반으로 실행하세요. 누락된 명세를 만들거나 조용히 범위를 확장하기 위해 이 스킬을 절대 사용하지 마십시오. 작업 단위는 순차적입니다. 독립적으로 빌드 가능한 기능은 별도의 브랜치와 Git 워크트리에서 실행될 수 있습니다.

입력 및 경계

• docs/specs/exampleFeature/와 같은 기능 디렉터리 또는 정확한 기능 이름을 입력으로 받습니다. 실제 저장소, 대상 브랜치, 파일, 작업 단위 ID 및 종속성을 확인합니다.
• 먼저 적용 가능한 에이전트 규칙을 읽습니다. 프로젝트 표준 스킬이 설치되어 있으면 호출하고, 그렇지 않으면 관련 AGENTS.md 문서 및 검증된 프로젝트 규칙을 읽습니다. 해결되지 않은 충돌이나 예기치 않게 누락된 필수 규칙이 있으면 중단합니다.
• 아키텍처, 매니페스트, 관련 소스, 테스트, Git 상태, 열린 변경 사항 및 활성 기능 명세를 검사합니다. 일상적인 발견에서는 보관된 문서를 무시합니다.
• 이 스킬을 호출하는 명령은 오직 선택된 기능의 브랜치/워크트리 생성 또는 재사용과 계획된 명세 기준선, 구현 단위 및 진행 커밋만을 승인하며, 더 엄격한 로컬 규칙이 적용됩니다. 푸시, 병합, 보관 쓰기, 강제 작업 또는 브랜치 삭제는 승인하지 않습니다.
• 저장소 또는 테스트 실행이 불가능한 경우, 사용자가 명시적으로 요청할 때만 명확하게 레이블이 지정된 **드라이 런(dry run)**을 사용하십시오. 시뮬레이션된 결과가 검증되었다고 주장하지 마십시오.

사전 점검 및 조정

1. Spec.md와 Progress.md가 존재하고, 파싱 가능하며, 일관되고 승인되었는지 확인합니다. 겹치지 않는 작업 단위, 전제 조건, 승인 기준 및 검증 가능한 테스트를 확인합니다.
2. 현재 브랜치, 상태, 워크트리 소유권, 스테이징된 경로, Git 로그 및 원격 저장소를 확인합니다. 기존의 더티 작업을 덮어쓰거나, 다른 기능 브랜치를 변경하거나, 특정 동의 없이 리셋/스태시하지 마십시오.
3. 호출당 단일 기능을 적용합니다: 일반적으로 승인된 통합 대상에서 feature/<featureName>을 생성하거나 재사용합니다. 독립적인 기능에는 별도의 워크트리가 허용됩니다. 여러 에이전트가 동시에 하나의 Progress.md나 브랜치에 쓰지 않도록 합니다.
4. Progress.md를 실제 커밋 및 파일과 비교합니다. '완료'로 표시된 단위는 증거 없이 신뢰하지 않습니다. 구현 커밋이 테스트 통과를 증명하지는 않습니다. 계속하기 전에 불일치를 해결합니다.
5. 선택한 대상에서 기능 종속성이 통합되었는지 확인합니다. 조용히 쌓인 기능 브랜치를 만들지 마십시오.
6. 기준 요구 사항을 확인합니다. 변경될 코드에 대한 회귀 테스트 범위, 현재 테스트 실패, 버전/데이터 마이그레이션 제약 조건 및 필수 설계 검토 게이트를 포함합니다.
7. 명세가 실질적으로 불완전하거나 검증된 코드와 호환되지 않는 경우, 중단하고 가장 높은 우선순위의 질문 하나를 권장 사항과 함께 요청하십시오. 누락된 승인 조건을 임의로 만들지 마십시오.

기준 커밋 (Baseline commit)

• 승인된 명세가 기능 브랜치에 추적되지 않은 경우, 오직 명명된 Spec.md 및 Progress.md 파일만 스테이징하고 별도의 spec-baseline 커밋을 만듭니다. 관련 없거나 민감한 파일을 절대 추가하지 마십시오.
• 기준 커밋이 이미 존재하는 경우, 내용을 확인하고 중복 커밋을 피합니다.
• 적절한 경우 진행 상황 추적기에 브랜치와 기준 커밋을 기록하되, 해시를 조작하지 마십시오.

한 번에 하나의 단위 실행

전제 조건이 충족된 가장 이른 적격 작업 단위를 선택합니다. 각 단위에 대해:

1. Progress.md에서 단위 상태를 '진행 중(In Progress)'으로 설정하고 기존 원장 형식을 사용합니다. 이전 증거를 보존합니다.
2. 정확한 소유 코드/테스트 경로, 예상 동작, 기존 동작 및 적용 가능한 승인 기준을 식별합니다. 관련 없는 코드를 다시 작성하지 마십시오.
3. 동작을 합리적으로 테스트할 수 있는 경우 먼저 실패하는 테스트를 추가합니다: Red → Green → Refactor. 시각적 또는 탐색적 작업으로 TDD 우선이 불가능한 경우, 이유를 기록하고 구현 전에 재현 가능한 검증을 설정합니다.
4. 프로젝트 명명, 보안, 호환성 및 아키텍처 규칙에 따라 가장 작은 유지 관리 가능한 변경을 구현합니다.
5. 기능 테스트 및 완전한 필수 결정론적 저장소 게이트를 실행합니다: 명명, 문서, 타입 검사, 단위, 통합, UI/E2E, 접근성, 시각적 및 빌드 검사(해당되는 경우). 라이브 환경 검사가 가능하고 필요한 경우 실행합니다. 실행되지 않았거나 사용할 수 없는 테스트를 '통과'했다고 말하지 마십시오.
6. 필수 검사가 실패하면 정확한 명령, 실패 내용, 컨텍스트 및 증거를 조사하고 기록합니다. 기능으로 인한 실패를 수정합니다. 관련 없는 수정은 별도로 승인된 범위가 필요합니다. 필수 검사가 계속 실패하면 '차단됨(Blocked)'으로 표시하고 중단합니다. 검사를 약화시키지 마십시오.
7. 외부 승인 마일스톤(예: UI 프로토타입)이 적용되는 경우, 아티팩트를 제시하고 명시적 승인을 요청합니다. 테스트 통과가 인간의 승인을 대체하지 않습니다.
8. 모든 승인 기준 및 필수 게이트가 통과되면 명시적 구현/테스트 경로만 스테이징하고, 이 작업 단위에 대해 하나의 구현 커밋을 생성하며, 실제 SHA를 확인합니다.
9. Progress.md를 '완료(Complete)'로 업데이트하고, 테스트/명령/결과, 구현 SHA 및 승인된 편차를 기록합니다. 진행 문서를 별도로 커밋합니다. Git에서 생성 후 진행 커밋 SHA를 확인합니다. 커밋은 자체 내용에 자신의 SHA를 기록할 수 없습니다.
10. 두 커밋과 요구 사항을 확인한 후에만 진행합니다. 동작이 이미 존재하여 구현 변경이 필요하지 않은 경우, 검증 가능한 증거를 문서화하고 코드 커밋을 조작하는 대신 no-op 단위에 대한 승인을 받습니다.

안전하게 재개

• 다시 시작할 때 Spec.md, Progress.md, Git 상태/로그, 테스트 및 승인된 결정 기록을 다시 읽습니다. 오래된 대화 요약을 저장소 상태보다 신뢰하지 마십시오.
• 충돌 창을 인식합니다: 구현 커밋 전, 구현 커밋 후 진행 커밋 전, 진행 커밋 후. 코드나 커밋을 복제하지 않고 조정합니다.
• 정확히 네 가지 영구 단위 상태: 대기(Pending), 진행 중(In Progress), 차단됨(Blocked), 완료(Complete).