guide-fix

Guide Fix — 가이드 불일치 수정

/guide-check로 생성된 check 결과의 불일치 항목을 .harness/guide.md에 반영하고 수정 기록을 저장한다.

사용법

/guide-fix                                               # 가장 최근 check 결과 사용
/guide-fix .harness/guide/checks/20260410_143022-check.json  # 특정 check 결과 지정

실행 흐름

Step 0: Check 결과 로드

1. 인자 있음 → 지정된 JSON 파일을 Read
2. 인자 없음 → .harness/guide/checks/ 디렉토리에서 가장 최근 *-check.json 자동 탐지
3. JSON이 없으면 안내 후 중단:

   Check 결과를 찾을 수 없습니다.
   먼저 /guide-check 를 실행하세요.
   

Step 1: 수정 계획 수립

auto_fixable 항목만 필터링하여 수정 계획을 사용자에게 보여준다:

## 수정 계획

| ID | 섹션 | 내용 | 심각도 |
|----|------|------|--------|
| GC-001 | API 엔드포인트 | POST /api/v1/payments 추가 | Major |
| GC-002 | 데이터 모델 | Order.payment_method 필드 추가 | Minor |
| GC-003 | 디렉토리 구조 | src/integrations/ 추가 | Minor |

총 3건 수정 예정. 진행할까요?

수동 확인 필요 항목 (이번에 수정하지 않음):
- GC-004: 기술 스택 — stripe 의존성 목적 확인 필요 (수동)

사용자 확인 후 진행한다.

Step 2: 섹션별 가이드 업데이트

각 issue의 section에 따라 .harness/guide.md의 해당 섹션을 수정한다:

api_endpoints — API 엔드포인트 섹션 수정

• missing_in_guide: 코드에서 실제 엔드포인트 정보를 읽어 표에 행 추가
• removed_from_code: 해당 행 삭제 (또는 [삭제됨] 표시)
• path_changed: 경로 업데이트

data_models — 데이터 모델 섹션 수정

• field_mismatch: 실제 타입/스키마 파일을 읽어 모델 설명 업데이트
• model_added: 새 모델 섹션 추가
• model_removed: 모델 섹션 삭제 또는 [삭제됨] 표시

directory_structure — 디렉토리 구조 섹션 수정

• 실제 디렉토리 목록 반영

tech_stack — 기술 스택 섹션 수정

• package.json 재읽어 버전/의존성 업데이트

env_config — 환경 설정 섹션 수정

• 코드에서 추출된 환경변수 목록 반영

수정 시 가이드 하단 변경 이력 표에 항목을 추가한다:

| YYYY-MM-DD | guide-fix: GC-001, GC-002, GC-003 반영 | def5678 |

Step 3: 결과 저장

.harness/guide/fixes/{YYYYMMDD_HHmmss}-fix.json과 .harness/guide/fixes/{YYYYMMDD_HHmmss}-fix.md를 저장한다.

JSON 형식:

{
  "metadata": {
    "date": "YYYY-MM-DDTHH:mm:ss",
    "source_check": "YYYYMMDD_HHmmss-check.json",
    "total_issues": 4,
    "fixed": 3,
    "skipped": 1
  },
  "results": [
    {"id": "GC-001", "status": "fixed", "section": "api_endpoints", "description": "POST /api/v1/payments 추가"},
    {"id": "GC-002", "status": "fixed", "section": "data_models",   "description": "Order.payment_method 추가"},
    {"id": "GC-003", "status": "fixed", "section": "directory_structure", "description": "src/integrations/ 추가"},
    {"id": "GC-004", "status": "skipped", "reason": "manual_required", "description": "stripe 의존성 목적 확인 필요"}
  ]
}

Step 4: 히스토리 갱신

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

{
  "date": "YYYY-MM-DDTHH:mm:ss",
  "action": "fix",
  "commit": "def5678",
  "source_check": "YYYYMMDD_HHmmss-check.json",
  "result_file": "YYYYMMDD_HHmmss-fix.json",
  "fixed": 3,
  "skipped": 1
}

Step 5: 완료 보고

## Guide Fix 완료

### 수정 결과
| ID | 섹션 | 내용 | 결과 |
|----|------|------|------|
| GC-001 | API 엔드포인트 | POST /api/v1/payments 추가 | 수정 완료 |
| GC-002 | 데이터 모델 | Order.payment_method 추가 | 수정 완료 |
| GC-003 | 디렉토리 구조 | src/integrations/ 추가 | 수정 완료 |
| GC-004 | 기술 스택 | stripe 의존성 | 스킵 (수동 확인 필요) |

### 요약
- 수정 완료: 3건
- 스킵: 1건

저장:
- .harness/guide/fixes/YYYYMMDD_HHmmss-fix.md
- .harness/guide/fixes/YYYYMMDD_HHmmss-fix.json
- .harness/guide.md 업데이트됨

수동 확인 필요 항목:
- GC-004: stripe 의존성 추가 목적을 확인하고 기술 스택 섹션에 직접 추가하세요

안전 장치

1. 수정 전 사용자 확인 필수 — 수정 계획을 보여주고 승인 후 진행
2. auto_fixable만 수정 — manual_required 항목은 절대 건드리지 않음
3. 가이드만 수정 — 실제 소스 코드는 절대 변경하지 않음
4. 실패 시 안내 — git checkout -- .harness/guide.md로 복구 가능함을 안내