# GSD Core 업데이트 방법

기존 GSD Core 설치를 최신 릴리즈로 업데이트하고, 확정 전에 변경 로그를 미리보고, 업데이트가 덮어쓸 로컬 커스터마이징을 복구합니다.

**필요한 것:** GSD가 설치된 것과 동일한 런타임. 업데이트 명령은 내부적으로 인스톨러를 다시 실행하므로 Node.js와 npx가 필요합니다(원래 설치와 동일한 요구 사항).

---

## 표준 업데이트 경로

AI 런타임 내에서 실행합니다:

```bash
/gsd-update
```

GSD가 수행하는 작업:

1. 설치된 버전과 설치 범위(전역 또는 로컬)를 감지합니다.
2. npm에서 `@opengsd/gsd-core`의 최신 릴리즈를 확인합니다.
3. 변경 로그를 가져와 설치된 버전과 최신 버전 사이의 변경 사항을 표시합니다.
4. 아무것도 건드리기 전에 확인을 요청합니다.
5. GSD 관리 디렉터리 내에서 발견된 사용자 추가 파일을 `gsd-user-files-backup/`에 백업합니다.
6. 인스톨러를 실행합니다(`npx @opengsd/gsd-core@latest --<runtime> --<scope>`).
7. 업데이트 확인 캐시를 초기화하여 상태 표시줄 인디케이터가 재설정됩니다.
8. 로컬에서 수정된 GSD 파일이 `gsd-local-patches/`에 백업되었는지 보고합니다.

새로운 명령과 에이전트를 적용하려면 업데이트 후 런타임을 재시작하세요.

---

## 플래그

| 플래그 | 수행하는 작업 |
|------|--------------|
| `--sync` | 업데이트 후 GSD 레지스트리에서 스킬 동기화 |
| `--reapply` | 업데이트 후 `gsd-local-patches/`에서 로컬에서 수정된 GSD 파일 다시 병합 |

```bash
/gsd-update --sync        # 업데이트 및 스킬 동기화
/gsd-update --reapply     # 업데이트 및 로컬 패치 재적용
```

---

## 업데이트 전 변경 로그 검토

`/gsd-update`는 확인을 요청하기 *전에* 항상 설치된 버전과 최신 버전 사이의 변경 로그 diff를 표시합니다. GitHub를 별도로 방문할 필요가 없습니다. 출력은 다음과 같습니다:

```text
## GSD Update Available

Installed: 1.39.0
Latest:    1.41.0

### What's New
────────────────────────────────────────────────────────────
[changelog entries for 1.40.0 and 1.41.0]
────────────────────────────────────────────────────────────

Proceed with update? [Yes, update now / No, cancel]
```

변경 로그를 가져올 수 없는 경우(네트워크 접근 없음, npm 중단), 업데이트는 여전히 확인 후 진행됩니다 — 변경 로그 가용성에 의존하지 않습니다.

---

## 로컬 커스터마이징 복구

### GSD 관리 디렉터리에 추가한 파일

GSD가 소유하는 디렉터리 내에 커스텀 파일을 배치한 경우(예: `gsd-` 접두사가 붙은 커스텀 에이전트 또는 `commands/gsd/`에 있는 추가 파일), 인스톨러가 이를 감지하고 해당 디렉터리를 지우기 전에 `gsd-user-files-backup/`에 복사합니다. 업데이트 후 해당 백업 위치에서 수동으로 복원합니다.

GSD 관리 디렉터리 외부에 배치한 파일 — `gsd-` 접두사 없는 커스텀 에이전트, `commands/gsd/` 외부의 커스텀 명령, `CLAUDE.md` 파일, 커스텀 훅 — 은 인스톨러가 절대 건드리지 않습니다.

### 직접 수정한 GSD 파일

GSD가 설치한 파일을 편집한 경우(예: 에이전트의 시스템 프롬프트 수정), 인스톨러는 매니페스트에 대한 해시 비교를 통해 수정을 감지하고 파일을 `gsd-local-patches/`에 백업한 후 새 버전으로 교체합니다. 업데이트 후:

```bash
/gsd-update --reapply
```

이 명령은 새로 설치된 파일에 `gsd-local-patches/`의 수정 사항을 병합합니다.

이전 업데이트 후 `--reapply`를 건너뛰었고 지금 패치를 적용하고 싶다면:

```bash
/gsd-update --reapply
```

이미 최신 버전이면 GSD는 설치 단계를 건너뛰고 바로 패치 재적용으로 진행합니다 — 새 다운로드를 트리거하지 않고도 `--reapply`를 단독으로 실행하는 것이 안전합니다.

---

## npm을 사용할 수 없을 때

npm 중단, 네트워크 제한, 또는 소스 저장소에서 작업 중이어서 `npx @opengsd/gsd-core@latest`가 실패하는 경우 [docs/manual-update.md](../../manual-update.md)의 수동 업데이트 절차를 사용하세요. 해당 문서는 최신 커밋 풀링, hooks dist 빌드, `node bin/install.js` 직접 실행을 다룹니다.

---

## 이미 최신 버전인 경우

`/gsd-update`는 확인 메시지와 함께 조기 종료합니다 — 다운로드 없음, 설치 없음, 재시작 불필요.

---

## 인스톨러 마이그레이션

각 GSD 릴리즈에는 관리 파일을 이름 변경, 이동, 또는 폐기하는 인스톨러 마이그레이션이 포함될 수 있습니다. 마이그레이션 레이어는 새 패키지 페이로드가 작성되기 전에 자동으로 실행됩니다. 수정한 파일에 영향을 주는 마이그레이션은 자동으로 처리되지 않고 확인을 요청합니다. 전체 설계와 런타임 구성 계약 레지스트리는 [docs/installer-migrations.md](../../installer-migrations.md)를 참조하세요.

---

## 관련 문서

- [런타임에 설치](install-on-your-runtime.md)
- [명령 참조](../COMMANDS.md)
- [수동 업데이트](../../manual-update.md)
- [인스톨러 마이그레이션](../../installer-migrations.md)
- [문서 인덱스](../README.md)