research

Harness Engineering — 전문가 로드맵

Harness Engineering — 전문가 로드맵

최신 연구(OpenAI, Stripe, LangChain, HumanLayer) 기반으로 구성. mugyeon v1 완주 기준으로 업데이트 (2026-03-21)

전체 그림

Desktop (설계/연구/공부)          Claude Code (구현)
─────────────────────────────────────────────────────
"왜, 무엇을" 결정                "어떻게, 실행" 담당
  설계하자 → GitHub MCP            git pull → 구현
  연구하자 → Obsidian vault         git push → 기록
  공부하자 → Obsidian vault

         context-bridge.md
         (두 환경을 잇는 핸드오프)

         Stop Hook
         (세션 종료 시 git push 강제)

Stage 0 — 최소 harness ✅

  • global-CLAUDE.md (40줄)
  • project CLAUDE.md (포인터만, global 중복 없음)
  • feature_list.json

검증: F01~F10 전부 완주

Stage 1 — Context Engineering ✅

  • CLAUDE.md = 목차 + 포인터
  • docs/architecture.md + docs/decisions.md (ADR)
  • context-bridge.md (replace 방식)
  • claude_progress.log (tail 방식)

검증: ADR-001~003이 F04~F05 구현에 직접 반영됨

Stage 2 — State Management ✅

  • context-bridge.md replace 프로토콜 확립
  • global-CLAUDE.md ↔ 서버 sync_global.sh 자동화
  • Desktop user memory 등록

검증: 세션 재시작 후 ADR 기반으로 이어서 작업 가능

Stage 3 — Tool + Skill ⚠️

  • skill/job-processing.md 생성 (architecture 기반)
  • skill/feature-complete.md 미생성

미완: skill을 실제로 Claude Code가 참조해서 실행하는지 미검증

Stage 4 — Verification ✅

  • AC test: Claude Code가 자체 작성 (레이어 규칙 3개 + .gitignore)
  • CI: push 시 자동 실행
  • test_gitignore_required_entries에 *.db 포함

검증: F01~F10 전 기간 AC test 4/4 통과

Stage 5 — Bootstrap 자동화 ✅

  • bootstrap_init.sh: git 환경만 + sync_global.sh 자동 호출
  • sync_global.sh: rclone sync + symlink 검증 + Hook 설치
  • 새 프로젝트 시작 → 한 방에 완료

Stage 6 — Hook (추가됨) ✅

업계 갭이었던 Middleware를 Hook으로 부분 해결.

_config/hooks/
  stop-git-push.sh           ← Stop Hook (unpushed commit 감지 + push)
  post-write-gitignore-check.sh ← PostToolUse Hook
  pre-write-context-bridge-check.sh ← PreToolUse Hook
  settings.json              ← Hook 설정 (sync_global.sh가 자동 설치)

검증: F08 세션에서 Stop Hook 작동 확인 (unpushed commit → 자동 push)

Stage 7 — GC ○

미착수. v2 이후로 충분.

v1 완주 후 발견된 헛점 → 반영 결과

| 헛점 | 발견 시점 | 반영 | |------|---------|------| | git push 누락 | F01 | Stop Hook | | .db repo 추적 | F01 | .gitignore + PostToolUse Hook | | AC test *.db 누락 | F02 | F03에서 Claude Code가 추가 | | Stop Hook unpushed 감지 누락 | F06 테스트 | git log @{u}.. 추가 | | asyncio blocking subprocess | F04 코드 리뷰 | global-CLAUDE.md 패턴 추가 | | project CLAUDE.md global 중복 | 설계 단계 | 분리 구조 확립 |

핵심 자료

  • OpenAI Harness Engineering: https://openai.com/index/harness-engineering/
  • learn-claude-code: https://github.com/shareAI-lab/learn-claude-code
  • HumanLayer: https://www.humanlayer.dev/blog/skill-issue-harness-engineering-for-coding-agents
  • LangChain Open SWE: https://github.com/langchain-ai/open-swe
← research 목록으로홈으로