specify init을 실행하면, 방금 전까지 비어 있던 폴더에 몇 가지 디렉터리와 파일이 한꺼번에 생성됩니다. "이건 무슨 파일이지?", "멋대로 생겼는데 건드려도 되나?" —— 처음에 당혹감을 느끼는 부분이 바로 이 지점입니다.

하지만 내용물의 역할만 파악하면, Spec Kit이 "AI에 대한 지시(Prompt) + 프로젝트의 규칙(Constitution) + 각종 템플릿(Template)"의 조합으로 작동하고 있다는 것을 알 수 있습니다. 이 기사에서는 생성되는 .github / .specify / .vscode 세 가지를 차례대로 살펴보며, 각각이 무엇을 담당하고 있는지 해설합니다.

• specify init이 생성하는 세 가지 디렉터리의 역할을 알 수 있음
• .github/agents와 .github/prompts의 차이점과 왜 둘 다 존재하는지 알 수 있음 - 커스텀 에이전트(Custom Agent)와 슬래시 커맨드(Slash Command)의 관계를 이해할 수 있음
• constitution / scripts / templates가 각각 무엇을 담당하는지 알 수 있음 - 어디를 수정해야 하고 어디는 건드리지 말아야 하는지 판단할 수 있음

이하의 설명은 코딩 에이전트로 **GitHub Copilot (VS Code)**를 선택했을 경우의 구성입니다. Claude Code나 Codex CLI 등 다른 에이전트를 선택한 경우에는 각각의 사양에 따라 다른 위치와 파일명으로 생성됩니다. 기본적인 사고방식(지시·규칙·템플릿)은 공통입니다.

초기화 직후의 프로젝트는 대략 다음 세 가지로 나뉩니다.

파일 트리로 나타내면, Copilot을 선택했을 경우 대체로 다음과 같은 형태가 됩니다 (포함된 커맨드나 파일명은 버전에 따라 달라질 수 있습니다).

인사관리시스템/
├── .github/
│ ├── agents/ # 선택해서 사용하는 에이전트 본체
...

각각 자세히 살펴보겠습니다.

.github 안에는 agents와 prompts라는 두 개의 폴더가 들어 있습니다. 여기가 Spec Kit 커맨드 군의 실체입니다.

agents 폴더에는 speckit.analyze.agent.md와 같이 커맨드마다 1개의 파일이 나열됩니다. 내용을 열어보면 상당히 긴 영어 프롬프트(AI에 대한 상세한 지시)가 적혀 있습니다. 이것이 "해당 커맨드로 AI에게 무엇을 시킬 것인가"를 정의하는 본체입니다.

이 파일 군은 VS Code의 Copilot 채팅에 있는 에이전트 선택 드롭다운에 추가됩니다. 표준으로는 Ask(질문)・Edit(편집)・Agent(구현)・Plan(계획)과 같은 내장 에이전트가 준비되어 있지만, 거기에 Spec Kit 유래의 에이전트가 추가되는 형태입니다 (내장된 구성은 버전에 따라 달라질 수 있습니다).

VS Code의 "커스텀 에이전트(Custom Agent)"는 이전에는 "커스텀 채팅 모드(.chatmode.md)"라고 불렸던 기능이 이름과 형식을 바꾼 것입니다. .github/agents 폴더에 둔 .agent.md 파일이 독자적인 에이전트로 인식됩니다. 이름·설명·사용 가능한 도구·MCP 서버 등을 프런트매터(Frontmatter)에 작성하여 에이전트의 동작을 정의할 수 있습니다.

한편 prompts 폴더에는 speckit.analyze.prompt.md와 같은 파일이 들어 있습니다. 이쪽은 내용이 매우 심플하며, 대부분 대응하는 agents 측의 정의(speckit.analyze)를 참조만 하는 구조로 되어 있습니다.

이것은 Copilot 채팅에서 /(슬래시)를 입력했을 때 나타나는 **슬래시 커맨드(Slash Command)**의 입구입니다. /speckit.specify와 같이 입력하면 대응하는 처리를 호출할 수 있습니다.

이 이중 구성에는 경위가 있습니다. 이전에는 에이전트를 선택하는 메커니즘이 없어서, 슬래시 커맨드(prompts)만으로 Spec Kit을 사용했습니다. 그 후, 에이전트를 선택하여 전환할 수 있는 메커니즘(agents)이 추가되었기 때문에 이 방식이 더 편리하게 사용할 수 있게 되었습니다.

다만, 기존 방식대로 슬래시 커맨드 (slash command)를 사용하고 있는 사람도 있습니다. 그래서 슬래시 커맨드를 남겨둔 채, prompts 측에서 agents를 참조함으로써, '에이전트 선택'과 '슬래시 커맨드' 중 어느 입구를 통해서라도 동일한 처리를 호출할 수 있도록 하고 있습니다.

그림과 같이 입구는 두 개라도, 최종적으로 도달하는 지시의 본체(agents 측)는 공통입니다. 따라서 어느 쪽으로 호출하든 동일하게 동작합니다.

agents와 prompts의 내용은 Spec Kit이 관리하는 부분입니다. 구조를 이해하기 위해 살펴보는 것은 유익하지만, 일반적인 개발 과정에서 이곳을 직접 수정할 필요는 거의 없습니다. 동작을 세밀하게 조정하고 싶을 때만 내용을 파악한 후 신중하게 다루는 것이 안전합니다.

.specify 안에는 memory / scripts / templates 세 가지가 들어 있습니다. 이곳은 Spec Kit이 문서 생성을 진행하기 위한 토대입니다.

memory에는 constitution.md (헌법)가 들어 있습니다. 폴더 이름이 '기억 (memory)'인 것처럼, 여기에는 프로젝트의 가장 기본이 되는 규칙이 기록되어 갑니다.

초기 상태에서는 영어로 작성된 템플릿이 들어 있습니다. 내용을 보면 Core Principles (코어 원칙)라는 항목이 있으며, 예시로 Library-First (기능은 우선 독립된 라이브러리로 만든다)와 같은 원칙이 언급되어 있습니다. 이것은 어디까지나 초안일 뿐이며, 실제로는 이후의 단계 (/speckit.constitution 실행 등)를 통해 프로젝트 고유의 비협상 규칙(non-negotiable rules)이 이곳에 기록됩니다. 이후의 계획·태스크·구현은 이 헌법에 따라 진행됩니다.

scripts에는 계획을 세우거나 태스크를 만드는 등의 공정에서 Spec Kit이 사용하는 스크립트가 들어 있습니다. Bash (.sh) 버전과 PowerShell (.ps1) 버전 모두가 준비되어 있어, OS에 따라 구분하여 사용할 수 있습니다. 이것들은 Spec Kit이 필요에 따라 자동으로 실행하므로, 기본적으로 직접 건드릴 곳은 아닙니다.

Spec Kit은 'AI가 문서를 생성하며 진행하는' 도구입니다. templates에는 그 생성물의 초안이 들어 있습니다. 예를 들어 plan-template.md는 계획 문서 템플릿, spec-template.md는 사양(specification), tasks-template.md는 태스크 목록 템플릿입니다. 각각의 Markdown이 생성될 때 대응하는 템플릿이 밑바탕이 됩니다. 이곳도 통상적으로는 신경 쓰지 않아도 괜찮습니다.

마지막은 .vscode입니다. 안에는 settings.json이 들어 있으며, 이는 VS Code 에디터 자체의 설정을 작성하는 곳입니다.

Spec Kit의 초기화 시에는 이곳에 Spec Kit의 에이전트나 커맨드를 활성화하기 위한 설정 (true 등의 값)이 병합(merge)됩니다. 덕분에 생성된 에이전트/커맨드를 자동으로 사용할 수 있는 상태가 됩니다. 이곳도 기본적으로 직접 수정할 필요는 없습니다.

specify init이 처음에 생성하는 파일군은 구현 중에 스스로 열거나 수정할 일이 거의 없는 부분입니다. '구조를 이해해 두기 위한 것'이라고 생각하면 충분합니다. 역할을 요약표로 정리합니다.

위치	역할	평소에 수정하는가?
.github/agents	에이전트 본체 (AI에 대한 지시 내용)	기본적으로 건드리지 않음
.github/prompts	슬래시 커맨드용 (agents를 참조)	기본적으로 건드리지 않음
.specify/memory/constitution.md	프로젝트 규칙 (헌법)	커맨드를 통해 업데이트됨
.specify/scripts	내부 실행 스크립트 (sh / ps1)	건드리지 않음
.specify/templates	생성 문서의 초안	건드리지 않음
.vscode/settings.json	에디터 설정 (에이전트 활성화 등)	건드리지 않음

.github는 AI에 대한 지시·커맨드, .specify는 규칙과 템플릿, .vscode는 에디터 설정, 이라고 역할을 나눌 수 있습니다. -
agents

는 에이전트 본체이며, prompts는 슬래시 커맨드 (slash command)용으로 agents를 참조하고 있다고 설명할 수 있습니다. - 슬래시 커맨드와 에이전트 선택의 "입구는 2개, 본체는 공통"이라는 관계를 이해할 수 있습니다.

constitution.md가 프로젝트의 가장 근간이 되는 토대(규칙)라는 점을 이해했습니다.

scripts와 templates는 자동으로 사용되는 부분이며, 기본적으로는 건드리지 않는다는 점을 파악했습니다. - 다른 에이전트 (Claude Code, Codex CLI 등)에서는 생성 위치가 달라질 수 있다는 점을 알고 있습니다.

구조를 이해하고 나면, Spec Kit이 "마법"이 아니라 정성스럽게 준비된 프롬프트 (prompt)와 규칙의 집합체라는 사실이 납득됩니다. 이 부분을 파악해 두면, 다음 단계에서 실제로 /speckit.* 커맨드를 실행할 때도 무엇이 일어나고 있는지 놓치지 않고 진행할 수 있습니다.