# forge-harness 사용 가이드

> **이 문서는 '읽는' 문서다.** 명령을 찾으려면 `CHEATSHEET.md`, 과거 작업을 찾으려면
> `CATALOG.md`, FH 가 무엇이고 왜 작동하는지는 `README.md` 를 봐라. 여기는 **처음 쓰는 사람이
> 첫 세션을 완주하는 것**만 다룬다.

---

## 0. 먼저 — 지금 내 상태가 무엇인가

> 🗺️ FH 가 **무엇이고 · 어떻게 구현돼 있고 · 왜 믿을 만한지**를 한 장으로 먼저 보려면 [`docs/map/FH_MAP.md`](map/FH_MAP.md)
> (인터랙티브 그림: https://chrono-meta.github.io/forge-harness/). 이 가이드는 그 다음 «첫 세션 완주」다.

FH 는 세 가지 상태로 쓸 수 있고, **되는 일이 다르다.** 아래를 그대로 실행해서 확인해라.

```bash
ls CLAUDE.md knowledge/ plugins/ 2>/dev/null   # 있으면 → 클론했다 (A/B)
claude plugin list | grep fh-meta              # 있으면 → 플러그인이 깔렸다
ls tracks/ 2>/dev/null                         # 디렉토리가 있으면 → 프로젝트가 매핑돼 있다
```

| 상태 | 무엇이 되나 | 무엇이 안 되나 |
|---|---|---|
| **클론 + 플러그인** | 전부 | — |
| **클론만** | 규칙·지식·게이트(훅) | 슬래시 커맨드(`/harness-doctor` 등) |
| **플러그인만** | 스킬 호출 | `knowledge/` 정본, 세션 기록(`tracks/`), 자체 게이트 |

셋 다 아니면 `README.md` 의 설치 절을 먼저 보고 오면 된다.
확신이 안 서면 **`/install-doctor`** 를 부르면 기계가 대신 판정해준다.

---

## 1. 첫 세션 — 실제로 무엇을 타이핑하나

**'안녕' 한 마디면 된다.** 인사가 온보딩 트리거다(어느 언어든).

```
당신: 안녕
FH  : 🐿️  Welcome to FH. ① 첫 프로젝트 만들기 · ② 기존 프로젝트 매핑 …
```

문이 뜨면 **번호를 말하거나 그냥 하고 싶은 일을 문장으로 말하면 된다.** 문은 안내지 강제가 아니다.
바로 일을 시키고 싶으면 인사를 건너뛰고 작업을 말해도 된다 — 그러면 메뉴는 안 뜬다.

**문이 하는 일**

| 문 | 언제 고르나 |
|---|---|
| ① 프로젝트 매핑 | 이미 있는 레포를 FH 가 알게 한다. 여기서부터 대부분 시작한다 |
| ② 새 프로젝트 | 아직 없는 것을 처음부터 |
| ③ 가속/진단 | 매핑된 프로젝트에 대해 «개선해줘» · «진단해줘» |
| ④ 크로스 시너지 | 프로젝트가 2개 이상일 때만 뜬다 |
| 🔧 FH 자체 개발 | FH 를 고치는 사람에게만 뜬다 |
| 📖 가이드 · Q&A | 이 문서를 열거나, FH 사용법을 묻는다 |

---

## 2. 알아두면 헷갈리지 않는 것 넷

**ⓐ FH 는 '대신 해주는' 게 아니라 '틀리기 어렵게' 만든다.**
그래서 가끔 **막는다.** 커밋이 막히면 고장이 아니라 게이트가 일한 것이고, 화면에 **무엇을 하면
풀리는지**가 같이 뜬다. 그 문구를 그대로 따르면 된다.

**ⓑ '없음'과 '못 쟀음'을 구별해서 말한다.**
FH 는 확인 못 한 것을 0 으로 적지 않는다. `UNMEASURED` · `SKIPPED` · `못 쟀다` 같은 말이 보이면
**그건 실패가 아니라 정직한 공백**이다. 숫자가 안 나온 게 아니라 안 나왔다고 말하는 중이다.

**ⓒ 비가역한 일 앞에서는 반드시 멈춘다.**
공개 전환 · 삭제 · 히스토리 재작성. 되돌릴 수 있는 일(커밋 등)은 경고만 하고 넘어간다.
**이 둘의 차이가 FH 설계의 중심**이다.

**ⓓ 기록은 자동으로 쌓인다.**
`tracks/` 는 gitignored 라 공개 레포에 안 올라간다. 세션이 끝날 때 카드가 갱신되고,
다음 세션이 그걸 읽고 이어간다. '지난번에 뭐 했지'라고 물으면 거기서 찾아 답한다.

---

## 3. 자주 막히는 곳 (FAQ)

**Q. 커밋했는데 `🚫 BLOCKED` 가 뜬다.**
FH 자산(규칙·스킬·스크립트 등)을 고치면 4축 검증 마커를 요구한다. 화면에 **정확히 무엇을 어디에
쓰라고** 나온다. 우회(`--no-verify`)는 같은 훅에 있는 삭제 방지 게이트까지 같이 끄니 쓰지 마라.

**Q. 슬래시 커맨드가 안 먹는다.**
플러그인이 안 깔렸거나 옛 버전이다. `claude plugin list` 로 버전을 보고, 레포 `package.json` 의
버전과 다르면 `claude plugin update fh-meta@forge-harness` 후 재시작해라.
**등록됐다 ≠ 최신이다** — 이건 실제로 자주 난다.

**Q. 훅이 안 도는 것 같다.**
`git config core.hooksPath` 가 `templates/.git-hooks` 를 가리켜야 한다. 비어 있으면
`/install-wizard` 를 다시 돌려라(멱등이다).

**Q. 플러그인만 깔면 뭐가 없나?**
`knowledge/` 정본 · `tracks/` 세션 기록 · 이 레포 자체 게이트. 스킬은 돈다.

**Q. `tracks/` 는 왜 gitignored 인가?**
세션 기록엔 로컬 경로·프로젝트 이름 같은 개인 정보가 섞인다. 공개 레포에 안 올라가는 게 기본이고,
따로 보관하고 싶으면 개인 저장소를 붙이면 된다.

**Q. '진단해줘'와 '개선해줘'는 뭐가 다른가?**
같은 문이다(③). FH 가 기존 검사들을 모아 **M/S/R 로 등급 매긴 목록**을 주고, **자동으로 안 고친다.**
무엇을 할지는 사람이 고른다.

**Q. 토큰이 너무 든다.**
`/context-doctor` 를 불러라. 무엇이 상주 중이고 무엇을 뺄 수 있는지 진단한다.

---

## 4. 더 읽을 것

| 알고 싶은 것 | 어디 |
|---|---|
| 명령·트리거 문구 전체 | `CHEATSHEET.md` |
| FH 가 무엇이고 왜 작동하나 | `README.md` |
| 용어 | `knowledge/shared/GLOSSARY.md` |
| 예전에 무슨 작업을 했나 | `CATALOG.md` |
| 기여하기 | `docs/CONTRIBUTING.md` |

---

*이 문서가 답을 안 주면 그냥 물어봐라 — FH 는 위 문서들을 근거로 답하고, **없으면 없다고 말한다.***