harness (template)

자연어 기능 요청을 결정론적 품질 게이트를 통해 출시 가능하고, 테스트되고, 관측 가능한 코드로 변환하는 Claude Code 하네스 템플릿.

이 저장소는 새 서비스의 시작점 입니다. GitHub에서 "Use this template" 으로 복제한 뒤 .claude/steering/*.md 를 해당 서비스에 맞게 채우세요.

필수 요구사항

• Node.js 20 LTS
• Claude Code (npm install -g @anthropic-ai/claude-code)
• jq (권장) — hook JSON 파싱에 사용. 없으면 node 폴백으로 느리게 동작.
• bash — hook 실행. Windows 는 Git Bash 또는 WSL.

빠른 시작 (새 서비스 첫 세션)

# 1. GitHub 에서 "Use this template" → 새 레포 생성 → clone
git clone <your-new-repo-url>
cd <new-repo>
npm install

# 2. steering 3개 파일 채우기 (제일 중요!)
#    - .claude/steering/product.md    새 서비스의 비전/사용자/성공지표
#    - .claude/steering/tech.md       스택 조정 (기본: TS+Fastify+Prisma)
#    - .claude/steering/structure.md  디렉터리 규칙

# 3. Claude Code 세션
claude
> /spec-requirements <첫 기능 한 줄 설명>
# 이후: /spec-design → /spec-tasks → /spec-implement

이 템플릿이 제공하는 것

• Steering (.claude/steering/) — 제품 비전, 기술 스택, 구조 규칙 (템플릿 상태 — 채워넣기 필요)
• Skills (.claude/skills/) — 4단계 스펙 파이프라인 + EARS, TDD, 검증, 리뷰
• Subagents (.claude/agents/) — 6개 역할 한정 에이전트
• Hooks (.claude/hooks/) — 파괴적 명령 / 경로 / 품질 게이트 훅
• Evals (.claude/evals/) — PR 회귀 테스트 (promptfoo 골든 세트)
• Observability — 일자별 JSONL 감사 로그, 주간 드리프트 감지
• 공용 인프라 (src/shared/) — errors, logger, db (Prisma + SQLite WAL), circuit

디렉터리 구조

.claude/
  steering/     — 항상 켜진 컨텍스트 (product, tech, structure)
  skills/       — 필요 시 호출되는 워크플로 (spec-*, ears-writer, tdd-loop, ...)
  agents/       — 역할 한정 서브에이전트
  hooks/        — 불변 규칙을 강제하는 셸 스크립트
  specs/        — 기능별 디렉터리 (requirements.md, design.md, tasks.md)
  evals/        — promptfoo 설정 + 골든 세트
  audit/        — 일자별 JSONL 로그 (gitignored)
  docs/         — harness-design.md (전체 아키텍처 레퍼런스)
src/
  shared/       — errors, logger, db, circuit (재사용 가능한 인프라)
  app.ts        — Fastify 부팅 + /health /ready + AppError 핸들링
  main.ts       — 엔트리포인트 + SIGTERM 우아한 종료
  modules/      — (비어있음) 기능 모듈 추가 자리
docs/adr/       — 아키텍처 결정 기록 (ADR)
scripts/        — drift-check.sh 등 유지보수 스크립트
.github/workflows/ — CI: promptfoo eval + drift check

절대 규칙 (훅으로 강제됨)

1. .env*, secrets/**, src/legacy/**, .git/** 편집 금지
2. 파괴적 명령 금지 (rm -rf, DROP TABLE, git push --force)
3. 열린 태스크가 있거나 테스트/린트/타입체크가 실패하면 세션 종료 금지
4. 모든 HTTP 핸들러는 경계에서 zod 로 입력 검증
5. 모든 새 동작은 실패하는 테스트가 먼저 작성되어야 함 (TDD)

전체 아키텍처는 .claude/docs/harness-design.md 참고.