<div align="center">
<pre>
▄▀█ █ █ ▀█▀ █▀█ █▀ █▀█ █▀▀ █▀▀
█▀█ █▄█ █ █▄█ ▄█ █▀▀ ██▄ █▄▄
</pre>
스펙 기반 개발 자동화 (Spec-Driven Development Automation)
GitHub CI
GitHub Release
Go Report Card
License: MIT
AI 기반 명세(specification) 워크플로우를 통해 체계적으로 기능을 구축하세요.
</div
AI의 무질서한 결과물(slop)을 멈추세요. Autospec은 AI 코딩에 구조를 부여합니다: 명세(spec) → 계획(plan) → 작업(tasks) → 구현(implement) — 이 모든 것을 단일 명령어로 처리합니다.
**다중 에이전트 아키텍처 (multi-agent architecture)**로 구축되었으며 GitHub SpecKit에서 영감을 받은 Autospec은 YAML 우선(YAML-first) 아티팩트를 사용하여 명세 워크플로우를 재구상했습니다. 이를 통해 프로그래밍 방식 접근 및 검증이 가능해집니다. 이러한 원칙들은 개발자가 중요한 개발 워크플로우에 신뢰할 수 있는, 안정적이고 성능이 뛰어나며 유지보수가 용이한 소프트웨어를 보장합니다.
지원되는 에이전트: Claude Code, Codex CLI, OpenCode, 그리고 Jcode.
📦 설치 방법
curl -fsSL https://raw.githubusercontent.com/ariel-frischer/autospec/main/install.sh | sh
🎯 주요 기능
- 자동화된 워크플로우 오케스트레이션 (Automated Workflow Orchestration) — 의존성 순서에 따라 단계를 실행하며 실패 시 자동 재시도 기능을 제공합니다.
- YAML 우선 아티팩트 (YAML-First Artifacts) — 프로그래밍 방식 접근을 위한 기계가 읽을 수 있는
spec.yaml, plan.yaml, tasks.yaml 파일을 사용합니다.
- 스마트 유효성 검사 (Smart Validation) — 진행 전에 아티팩트 존재 여부와 완전성 기준 충족 여부를 검증합니다.
- 크로스 플랫폼 (Cross-Platform) — Linux 및 macOS(Intel/Apple Silicon)용 네이티브 바이너리를 제공합니다. Windows 사용자는 WSL을 사용하십시오.
- 유연한 단계 선택 (Flexible Stage Selection) — 직관적인 플래그(
-spti, -a 등)를 사용하여 단계를 혼합하고 매칭할 수 있습니다.
- 셸 완성(Shell Completion) — bash, zsh, fish용 자동 완성 기능을 제공합니다.
- OS 알림 (OS Notifications) — 사용자 지정 사운드 지원을 포함한 네이티브 데스크톱 알림을 제공합니다.
- 히스토리 추적 (History Tracking) — 상태, 지속 시간 및 종료 코드를 통해 명령어 실행 기록 조회 및 필터링이 가능합니다.
- 자동 커밋 (Auto-Commit) — .gitignore 관리와 컨벤셔널 커밋 메시지를 포함하여 자동으로 git 커밋을 생성합니다.
- 멀티 에이전트 (Multi-Agent) — Claude Code, Codex CLI, OpenCode, Jcode 및 사용자 지정 에이전트 명령을 지원합니다.
- 단계별 모델 및 프로필 (Per-Stage Models & Profiles) — 단계별로 모델을 선택(
models.<stage>)하고 --profile을 사용하여 전체 설정 세트를 전환할 수 있습니다.
- 깔끔한 중단 (Clean Interruption) — Ctrl+C, 시간 초과(timeouts), 취소(cancellation) 시 에이전트와 모든 하위 프로세스를 안전하게 중지시킵니다.
✨ Autospec을 차별화하는 요소는 무엇인가요?
원래 GitHub SpecKit에서 영감을 받은 Autospec은 YAML 네이티브 아티팩트, 프로그래밍 방식 유효성 검사, 그리고 컨텍스트 효율적인 구현 실행에 중점을 둔 독립형 Go CLI입니다.
| 기능 (Feature) | GitHub SpecKit | Autospec |
|---|
| 출력 형식 (Output Format) | Markdown | YAML (기계가 읽을 수 있음) |
| ... | | |
🚀 빠른 시작하기
autospec이 처음인가요? 빠른 시작 가이드를 참조하거나 대화형 데모를 실행해 보세요.
필수 조건 (Prerequisites)
프로젝트 초기화 (Initialize Your Project)
-
git 저장소/프로젝트 디렉터리로 이동한 다음, 의존성을 확인합니다:
-
Autospec을 초기화합니다 (설정, 명령어 및 스크립트):
autospec init
autospec init ~/projects/myapp
autospec init --ai codex
...
지원되는 경우 기본적으로 전역 설정에 쓰기 권한을 가집니다. Codex 프로젝트 메타데이터는 --project와 함께 사용해야 .codex/config.toml에 작성됩니다.
-
프로젝트 헌법(constitution)을 생성합니다 (프로젝트당 한 번, 구성된 에이전트를 트리거함):
🎮 사용법 (Usage)
핵심 흐름 명령어 (Core Flow Commands)
specify → plan → tasks → implement
핵심 워크플로우는 순차적으로 네 단계를 실행하며, 각 단계마다 YAML 아티팩트를 생성합니다:
| 단계 | 명령어 | 생성물 | 설명 |
|---|
| specify | autospec specify "desc" | specs/001-feature/spec.yaml | 요구사항이 포함된 기능 명세서 (Feature specification) |
| ... | | | |
브랜치 생성: specify는 스펙을 생성하기 전에 자동으로 새로운 기능 브랜치를 생성하고 체크아웃합니다 (예: spec/001-user-auth).
권장 워크플로우 (Recommended Workflow)
- 명세서를 생성합니다.
- 필요한 경우
specs/001-user-auth/spec.yaml을 검토하고 편집합니다.
- plan → tasks → implement로 진행합니다.
autospec run -s "OAuth를 사용한 사용자 인증 추가"
autospec run -pti
이 반복적인 접근 방식은 구현에 전념하기 전에 스펙을 검토하고 다듬을 수 있게 해줍니다.
run을 사용한 유연한 단계 선택 (Flexible Stage Selection with run)
autospec run -a "OAuth를 사용한 사용자 인증 추가"
...
바로가기 명령어 (Shortcut Commands)
모든 핵심 스테이지: specify → plan → tasks → implement
autospec all "기능 설명 추가"
...
구현 실행 모드 (Implementation Execution Modes)
다양한 수준의 컨텍스트 격리(context isolation)를 통해 구현이 어떻게 실행되는지 제어합니다:
autospec implement
autospec implement --from-phase 3
...
설정 파일에서 기본 모드를 지정하세요: implement_method: phases | tasks | single-session
--tasks, --phases, 그리고 --single-session은 상호 배타적입니다. 작업(Task) 수준의 실행은 의존성 순서를 준수하며, 각 작업이 완료된 후에만 다음 단계로 진행하고 유효성을 검사합니다.
세션을 격리하는 이유? 컨텍스트 축적은 LLM 성능 저하와 더 높은 API 비용을 초래합니다(각 턴마다 전체 컨텍스트가 청구됨). 스테이지/작업 격리는 대규모 스펙의 경우 비용을 80%+ 절감할 수 있습니다. 자세한 내용은 [FAQ]를 참조하세요.
선택적 스테이지 명령어 (Optional Stage Commands)
autospec constitution "보안 강조"
...
스테이지 플래그 참조 (run 명령어)
| 플래그 | 스테이지 | 설명 |
|---|
-s | specify | 기능 스펙 생성 |
| ... | | |
스테이지는 플래그 순서에 관계없이 항상 표준(canonical) 순서로 실행됩니다:
constitution → specify → clarify → plan → tasks → checklist → analyze → implement
작업 관리 (Task Management)
Claude가 구현 과정 중 자동으로 작업 상태를 업데이트합니다. 수동 업데이트는 다음과 같습니다:
autospec update-task T001 InProgress
autospec update-task T001 Completed
autospec update-task T001 Blocked
기록 추적 (History Tracking)
필터링 및 상태 추적으로 명령어 실행 기록을 확인합니다. 자세한 내용은 [docs/public/reference.md]를 참조하세요.
autospec history
autospec history -n 10
autospec history --status failed
📁 출력 구조 (Output Structure)
Autospec은 구조화된 YAML 아티팩트를 생성합니다:
specs/
└── 001-user-auth/
├── spec.yaml # 기능 명세(Feature specification)
...
예시 tasks.yaml
feature: user-authentication
tasks:
- id: T001
...
⚙️ 설정 (Configuration)
설정 파일 (YAML 형식)
- 사용자 설정(User config):
~/.config/autospec/config.yml (XDG 준수)
- 프로젝트 설정(Project config):
.autospec/config.yml
우선순위: 환경 변수(Environment vars) > 프로젝트 설정(Project config) > 사용자 설정(User config) > 기본값(Defaults)
명명된 프로필(~/.config/autospec/profiles/<name>.yml 또는 .autospec/profiles/<name>.yml)은 --profile <name> 명령 하나로 여러 설정을 계층화하여 적용합니다. 이들은 autospec config profiles와 autospec config create <name>으로 관리할 수 있습니다.
모든 설정 (All Settings)
사용자 지정 에이전트 구성 (Custom Agent Configuration)
에이전트 호출에 대한 완전한 제어를 위해서는 custom_agent를 사용합니다:
custom_agent:
command: claude
args:
...
또는 단일 명령어 문자열로 지정할 수 있습니다:
custom_agent_cmd: "claude -p --model claude-sonnet-5 {{PROMPT}}"
OpenCode 설정 및 환경 변수를 포함한 전체 세부 정보는 에이전트 구성(Agent Configuration)을 참조하세요.
Jcode Go SDK
Autospec의 옵트인 네이티브 jcode SDK 러너(jcode.runner: sdk)는 게시된 github.com/ariel-frischer/jcode-go 모듈과 함께 작동합니다. 이는 상위 Jcode를 위한 Ariel Frischer의 비공식 커뮤니티 SDK이며, 공식 CLI 러너가 기본값으로 유지됩니다.
명령어 (Commands)
autospec init
autospec init --project
autospec config show
...
🐚 쉘 자동 완성 (Shell Completion)
쉘 자동 완성(사용하는 쉘을 자동으로 감지합니다)을 설정하는 가장 쉬운 방법:
autospec completion install
또는 특정 쉘에 대해 설치할 수 있습니다:
autospec completion install bash
autospec completion install zsh
autospec completion install fish
자세한 설정 및 수동 지침은 docs/public/SHELL-COMPLETION.md을 참조하세요.
🔧 종료 코드 (Exit Codes)
CI/CD 통합을 위해 표준화된 종료 코드(0-5)를 사용합니다. 자세한 내용은 docs/public/reference.md를 참조하십시오.
autospec run -a "feature" && echo "Success" || echo "Failed: $?"
🔍 문제 해결 (Troubleshooting)
autospec doctor
autospec --debug run -a "feature"
autospec config show
일반적인 문제 및 해결 방법은 docs/public/troubleshooting.md를 참조하십시오.
📝 대화형 세션을 위한 슬래시 명령어 (Slash Commands for Interactive Sessions)
autospec init을 사용하면 대화형 세션용 에이전트 네이티브 프롬프트가 설치됩니다. Claude Code는 .claude/skills/autospec.specify/SKILL.md와 같은 프로젝트 스킬을 받아 /autospec.specify 호출을 유지합니다. Codex 및 OpenCode는 대화형 $autospec-specify / $autospec-clarify 사용을 위해 .agents/skills/autospec-* 스킬을 공유합니다. Codex 및 OpenCode CLI 워크플로우 실행은 codex exec와 opencode run을 통해 렌더링된 프롬프트 텍스트를 직접 받으며, OpenCode init은 더 이상 .opencode/command 파일을 생성하지 않습니다.
/autospec.specify
/autospec.plan
...
이러한 명령어는 autospec의 자동화된 (-p) 모드보다 채팅 기반 반복(chat-based iteration)을 선호할 때 사용하십시오.
📚 문서 (Documentation)
전체 문서: ariel-frischer.github.io/autospec
📥 소스에서 빌드 (Build from Source)
Go 1.25+가 필요합니다.
git clone https://github.com/ariel-frischer/autospec.git
cd autospec
make install
🗺️ 로드맵 (Roadmap)
비정기 아이디어에는 후보 에이전트 프리셋(Cursor CLI, Copilot CLI, Amp, Qwen Code, omp)이 포함되며, 이는 [docs/internal/roadmap.md]에 기록되어 있습니다. 에이전트 프리셋은 수요 기반으로 제공됩니다. 만약 특정 프리셋을 원한다면 이슈를 열어주세요. 그 전까지는 헤드리스 모드를 지원하는 모든 에이전트를 사용자 지정 에이전트 설정을 통해 사용할 수 있습니다.
🤝 기여 (Contributing)
기여를 환영합니다! 개발 가이드라인은 CONTRIBUTORS.md를 참고하세요.
📄 라이선스 (License)
MIT 라이선스를 따릅니다 — 자세한 내용은 LICENSE를 확인하세요.
문서화(Documentation): autospec --help
이슈(Issues): github.com/ariel-frischer/autospec/issues
⭐ Autospec을 유용하게 사용하셨다면 GitHub에서 별점을 남겨주세요!