harness-export

Harness Export — 규범을 하네스 중립으로 내보내기

CCK의 규범(rules/*.md)은 Claude Code의 SessionStart 훅으로만 주입된다. 그런데 Orca·Paseo 같은 ADE에서는 한 레포에 Claude Code와 Codex·OpenCode·Pi를 동시에 붙여 굴린다. 그 순간 레포의 절반은 CCK 규율 밖에서 동작한다.

이 스킬은 규범을 AGENTS.md(Codex·OpenCode·Copilot CLI·Cursor가 공통으로 읽는 사실상 표준)로 내보내 그 구멍을 메운다.

사용 시점

상황	실행
레포를 두 개 이상의 하네스가 만진다	/harness-export 1회 → AGENTS.md 커밋
rules/*.md를 고쳤다	재생성 (안 하면 다른 하네스가 옛 규범을 읽는다)
CI/게이트에서 최신 여부만 확인	--check

절차

소비자(플러그인 설치) 환경 — 기본 경로

구현은 플러그인 안에 있다(<플러그인 루트>/hooks/export_harness.py). 설치한 프로젝트에는 이 kit의 scripts/가 없으므로 이 경로를 쓴다.

$CLAUDE_PLUGIN_ROOT를 그대로 신뢰하지 마라. 이 변수는 스킬의 Bash 컨텍스트에 설정돼 있지 않을 수 있다(kit의 feedback.sh·auto-dev가 같은 이유로 의존을 제거했다). 빈 값이면 python3 "/hooks/export_harness.py"가 되어 파일 없음으로 종료코드 2가 나고, exit 표상 2는 "SKIPPED"라서 원인을 오보고하게 된다. 아래처럼 먼저 해석하라.

# 1) 구현 위치 해석 — 변수가 비면 캐시에서 찾는다
EH="${CLAUDE_PLUGIN_ROOT:-}/hooks/export_harness.py"
[ -f "$EH" ] || EH=$(ls -1 ~/.claude/plugins/cache/*/claude-code-kit/*/hooks/export_harness.py 2>/dev/null | sort -V | tail -1)
[ -f "$EH" ] || { echo "export_harness.py를 찾지 못했다 — 플러그인 설치 확인"; exit 2; }

# 2) 현재 프로젝트(git 최상위)의 AGENTS.md 갱신
python3 "$EH"

# 3) 드리프트 검사만 (기록하지 않음)
python3 "$EH" --check

# 4) 블록 내용만 확인 / 다른 프로젝트 대상
python3 "$EH" --stdout
python3 "$EH" --target /path/to/project

--plugin-root를 명시했는데 그 경로에 rules/가 없으면 자동 탐색으로 폴백하지 않고 exit 2다. 지정한 것과 다른 레포의 규범을 내보내고 성공을 보고하는 사고를 막는다. 명시하지 않으면 스크립트 자기 위치가 1순위이고(플러그인 캐시에서도 불변), 환경변수는 그 다음이다 — 셸에 남은 다른 플러그인의 값이 남의 규범을 내보내지 않도록.

kit 레포에서 개발할 때

./scripts/export-harness.sh          # 내보내기
./scripts/export-harness.sh --check  # 드리프트 검사 (게이트가 쓰는 명령)

exit code

code	의미	대응
0	성공 / 드리프트 없음	—
1	드리프트 · 블록 본문 변조 · 마커 손상 · 분류 미등재/유령 엔트리 · 인코딩 실패 · 트리 밖 심링크	stderr의 원인을 읽어라 — 재생성으로 안 고쳐지는 종류가 있다
2	SKIPPED — 규범 소스 미탐지	--plugin-root 지정. 0으로 위장하지 말 것

불변식 [건너뛰기 금지]