---
name: guide-init
description: "프로젝트를 분석하여 .harness/guide.md 가이드 문서를 생성하거나 최신 작업 내용을 반영하여 업데이트한다."
---

# Init Guide — 가이드 문서 생성/업데이트

프로젝트 구조, 코드, 최근 커밋을 분석하여 `.harness/guide.md` 가이드 문서를 생성하거나 업데이트한다.

## 사용법

```
/guide-init              # 신규 생성 또는 전체 재생성
/guide-init --update     # 최근 변경 내용을 기존 가이드에 반영
```

## 실행 흐름

### Step 0: 기존 가이드 확인

`.harness/guide.md`가 존재하는지 확인한다.

- **존재 + `--update` 플래그** → Step 2 (변경 분석)로 바로 이동
- **존재 + 플래그 없음** → 사용자에게 확인:
  ```
  기존 가이드가 있습니다. 전체 재생성하시겠습니까?
  (--update 플래그로 최근 변경만 반영할 수 있습니다)
  ```
- **없음** → Step 1 (전체 분석)부터 진행

### Step 1: 프로젝트 전체 분석 (신규 생성 시)

다음 항목을 수집한다:

1. **기술 스택**: `package.json`, `tsconfig.json`, `pyproject.toml`, `Cargo.toml` 등에서 추론
2. **디렉토리 구조**: 주요 디렉토리와 역할 파악 (depth 2~3)
3. **진입점 파악**: `main.*`, `index.*`, `app.*`, `server.*` 등
4. **모듈/레이어 구조**: 도메인, 서비스, 컨트롤러, 모델 등 레이어 식별
5. **API 구조**: 라우트 파일, 엔드포인트 목록 (존재 시)
6. **데이터 모델**: 스키마, 모델 파일 (존재 시)
7. **설정 방식**: 환경변수, config 파일 패턴
8. **테스트 구조**: 테스트 파일 위치, 테스트 러너
9. **빌드/배포**: 스크립트, CI 설정 (존재 시)

수집 명령 예시:
```bash
# 구조 파악
find . -type f -name "*.ts" | grep -v node_modules | head -50
git log --oneline -20
```

### Step 2: 변경 분석 (`--update` 시)

`.harness/guide-history.json`에서 마지막 `guide-init` 실행 날짜를 확인한다.

```bash
git log --oneline --after="{마지막 실행일}" --name-status
git diff {마지막 실행일 커밋}...HEAD --stat
```

변경 내용을 분류:
- **새로 추가된 모듈/파일** → 가이드에 추가
- **삭제된 모듈/파일** → 가이드에서 제거
- **변경된 인터페이스** → 가이드 해당 섹션 업데이트
- **리팩토링** → 구조/레이어 설명 업데이트

### Step 3: 가이드 문서 작성

`.harness/guide.md`를 생성/업데이트한다:

```markdown
# {프로젝트명} 가이드

> 생성일: YYYY-MM-DD | 마지막 업데이트: YYYY-MM-DD

## 개요

{프로젝트 목적 1-3줄}

## 기술 스택

| 항목 | 내용 |
|------|------|
| 언어 | TypeScript 5.x |
| 런타임 | Node.js 20 |
| 프레임워크 | ... |
| 데이터베이스 | ... |

## 디렉토리 구조

```
src/
  api/          # HTTP 라우트 핸들러
  services/     # 비즈니스 로직
  models/       # 데이터 모델/스키마
  utils/        # 공통 유틸리티
```

## 아키텍처

{레이어 구조, 모듈 간 의존 관계 설명}

## API 엔드포인트

| Method | Path | 설명 |
|--------|------|------|
| GET | /api/v1/... | ... |

## 데이터 모델

{주요 모델 구조}

## 환경 설정

{필요한 환경변수 목록과 설명}

## 개발 가이드

### 코딩 컨벤션

{프로젝트에서 발견된 패턴 기술}

### 테스트

{테스트 실행 방법, 테스트 파일 위치}

### 빌드 및 배포

{빌드 명령어, 배포 방식}

## 변경 이력

| 날짜 | 변경 내용 | 커밋 |
|------|----------|------|
| YYYY-MM-DD | 초기 가이드 생성 | - |
```

### Step 4: 히스토리 기록

`.harness/guide-history.json`에 실행 이력을 추가한다:

```json
{
  "entries": [
    {
      "date": "YYYY-MM-DDTHH:mm:ss",
      "action": "init",
      "commit": "abc1234",
      "note": "초기 가이드 생성"
    },
    {
      "date": "YYYY-MM-DDTHH:mm:ss",
      "action": "update",
      "commit": "def5678",
      "changed_sections": ["API 엔드포인트", "데이터 모델"],
      "note": "결제 모듈 추가 반영"
    }
  ]
}
```

### Step 5: 완료 보고

```
가이드 생성 완료: .harness/guide.md
- 섹션: 8개
- 커버된 파일: 42개
- 다음: /guide-check 로 현재 코드와 일치 여부를 확인하세요
```

## 주의사항

- 가이드는 **정적 문서가 아님** — 코드와 함께 진화해야 한다
- 추측 기반 내용은 `(추정)` 표시 후 사용자 확인 권장
- 민감한 환경변수 값은 절대 기록하지 않음 (키 이름만 기록)