<div align="center">
<img src="https://github.com/spec-kitty/spec-kitty/raw/main/docs/assets/logo_small.webp" alt="Spec Kitty logo"/>
<h1>Spec Kitty</h1>
<p><strong>AI 코딩 에이전트, 다중 에이전트 워크플로우 및 거버넌스 소프트웨어 팩토리를 위한 스펙 기반 개발(Spec-driven development).</strong></p>
</div>
Spec Kitty는 제품 의도(product intent)를 리포지토리 네이티브 AI 코딩 워크플로우로 변환하는 오픈 소스 CLI입니다:
spec -> plan -> tasks -> next -> review -> accept -> merge
이를 사용하여 Claude Code, Codex, Cursor, Gemini, GitHub Copilot, Windsurf, OpenCode 및 기타 AI 코딩 에이전트를 중심으로 거버넌스 소프트웨어 팩토리를 구축할 수 있습니다. Spec Kitty는 스펙(specs), 계획(plans), 작업 패키지(work packages), 승인 기준(acceptance criteria), 검토 상태(review state), 그리고 병합 결정(merge decisions)을 리포지토리에 유지하며, 에이전트들에게 격리된 git worktree를 제공하여 브랜치 혼란 없이 병렬로 구현이 이루어질 수 있도록 합니다.
PyPI version
License: MIT
Python 3.11+
Team Kitty 4.x 프리릴리스
main 브랜치는 4.x 릴리스 후보(release-candidate) 라인을 담고 있습니다. RC2를 테스트하려면 정확한 버전을 설치하세요:
uv tool install 'spec-kitty-cli==4.0.0rc2'
이 프리릴리스는 자격 검증용이며, 안정적인 출시 승인은 보류 중입니다.
일반적인 안정 버전 설치는 계속해서 게시된 안정 버전을 선택합니다.
블랙박스가 아닌 밝은 소프트웨어 팩토리
Spec Kitty는 반복 가능한 입력, 명확한 작업 패키지 경계, 격리된 실행, 가시적인 진행 상황, 그리고 검토 게이트를 가진 소프트웨어 팩토리를 구축하는 팀을 위한 것입니다. 어두운(dark) 소프트웨어 팩토리와 자율 코딩 실험도 지원할 수 있지만, 기본적으로는 의도적으로 블랙박스가 아닙니다. 인간이 의도, 아키텍처, 그리고 승인 기준을 정의하고; 에이전트가 추적 가능한 worktree 내부에서 구현하며; 검토자는 감사 기록(audit trail)과 함께 승인, 거부 또는 병합합니다.
목표는 더 많은 프롬프트 텍스트를 만드는 것이 아닙니다. 목표는 리포지토리가 진실의 원천(source of truth)으로 남아있는 에이전트 기반 코딩을 위한 지속 가능한 운영 체제입니다.
귀하에게 적합한가요?
Spec Kitty를 사용해야 할 때:
- AI 코딩 세션에서 요구사항(requirements), 결정 사항(decisions), 또는 인수 기준(acceptance criteria)을 잃어버립니다.
- Git에 스펙(specs), 계획(plans), 작업 항목(tasks), 검토 내용(reviews), 그리고 병합 상태(merge state)를 저장하고 싶습니다.
- 여러 에이전트 또는 개발자는 명확한 작업 패키지 경계가 필요합니다.
- Claude Code, Codex, Cursor, Copilot, Gemini, 또는 Windsurf 작업을 병렬로 실행하며 Git 작업 트리(worktree) 격리가 필요합니다.
- 직관적인 코딩 방식(vibe coding)에서 반복 가능한 스펙 기반 개발 워크플로우로 전환하고 있습니다.
- 먼저 로컬 워크플로우를 원하며, 나중에 선택적 호스팅 트래커 및 동기화 통합을 추가하기를 원합니다.
일회성 수정, 작은 스크립트 또는 Git을 사용하지 않는 팀에게는 과도할 수 있습니다.
제공하는 기능 (What It Provides)
| 필요 사항 | Spec Kitty가 제공하는 것 |
|---|
| 의도(intent)부터 시작하기 | 안내되는 specify, plan, 및 tasks 워크플로우 |
| ... | |
일반적인 사용 사례 (Common Use Cases)
- 임시적이고 직관적인 코딩 방식을 스펙 기반 개발로 대체합니다.
- GitHub 이슈, 제품 요구사항 또는 버그 보고서를 실행 가능한 작업 패키지로 변환합니다.
- 세션 간 컨텍스트를 잃지 않으면서 여러 AI 코딩 에이전트를 조정합니다.
- 아키텍처 결정 사항, 제약 조건 및 인수 기준을 코드와 가깝게 유지합니다.
- 검토(review), 테스트 또는 병합 결정을 숨기지 않으면서 더 높은 자율성으로 확장할 수 있는 거버넌스된 소프트웨어 팩토리(software factory)를 구축합니다.
거버넌스 계층 (Governance layer)
Spec Kitty는 런타임 거버넌스를 에이전트 전용 프롬프트 텍스트로 취급하는 대신 레포지토리(repo) 내에 유지합니다. [docs/architecture/trail-model.md]의 트레일 모델(trail model)은 spec-kitty dispatch "<request>"가 운영자 의도(operator intent)를 런타임 동작으로 어떻게 매핑하는지 설명하며, [docs/architecture/host-surface-parity.md]는 CLI, 슬래시 명령어(slash-command), 그리고 호스팅된 인터페이스 전반에 걸친 일치성(parity)을 추적합니다.
주요 독립형 거버넌스 명령어는 다음과 같습니다:
spec-kitty dispatch "<request>" - 거버넌스 컨텍스트를 로드하고, Op 레코드를 열고, 에이전트가 작업을 수행하기 전에 사용해야 하는 컨텍스트를 반환합니다.
빠른 시작 (Quick Start)
CLI 설치:
pipx install spec-kitty-cli
pipx는 Spec Kitty를 자체 가상 환경에 유지하고 최신 Linux 배포판에서 흔히 발생하는 externally-managed-environment 오류를 방지하기 때문에 CLI(명령줄 인터페이스)의 선호 설치 프로그램입니다.
다른 지원되는 설치 방법:
uv tool install spec-kitty-cli
python -m pip install spec-kitty-cli
프로젝트 생성 또는 초기화:
spec-kitty init my-project --ai claude
cd my-project
spec-kitty verify-setup
필요에 따라 claude를 에이전트 키로 교체하십시오. 일반적인 선택지에는 codex, cursor, gemini, copilot, opencode, qwen, windsurf, kiro, vibe, pi, letta, antigravity, 그리고 llxprt가 포함됩니다. 현재 목록은 Supported Agents를 참조하십시오.
프로젝트에서 AI 코딩 에이전트를 열고 핵심 워크플로우를 실행합니다:
/spec-kitty.charter
/spec-kitty.specify 작은 작업 목록 앱을 구축합니다.
/spec-kitty.plan
...
Spec Kitty를 에이전트 스킬로 로드하는 에이전트(Codex, Vibe, Pi, Letta, Antigravity)는 동일한 명령어를 실행합니다. 이 명령어들은 spec-kitty-<command>라는 이름의 스킬로 작동하며, 예를 들어 Codex에서는 $spec-kitty-specify, Pi에서는 /skill:spec-kitty-specify, 그리고 다른 에이전트들에서는 /spec-kitty-specify를 사용합니다.
그런 다음 런타임(runtime)이 임무가 준비될 때까지 다음 조치를 선택하도록 합니다:
spec-kitty next --agent claude --mission <mission-slug>
검토하고, 수락하고, 병합하며, 루프를 닫습니다:
/spec-kitty.review
/spec-kitty.accept
/spec-kitty.merge --push
병합(merge) 후에는 /spec-kitty-mission-review를 실행합니다. 임무의 retrospective.yaml은 런타임 종점(HiC 프롬프트 또는 자율 촉진자) 중에 작성되며, merge에 의해 생성되는 것이 아닙니다. 이 파일이 존재하면, 크로스 미션 보기에는 spec-kitty retrospect summary를 사용하고, 스테이징된 제안을 적용하려면 spec-kitty agent retrospect synthesize --mission <mission-slug>를 사용하여야 합니다 (기본값은 건너뛰기(dry-run)이므로, 변경하려면 --apply를 전달하십시오).
전체 워크스루는 Your First Mission를 참조하십시오.
일상적인 명령어
| 명령어 (Command) | 목적 (Purpose) |
|---|
spec-kitty init . --ai <agent> | 현재 리포지토리에 Spec Kitty 추가 |
| ... | |
문서화 (Documentation)
여기서 시작하세요:
더 깊은 주제:
호스팅 인증(auth), 동기화(sync), 추적기 흐름(tracker flows)이 open-core에서 제거되었습니다(#6164; 코드는 spec-kitty/event-router에 보존되어 있습니다). 배경 정보는 Launch-Readiness Behavior를 참조하십시오.
FAQ (자주 묻는 질문)
스펙 키티(Spec Kitty)는 다크 소프트웨어 팩토리(dark software factories)에 사용되나요?
스펙 키티는 다크 소프트웨어 팩토리 또는 자율 코딩 파이프라인의 일부로 사용될 수 있지만, 기본 모델은 관리되고 인간 개입형(human-in-loop)입니다. 이 도구는 스펙, 작업 패키지, 에이전트 행동, 검토 결정 및 병합 상태를 리포지토리에서 가시적으로 유지합니다.
스펙 키티는 어떤 AI 코딩 에이전트를 지원하나요?
스펙 키티는 Claude Code, Codex, Cursor, Gemini, GitHub Copilot, OpenCode, Qwen, Windsurf, Kiro, Vibe, Pi, Letta, Antigravity를 포함한 일반적인 AI 코딩 에이전트 및 코딩 하네스를 지원합니다. 지원되는 에이전트 (Supported Agents)를 참조하십시오.
스펙 키티는 프롬프트 템플릿이나 Spec Kit과 어떻게 다른가요?
Spec Kitty는 스펙 기반 개발 워크플로우(spec-driven development workflows)에서 영감을 받았지만, 리포지토리 네이티브 미션 상태(repo-native mission state), 작업 패키지 레인(work-package lanes), git worktree 격리(git worktree isolation), 거버넌스 명령어(governance commands), 그리고 명시적인 next -> review -> accept -> merge 런타임 루프를 추가합니다.
Spec Kitty는 SaaS 서비스가 필요한가요?
아닙니다. Spec Kitty는 로컬 우선(local-first) 방식이며 핵심 아티팩트(core artifacts)를 사용자의 리포지토리에 저장합니다. 호스팅 트래커 및 동기화 통합은 선택 사항입니다.
개발 (Development)
git clone https://github.com/spec-kitty/spec-kitty.git
cd spec-kitty
pip install -e ".[test]"
소스 체크아웃(source checkout)에서 템플릿을 테스트할 때:
export SPEC_KITTY_TEMPLATE_ROOT="$(pwd)"
spec-kitty init my-project --ai claude
기여 가이드라인(contribution guidelines)은 Contributing guide를 참조하세요.
지원 (Support)
라이선스 (License)
Spec Kitty는 MIT License 하에 배포됩니다.
