feat(harness): Hook 통합 — Memo 패턴 자동화 (선택, PR #11 후속)

[namojo]

배경 및 동기

별도로 제안된 Memo 패턴 (선택) PR(#11)을 적용한 하네스에서, 사용자가 "세션 재개 자동화", "컨텍스트 자동 주입", "컴팩트 시 자동 저장" 같은 자동화를 원할 때만 제안할 수 있는 hook 가이드를 추가합니다.

무엇을 추가하는가

skills/harness/references/hook-integration.md (신규, 약 245줄)를 추가하고, skills/harness/SKILL.md의 참고 섹션에 항목을 1줄 추가합니다.

가장 중요한 원칙 — 자동화는 default가 아니다

harness는 사용자 settings.json을 절대 직접 수정하지 않는다.

다음 두 조건을 모두 만족할 때만 hook 적용을 제안합니다.

1. Memo 패턴(PR feat(harness): Memo 패턴 — 분산 슬롯 + 공유 헤더 (선택) #11)이 적용된 하네스를 생성했다.
2. 사용자가 명시적으로 "자동으로 status를 읽어줘", "세션 재개 자동화", "컴팩트 시 자동 저장" 같은 요구를 했다.

위 두 조건을 만족하지 않으면 이 문서를 끌어들이지 않습니다.

위험 요소 (5가지)

위험	설명
settings.json 직접 수정 금지	harness는 절대 사용자 settings.json을 직접 수정하지 않는다. update-config 스킬에 위임하거나, 사용자에게 패치 텍스트를 보여주고 본인이 적용하도록 한다.
hook은 사용자 환경에서 실행	잘못된 hook은 모든 세션 시작·도구 호출에 영향. 무한 루프·실패 시 차단도 가능.
hook 출력은 컨텍스트에 주입	큰 출력은 매 세션마다 토큰을 잡아먹는다. status.md를 통째로 주입하지 말고 공유 헤더만 주입할 것.
secrets/credentials 노출 위험	hook 스크립트가 cwd 기반으로 동작할 때 .env 등을 실수로 읽지 않도록 경로를 명시적으로 제한.
Windows 경로 차이	bash 스크립트는 Unix 경로(/)를 쓰지만 사용자 환경은 Windows. $CLAUDE_PROJECT_DIR을 항상 따옴표로 감싸고 경로 구분자에 주의.

3가지 Hook 패턴

패턴 1 — SessionStart로 status 자동 주입

SessionStart hook이 .harness/status.md의 공유 헤더 80줄만 잘라 additionalContext로 주입합니다. 슬롯 전체를 자동 주입하면 토큰이 폭발하므로, 슬롯은 에이전트가 필요 시 직접 Read하도록 합니다.

#!/usr/bin/env bash
set -euo pipefail
STATUS_FILE="${CLAUDE_PROJECT_DIR}/.harness/status.md"
[[ -f "$STATUS_FILE" ]] || exit 0
CONTENT=$(head -n 80 "$STATUS_FILE")
# 공유 헤더만 주입. 슬롯은 에이전트가 필요 시 직접 Read.
# additionalContext에 80줄 이하로 잘라 토큰 폭발 방지.

패턴 2 — PreCompact 직전 슬롯 갱신

컴팩트는 Claude의 결정이므로 hook은 "지금 무엇을 했는지"를 모릅니다. 따라서 두 가지 접근:

• 옵션 A (권장): hook은 알림만 — "곧 컴팩트 발생, 본인 슬롯에 핵심 진척 1줄 append하세요"를 additionalContext로 주입. 갱신은 에이전트가.
• 옵션 B (안전망): hook이 모든 활성 슬롯에 {timestamp} pre-compact triggered 한 줄 자동 append. 정보량은 적지만 손실 방지.

패턴 3 — Stop hook으로 timestamp 갱신 (선택)

매 턴 종료 시 status.md의 Last Updated만 새로 찍습니다. 어떤 컨텍스트도 주입하지 않습니다. 본문 갱신은 에이전트가 마일스톤 시점에 직접 합니다.

settings.json 통합 예시

settings.json에 SessionStart matcher(resume|startup|clear)와 PreCompact hook을 등록합니다. 이 패치는 사용자가 직접 적용합니다. harness/Claude는 절대 settings.json에 자동 쓰지 않습니다. 사용자가 자동 적용을 원하면 update-config 스킬을 호출하라고 안내합니다.

환경 주의사항

환경	주의점
Windows + Git Bash	hook 스크립트는 POSIX bash. .sh 확장자 유지. CRLF 대신 LF
Windows 경로	$CLAUDE_PROJECT_DIR이 C:/Users/... 형태. head/sed는 forward slash 그대로
Proxy 환경	hook 스크립트 자체는 네트워크 미사용. git 호출 시는 사용자 git config 따름
Permissions 환경	hook은 Bash 권한과 무관하게 hook 시스템이 직접 실행
무한 루프 방지	hook 안에서 Claude 호출 금지

Hook 없이도 동작하는가?

예. Memo 패턴 자체는 hook 없이도 동작합니다.

• 에이전트 정의에 "작업 시작 시 .harness/status.md Read" 지침이 있으면 hook 없이도 직접 읽습니다.
• PreCompact 자동 갱신이 없어도 에이전트가 마일스톤 시점에 자기 슬롯에 append합니다.
• hook은 자동화의 편의이지 기능의 필수 조건이 아닙니다.

따라서 hook 적용은 있으면 좋고 없어도 동작하는 옵션입니다. 사용자가 망설이면 끄고 시작하고, 익숙해지면 켜는 단계적 도입이 안전합니다.

검토 체크리스트 (사용자에게 제안 전 Claude/하네스가 점검)

• Memo 패턴이 실제 적용된 하네스인가?
• hook 스크립트가 secret/credential/*.env 파일을 읽지 않도록 경로 제한되었는가?
• additionalContext가 80줄 이하로 잘려 있는가?
• set -euo pipefail 등으로 hook 실패 시 빠르게 종료하는가?
• 파일이 없을 때 조용히 종료(exit 0)하는가?
• hook 동작을 사용자가 끌 수 있는 방법(주석 처리/조건 변수)이 있는가?
• 사용자에게 패치 텍스트를 보여주고 명시적 승인을 받았는가?

의존성

본 PR은 PR #11 (Memo 패턴) 이후에 머지되는 것이 자연스럽습니다. 단, 코드 충돌은 없으므로 머지 순서가 바뀌어도 무방합니다 (참고 섹션 항목만 추가).

변경 사항

• 신규: skills/harness/references/hook-integration.md (243줄)
• 수정: skills/harness/SKILL.md
  • ## 참고 섹션에 Hook 통합 1줄 추가 ("사용자 명시 승인 없이 적용 금지" 명시)

체크리스트

• 신규 파일은 references/ 하위에 배치 (조건부 로딩)
• SKILL.md 본문에는 조건부 가이드임을 명시
• settings.json 자동 수정 금지 규칙을 references/ 양쪽에 명시
• secrets/credentials 노출, Windows 경로, 무한 루프 방지 등 위험 항목 정리
• hook 없이도 Memo 패턴이 동작함을 명시 (단계적 도입 권장)
• 7개 검토 체크리스트 포함