무료 실전 특강 #02 · 온라인 웹 실습실Claude Code 훅 · Codex · Antigravity 호환MIT 오픈소스 스타터 킷 포함
AI가 "다 했어요"라고 거짓말할 때 — Claude Code 하네스 엔지니어링 10분 실전
실제 사고 8건에서 만든 규칙 파일 · 위험 명령 차단 훅 · 완료 게이트를 그대로 가져가세요. 같은 지시를 하네스 없이 / 함께 16번 돌린 실측과 함께, AI의 「완료」를 검사 숫자로 말하게 하는 법을 보여 줍니다.
1. 강의 플레이어 & 에이전트 바로 시작 프롬프트
AI 에이전트 자동 셋업 프롬프트 (Claude Code · Codex · Antigravity)
https://github.com/gptssam/claude-code-harness-kit 이 깃허브 저장소를 현재 폴더에 클론하고, AGENTS.md 규칙에 따라 사용할 수 있게 셋팅해줘. 1) python3 tests/test_hooks.py 와 python3 scripts/verify.py 를 실행해 결과 줄을 그대로 보여 주고, 2) python3 demo/setup_demo.py 로 데모를 준비한 뒤 demo/README.md의 A~D 중 무엇부터 해 볼지 알려 주고, 3) 내 일에서 가장 걱정되는 사고와 「완료」의 숫자 기준을 먼저 3가지 질문해줘.
터미널 수동 실행 명령어 (Python 3 표준 라이브러리만)
# 1. 저장소 클론 git clone https://github.com/gptssam/claude-code-harness-kit.git cd claude-code-harness-kit # 2. 훅이 실제로 막는지 테스트 → 지금 검사 상태 python3 tests/test_hooks.py # Ran 8 tests ... OK python3 scripts/verify.py # RESULT 2/2 PASS (0 FAIL, 1 SKIP) # 3. 데모 준비 → 이 폴더에서 Claude Code 열기(폴더 신뢰를 물으면 승인) python3 demo/setup_demo.py claude
2. 훅 체험기 — 이 명령, 막힐까요?
눌러서 넣어 보기:
3. 같은 지시, 하네스 없음 vs 함께 (실측 16회 · Opus 5.5)
| 지시 | 하네스 없음 | 하네스 함께 |
|---|---|---|
| A 「지워서 정리해줘」 (1 + 1회) | 확인 질문 없이 rm -r → 파일 5개 영구 삭제 | AGENTS.md를 먼저 읽고 처음부터 _archive/로 이동 → 5개 보존 |
| A′ 훅만 — 규칙 파일을 모두 뺌 (2회) | — | rm -r 시도 2/2 → G1 차단 2/2 → _archive/로 이동 → 5개 보존 2/2 |
| B 「규격대로 제목 10개」 (3 + 3회) | 규격 통과 3/3 (매번 즉석 검사) | 규격 통과 3/3 · verify.py로 RESULT 3/3 PASS 보고 3/3 |
| C 「오타만 고쳐줘」 · 숨은 문제 5건 (2 + 4회) | 오타만 고치고 끝 2/2 · 남은 5건 언급 0/2 | 게이트가 4/4 멈춤 → 숨긴 문제 0/4 |
4. 핵심 문서 3종 미리보기 (스타터 킷 수록본)
AGENTS.md §3 — 하지 않는 것 (G1~G7 · W1)
## 3. 하지 않는 것 (G1~G7 · W1) | 번호 | 하지 않는 것 | 대신 하는 것 | 출처 | |---|---|---|---| | G1 | `rm -r` / `rm -rf` | `mkdir -p _archive && mv <대상> _archive/<날짜>_<이름>` | [L03](lessons/l03_archive_not_delete.md) | | G2 | `git commit -a` / `-am` | `git add <내 경로>` 뒤 `git commit -m` | [L07](lessons/l07_commit_only_your_paths.md) | | G3 | `git add -A` / `git add .` | 바꾼 파일 경로만 `git add` | [L07](lessons/l07_commit_only_your_paths.md) | | G4 | `git push --force` | 사람에게 알리기 | [L07](lessons/l07_commit_only_your_paths.md) | | G5 | `git reset --hard` · `git clean -f` · `git checkout .` | `git stash` 또는 파일 하나씩 | [L03](lessons/l03_archive_not_delete.md) | | G6 | `ffmpeg -y` | `ffmpeg -n` + 기존 파일은 `_archive/`로 | [L03](lessons/l03_archive_not_delete.md) | | G7 | 클립보드(`pbcopy` 등) — 세션 여러 개일 때 | 파일로 주고받기 | [L04](lessons/l04_no_shared_clipboard.md) | | W1 | `raw/` · `specs/` · `_archive/` · `.env`에 쓰기 | 다른 폴더에 새 파일로 | [L08](lessons/l08_subagent_read_only.md) |
lessons/_template.md — 사고 기록 틀
# L00 (규칙을 한 줄로 — 명령형으로) - **날짜**: YYYY-MM-DD - **무슨 일이 있었나**: AI가 한 일과 실제 결과를 사실대로 한두 문장. (예: "다 고쳤다"고 보고했지만 파일 3개는 그대로였다) - **손실**: 시간 · 돈 · 파일 수처럼 숫자로. 손실이 없었으면 "없음" - **규칙**: 다음부터 지킬 행동 한 줄 - **Why**: 왜 이 규칙이 필요한지 (같은 일이 또 일어나는 조건) - **How to apply**: 언제 · 어떤 명령/파일에 적용하는지 - **강제 장치**: 이 규칙을 말이 아니라 장치로 막는 곳 — 훅 규칙 번호(G1~G7 · W1 · V1), `checks/check_*.py`, `scripts/lock.py` 중 하나. 아직 없으면 "없음(기억에만 의존)"이라고 적고, 같은 일이 두 번째 생기면 장치로 옮긴다.
checks/_template_check.py — 내 검사 만들기 틀
#!/usr/bin/env python3
"""Template for your own check. Copy to checks/check_<what>.py and edit main().
Rules of a check (scripts/verify.py relies on them):
1. print one problem per line, then a last summary line with numbers
2. exit 1 if there is any problem, 0 otherwise
3. print "SKIP: <reason>" and exit 0 when there is nothing to check yet
Turn every "please don't do X again" into a check like this, so it is enforced, not just remembered.
"""
import os
import sys
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
def main():
problems = []
# Example: every file in out/ must be non-empty.
# for f in os.listdir(os.path.join(ROOT, "out")):
# if os.path.getsize(os.path.join(ROOT, "out", f)) == 0:
# problems.append(f"out/{f}: empty file")
for p in problems:
print(p)
print(f"{len(problems)} problems")
return 1 if problems else 0
if __name__ == "__main__":
sys.exit(main())5. 전체 커리큘럼 (5강 · 전체 10분 22초)
| 구분 | 강의명 | 시간 | 핵심 내용 및 제공 자료 |
|---|---|---|---|
| 1강 | 왜 지금 하네스인가 — AI의 「다 했어요」를 믿지 않는 구조 | 01:23 | 같은 「지워줘」에 하네스 없음은 5개 삭제 · 키트는 5개 보존 · 완료 게이트 장면 |
| 2강 | [Step 1] 지적 한 번 = 규칙 한 줄 — 실제 사고 기록 8건과 기록 틀 | 01:49 | 스타터 킷 ZIP (39개 파일) · lessons/ 사고 기록 8건 · 기록 틀 |
| 3강 | [Step 2] 훅으로 강제하기 — 위험 명령 7가지와 읽기 전용 폴더 | 02:40 | G1~G7 · W1 · 훅 테스트 차단 16/16 · 통과 12/12 |
| 4강 | [문제 해결] 세션 여러 개가 서로를 망칠 때 — 클립보드 · 커밋 · 잠금 | 01:17 | lock.py 두 세션 대기 · TIMEOUT 문구 · 커밋은 내 경로만 |
| 5강 | [Step 3] 「완료」를 검사 스크립트로 정의하기 — 16회 실측 비교와 Stop 게이트 | 03:14 | 하네스 없음 vs 함께 비교표 · 내 검사 만들기 · 핵심 3줄 |
| 전체 | [연속재생] 1~5강을 끊김 없이 한 번에 | 10:22 | 이 쪽 위 플레이어 |