Klerith/fernando-skills

해결하는 문제

Claude Code와 같은 LLM에게 "아르카노이드 게임을 만들어 줘"와 같은 광범위한 요청을 하면, 그것은 조용히 즉흥적으로 대응하는 경향이 있습니다—여러분의 입력 없이 수십 가지 설계 결정(클래스 대 함수, 전역 대 로컬 상태, 명명 등)을 내립니다. 이러한 각 결정은 나중에 되돌리기 어렵습니다. LLM은 코드를 너무 빨리 생성하여 결정이 보이지 않게 되고, 각 대화가 이전 선택에 대한 기억 없이 새로 시작되며, 동일한 컨텍스트를 수동으로 붙여넣느라 컨텍스트를 낭비하기 때문에 문제는 더 심각합니다. 이 프로젝트는 사양을 핵심 산출물로 만들어 이 세 가지를 모두 해결합니다: 명시적인 결정을 강제하고, 세션 간에 지속하며, 안정적인 참조로 한 번 로드합니다.

작동 방식

이 프로젝트는 쌍으로 작동하는 두 개의 Claude Code 스킬을 제공합니다. /spec 스킬은 기능 사양 설계를 안내합니다. 프로젝트의 메모리 파일(CLAUDE.md, AGENTS.md 또는 README.md)과 기존 사양을 읽은 다음, 기능이 명확해질 때까지 3-5개 블록으로 명확화 질문을 합니다. 사양을 섹션별로 구축하고, 각 부분을 확인한 후 다음으로 진행하며, 마지막으로 specs/NN-slug.md로 상태 Draft로 저장합니다.

그런 다음 채팅 외부(편집기에서)에서 사양을 다시 읽고 상태를 Approved로 수동으로 변경합니다—이는 의도적인 인간 행동입니다. Claude는 자신의 작업을 승인할 수 없기 때문입니다. 승인한 후에만 /spec-impl을 사용할 수 있습니다.

/spec-impl 스킬은 사양을 찾고, 상태가 Approved인지 확인하고, git 브랜치(예: spec-03-levels-and-highscores)를 생성하고(다르게 구성되지 않은 경우), 순서가 지정된 계획에 따라 사양을 단계별로 구현합니다. 각 단계 후에 diff를 검토할 수 있도록 일시 중지합니다. 구현 중에 변경해야 할 사항이 있으면 계획 모드로 돌아가 사양을 업데이트합니다—코드에 직접 즉흥적으로 대응하지 않습니다.

사양 자체는 README에 설명된 6부분 구조를 따릅니다: 한 문장 목표, 명시적인 범위 내 및 범위 외 항목, 구체적인 이름과 경로가 있는 데이터 모델, 각 단계가 시스템을 작동 상태로 유지하는 순서가 지정된 구현 계획, 검증 가능한 수용 기준(예: "Esc를 누르면 게임이 일시 중지되고 메뉴가 표시됨"과 같은 부울 체크 항목), 그리고 이유와 함께 내려진 결정과 폐기된 결정의 기록.

대상 사용자

이것은 Claude Code(또는 포함된 설치 프로그램을 통해 Cursor, Codex, Antigravity와 같은 다른 코딩 에이전트)를 사용하는 개발자를 위한 것으로, 계획되지 않은 LLM 코드 생성의 혼란을 피하려는 사람들을 위한 것입니다. 작업이 두 개 이상의 파일에 영향을 미치고, 되돌리기 어려운 결정(스키마, 형식, API)을 포함하고, 한 세션보다 오래 걸리거나, 다른 산출물에 의해 재사용되는 계약을 생성할 때 이상적입니다. 사소한 버그 수정, 기계적 리팩토링, 탐색적 실험 또는 단일 프롬프트에 맞는 일회성 작업에는 적합하지 않습니다.

하이라이트

• 두 개의 쌍을 이루는 스킬: /spec(설계) 및 /spec-impl(구현).
• 사양은 git에서 버전 관리되며 지속적인 설계 결정 로그로 사용됩니다.
• 인간 승인 필요: 구현을 시작하기 전에 사양 상태를 Draft에서 Approved로 수동으로 변경해야 합니다.
• 각 diff를 검토하기 위해 일시 중지하는 단계별 구현—더 이상 거대한 400줄 커밋은 없습니다.
• Claude Code를 넘어: 설치 프로그램 스크립트가 Cursor, Codex 및 Antigravity에 맞게 스킬을 조정합니다.
• 사양에는 "잘 작동함" 또는 "좋은 UX"와 같은 모호한 진술이 아닌 검증 가능한 부울 수용 기준이 포함됩니다.
• README의 정신적 규칙: 계획 모드를 열고 싶다면 아마 필요할 것입니다; 기능 계획이 지루하다면 아마 필요하지 않을 것입니다.