forge-harness 사용 가이드

September 5, 2026 · View on GitHub

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

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

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

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

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 는 위 문서들을 근거로 답하고, 없으면 없다고 말한다.