guide-init

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 설정 (존재 시)

수집 명령 예시:

# 구조 파악
find . -type f -name "*.ts" | grep -v node_modules | head -50
git log --oneline -20

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

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

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

변경 내용을 분류:

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

Step 3: 가이드 문서 작성

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

# {프로젝트명} 가이드

> 생성일: 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에 실행 이력을 추가한다:

{
  "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 로 현재 코드와 일치 여부를 확인하세요

주의사항

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