한국어
구독

← 강좌 목록으로 돌아가기

무료 실전 특강 #02 · 온라인 웹 실습실Claude Code 훅 · Codex · Antigravity 호환MIT 오픈소스 스타터 킷 포함

AI가 "다 했어요"라고 거짓말할 때 — Claude Code 하네스 엔지니어링 10분 실전

실제 사고 8건에서 만든 규칙 파일 · 위험 명령 차단 훅 · 완료 게이트를 그대로 가져가세요. 같은 지시를 하네스 없이 / 함께 16번 돌린 실측과 함께, AI의 「완료」를 검사 숫자로 말하게 하는 법을 보여 줍니다.

1. 강의 플레이어 & 에이전트 바로 시작 프롬프트

영상 아래 챕터 버튼으로 원하는 강으로 바로 이동합니다. 오른쪽 프롬프트를 복사해 Claude Code · Codex · Antigravity에 붙여 넣으면 클론부터 훅 테스트 · 검사까지 자동으로 진행됩니다.

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. 훅 체험기 — 이 명령, 막힐까요?

AI가 실행하려는 명령을 넣어 보세요. 키트의 guard_bash.py(G1~G7)와 같은 규칙으로 바로 판정합니다. 명령은 실행되지 않고, 이 브라우저 밖으로 보내지지 않습니다.

눌러서 넣어 보기:

키트 테스트(차단 16건 · 통과 12건)와 추가 사례 38건, 모두 66건을 실제 훅과 대조해 같은 판정을 확인했습니다.

3. 같은 지시, 하네스 없음 vs 함께 (실측 16회 · Opus 5.5)

Claude Code 2.1.306 · claude-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종 미리보기 (스타터 킷 수록본)

ZIP을 풀기 전에도 아래 세 문서를 바로 복사해 내 프로젝트에 붙일 수 있습니다.

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:40G1~G7 · W1 · 훅 테스트 차단 16/16 · 통과 12/12
4강[문제 해결] 세션 여러 개가 서로를 망칠 때 — 클립보드 · 커밋 · 잠금01:17lock.py 두 세션 대기 · TIMEOUT 문구 · 커밋은 내 경로만
5강[Step 3] 「완료」를 검사 스크립트로 정의하기 — 16회 실측 비교와 Stop 게이트03:14하네스 없음 vs 함께 비교표 · 내 검사 만들기 · 핵심 3줄
전체[연속재생] 1~5강을 끊김 없이 한 번에10:22이 쪽 위 플레이어
함께 성장하기 · COMMUNITY

만든 것을 나누는 곳

막히는 에러는 AI 에이전트에게 먼저 물어보시는 게 가장 빠릅니다. 직접 만든 규칙 한 줄과 검사 스크립트는 오픈채팅방에서 서로 나눠요.