speckit-companion: AI 어시스턴트와 Spec Kit을 위한 VS Code 확장 프로그램

speckit-companion.dev · 문서(Docs) · 설치(Install) · 첫 번째 spec 작성하기(Your first spec) · 변경 로그(Changelog)

SpecKit Companion은 AI 어시스턴트와 Spec Kit을 사용하여 개발하는 개발자를 위한 VS Code 확장 프로그램입니다. 이 확장은 프로젝트의 모든 spec을 보여주고, 각각의 spec을 읽고 댓글을 달 수 있는 페이지로 렌더링하며, 실행 과정을 추적하고, AI가 무엇을 했는지 그리고 왜 그렇게 했는지 기록을 유지합니다. 사용자의 spec은 레포지토리 내에서 일반 마크다운(plain markdown) 형태로 유지됩니다.

0.36.0 버전의 새로운 기능: 새 모드를 통해 Claude Code 내부에서 Spec Kit 실행 과정을 추적할 수 있게 되었습니다. 이 모드는 spec을 프롬프트 위에 고정하고, 기록된 내용 옆에 단계와 작업을 체크 표시합니다. 버그나 아이디어는 자체 사이드바 패널을 가지며 페이지로 열립니다: 버그는 이야기(story)처럼 읽히고, 결정된 아이디어는 결정 사항(decision)으로 읽힙니다. 뷰어에는 열린 질문에 답변하고, Converge를 실행하며, 작업 목록에서 GitHub 이슈를 생성하는 버튼이 추가되었으며, Copilot 앱 보드도 이제 모든 Spec Kit 프로젝트를 추적합니다. 전체 노트: [Changelog].

확장 프로그램 보기(Extensions view)에서 SpecKit Companion을 검색하거나 다음 명령어를 실행하세요:

code --install-extension alfredoperez.speckit-companion

폴더를 열고, 활동 표시줄(activity bar)의 SpecKit 아이콘을 클릭한 후, 요청할 때 AI 어시스턴트를 선택하기만 하면 됩니다. 이것으로 spec을 읽고 검토하고 실행하는 데 충분합니다. Open VSX에서도 사용 가능합니다.

이 두 번째 절반은 선택 사항입니다. 이는 각 실행(단계 시간, 결정, 확인)을 기록하고, 더 간소화된 Companion 파이프라인, 재개 버튼(Resume button), 그리고 살아있는 spec을 제공합니다. 프로젝트 루트에서 다음 명령어로 추가하세요:

specify extension add companion --from https://github.com/alfredoperez/speckit-companion/releases/download/companion-latest/companion.zip --force

이 명령어는 확장 프로그램이 있는 Spec Kit CLI가 필요합니다. 단계가 실패했을 때 무엇을 해야 하는지에 대한 전체 가이드라인은 설치 페이지에 있습니다.

spec은 마크다운의 벽처럼 열리는 것이 아니라, 하나의 페이지로 열립니다. 요구사항(Requirements)은 레이블이 지정된 행으로 표시되고, 수용 시나리오(acceptance scenarios)는 Given, When, Then 형식으로 읽히며, 작업(tasks)은 해당 단계 아래에 위치하고, mermaid 다이어그램은 확대 기능과 함께 인라인으로 렌더링됩니다. 푸터에는 다음 단계가 제공되며, 실행 중인 단계를 앞서 나가지 않습니다.

스펙의 특정 라인에 풀 리퀘스트(pull request)를 검토하듯이 코멘트를 남길 수 있습니다. 코멘트는 추가하는 순간 저장되며 커밋할 수 있어, 나중에 다른 세션이나 다른 기기에서 검토해도 이어서 작업할 수 있습니다. Refine을 클릭하면 보류 중인 코멘트가 어시스턴트로 전송되어 스펙이 제자리에서 수정됩니다.

파이프라인 레일(pipeline rail)은 단계별로 잠금 해제되며, 항상 다음 단계를 제공하는 버튼이 있고 구현 작업이 진행되는 동안 태스크들이 완료됩니다. 액션들은 해당 단계가 확정될 때까지 잠겨 있습니다.

실행 기록이 있는 스펙은 개요(Overview)에서 열립니다. 이 스펙이 존재하는 이유, 각 단계에 걸린 시간, 결정된 사항과 각각 거부된 내용, 검증된 내용, 그리고 어떤 요구사항이 어떤 테스트로 커버되는지 알 수 있습니다. 리뷰어는 또는 나중에 접속한 사용자는 이를 읽고 질문할 필요가 없습니다. 기록을 작성하는 Companion Spec Kit 확장이 필요합니다.

스펙은 상태별로 그룹화되며, 각 문서에는 실시간 상태와 해당 스펙이 마지막으로 전송된 어시스턴트 정보가 표시됩니다. 스펙 위에 마우스를 올리면 작업을 재개할 수 있습니다. 필터링하거나, 정렬하거나, 여러 개를 한 번에 선택할 수 있습니다. 수백 개의 완료된 스펙을 가진 작업 공간도 짧은 목록으로 열립니다.

Spec Kit의 버그 흐름(bug flow)과 아이디어 평가(idea assessment)는 각각 Specs 아래에 패널이 있습니다. 버그는 '수정 필요(To fix)', '테스트 필요(To test)', '검증됨(Verified)', '종료됨(Closed)'으로 그룹화됩니다. 아이디어는 '평가 중(Assessing)'과 '결정됨(Decided)'으로 그룹화되며, 각 행에 판정이 표시됩니다. 패널에서 **+**를 누르면 새 버그(New Bug) 또는 **새 아이디어(New Idea)**를 열고 설명한 후 어시스턴트로 전송할 수 있습니다. 패널은 Spec Kit 확장이 없을 경우 설치하도록 제안합니다.

버그는 **스토리(Story)**에서 열립니다. 한 문장으로 현재 상태와 무엇이 잘못되었는지, 무엇이 변경되었는지, 그리고 어떻게 검증되었는지를 설명합니다. 페이지 하단의 버튼은 다음 단계인 버그 수정(Fix bug), 그다음 **수정 사항 테스트(Test fix)**입니다.

결정된 아이디어는 **의사 결정(Decision)**에서 열립니다. 판정, 그 이유, 그리고 점수표가 있습니다. '진행(go)' 결정으로부터 스펙을 생성할 수 있습니다.

보고서에 미해결 질문이 있는 경우, **답변(Answer)**을 클릭하고 답변을 입력하여 전송합니다. 어시스턴트가 사용자의 답변으로 보고서의 명령을 다시 실행하고, 보고서는 확정된 상태로 돌아옵니다.

가이드: 버그 수정 및 아이디어 평가.

Tasks 탭에서 **기타 작업(Other actions)**에 **GitHub 이슈 생성(Create GitHub issues)**이 있습니다. 이는 태스크당 하나의 이슈를 Spec Kit의 /speckit.taskstoissues로 전송합니다.

Companion은 이슈가 실제이기 때문에 먼저 질문합니다. 이를 위해서는 GitHub 원격 저장소와 GitHub MCP 서버가 필요합니다.

빌드가 완료된 스펙에는 푸터와 사이드바 메뉴에 수렴(Converge) 버튼이 있습니다. 이 버튼을 누르면 Spec Kit의 /speckit.converge를 전송하여 코드를 스펙과 비교하고, 아직 누락된 작업은 모두 태스크 목록에 추가합니다.

speckit.defaultWorkflow에서 워크플로우를 한 번 선택하면, 실행의 모든 단계가 그 선택을 전송합니다. Companion 파이프라인은 스펙을 60~68% 더 작게 작성하고, 임시 파일을 남기지 않으며, 변경 사항에 맞춰 크기를 조절합니다. 작은 규모는 절차를 건너뛰고, 큰 규모는 전체 specify, plan, tasks, implement 흐름을 유지합니다. 저희의 벤치마크에서는 정확도가 동률이었습니다. 수치는 워크플로우 선택 아래에 있습니다.

특징 스펙(feature spec)은 하나의 변경 사항을 설명한 후 조용해집니다. 반면 **살아있는 스펙(living spec)**은 체크아웃이나 청구와 같은 하나의 기능을 설명하며 최신 상태를 유지합니다. 사용자의 어시스턴트는 해당 영역에 기능이 닿을 때 이를 읽고, 기능이 출시될 때 업데이트됩니다. 살아있는 스펙은 한 폴더에 모으거나 해당 코드가 설명하는 코드 옆에 보관하세요.

사이드바에는 각 기능의 테스트 커버리지가 표시되며, 코드가 이동할 경우 드리프트(drift)를 알려줍니다. 뷰어는 각 요구사항을 승인하거나 제거할 수 있는 카드 형태로 보여주며, 상태 표시줄은 열려 있는 파일에 대해 몇 개의 살아있는 스펙이 설명하고 있는지 알려줍니다. 살아있는 스펙은 선택 사항입니다. 가이드: 살아있는 스펙.

**워크플로우 빌더(Workflow Builder)**는 프로젝트가 실행되는 Companion 파이프라인을 그립니다. 각 단계는 하나의 열로, 그 단계의 페이즈와 노드, 그리고 연결된 훅들을 보여줍니다. Specs 사이드바 상단의 회로 아이콘에서 열 수 있습니다.

보드를 통해 다음 작업을 수행할 수 있습니다:

어떤 단계 전후에든 자신만의 작업(기술(skill), 지침(instruction), 셸 명령어(shell command) 또는 노드(node))을 첨부할 수 있습니다. 드래그하여 노드를 재배열하거나, 하나의 노드를 다른 단계로 이동시킬 수 있습니다. 자신의 말로 노드를 다시 작성해 보세요. 업그레이드는 절대 사용자의 사본을 덮어쓰지 않습니다. 자신만의 단계를 추가하고 고유한 /speckit.companion.<name> 명령어를 사용할 수 있습니다. 결정 경로를 변경할 수도 있습니다. 각 답변이 "이 변화는 얼마나 큰가요?"를 건너뛰게 할 단계와, 어떤 경고 메시지를 먼저 표시할지 선택합니다. 살아있는 스펙(living specs)을 켜거나 끄고, 스펙이 위치할 곳을 선택하며, 등록된 기능들을 그 옆에 나열할 수 있습니다. 여러 워크플로우를 유지하고 전환할 수 있으며, 오늘 실행하는 것부터 또는 Companion이 제공하는 것부터 시작할 수 있습니다.

프로젝트가 변경한 모든 내용은 하나의 색상으로 표시되므로, 무엇이 자신 것인지 한눈에 알 수 있습니다. 변경 사항은 .specify/companion.yml에 저장되며, Build를 통해 적용됩니다. 가이드: Workflow Builder.

스톡 Spec Kit을 실행하는 프로젝트의 경우, 보드는 해당 프로젝트의 파일에서 자체 워크플로우를 그리고, Spec Kit 자체의 내용(확장 훅 스위치, 작성하는 문서 템플릿, 그리고 /speckit.constitution에 전달되는 규정)을 변경합니다.

사용자만의 프로세스입니다. 워크플로우 빌더 보드 위가 아닌 VS Code 설정에 작성된 사용자 정의 단계(Custom phases), 사용자 정의 명령어(custom commands), 사용자 정의 출력 파일(custom output files)을 사용하며, 사이드바와 뷰어 또한 이에 맞춰 조정됩니다. 사용자 정의 워크플로우

어떤 어시스턴트가 어떤 스펙을 가졌는지. Companion에서 실행하는 스펙은 해당 어시스턴트의 이름이 사이드바 행과 뷰어 헤더에 표시되며, **터미널 보기(Show Terminal)는 터미널을 전면으로 가져오며, 그 터미널이 열려 있는 동안 유지됩니다. 사이드바 참조다중 루트 작업 공간(Multi-root workspaces).**Companion은 Spec Kit 파일이 포함된 폴더를 선택하거나, speckit.projectFolder에 지정한 폴더를 사용합니다.

. 설정(Configuration) 오프라인 작동, 기본적으로 주의 필요. 글꼴과 아이콘은 확장 프로그램에 포함되어 있으며, 파괴적인 작업(destructive actions)을 수행할 때는 먼저 사용자에게 묻거나 되돌리기(undo) 옵션을 제공하고, '동작 최소화(Reduce Motion)' 설정을 준수합니다. 뷰어 참고 자료

Companion는 speckit.aiProvider에서 선택한 어시스턴트에게 각 단계를 전송합니다.

Claude Code, Oh My Pi, Gemini CLI, GitHub Copilot CLI, Codex CLI, Qwen Code, OpenCode, Wibey 또는 Antigravity를 터미널이나 에디터의 채팅 패널(Copilot, Cursor, Windsurf, Claude Code 패널)에서 사용할 수 있습니다. 각 서비스가 지원하는 기능: 지원되는 AI 제공업체.

기존 Spec Kit과 함께 작동합니다. Companion Spec Kit 확장 프로그램이 없어도 스펙은 여전히 렌더링되고, 주석도 계속 작동하며, 각 단계는 기존의 /speckit.* 명령어를 실행합니다. 다만 기록되는 내용만 적을 뿐입니다.

동일한 스펙과 동일한 실행 기록은 다른 두 곳에서도 표시됩니다. 이 두 곳 모두 VS Code 확장 프로그램이 필요하지 않습니다.

스펙 보드(spec board)는 채팅 옆에 캔버스로 열립니다. 여기에는 파이프라인과 작업을 가진 모든 스펙이 나열되며, 에이전트가 작성함에 따라 업데이트되고, 버튼을 통해 다음 단계를 실행합니다. 보드 설치하기

실행 기록의 재현(recreation)이며 속도가 빠릅니다. 이 보드가 실제이고, 주변 창은 Copilot 앱을 위한 대체 화면입니다.

SpecKit Companion 모드는 프롬프트 위 밴드와 트랜스크립트 옆 패널에 실행 상태를 표시하며, /speckit-tracker로 스펙 전환이 가능합니다. 모드 설치하기

claude plugin marketplace add https://speckit-companion.dev/plugins/marketplace.json
claude plugin install speckit-companion@speckit-companion

모든 것은 리포지토리의 일반 파일에 존재합니다: 스펙 마크다운, 그리고 각 스펙 옆의 .spec-context.json 실행 기록입니다. 뷰어와 터미널은 동일한 파일을 읽기 때문에, 한 곳에서 실행한 단계는 다른 곳에도 표시됩니다. 이 확장 프로그램은 선택된 어시스턴트에게 명령어 텍스트를 전송하고 디스크에 저장되는 내용을 읽습니다. 사용자의 프롬프트나 스펙이 저희 서버를 통과하는 일은 없습니다.

문서는 speckit-companion.dev/docs에서 확인할 수 있습니다.

시작: 설치, 첫 번째 스펙 및 Spec 기반 개발IDE 내에서: 사이드바, 뷰어 내부, 각 단계, 개요(Overview), 라이빙 스펙(living specs) 및 워크플로우 빌더(Workflow Builder)Copilot 앱에서: 보드를 설치하고 단계를 실행Claude Code에서: 모드를 설치하고 표시되는 내용참고 자료: 구성(configuration), 명령어(commands), AI 제공업체(AI providers) 및 원격 측정(telemetry)이 저장소에서: 소스 코드부터 시작하기, 아키텍처(Architecture), 기여(Contributing) 및 변경 로그(Changelog)

이 확장 프로그램은 익명화되고 PII(개인 식별 정보)가 포함되지 않은 사용량 원격 측정 데이터(제공업체 선택, 전송된 단계, 생명 주기 카운트; 프롬프트 내용, 경로 또는 이름은 절대 아님)를 전송합니다. 두 개의 스위치가 이를 제어하며, 둘 중 하나라도 꺼져 있으면 아무것도 전송되지 않습니다: speckit.telemetry

그리고 VS Code의 전역 원격 측정 수준입니다. 완전 공개: 원격 측정(Telemetry).

SpecKit Companion은 무료 오픈 소스입니다. 만약 이 프로젝트가 시간을 절약해 준다면, GitHub Sponsors를 통해 개발을 지원할 수 있습니다. 또한 Marketplace 목록에서