프로젝트 무관(project-agnostic) AI 코딩 하네스 — 어느 repo 에든 드롭인. 실행·파일·프롬프트 단계에 끼어들어 규칙을 강제하고, 모든 결과를 append-only JSONL 로 남긴다.

🔧 하네스 = "AI 코딩 보안검색대" — AI 에이전트(Claude Code / Codex 등)가 명령을 실행하거나 파일을 고치기 직전·직후에 게이트를 통과시켜, 위험한 동작은 막고(block) 잠금 파일 수정은 경고(warn)하며 검증·인계를 자동화한다. ESLint 가 "코드 문법"만 본다면, 하네스는 명령 실행·파일 잠금·검증·세션 인계까지 작업 흐름 전체를 단속한다.

이 저장소는 dancinlab 의 모든 repo(edge · anima · ...)가 공유하는 엔진이다. 프로젝트마다 달라지는 것은 harness.config.json + .harness/*.json(규칙 데이터)뿐이고, .ts 엔진 코드는 전부 공유한다.

🌐 언어 무관: 웹뿐 아니라 Python · Rust · C/C++ · Go · Swift · hexa 로컬/모바일 앱에도 쓴다. init 이 스택을 감지해 검증 명령(cargo/pytest/swift build/...)과 다국어 우회패턴(# type: ignore·#[allow]·swiftlint:disable...)을 자동 적용. 엔진 실행에 개발머신 Node 1개만 필요(타깃 빌드와 무관). → docs/languages.md

[ edge repo ]──┐
[ anima repo ]─┼──▶ 같은 .ts 엔진 (이 repo)
[ 다른 repo ]──┘ ▲さんかく
 │ 각자 harness.config.json + .harness/*.json 으로
 └─ 규칙만 다르게 주입

harness/
├── bin/harness 실행 입구 (bash — tsx 런타임 자동탐색)
├── cli/index.ts 디스패처 (harness lint → lint.ts)
├── lib/ 공용 부품
│ ├── paths.ts repo-root 자동탐색 (harness.config.json / .git 상향 탐색)
│ ├── config.ts harness.config.json 로드 + 기본값 머지
│ ├── lockdown.ts L0(잠금) 파일 목록 (config + 🔴 마크다운 블록 파싱)
│ ├── log.ts json.ts exec.ts
├── modules/ 기능 12종 (아래 표)
├── config/ 번들 기본 규칙 (도메인-무관)
│ ├── enforcement.json 실행/쓰기 차단 규칙 + 프롬프트 힌트
│ ├── keywords.json 프롬프트 키워드 트리거
│ └── severity-map.json 오류 severity 분류
└── harness.config.example.json

commands/*.md — 전체 사용자-대면 명령이 bare /cmd 슬래시 명령으로 노출된다(/paper·/imagine· /pr-cycle·/sbs·/fleet·/fleet-lab·/ing·/ci·/kick·/poll ...). 각 .md 는 프런트매터(description + Triggers 자연어구 + argument-hint + allowed-tools: Bash)와 !harness $ARGUMENTS`` 본문의 얇은 위임자 — Claude Code 가 description/Triggers 로 인지한다(한국어·영어 트리거 양쪽).

노출 경로 = harness shadow (bare · user-scope): Claude Code 는 플러그인 명령을 무조건 /plugin:cmd 네임스페이스로 띄우므로, 그대로 두면 harness shadow 의 bare /fleet 와 플러그인 /harness:fleet 가 picker 에 2줄로 중복된다. 그래서 .claude-plugin/plugin.json 이 commands: [] (기본 commands/ 스캔을 빈 목록으로 대체)로 플러그인 명령 등록을 끄고, 슬래시 노출은 harness shadow 가 commands/*.md 를 ~/.claude/commands/ 에 bare /cmd 위임자로 미러하는 단일 경로만 쓴다(마커 추적 · 손수 작성한 동명 파일은 보존 · shadow remove 로 정리) → picker 에 bare 1줄. SHADOW_MARKER 추적 주석은 frontmatter 닫는 --- 뒤에 삽입한다 — Claude Code 는 --- 가 1행일 때만 description: 을 읽으므로, 앞에 붙이면 picker 가 마커 주석을 설명으로 표시한다.

자기완결(self-contained) 플러그인 · 프로젝트 무관: marketplace source: "." 라 repo 루트가 곧 플러그인 — 훅뿐 아니라 harness CLI 본체(bin/·cli/·lib/·modules/·config/·commands/)까지 한 덩어리로 실린다 (commands/ 는 shadow 가 미러하는 SOURCE 로 실릴 뿐, 플러그인 명령으로 로드되진 않는다). 훅은 ${CLAUDE_PLUGIN_ROOT}/bin/harness(플러그인 자기 번들)를 실행하므로, /plugin update + 리로드 한 번에 CLI·hooks 가 최신화된다 — 프로젝트마다 복사·갱신도, 별도 harness self-update 도 불필요(슬래시는 갱신 후 harness shadow 재실행으로 반영). (전역 harness on PATH 는 폴백.) 재생성기 = _tools/gen_commands.py. hook-내부 전용(pre/post/prompt)은 슬래시로 노출하지 않는다.

ing add 자유텍스트에 셸 특수문자(괄호·따옴표·$·→)가 있으면 슬래시 $ARGUMENTS 무인용 확장이 깨진다 — printf '%s' "<text>" \| harness ing add --stdin (STDIN 경로)로 안전하게 등록한다(--to <repo> 와도 호환).

머신에 하네스를 공용 명령으로 깔고 전역 훅까지 한 방에 배선한다(특정 repo 단독 세팅 아님). 부트스트랩 one-liner:

curl -fsSL https://raw.githubusercontent.com/dancinlab/harness/main/scripts/install.sh | bash

하는 일(멱등 — 재실행 = 최신으로 갱신):

⬇ clone dancinlab/harness → ~/.harness/cli
🔗 link harness 래퍼 → ~/.local/bin/harness (PATH 안내)
🪝 hooks harness install-hooks --global (모든 Claude Code 세션에 가드/주입)

이후 갱신은 harness self-update, 이미 하네스가 깔려 있으면 harness install 로도 동일 동작. 훅 없이 깔려면 --no-hooks, 미리보기는 --dry-run. 그다음 특정 repo 에 적용하려면 아래 1·2 단계(또는 harness init).

cd your-repo
git submodule add https://github.com/dancinlab/harness .harness-engine
# 또는 그냥 clone / vendor 해도 됨

bash .harness-engine/bin/harness init --hooks

이 한 줄이 만든다 (기존 파일은 보존, --force 만 예외 · --dry-run 으로 미리보기):

✓ harness.config.json 프로젝트명 자동감지
✓ .harness/enforcement.json 번들 기본 규칙 복사 (repo 가 수정)
✓ .harness/keywords.json
✓ .harness/severity-map.json
✓ .gitignore 로그 무시 추가
✓ scripts/harness 얇은 래퍼
✓ .claude/settings.json hook 배선 (--hooks 일 때)

생성 후 harness.config.json 의 verify.checks · lockdown.files 만 repo 에 맞게 채우면 된다.

수동 설정도 가능: .harness/*.json 을 두지 않으면 번들 기본 규칙(config/*.json)이 자동 적용된다.

제거: harness uninstall (주입물만 제거, 사용자 콘텐츠 보존 · --dry-run 미리보기). 상세 docs/install.md.

bash .harness-engine/bin/harness audit
bash .harness-engine/bin/harness ci list

.claude/settings.json:

{
 "hooks": {
 "PreToolUse": [
 { "matcher": "Bash", "hooks": [{ "type": "command", "command": "CLAUDE_TOOL_INPUT=\"$CLAUDE_TOOL_INPUT\" bash .harness-engine/bin/harness pre bash" }] },
 { "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "CLAUDE_TOOL_INPUT=\"$CLAUDE_TOOL_INPUT\" bash .harness-engine/bin/harness pre write" }] }
 ],
 "PostToolUse": [
 { "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "bash .harness-engine/bin/harness post edit \"$CLAUDE_FILE_PATH\"" }] }
 ],
 "UserPromptSubmit": [
 { "hooks": [{ "type": "command", "command": "bash .harness-engine/bin/harness prompt \"$CLAUDE_USER_PROMPT\"" }] }
 ]
 }
}

환경변수 이름(CLAUDE_TOOL_INPUT 등)은 런타임 버전에 따라 다를 수 있다. 하네스는 CLAUDE_TOOL_INPUT 와 CODEX_TOOL_INPUT 둘 다 읽는다. JSON 형식: {"command":"...","file_path":"...","content":"..."}.

💡 harness install-hooks [--global|--repo] 는 hook 배선과 함께 settings.json 의 env 에 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 도 세팅한다 — 백그라운드 subagent 에 SendMessage(agent-teams)를 기본 활성화. 이미 그 키가 있으면 사용자 값을 보존한다(덮어쓰지 않음). 끄려면 그 키를 "0" 으로 두면 된다.

사용자 프롬프트 ─▶ [prompt] 키워드 트리거 + 힌트 주입
에이전트 Bash ─▶ [pre bash] ─ 매칭? ─▶ block(stdout JSON) / warn(stderr) / 통과(침묵)
 │
 ▼ (실행 후)
 [post bash <exit>] ─ 0≠exit ─▶ errors 큐 라우팅
에이전트 Edit ─▶ [pre write] ─ 경로/내용 규칙 ─▶ block/warn
 [post edit <file>] ─ L0? ─▶ 경고
커밋 전 ─▶ [lint] + [verify]
세션 종료 ─▶ [ing]

모든 단계는 .harness/logs/*.jsonl 에 한 줄씩 쌓인다 → audit 이 이를 읽어 건강도를 점수화한다.

• docs/languages.md — 언어/플랫폼 범용성 (Python·Rust·C·Go·Swift·hexa 프리셋 + Node 런타임 요구)
• ARCHITECTURE.json — 하네스 아키텍처 트리 SSOT (컬럼형 노드: 이름·역할·구분·상세). 사람용 뷰어는 ARCHITECTURE.html — 로컬은 python3 serve.py(서버 + 브라우저 자동 오픈), 원격은 raw.githack.com / GitHub Pages
• docs/install.md — repo 통합 상세 (submodule / vendor / 멀티 repo)
• docs/extending.md — 규칙 추가, 도메인 모듈 확장 패턴

이 repo 자체가 하네스를 쓴다(dogfooding) — harness.config.json + .claude/settings.json self hooks + pre-commit bin/harness lint. 코어(.ts) 변경 시 CHANGELOG 동시 갱신이 강제되고, 번들 enforcement(root-cause·secret·force-push)가 자기 코드에도 적용된다. 단 protectedBranches 미설정으로 자기 개발 흐름(main 직접 push)은 막지 않는다.

매 사이클(harness pr-cycle)의 doc-gate 는 의미있는 변경에 대해 CHANGELOG.md(append) + (존재 시) ARCHITECTURE.md·README.md 현행화를 요구한다 — 셋 중 미갱신이 있으면 머지를 거부한다(--no-doc 는 진짜 문서 불필요할 때만). 이 README 도 그 대상이므로 매 사이클 최신 상태로 유지된다. (commons c12)

harness pr-cycle 은 검증된 머지 직후 로컬 base(main) 를 origin/base 로 ff-sync 한다(feature 브랜치에서 git fetch origin <base>:<base> — checkout 전환 없이 로컬 main 뒤처짐 방지, non-ff 거부=안전). origin 만 갱신하고 로컬 main 을 방치하지 않으므로, 다음 작업 브랜치는 항상 최신 base 에서 분기된다. (commons c12)

같은 doc-gate 가 pre-commit harness lint 에서도 발화한다 — pr-cycle 을 거치지 않는 작업이라도, 의미있는 코드 변경이 staged 인데 CHANGELOG / (존재 시) ARCHITECTURE·README 가 같이 staged 안 됐으면 commit 을 차단한다(CHANGELOG-MISSING·ARCHITECTURE-MISSING·README-MISSING, 모두 block). 즉 "모든 작업 이후" 문서 현행화가 강제된다. 진짜 문서 불필요한 변경만 git commit --no-verify.

MIT