# 빠른 시작

> 워크스페이스를 만들고 GitHub 저장소를 연결해 첫 개발문서를 생성하는 과정을 안내합니다.

이 가이드는 워크스페이스를 만들고 GitHub 저장소를 연결해 첫 개발문서를 생성하기까지의 과정을 다룹니다. 끝까지 따라오면 코드를 근거로 만든 문서 한 편과, 이후 코드 변경을 수정안으로 받을 준비가 된 문서 프로젝트가 생깁니다.

## 준비물

- 문서화할 코드가 있는 **GitHub 저장소** — 개인 저장소 또는 조직 저장소
- 조직 저장소라면 **GitHub 조직 관리자의 승인**을 받을 수 있는 상태
- 워크스페이스에서 문서 프로젝트를 만들 수 있는 **편집자 이상 권한** (처음 워크스페이스를 만든 사람은 소유자입니다)
- **프로·맥스·팀·엔터프라이즈** 플랜 — 문서 프로젝트는 유료 플랜 기능입니다. 프로·팀 플랜은 14일 무료 체험으로 시작할 수 있습니다.

<Note>
  무료 플랜에서도 문서 작성, AI 채팅, [워크스페이스 RAG](/ko/knowledge/rag)는 사용할 수 있습니다. 먼저 둘러보고 싶다면 [화면 둘러보기](/ko/workspace/tour)부터 시작하세요.
</Note>

## 첫 문서 만들기

<Steps>
  <Step title="가입하고 워크스페이스 만들기">
    [specify.app](https://specify.app/ko)에서 가입한 뒤 워크스페이스를 만듭니다. 무료 플랜은 신용카드 없이 시작할 수 있고, 문서 프로젝트를 쓰려면 프로 이상 플랜으로 바꿉니다([요금제](/ko/resources/plans) 참고).
  </Step>
  <Step title="프로젝트 만들기 열기">
    사이드바의 **신규(+)** 버튼을 누르고 **프로젝트 만들기**를 선택합니다. 가운데에 **문서 프로젝트 설정** 탭이 열립니다.

    <Screenshot name="new-menu" alt="사이드바 신규 메뉴에 프로젝트 만들기, 새 문서, 새 채팅, 외부 노드 추가가 표시된 화면" />
  </Step>
  <Step title="GitHub 연결하기">
    소스 단계의 **GitHub 연결**을 누르고, Specify가 읽을 GitHub 계정과 저장소 접근을 허용합니다.

    <Screenshot name="project-wizard-source" alt="문서 프로젝트 만들기의 소스 단계에 GitHub 연결 버튼이 있는 화면" />

    조직 저장소는 GitHub 조직 관리자가 요청을 승인한 뒤에 연결됩니다. 승인이 끝나면 같은 화면에서 다시 연결을 눌러 완료하세요. 자세한 내용은 [GitHub 연결](/ko/guides/github)을 참고하세요.
  </Step>
  <Step title="소스 선택하기">
    **GitHub 계정**을 고르고 문서화할 **저장소**와 **브랜치**를 선택한 뒤 **다음**을 누릅니다. 이 저장소와 브랜치가 이후 모든 문서와 수정안의 근거가 됩니다.
  </Step>
  <Step title="문서 종류 선택하기">
    **문서** 단계에서 에이전트가 먼저 만들 문서 스킬을 선택합니다. 이번 생성에서 강조할 점이 있다면 **이번 생성에서 강조할 점 (선택)**에 문서를 읽을 대상, 강조할 내용, 원하는 상세 수준을 적어 주세요. 예를 들어 "배포 절차를 중심으로"처럼 적을 수 있습니다.
  </Step>
  <Step title="갱신 방식 정하기">
    같은 단계에서 **저장소 변경을 자동으로 반영**을 켜면 선택한 브랜치에 코드가 반영될 때 문서 수정안을 준비합니다. 매번 문서 전체를 다시 생성하는 스킬은 자동 갱신을 지원하지 않으며, 필요할 때 다시 생성합니다.
  </Step>
  <Step title="첫 문서 생성 확인하기">
    **문서 N종 만들기**를 누르면 문서 에이전트가 선택한 문서를 작성합니다. 이 화면을 닫아도 괜찮습니다. **인박스**가 생성 작업을 계속 추적하며 완료, 실패, 다시 시도 옵션을 보여 줍니다.
  </Step>
</Steps>

<Tip>
  처음에는 문서 하나로 시작해 보세요. 생성된 문서를 팀과 함께 검토한 뒤, 같은 프로젝트 폴더에 다른 가이드나 레퍼런스를 추가로 생성할 수 있습니다.
</Tip>

## 생성이 끝나면

생성된 페이지에는 소스 링크가 남아, 이후 저장소 변경을 정확한 근거와 함께 검토할 수 있습니다. 다음 단계로 이어가 보세요.

<CardGroup cols={2}>
  <Card icon="workflow" title="수정안 검토와 반영" href="/ko/guides/review-proposals">코드가 바뀌었을 때 도착하는 수정안을 검토하는 방법입니다.</Card>
  <Card icon="users" title="팀 초대와 권한" href="/ko/workspace/members">팀원을 초대하고 역할을 정합니다.</Card>
  <Card icon="terminal" title="코딩 에이전트 연결" href="/ko/mcp/connect">Claude Code·Codex에서 워크스페이스 문서를 참고하게 합니다.</Card>
  <Card icon="message" title="AI에게 질문하기" href="/ko/guides/ask-ai">생성된 문서와 코드 맥락을 근거로 질문합니다.</Card>
</CardGroup>

## 문제 해결

| 증상 | 확인할 점 |
| --- | --- |
| 저장소 목록이 비어 있음 | 선택한 GitHub 계정에 Specify 접근이 허용된 저장소가 있는지 확인합니다. 조직 저장소는 조직 관리자 승인이 필요합니다. |
| 무료 플랜에서 문서 생성이 시작되지 않음 | 문서 프로젝트는 프로 이상 플랜에서 사용할 수 있습니다. [요금제](/ko/resources/plans)를 확인하세요. |
| 문서 프로젝트를 만들 수 없음 | 뷰어 권한으로는 만들 수 없습니다. 편집 권한이 있는 멤버에게 요청하세요. 워크스페이스 쓰기가 잠겨 있다면 구독 상태를 확인하세요. |
| 생성이 오래 걸림 | 화면을 닫아도 인박스가 작업을 추적합니다. 완료되면 인박스에서 결과를 확인할 수 있습니다. |
| 생성 확인이 필요하다고 표시됨 | 프로젝트는 저장되어 있습니다. 표시된 사유를 확인한 뒤 다시 시도하거나 소스를 변경하세요. |