Release Setup v5.3.0 · SukbeomH/HExoskeleton

Quick Start

에이전트에게 아래 프롬프트를 복사하여 전달하면 프로젝트에 HXSK를 자동 구성합니다.
모든 에이전트(Claude Code, Gemini, Copilot, Cursor, Windsurf)를 하나의 프롬프트로 지원합니다.

Changes in v5.3.0

신규

Iron Laws 3개 — AGENTS.md에 비타협 규칙 (NO EDIT w/o READ, NO CLAIM w/o VERIFY, NO WRITE to exist)
합리화 테이블 12항목 — empirical-validation 스킬에 허위 완료/Read 건너뛰기/작업 중단 차단
Gate Function 5단계 — IDENTIFY→RUN→READ→VERIFY→CLAIM 완료 검증 게이트
Thinking Budget — 깊은 추론 필요 상황 트리거 (CLAUDE.md + empirical-validation)
read-before-edit.py — PreToolUse 훅, Read 없이 Edit 차단 (Iron Law 인프라 강제)
track-read-history.py — PostToolUse 훅, Read 이력 기록
write-guard.py — PreToolUse 훅, 기존 파일 Write 차단
spec-reviewer 에이전트 — 스펙 준수 리뷰 (2단계 리뷰 Step 1)
DESIGN-PHILOSOPHY.md — 9가지 설계 원칙, 작성 규칙, 연구 근거, 방향성

개선

15개 SKILL.md description CSO 최적화 — 트리거 조건만 기재 (SkillReducer 2026 기반)
post-turn-verify.sh — 완료 키워드 감지 시 검증 명령 이력 확인 게이트 추가
4개 핵심 스킬에 Cross-skill 의존성 마커 추가 (REQUIRED/RECOMMENDED)
2개 스킬에 보조 문서 추가 (anti-patterns.md, root-cause-tracing.md)
session-start.sh — read-history.log 초기화 추가
skill-testing 스킬 — RED→GREEN→REFACTOR 사이클, 압박 시나리오 4유형, 메타 테스트
subagent-implementer.md / subagent-reviewer.md — 서브에이전트 프롬프트 템플릿 표준화
collect-rationalization.sh — Stop 훅, 합리화 시그널 15패턴 + Iron Law 위반 자동 수집
rationalization-update-guide.md — 합리화 테이블 갱신 프로세스 가이드
pre-pr-check.sh — GITHUB_HEAD_REF로 PR 소스 브랜치 정확 감지 (오탐 수정)

수정

check-consistency.sh — dead component 탐지 grep exit code + wc 멀티라인 처리

연구

superpowers-analysis.md — Superpowers 플러그인 14개 스킬, 10가지 패턴 분석
superpowers-references.md — 7패턴 × 20개 학술/산업 출처

setup.md

아래 코드 블럭을 복사하여 에이전트에게 전달하세요.

setup.md 전체 내용 (클릭하여 펼치기)

# HXSK Setup

아래 지침에 따라 현재 프로젝트에 HExoskeleton(HXSK) 개발 방법론을 구성하세요.

## Step 0: 상태 감지

```bash
test -f .hxsk/.bootstrap-version && echo "UPDATE" || echo "FRESH"
```

- **FRESH** → 아래 "초기 설치" (Step 1~8)
- **UPDATE** → 아래 "업데이트"

---

## 초기 설치

### Step 1: 진입점 읽기

이 레포의 `llms.txt`를 읽어 사용 가능한 리소스 목록을 파악하세요.

### Step 2: 에이전트 지침 설정

당신의 에이전트 유형에 맞는 지침 파일을 프로젝트 루트에 저장하세요:

| 에이전트 | 파일 |
|----------|------|
| Claude Code | `CLAUDE.md` |
| Gemini CLI | `GEMINI.md` |
| 기타 (Copilot, Cursor, Windsurf 등) | `AGENTS.md` |

### Step 3: HXSK 문서 구조 생성

`.hxsk/` 디렉토리를 만들고 working docs를 생성하세요:

```
.hxsk/
├── SPEC.md       ← 프로젝트 명세 (필수)
├── STATE.md      ← 현재 상태 (필수)
├── PATTERNS.md   ← 학습된 패턴 (필수)
├── DECISIONS.md  ← 아키텍처 결정 기록
├── templates/    ← 문서 템플릿 (llms.txt에서 fetch)
└── examples/     ← 사용 예시
```

### Step 4: 스킬 및 에이전트 설치

`.hxsk/skills/INDEX.md`를 참조하여 스킬을, `.hxsk/agents/INDEX.md`를 참조하여 에이전트를 가져오세요.

**필수 스킬** (반드시 설치):

| 스킬 | 용도 |
|------|------|
| `bootstrap` | 프로젝트 초기화 + 업데이트 감지 |
| `planner` | SPEC 기반 실행 계획 수립 |
| `executor` | 계획 실행 (atomic commits) |
| `verifier` | 경험적 증거 기반 검증 |
| `memory-protocol` | 메모리 저장/검색 프로토콜 |

**Claude Code 설치 방법:**
```bash
# 스킬: .hxsk/skills/ → .claude/skills/ (심볼릭 링크 — 원본 수정 시 자동 반영)
mkdir -p .claude/skills
for skill_dir in .hxsk/skills/*/; do
    skill_name=$(basename "$skill_dir")
    ln -sfn "../../.hxsk/skills/$skill_name" ".claude/skills/$skill_name"
done

# 에이전트: .hxsk/agents/*.md → .claude/agents/ (INDEX.md 제외)
mkdir -p .claude/agents
for agent in .hxsk/agents/*.md; do
    [[ "$(basename "$agent")" == "INDEX.md" ]] && continue
    ln -sf "../../.hxsk/agents/$(basename "$agent")" ".claude/agents/$(basename "$agent")"
done
```

> 심볼릭 링크를 사용하므로 `.hxsk/`의 스킬/에이전트 수정이 `.claude/`에 즉시 반영됩니다.
> 모든 스킬이 `/skill-name` 슬래시 커맨드로 자동 등록됩니다.

**Gemini CLI** → `.agent/skills/{name}/SKILL.md`, `.agent/agents/{name}.md`에 배치
**기타** → 에이전트 문서에 따라 배치

> **주의**: `.hxsk/.bootstrap-version` 파일을 직접 생성하지 마세요. `bootstrap.sh`가 자동 생성합니다.

### Step 5: 에이전트별 자동 로드 경로 연결

`AGENTS.md`를 각 에이전트의 자동 로드 경로에 심볼릭 링크로 연결하세요:

```bash
# GitHub Copilot
mkdir -p .github
ln -sf ../AGENTS.md .github/copilot-instructions.md

# Cursor
ln -sf AGENTS.md .cursorrules

# Windsurf
ln -sf AGENTS.md .windsurfrules
```

### Step 6: 훅 설치 (Claude Code만)

> Claude Code가 아닌 에이전트는 이 단계를 건너뛰세요. AGENTS.md의 Agent Boundaries 규칙으로 대체됩니다.

`.hxsk/hooks/INDEX.md`에서 훅 스크립트를 가져와 `.claude/settings.json`에 등록:

```json
{
  "hooks": {
    "SessionStart": [
      {"matcher": "startup|resume", "hooks": [{"type": "command", "command": ".hxsk/hooks/session-start.sh", "timeout": 10}]}
    ],
    "PreToolUse": [
      {"matcher": "Edit|Write|Read", "hooks": [{"type": "command", "command": ".hxsk/hooks/file-protect.py", "timeout": 5}]},
      {"matcher": "Bash", "hooks": [{"type": "command", "command": ".hxsk/hooks/bash-guard.py", "timeout": 5}]}
    ],
    "PostToolUse": [
      {"matcher": "Edit|Write", "hooks": [
        {"type": "command", "command": ".hxsk/hooks/auto-format.sh", "timeout": 30},
        {"type": "command", "command": ".hxsk/hooks/track-modifications.sh", "timeout": 2}
      ]},
      {"matcher": "Bash", "hooks": [{"type": "command", "command": ".hxsk/hooks/track-modifications.sh", "timeout": 2}]}
    ],
    "PreCompact": [
      {"matcher": "auto|manual", "hooks": [{"type": "command", "command": ".hxsk/hooks/pre-compact-save.sh", "timeout": 10}]}
    ],
    "Stop": [
      {"hooks": [
        {"type": "command", "command": ".hxsk/hooks/post-turn-verify.sh", "timeout": 15},
        {"type": "command", "command": ".hxsk/hooks/stop-context-save.sh", "timeout": 10}
      ]}
    ],
    "SubagentStop": [
      {"hooks": [{"type": "prompt", "prompt": "## SubagentStop\n- 핵심 결과 2-3문장 요약\n- 코드 변경 시: `touch .hxsk/.modified-this-session`\n- 재사용 패턴 발견 시: PATTERNS.md에 추가 검토\n- 스킬 본문을 결과에 복제하지 말 것"}]}
    ],
    "SessionEnd": [
      {"hooks": [
        {"type": "command", "command": ".hxsk/hooks/save-transcript.sh", "timeout": 10},
        {"type": "command", "command": ".hxsk/hooks/save-session-changes.sh", "timeout": 10}
      ]}
    ]
  }
}
```

### Step 7: 메모리 시스템 확인 (Claude Code만)

> Claude Code가 아닌 에이전트는 이 단계를 건너뛰세요.

```bash
# 메모리 저장
bash .hxsk/hooks/md-store-memory.sh "제목" "내용" "태그" "타입"

# 메모리 검색
bash .hxsk/hooks/md-recall-memory.sh "검색어" "." 5 compact
```

### Step 8: README에 뱃지 추가 (선택)

```markdown
[![HExoskeleton](https://img.shields.io/badge/assisted%20with-HExoskeleton-blueviolet?style=flat-square)](https://github.com/SukbeomH/HExoskeleton)
```

### 완료 확인

- [ ] 에이전트 지침 파일이 프로젝트 루트에 존재
- [ ] `.hxsk/` 디렉토리에 SPEC.md, STATE.md, PATTERNS.md 존재
- [ ] SPEC.md에 프로젝트 실제 내용 반영 (플레이스홀더 `{...}` 가 남아있으면 안 됨)
- [ ] 필수 스킬 5개가 에이전트 설정 디렉토리에 배치됨 (bootstrap, planner, executor, verifier, memory-protocol)
- [ ] 에이전트 정의 파일이 에이전트 설정 디렉토리에 배치됨
- [ ] (선택) 에이전트별 심볼릭 링크 생성됨
- [ ] (Claude Code) 훅 **8개 이벤트** 모두 `.claude/settings.json`에 등록됨 (SessionStart, PreToolUse, PostToolUse, PreCompact, Stop, SubagentStop, SessionEnd)
- [ ] (Claude Code) 메모리 명령어 동작 확인

### 초기 설치 후 다음 단계

```
/bootstrap    # 프로젝트 분석 및 메모리 초기화 (← .bootstrap-version 자동 생성)
/planner      # SPEC 기반 실행 계획 수립
```

---

## 업데이트

이전 설치가 감지되었습니다.

### Step 1: bootstrap 실행

```bash
bash .hxsk/scripts/bootstrap.sh
```

출력 태그:
- `[OK]` — 변경 없음
- `[NEW]` — 새로 추가됨
- `[UPDATED]` — 변경됨 (↳ 관련: 2-hop 컨텍스트 표시)

### Step 2: 에이전트별 설정 갱신

`[NEW]` 또는 `[UPDATED]`가 있는 경우:
- 스킬 추가/변경 → 에이전트 스킬 디렉토리 갱신
- 에이전트 지침 변경 → CLAUDE.md/GEMINI.md/AGENTS.md 갱신

**Claude Code인 경우 추가로:**
- 훅 변경 → `.claude/settings.json` 갱신
- 스킬 변경 → `.claude/skills/{name}/SKILL.md` 복사

### Step 3: 확인

```bash
bash .hxsk/scripts/bootstrap.sh
```

모든 항목이 `[OK]`이면 업데이트 완료.

첨부 파일

파일	설명
`setup.md`	통합 setup 프롬프트 (모든 에이전트 지원)
`AGENTS.md`	공통 에이전트 지침
`CLAUDE.md`	Claude Code 지침
`GEMINI.md`	Gemini CLI 지침
`llms.txt`	LLM 진입점 (리소스 목록)

v5.3.0 · 초기 설치/업데이트를 자동 감지합니다.

Navigation Menu

Repository navigation

Setup v5.3.0

Choose a tag to compare

Sorry, something went wrong.

Sorry, something went wrong.

Uh oh!

No results found

Quick Start

Changes in v5.3.0

신규

개선

수정

연구

setup.md

첨부 파일

Uh oh!