convez.ai
Agente
hanbyeol

cc-harness

hanbyeol/cc-harness

Ver no GitHub
InicialPluginScore · de 0 a 100

One command to bootstrap a full-SDLC harness for Claude Code. Hooks, rules, agents, phase gates — polyglot monorepo ready.

Instalação

$npx convez-ai hanbyeol/cc-harness

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 dias
Versão
v2.0.67
Issues abertas
0
Contribuidores
2

README

A tradução para o português deste README ainda está na fila.

cc-harness

A full-SDLC harness for Claude Code — quality gates, security by design, and a development methodology that enforces itself.

Claude Code의 전체 개발 생명주기(설계 정제 → 기획 → 아키텍처 → 구현 → 검증 → 배포 → 관측)를 구조화하는 harness입니다. plugin 설치 한 번으로 8 agents · 11 skills · 7 hooks · 11 rules가 적용됩니다.

Note: 이 프로젝트는 Harness.io (CI/CD 플랫폼)와 무관합니다. 여기서 "harness"는 AI agent harness engineering 개념 — 에이전트가 일관된 품질로 일하도록 둘러싸는 구조 — 을 의미합니다.

핵심 설계 원칙

원칙구현
Generator–Evaluator 분리구현자(implementer)는 자기 작업을 통과 판정할 수 없다 — 독립 evaluator만 passes: true 설정 가능
min-of-5 품질 게이트종합 점수 = 기능·품질·보안·에러처리·테스트 5개 점수의 최솟값. 평균으로 약점을 가릴 수 없다
Evidence over claims실행하지 않은 검증은 완료가 아니다 — implementer는 실행 결과(evidence)를 첨부, evaluator는 미실행 차원에 7점 이상을 줄 수 없다(unverified 상한)
기준 역전파구현 중 발견한 기준 갭은 코드가 아니라 상위 산출물(SPEC, acceptance criteria)부터 보완한다
Security by design기능마다 security_tier 태깅 — critical 기능은 보안 점수 7 미만 시 다른 점수와 무관하게 자동 fail
결정론적 강제프롬프트 규율에만 의존하지 않는다 — 위험 명령 차단, 자동 포맷, 품질 게이트, 시크릿 스캔은 훅이 집행
모델 라우팅설계·판정·코딩·보안처럼 추론이 결과를 좌우하는 단계는 Opus, 스펙·테스트·배포는 Sonnet, 체크리스트성 QA는 Haiku — 할당은 config/models.json 단일 출처로 관리하고 model-tiering 프로브가 역전을 탐지

Quick Start

Plugin Install (권장)

# 1. Marketplace 등록
/plugin marketplace add hanbyeol/cc-harness

# 2. Plugin 설치
/plugin install cc-harness

또는 /plugin → Discover 탭에서 cc-harness 검색 → Install.

설치 후 첫 세션에서 자동으로:

  • agents·skills·hooks가 네이티브 로딩 (프로젝트에 복사하지 않음 — 업데이트 즉시 반영)
  • rules가 .claude/rules/에 복사 (path-scoped 규칙은 프로젝트 단위)
  • CLAUDE.md에 하네스 워크플로우 섹션 삽입 (멱등 — 중복 삽입 없음)
  • 세션 컨텍스트(브랜치, phase, 미완료 기능) 주입 시작

/progress를 실행하면 현재 상태와 다음 작업을 확인할 수 있습니다.

Bootstrapper (전체 프로젝트 스캐폴딩)

progress 추적, docs 템플릿, Makefile까지 포함한 전체 스캐폴딩이 필요하면:

npx cc-harness --preset go-k8s            # npx
bash <(curl -sL https://raw.githubusercontent.com/hanbyeol/cc-harness/main/init.sh)   # npm 없이
git add .claude/ CLAUDE.md progress/ docs/ evals/ Makefile
git commit -m "chore: initialize SDLC harness"
claude

동작 방식 — 워크플로우

개발 흐름

 Phase 0.5         Phase 1        Phase 2        Phase 3            Phase 4             Phase 5      Phase 6
 설계 정제     ▶   기획       ▶   설계       ▶   구현           ▶   검증            ▶   배포     ▶   관측
 /brainstorm       spec-writer    architect      /implement         evaluator(게이트)    deploy-op    metrics
 (소크라테스식      (인터뷰 브리프  (위협 모델링,   Sprint Contract    ──병렬──▶            (staging→    logs
  질문, 대안        → SPEC,       SECURITY-      → Plan 게이트       test-writer          canary→      alerts
  비교)            criteria)      CHECKLIST,     → TDD 구현          security-auditor     prod,        runbooks
                                  ADR)           → 검증 요청         qa-reviewer          롤백)

기능 하나의 생애 (Generator–Evaluator Loop)

 /change-request ─▶ 산출물 갱신 ─▶ Sprint Contract(agreed:false) ─▶ Plan 게이트(사용자 승인)
                                                                          │ 승인
                                                                          ▼
        ┌──────────────────────────────  implementer (TDD: RED→GREEN→REFACTOR + evidence)
        │ 반려(피드백)                              │ 구현 완료
        ▼                                          ▼
   /implement --retry ◀───────────────  evaluator (5차원 채점, min-of-5, 실행 근거 기반)
                                                   │ pass → passes: true
                                                   ▼
                          test-writer + security-auditor + qa-reviewer (병렬)
                                                   │ 통과
                                                   ▼
                                          /finish-branch → PR/머지

핵심 게이트:

  • Plan 게이트: Sprint Contract(acceptance/security/error criteria + 체크포인트 태스크)는 사용자가 ExitPlanMode로 승인해야 agreed: true — 승인 없이 구현 시작 불가
  • Evaluator 게이트: 5개 점수 모두 임계값(기본 7) 이상이어야 통과. 채점은 이 세션에서 직접 실행한 테스트 결과 기반
  • Phase 게이트: progress/phase-gate.json의 criteria가 모두 충족되어야 다음 phase 진입

구성 요소

Agents (8개)

AgentPhase역할모델
spec-writer1. 기획인터뷰 브리프 → SPEC.md + acceptance criteria (미해결 항목은 open_questions 반환)Sonnet 4.6
architect2. 설계아키텍처 + 위협 모델링(STRIDE) + SECURITY-CHECKLIST + ADROpus 4.8
implementer3. 구현TDD(RED-GREEN-REFACTOR) 구현 + 보안 셀프체크 + 실행 evidenceOpus 4.8
evaluator게이트5차원 품질 평가 (min-of-5, 점수 앵커, unverified 상한)Opus 4.8
test-writer4. 검증통합/E2E/보안 테스트 (worktree 격리로 병렬 실행)Sonnet 4.6
security-auditor4. 검증보안 감사 + supply chain + 위협 모델 대비 검증Opus 4.8
qa-reviewer4. 검증크로스 기능 통합 QA (사용자 관점)Haiku 4.5
deploy-operator5. 배포배포 전 검증 → staging → canary → prod, 자동 롤백Sonnet 4.6

모델 라우팅 — 작업 난이도에 맞춰 차등 배치. 할당은 config/models.json을 단일 출처로 관리하며 agents/*.md frontmatter와 일치해야 한다(불일치·역전·미등록은 model-tiering 프로브가 정적 탐지):

  • Opus 4.8 (claude-opus-4-8): 추론 품질이 결과를 좌우하는 단계 — 설계(architect), 품질 게이트(evaluator), 에이전틱 코딩(implementer), 보안 감사(security-auditor). security-auditor는 방어 목적 분석까지 refusal하지 않도록 cyber-refusal이 없는 Opus를 고수한다.
  • Sonnet 4.6 (claude-sonnet-4-6): 실코딩성·안전 마진이 필요한 단계 — 스펙(spec-writer), 테스트 작성(test-writer, evaluator의 커버리지 차원에 직결), 배포(deploy-operator).
  • Haiku 4.5 (claude-haiku-4-5): 체크리스트성 크로스 기능 QA(qa-reviewer).

phase별 선언 단가(per-1M)는 scripts/cost-report.sh로 확인할 수 있습니다 — 읽기 전용, 실제 청구가 아닌 config 선언값입니다.

서브에이전트 제약: 서브에이전트는 사용자에게 질문할 수 없습니다 — 사용자 입력이 필요한 결정(인터뷰, 승인)은 메인 루프가 디스패치 전에 수집해 프롬프트로 전달하는 구조입니다.

Skills (11개)

Skill설명
/brainstorm코드/스펙 전 소크라테스식 설계 정제 — 대안 비교, docs/brainstorms/ 산출 (Phase 0.5)
/change-request기능 추가/변경/삭제 시 산출물 연쇄 업데이트 + 의존성 영향 분석
/implementSprint Contract → Plan 게이트 → 체크포인트 태스크 TDD 구현 → evaluator 검증
/hotfix경량 긴급 수정 — 실패 재현 테스트 먼저, 3파일 이하, 비보안
/debug원인 불명 버그의 4단계 디버깅: 재현 고정 → 근본원인 추적 → 최소 수정 → 회귀 테스트
/finish-branch브랜치 마무리: 전체 테스트 → drift 확인 → PR 생성/로컬 머지/보류
/improve자기개선 루프 1회전 — 진단 프로브 → 후보 → 기존 게이트 오케스트레이션
/plan-review(iac 프로파일) terraform plan diff 리뷰 게이트 — 정책·smoke·drift
/rollout(ops 프로파일) 라이브 k8s 변경 안전 루프 — 관측→승인→롤백→health
/progress진행 대시보드(phase, 기능, 최근 피드백) + 다음 액션 제안
/sync-docs코드-문서 drift 감지 (--deep: 1M 컨텍스트 전수 교차 검사)

자연어로 말해도 됩니다 — CLAUDE.md의 라우팅 테이블이 의도를 분기합니다: "왜 안 되지?" → /debug · "구현해줘" → /implement · "작업 끝났어" → /finish-branch

프로세스 방법론(brainstorm/TDD/debug/finish-branch)은 obra/superpowers에서 선택적으로 채택했습니다. inline self-review는 독립 evaluator를 유지하기 위해 의도적으로 채택하지 않았습니다 — 근거는 ADR-003.

Hooks (7개)

plugin 설치 시 hooks.json으로 네이티브 등록됩니다 — settings.json 수정 불필요:

EventHook동작
SessionStartsetup-claudemd.shrules 복사·갱신, CLAUDE.md 섹션 세팅(멱등), 버전 업그레이드 마이그레이션
SessionStartsession-context.sh브랜치·phase·미완료 기능·handoff 주입 + agent-comms 아카이빙
PreToolUse (Bash)pre-bash-firewall.sh파괴적 명령 deny / 복구 가능한 위험 명령 ask
PreToolUse (Edit|Write)invariant-guard.sh검증 장치 약화(임계값 하향·deny 삭제·테스트 삭제) 차단 (INVARIANTS.md)
PostToolUsepost-edit-format.sh자동 포맷팅 (gofmt, prettier, swiftformat, ktlint, dart 등)
Stoppre-commit-gate.sh변경 언어별 테스트 + 커버리지 기록 + 시크릿 스캔 (동일 트리 재실행 skip 캐시)
Stopsession-handoff.sh세션 상태 저장 (draft 병합 → 다음 세션 주입)

hooks/lib.sh는 이벤트 훅이 아니라 위 훅들이 공유하는 라이브러리(cfg_get·version_lt·harness_cd)입니다.

Firewall 2-tier 정책:

  • deny: 루트/홈/시스템 디렉토리 rm, git push --force(--force-with-lease는 허용), pipe-to-shell(중간 파이프 우회 포함), fork bomb, DROP TABLE, eval/명령치환 우회 등
  • ask: git reset --hard, git clean -f 등 정상 워크플로우에서 쓰이지만 uncommitted 변경을 잃을 수 있는 명령 — 차단 대신 사용자 확인

Rules (11개)

Path-scoped 규칙 — 해당 파일 작업 시에만 로드:

general · go-backend · react-frontend · k8s-infra · proto-api · ios-swift · android-kotlin · react-native · flutter-dart · spring-boot · unity3d

자동으로 작동하는 것들

claude 실행만 하면 아래가 전부 자동입니다:

이벤트동작
세션 시작브랜치, phase, 미완료 기능, 이전 세션 handoff, 마지막 evaluator 피드백 주입
코드 편집언어별 포맷터 자동 실행
Bash 실행파괴적 명령 deny / 위험 명령 ask
세션 종료변경 파일 언어별 테스트 + 커버리지 기록(progress/coverage-report.json) + 시크릿 스캔, 상태 저장
plugin 업데이트버전 감지 → 마이그레이션 + 미수정 rules 자동 갱신 (수정본 보존)

업그레이드

plugin 업데이트(/plugin → Installed) 후 첫 세션에서 자동 마이그레이션됩니다:

  • .claude/.cc-harness-installed의 설치 버전과 비교 — 같으면 아무 작업 안 함 (세션 비용 0)
  • rules는 sha256 manifest로 pristine 판별 — 수정하지 않은 파일만 새 버전으로 갱신, 수정본은 보존 + 안내
  • v1.4 이하에서 복사된 .claude/agents|skills|hooks 중복본은 자동 정리 (과거 릴리스 해시로 pristine 식별, 커스터마이징은 보존)
  • {이전} → {새 버전} 전환 내역을 세션 시작 시 출력

한 repo가 여러 라이프사이클을 겸하면 harness-config.json의 "profiles": ["iac","ops"] 배열로 동시 적용할 수 있습니다(워크플로우 섹션이 연결 주입됨).

상세: ADR-002 (versioned upgrade), ADR-001 (plugin-native loading)

Plugin vs Bootstrapper

Plugin (/plugin install)Bootstrapper (npx cc-harness)
agents (8) / skills (11) / hooks (7)O — 네이티브 로딩 (업데이트 즉시 반영)O — .claude/ 복사
rules (11)O — .claude/rules/ 복사O — 프리셋 기반 선택
settings.json불필요 (hooks.json 네이티브)O
progress/ · docs/ · evals/ · Makefile · CLAUDE.md 스캐폴딩CLAUDE.md 섹션만O
프리셋 선택-O

Plugin — 기존 프로젝트에 즉시 적용, 업데이트 자동 전파. Bootstrapper — 새 프로젝트 전체 스캐폴딩.

Presets (Bootstrapper)

Preset포함 항목사용 예
go-minimalGo rules + hooksGo 단일 서비스
go-k8sGo + K8s + deploy agentGo 마이크로서비스
fullstackGo + React + iOS + Android + K8s + Proto폴리글랏 모노레포
mobileReact Native + Flutter모바일 전용
unityUnity3D + C# + mcp-unity게임 개발
custom대화형 선택맞춤 구성
npx cc-harness --preset fullstack --name my-project
npx cc-harness --preset go-minimal --force    # 기존 .claude/ 덮어쓰기
npx cc-harness --update                       # 기존 설치 업데이트

커스터마이징

규칙 추가

cat > .claude/rules/my-rule.md << 'EOF'
---
paths:
  - "src/special/**/*.go"
---
# Special Directory Rules
- 이 디렉토리는 특별한 규칙을 따른다
EOF

plugin이 관리하는 기본 rules를 수정해도 됩니다 — 업그레이드 시 수정본은 덮어쓰지 않고 보존됩니다.

Skill 추가

mkdir -p .claude/skills/deploy-checklist
cat > .claude/skills/deploy-checklist/SKILL.md << 'EOF'
---
name: deploy-checklist
description: "배포 전 체크리스트. TRIGGER: '배포 준비', 'deploy checklist' 요청 시 실행."
---
# Deploy Checklist
1. 모든 테스트 통과 확인
2. staging 배포 및 스모크 테스트
EOF

description의 TRIGGER 문구가 자연어 자동 라우팅의 단서가 됩니다.

Hook 추가

프로젝트 전용 훅은 .claude/settings.json에 추가합니다 (plugin 훅과 공존):

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "mcp__github__create_pull_request",
      "hooks": [{ "type": "command", "command": "bash \"${CLAUDE_PROJECT_DIR}/.claude/hooks/pre-pr-test.sh\"" }]
    }]
  }
}

채점 임계값 조정

progress/harness-config.json:

{
  "scoring": {
    "pass_threshold": 7,
    "security_thresholds": { "critical": 7, "standard": 5, "low": 3 }
  },
  "agent_comms": { "max_files_per_type": 10, "archive_enabled": true }
}

Improvement Loop

harness 자체도 실패에서 배웁니다:

실패 패턴해결 위치
반복되는 코딩 실수.claude/rules/에 규칙 추가, progress/lessons.md에 교훈 축적
evaluator 오판 (통과시켰는데 버그)evals/calibration/false-positives.json에 기록 → 이후 채점 보정
위험 명령어 통과pre-bash-firewall.sh에 패턴 추가 (bats 테스트와 함께)
포맷팅 누락post-edit-format.sh에 케이스 추가
반복 참조하는 절차.claude/skills/에 스킬 추가
컨텍스트 오염sub-agent로 작업 격리, 세션 간 인계는 handoff가 담당

설계 결정 (ADRs)

ADR결정
ADR-001agents/skills/hooks 복사 → plugin 네이티브 로딩 (이중 등록 제거, v1.5.0)
ADR-002버전 기록 + hash manifest 기반 업그레이드 프로세스 (v1.5.0)
ADR-003superpowers 방법론 선택적 채택 — 독립 evaluator는 유지 (v1.6.0)

Background

이 프로젝트는 다음 자료들의 best practice를 하나의 실행 가능한 harness로 통합한 것입니다:

Requirements

  • git — 프로젝트가 git repository여야 합니다
  • jq — 권장. 없으면 bash firewall이 비활성화되고(경고 출력) 세션 컨텍스트 주입이 축소됩니다
  • bash 3.2+ (hooks), 4.0+ (bootstrapper)
  • 각 언어 도구 (선택 — 없으면 해당 hook이 graceful skip)
  • 개발 시: bats, shellcheck (테스트 273개, CI에서 강제)

License

MIT

Ver o original no GitHub

Bom para

Relacionados