From c25e55b64b5e432147abe64d209fcb8422487111 Mon Sep 17 00:00:00 2001 From: ythong Date: Wed, 17 Jun 2026 13:48:56 +0900 Subject: [PATCH] =?UTF-8?q?feat:=20harness=20+=20zio-harness=20Claude=20Co?= =?UTF-8?q?de=20=ED=94=8C=EB=9F=AC=EA=B7=B8=EC=9D=B8=20=EC=B4=88=EA=B8=B0?= =?UTF-8?q?=20=EB=B0=B0=ED=8F=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - harness: 도메인 한 줄 → 에이전트 팀 자동 생성 메타 스킬 (v1.2.0) - zio-harness: React + Spring Boot + Mobile 풀스택 개발 에이전트 팀 (v1.0.0) - 에이전트 4종: orchestrator / analyst / bot / agent - PROJECT_MAP.md 폴더 구조 메모리 시스템 - references/: react, spring-boot, mobile, playwright, database, folder-map Co-Authored-By: Claude Sonnet 4.6 --- .claude-plugin/marketplace.json | 22 + .claude-plugin/plugin.json | 31 + .github/ISSUE_TEMPLATE/bug_report.yml | 86 + .github/ISSUE_TEMPLATE/config.yml | 8 + .github/ISSUE_TEMPLATE/feature_request.yml | 62 + .github/ISSUE_TEMPLATE/question.yml | 35 + .github/PULL_REQUEST_TEMPLATE.md | 58 + .gitignore | 4 + CHANGELOG.md | 104 ++ CLAUDE.md | 63 + CONTRIBUTING.md | 211 +++ LICENSE | 190 +++ PROJECT_MAP.md | 163 ++ README.md | 302 ++++ README_JA.md | 305 ++++ README_KO.md | 298 ++++ docs/experimental-dependency.md | 153 ++ docs/quickstart.md | 117 ++ harness_banner.png | Bin 0 -> 2898052 bytes harness_icon.png | Bin 0 -> 1319022 bytes harness_social.png | Bin 0 -> 2526280 bytes harness_team.png | Bin 0 -> 2674796 bytes index.html | 1418 +++++++++++++++++ privacy.html | 90 ++ skills/harness/SKILL.md | 457 ++++++ .../references/agent-design-patterns.md | 300 ++++ .../references/orchestrator-template.md | 292 ++++ skills/harness/references/qa-agent-guide.md | 228 +++ .../harness/references/skill-testing-guide.md | 307 ++++ .../harness/references/skill-writing-guide.md | 298 ++++ skills/harness/references/team-examples.md | 328 ++++ skills/zio-harness/SKILL.md | 141 ++ skills/zio-harness/references/agent.md | 91 ++ skills/zio-harness/references/analyst.md | 87 + skills/zio-harness/references/bot.md | 111 ++ skills/zio-harness/references/database.md | 269 ++++ skills/zio-harness/references/folder-map.md | 142 ++ skills/zio-harness/references/mobile.md | 205 +++ skills/zio-harness/references/orchestrator.md | 67 + skills/zio-harness/references/playwright.md | 219 +++ skills/zio-harness/references/react.md | 160 ++ skills/zio-harness/references/spring-boot.md | 284 ++++ 42 files changed, 7706 insertions(+) create mode 100644 .claude-plugin/marketplace.json create mode 100644 .claude-plugin/plugin.json create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/ISSUE_TEMPLATE/question.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .gitignore create mode 100644 CHANGELOG.md create mode 100644 CLAUDE.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 PROJECT_MAP.md create mode 100644 README.md create mode 100644 README_JA.md create mode 100644 README_KO.md create mode 100644 docs/experimental-dependency.md create mode 100644 docs/quickstart.md create mode 100644 harness_banner.png create mode 100644 harness_icon.png create mode 100644 harness_social.png create mode 100644 harness_team.png create mode 100644 index.html create mode 100644 privacy.html create mode 100644 skills/harness/SKILL.md create mode 100644 skills/harness/references/agent-design-patterns.md create mode 100644 skills/harness/references/orchestrator-template.md create mode 100644 skills/harness/references/qa-agent-guide.md create mode 100644 skills/harness/references/skill-testing-guide.md create mode 100644 skills/harness/references/skill-writing-guide.md create mode 100644 skills/harness/references/team-examples.md create mode 100644 skills/zio-harness/SKILL.md create mode 100644 skills/zio-harness/references/agent.md create mode 100644 skills/zio-harness/references/analyst.md create mode 100644 skills/zio-harness/references/bot.md create mode 100644 skills/zio-harness/references/database.md create mode 100644 skills/zio-harness/references/folder-map.md create mode 100644 skills/zio-harness/references/mobile.md create mode 100644 skills/zio-harness/references/orchestrator.md create mode 100644 skills/zio-harness/references/playwright.md create mode 100644 skills/zio-harness/references/react.md create mode 100644 skills/zio-harness/references/spring-boot.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..162b872 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,22 @@ +{ + "name": "harness-marketplace", + "owner": { + "name": "ythong", + "email": "ythong86@gmail.com", + "url": "https://git.zioinfo.co.kr/ythong" + }, + "plugins": [ + { + "name": "harness", + "source": "./", + "description": "에이전트 팀 & 스킬 아키텍트. 도메인/프로젝트에 맞는 하네스를 구성하고, 전문 에이전트를 정의하며, 에이전트가 사용할 스킬을 생성하는 메타 스킬.", + "version": "1.2.0" + }, + { + "name": "zio-harness", + "source": "./skills/zio-harness", + "description": "React + Spring Boot + Mobile App 풀스택 개발 하네스. orchestrator·analyst·bot·agent 에이전트 팀이 기능 개발·테스트·배포를 파이프라인으로 처리. PROJECT_MAP.md로 폴더 구조를 세션 간 기억.", + "version": "1.0.0" + } + ] +} diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..1dbb253 --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,31 @@ +{ + "name": "harness", + "description": "The team-architecture factory for Claude Code — a meta-skill that turns a domain description into an agent team and the skills they use, with six pre-defined team-architecture patterns (Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor, Hierarchical Delegation). Claude Code용 팀 아키텍처 팩토리: 도메인 한 문장을 에이전트 팀과 스킬 세트로 변환하는 메타 스킬.", + "version": "1.2.0", + "author": { + "name": "ythong", + "url": "https://git.zioinfo.co.kr/ythong" + }, + "homepage": "https://git.zioinfo.co.kr/ythong/harness", + "repository": "https://git.zioinfo.co.kr/ythong/harness", + "license": "Apache-2.0", + "keywords": [ + "harness", + "harness-factory", + "team-architecture-factory", + "agent-team", + "skill-architect", + "meta-skill", + "orchestration", + "claude-code", + "claude-code-plugin", + "agent-scaffolding", + "multi-agent", + "pipeline", + "fan-out-fan-in", + "expert-pool", + "producer-reviewer", + "supervisor", + "hierarchical-delegation" + ] +} diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..b99b885 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,86 @@ +name: Bug report +description: Report a defect in Harness (unexpected behavior, crash, broken install, etc.) +title: "[bug] " +labels: ["bug", "needs-triage"] +assignees: + - revfactory +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to file a bug report. + + Before submitting, please skim open issues to avoid duplicates. + + **Triage SLA:** we aim to label new issues within 48h and respond substantively within 72h on business days (see [CONTRIBUTING.md](../../CONTRIBUTING.md)). + + - type: input + id: claude-code-version + attributes: + label: Claude Code version + description: Output of `claude --version` (e.g. `2.3.1`) + placeholder: "2.x.y" + validations: + required: true + + - type: dropdown + id: experimental-flag + attributes: + label: Experimental Agent Teams flag state + description: Is `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` set in the shell where you hit this bug? + options: + - "Yes, flag is set to 1" + - "No, flag is unset" + - "I don't know / N/A" + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Reproduction steps + description: Minimal steps to reproduce. Commands, config, and inputs please. + placeholder: | + 1. `claude plugin marketplace add harness@harness` + 2. `export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` + 3. `claude "build a harness for ..."` + 4. observe ... + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected behavior + description: What did you expect to happen? + validations: + required: true + + - type: textarea + id: actual + attributes: + label: Actual behavior + description: What actually happened? Include error messages / stack traces verbatim. + validations: + required: true + + - type: dropdown + id: os + attributes: + label: Operating system + options: + - "macOS" + - "Linux" + - "Windows (WSL)" + - "Windows (native)" + - "Other (describe below)" + validations: + required: true + + - type: textarea + id: context + attributes: + label: Additional context (optional) + description: Logs, screenshots, or anything else that might help. Redact anything sensitive. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..cd34d2e --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: GitHub Discussions — open-ended questions & RFCs + url: https://github.com/revfactory/harness/discussions + about: Prefer this for design discussions, ideas, "how should we think about X", and anything not yet actionable as an issue. + - name: Security disclosure (private) + url: mailto:robin.hwang@kakaocorp.com?subject=%5Bharness-security%5D + about: Report security issues privately. Acknowledgement within 7 days, patch target 30 days. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..ec2b397 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,62 @@ +name: Feature request +description: Propose a new capability or enhancement for Harness +title: "[feat] " +labels: ["enhancement", "needs-discussion"] +body: + - type: markdown + attributes: + value: | + Thanks for the idea. Features take a bit of back-and-forth — please help us with the "why" before the "what". + + For anything RFC-sized (new pattern family, runtime support, breaking API), consider starting in [GitHub Discussions](https://github.com/revfactory/harness/discussions) first. + + - type: textarea + id: problem + attributes: + label: What problem does this solve? + description: Describe the user or engineering pain point. Concrete scenario preferred. + placeholder: | + When I scaffold a team for ___, I end up manually ___ because ___. + validations: + required: true + + - type: textarea + id: proposal + attributes: + label: Proposed solution + description: Your idea for fixing it. Sketch API / CLI / workflow if relevant. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + description: What other approaches did you think about, and why did you not pick them? + validations: + required: false + + - type: dropdown + id: related-pattern + attributes: + label: Related team-architecture pattern (if any) + description: Which of the 6 built-in patterns is this most relevant to? + options: + - "Not pattern-specific" + - "Pipeline" + - "Fan-out / Fan-in" + - "Expert Pool" + - "Producer–Reviewer" + - "Supervisor" + - "Hierarchical Delegation" + - "A new pattern (please describe below)" + validations: + required: true + + - type: textarea + id: additional + attributes: + label: Additional context (optional) + description: Links, prior art, screenshots, anything else. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/question.yml b/.github/ISSUE_TEMPLATE/question.yml new file mode 100644 index 0000000..664ffe0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.yml @@ -0,0 +1,35 @@ +name: Question +description: Ask a how-to or clarification question about Harness +title: "[question] " +labels: ["question", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Questions are welcome. If your question is open-ended or invites discussion, [GitHub Discussions](https://github.com/revfactory/harness/discussions) is usually a better venue. + + We try to triage questions within 48h. + + - type: textarea + id: question + attributes: + label: Your question + description: What would you like to know? + validations: + required: true + + - type: textarea + id: tried + attributes: + label: What have you tried? + description: Commands run, docs read, related issues you've already found. + validations: + required: false + + - type: textarea + id: docs + attributes: + label: Related docs / links (optional) + description: Paste links to sections of the README, docs, or issues you've already read. + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..17ad83f --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,58 @@ + + +## Summary + + + +## Motivation + + + +- Closes # +- Related to # + +## Scope of change + + + +- [ ] Skill / meta-skill logic +- [ ] Agent template(s) +- [ ] Plugin manifest (`.claude-plugin/plugin.json`, `marketplace.json`) +- [ ] Documentation (`README.md`, `README_KO.md`, `README_JA.md`, `docs/`) +- [ ] `CHANGELOG.md` +- [ ] CI / GitHub Actions +- [ ] Tests +- [ ] Other (describe): + +## Tests + + + +- [ ] `npx markdownlint '**/*.md'` passes +- [ ] Manual repro of the change works as expected +- [ ] New unit / integration tests added (if applicable) +- [ ] N/A — explain below + +## CHANGELOG update + + + +- [ ] Yes — added to `CHANGELOG.md` +- [ ] No — this change is not user-visible (docs-only / internal refactor) + +## SemVer impact + + + +- [ ] **Patch** — bug fix, no API change (`fix:`) +- [ ] **Minor** — additive, backward-compatible (`feat:`) +- [ ] **Major** — breaking change (`feat!:` or `BREAKING CHANGE:` in commit footer) +- [ ] **None** — docs / chore / refactor / test + +## Additional notes + + diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..1d0262a --- /dev/null +++ b/.gitignore @@ -0,0 +1,4 @@ +.DS_Store +.claude/ +_workspace/ +*.pptx diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..1be8060 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,104 @@ +# Changelog + +이 프로젝트는 [Semantic Versioning](https://semver.org/)을 따릅니다. + +## [Unreleased] + +### Added +- 신규 에이전트/스킬 생성 전 중복 검토 단계 (Phase 3-0, Phase 4-0) +- `references/agent-design-patterns.md` "에이전트 재사용 설계" 섹션 +- `references/skill-writing-guide.md` §9 "스킬 재사용 설계" + +### Changed +- Phase 선택 매트릭스에 3-0/4-0 명시 +- Phase 2-3에 재사용 검토 단계 포인터 추가 +- 산출물 체크리스트에 재사용 검토 항목 2개 추가 + +--- + +## [1.2.1] - 2026-04-18 + +### Fixed + +- **버전 정합성 동기화** — README.md / README_KO.md / README_JA.md 뱃지가 `v1.0.1`, `.claude-plugin/marketplace.json`이 `1.1.0`, `.claude-plugin/plugin.json`이 `1.2.0`으로 3중 불일치 → 모두 **v1.2.0**으로 통일 (plugin.json 기준) +- **태그드 릴리스 0건 상태 해소 준비** — v1.0.0 / v1.0.1 / v1.1.0 / v1.2.0 소급 태그 계획 작성 (`_workspace/release/audit-2026-04-18.md` §4 참조) + +### Added + +- **포지셔닝 선언: "harness factory"** — README 상단에 카테고리 자기 규정 문구를 도입. "에이전트 + 스킬을 도메인별로 찍어내는 하네스 팩토리"로 카테고리 선점 (단일 에이전트/프롬프트 프레임워크 대비 차별화) +- **CONTRIBUTING.md** — 기여 가이드 및 SLA 명시 (PR 1차 응답 72h, Issue triage 48h). 커뮤니티 온보딩 장벽 해소 +- **docs/ 디렉토리** — 장기 문서(아키텍처, 마이그레이션, 패턴 카탈로그) 이전 공간 신설. README 비대화 방지 및 검색성 향상 +- **Issue #3 응답 정책** — 커뮤니티 이슈에 대한 공식 응답 템플릿 및 트리아지 프로세스 추가 + +### Changed + +- `.claude-plugin/marketplace.json` version: `1.1.0` → `1.2.0` +- README 뱃지 (EN/KO/JA 3종): `Version-1.0.1` → `Version-1.2.0` +- **`.claude-plugin/plugin.json` description 재작성** — `"Agent Team & Skill Architect — Meta-skill that designs..."` → `"The team-architecture factory for Claude Code — a meta-skill that turns a domain description into an agent team and the skills they use, with six pre-defined team-architecture patterns..."` (EN+KO 병기, L3 Meta-Factory 포지셔닝 반영) +- **`.claude-plugin/plugin.json` keywords 확장** — 5개 → 17개 (`harness-factory`, `team-architecture-factory`, `claude-code-plugin`, `agent-scaffolding`, `multi-agent`, 6패턴 키워드 6종 추가) + +## [1.2.0] - 2026-04-08 + +### Changed + +- **CLAUDE.md 등록 정책 간소화 (중복 제거)** — Phase 5-4 "컨텍스트 등록"을 "포인터 등록"으로 전환. 에이전트 목록·스킬 목록·디렉토리 구조·실행 규칙 상세를 CLAUDE.md에서 제거하고 **트리거 규칙 + 변경 이력**만 남김. 에이전트/스킬 목록은 `.claude/agents/`, `.claude/skills/` 및 오케스트레이터 스킬에서 단일 출처로 관리 +- **Phase 3/4 임시 동기화 단계 삭제** — CLAUDE.md 동기화 부담을 줄이기 위해 Phase 3/4의 임시 동기화 지시 제거. 최종 포인터 등록은 Phase 5-4에서 1회만 수행 +- **핵심 원칙 3번 재정의** — "CLAUDE.md에 하네스 컨텍스트를 등록한다" → "CLAUDE.md에 하네스 포인터를 등록한다" +- **CLAUDE.md vs 오케스트레이터 역할 분담표 삭제** — 포인터 정책으로 단순화되어 표 자체가 불필요해짐 + +### Added + +- **Phase 2-1: 하이브리드 실행 모드** — 에이전트 팀 / 서브 에이전트에 더해 Phase별로 모드를 섞는 하이브리드 패턴 추가. 자주 쓰이는 조합(병렬 수집→합의 통합, 팀 생성→검증, Phase 간 팀 재구성) 명시 +- **Phase 2-1 실행 모드 비교표** — 팀/서브/하이브리드 3종 특성 및 의사결정 순서 3단계 제공 +- **Phase 5-0 하이브리드 오케스트레이터 패턴** — 하이브리드 구성 시 각 Phase 상단에 실행 모드를 명시하는 규칙 +- **Phase 5-1 반환값 기반 데이터 전달** — 서브 에이전트 모드 전용 데이터 전달 전략 추가 (기존 메시지/태스크/파일 + 반환값) +- **Phase 5-1 권장 조합 (서브/하이브리드)** — 팀 모드 외 서브 모드와 하이브리드에서의 데이터 전달 권장 조합 명시 + +## [1.1.0] - 2026-04-05 + +### Added + +- **Phase 0: 현황 감사** — 트리거 시 기존 하네스 상태를 먼저 확인하고 신규 구축/기존 확장/운영·유지보수 3분기로 라우팅 +- **기존 확장 Phase 선택 매트릭스** — 에이전트 추가/스킬 추가/아키텍처 변경별 필요 Phase를 명시한 결정표 +- **Phase 3/4 CLAUDE.md 임시 동기화** — 에이전트·스킬 생성 직후 CLAUDE.md에 즉시 반영 (세션 중단 내성) +- **Phase 5-4: CLAUDE.md 하네스 컨텍스트 등록** — 에이전트 팀 구조·스킬 목록·실행 규칙·디렉토리 구조·변경 이력을 기록. CLAUDE.md vs 오케스트레이터 역할 분담표 포함 +- **Phase 5-5: 후속 작업 지원** — 오케스트레이터 description에 후속 키워드 필수 포함, Phase 0 컨텍스트 확인 단계로 초기/부분재실행/새실행 자동 판별 +- **Phase 5 오케스트레이터 수정 경로** — 기존 확장 시 오케스트레이터를 새로 만들지 않고 수정하는 가이드 +- **Phase 7: 하네스 진화 메커니즘** — 실행 후 피드백 수집 → 피드백 유형별 수정 대상 매핑 → 변경 이력 기록 → 자동 진화 트리거 +- **Phase 7-5: 운영/유지보수 워크플로우** — 현황 감사→점진적 수정→CLAUDE.md 동기화→변경 검증 4단계 +- **description에 운영/유지보수 트리거** — '하네스 점검', '하네스 감사', '하네스 현황', '에이전트/스킬 동기화' 키워드 +- **산출물 체크리스트 강화** — CLAUDE.md 동기화 완료, 변경 이력 기록, Phase 0 컨텍스트 확인 항목 추가 +- 오케스트레이터 템플릿에 Phase 0 (컨텍스트 확인) 추가 — 에이전트 팀/서브 에이전트 모드 모두 적용 +- 오케스트레이터 description 템플릿에 후속 작업 키워드 패턴 포함 + +### Changed + +- 핵심 원칙 2개 → 4개로 확장 (CLAUDE.md 등록, 진화 시스템 추가) +- **"진화 로그" → "변경 이력" 통일** — 이름과 스키마(4컬럼: 날짜/변경내용/대상/사유)를 전 섹션에서 일원화 +- **Phase 1 Step 3** — Phase 0 감사 결과를 기반으로 충돌 분석하도록 변경 (중복 제거) +- **5-4 CLAUDE.md 템플릿 코드 블록** — 중첩 렌더링 깨짐 수정 (3백틱→4백틱) +- **역할 분담표 확장** — 스킬 목록, 디렉토리 구조, 변경 이력 행 추가 +- **오케스트레이터 템플릿** — Phase 0 컨텍스트 확인 단계, 후속 작업 키워드 가이드 추가 + +## [1.0.1] - 2026-03-28 + +### Changed + +- SKILL.md ↔ references 간 중복 내용 제거 (330줄 → 285줄) + - Phase 2-1: 실행 모드 비교표/불릿 → 핵심 원칙 + agent-design-patterns.md 포인터 + - Phase 2-3: 에이전트 분리 기준 불릿 → 4축 요약 + agent-design-patterns.md 포인터 + - Phase 3: 에이전트 정의 템플릿 코드블록 → 필수 섹션 나열 + references 포인터 + - Phase 5-2: 에러 핸들링 5행 테이블 → 핵심 원칙 + orchestrator-template.md 포인터 + +## [1.0.0] - 2026-03-27 + +### Added + +- 6 Phase 워크플로우 기반 하네스 구성 메타 스킬 +- 6가지 에이전트 아키텍처 패턴 (파이프라인, 팬아웃/팬인, 전문가 풀, 생성-검증, 감독자, 계층적 위임) +- 에이전트 팀 / 서브 에이전트 실행 모드 지원 +- Progressive Disclosure 기반 스킬 생성 가이드 +- 오케스트레이터 템플릿 (에이전트 팀 모드 + 서브 에이전트 모드) +- QA 에이전트 통합 가이드 (실제 프로젝트 7개 버그 사례 기반) +- 스킬 테스트/평가 방법론 (With-skill vs Without-skill 비교) +- 실전 팀 구성 예시 5종 (리서치, 소설, 웹툰, 코드리뷰, 마이그레이션) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..dd6ab79 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,63 @@ +# harness-main — Claude Code 가이드 + +## 하네스: zio-harness (React + Spring Boot + Mobile) + +**목표:** React 프론트엔드 + Spring Boot 백엔드 + 모바일 앱 풀스택 개발을 에이전트 팀이 자동 조율한다. + +**트리거:** 기능 개발, 버그 수정, 테스트, 코드 분석, 폴더 구조 파악 요청 시 `zio-harness` 스킬을 사용하라. 단순 질문은 직접 응답 가능. + +**변경 이력:** +| 날짜 | 변경 내용 | 대상 | 사유 | +|------|----------|------|------| +| 2026-06-17 | zio-harness 초기 구성 | 전체 | React+SpringBoot+Mobile 풀스택 하네스 신규 생성 | + +--- + +## 하네스: harness (메타 스킬) + +**목표:** 새 도메인에 맞는 에이전트 팀과 스킬을 자동 생성하는 팩토리. + +**트리거:** "하네스 구성해줘", "에이전트 팀 설계해줘", 새 도메인 하네스 생성 요청 시 `harness` 스킬을 사용하라. + +--- + +## 폴더 구조 빠른 참조 + +``` +harness-main/ +├── .claude-plugin/ # 플러그인 매니페스트 +├── .claude/ +│ ├── agents/ # 에이전트 정의 파일 (4종) +│ │ ├── orchestrator.md # 전체 조율 +│ │ ├── analyst.md # 분석 + PROJECT_MAP 관리 +│ │ ├── bot.md # 테스트·빌드·자동화 +│ │ └── agent.md # 코드 구현 +│ └── skills/ # (추가 스킬 위치) +├── skills/ +│ ├── harness/ # 메타 하네스 스킬 +│ │ ├── SKILL.md +│ │ └── references/ # 패턴·템플릿·가이드 +│ └── zio-harness/ # 풀스택 개발 하네스 스킬 +│ ├── SKILL.md +│ └── references/ +│ ├── folder-map.md # PROJECT_MAP 생성 가이드 +│ ├── react.md # React 개발 패턴 +│ ├── spring-boot.md # Spring Boot 패턴 +│ ├── mobile.md # 모바일 앱 패턴 +│ ├── playwright.md # E2E 테스트 패턴 +│ ├── database.md # DB + MCP 패턴 +│ ├── orchestrator.md # 오케스트레이터 에이전트 가이드 +│ ├── analyst.md # 분석가 에이전트 가이드 +│ ├── bot.md # 봇 에이전트 가이드 +│ └── agent.md # 개발 에이전트 가이드 +└── _workspace/ # 에이전트 작업 중간 산출물 +``` + +## 핵심 파일 역할 + +| 파일 | 역할 | +|------|------| +| `PROJECT_MAP.md` (프로젝트 루트) | 폴더 구조 메모리 — 에이전트가 세션마다 읽는 기준 파일 | +| `skills/zio-harness/SKILL.md` | zio-harness 오케스트레이터 진입점 | +| `skills/harness/SKILL.md` | harness 메타 스킬 진입점 | +| `.claude/agents/*.md` | 에이전트 역할·원칙·통신 프로토콜 정의 | diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..f30728b --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,211 @@ +# Contributing to Harness + +Thanks for considering a contribution to **Harness** — a Claude Code meta-skill factory that designs agent teams and generates skills. + +This document covers: response SLAs, how to contribute, development setup, PR conventions, commit message rules, code of conduct, and maintainer list. + +--- + +## Response SLA (commitments) + +These are the maintainer response targets for this repository. They are **conservative** so that a small maintainer team can realistically keep them while scaling. + +| Surface | Target | Notes | +|---------|--------|-------| +| PR — 1st response | **< 72h** | Business days. A "1st response" means at minimum a label + one comment acknowledging the PR. | +| Issue triage & labeling | **< 48h** | Every new issue gets `needs-triage` removed and a type label (`bug` / `enhancement` / `question` / `discussion`) within 48h. | +| Bug resolve (P0 / P1) | **< 14d** | P0 = data loss / security / broken install. P1 = common path broken. P2/P3 tracked on roadmap without a hard SLA. | +| Security report | **< 7d** | Initial acknowledgement within 7 days. Patch target 30 days. Please see **Security** section below for the private channel. | +| Release cadence | **every 2 weeks** | Biweekly tag unless there is nothing shippable. P0 fixes may cut an off-schedule patch release. | + +If we miss an SLA, please feel free to ping the issue/PR — that is not rude, it is the agreed feedback loop. + +--- + +## How to Contribute + +Different kinds of contributions go through different entry points. Pick the one that fits. + +### Bug report + +- Open an issue using the **Bug report** form (`.github/ISSUE_TEMPLATE/bug_report.yml`). +- Required: Claude Code version, `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` flag state, reproduction steps, expected vs actual, OS. +- Small reproductions (< 30 lines) are ideal. If your repro needs a full project, link a public fork. + +### Feature request + +- Open an issue using the **Feature request** form. +- We expect a short "what problem does this solve" paragraph. If you have a proposal, put it in the PR-ready shape (which of the 6 team-architecture patterns does it extend / replace?). + +### Question + +- Open an issue using the **Question** form, **or** start a thread in [GitHub Discussions](https://github.com/revfactory/harness/discussions) if the matter is open-ended. + +### Discussion (RFC-sized ideas) + +- Prefer GitHub Discussions. Only promote to an issue once there is rough consensus on direction. + +### Pull Request + +- See **Pull Request Guidelines** below. +- Small PRs merge faster. Anything > 400 lines of diff should probably have been a Discussion first. + +### Security + +- Do **not** open a public issue for anything that could be abused. +- Email: `robin.hwang@kakaocorp.com` with subject prefix `[harness-security]`. +- We aim to acknowledge within 7 days (see SLA table). + +--- + +## Development Setup + +### Prerequisites + +- Claude Code `v2.x` (Agent Teams API required) +- Node.js `>= 18` (for local tooling used in CI) +- Git + +### Environment flag + +Harness currently requires Claude Code's experimental Agent Teams feature. Set the flag in your shell profile or per-session: + +```bash +export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 +``` + +We track this dependency in `docs/experimental-dependency.md` (if Anthropic promotes the flag to stable, we update the README within 72h per the SLA above). + +### Local plugin link + +To test your changes in a local Claude Code session without publishing to the marketplace: + +```bash +# From your checkout +claude plugin link ./harness + +# Verify +claude plugin list | grep harness +``` + +Unlink with `claude plugin unlink harness` when you're done. + +### Running the meta-skill + +```bash +claude "build a harness for a fintech risk-assessment team" +``` + +Scaffolded agents and skills land under `.claude/agents/` and `.claude/skills/` in the target project. + +### Tests & lints + +- Markdown lint: `npx markdownlint '**/*.md'` +- YAML lint (issue templates & workflows): `npx yaml-lint .github/` +- Skill metadata validation: `python scripts/validate_skills.py` (if present) + +CI runs these on every PR. Local execution is encouraged but not required — we won't block on CI-caught issues that are trivial to fix on merge. + +--- + +## Pull Request Guidelines + +### Branch naming + +Use the `type/short-description` shape: + +| Prefix | Use for | Example | +|--------|---------|---------| +| `feat/` | New user-visible capability | `feat/expert-pool-variance-mode` | +| `fix/` | Bug fix | `fix/agent-teams-flag-detection` | +| `docs/` | Docs-only changes | `docs/quickstart-gemini-section` | +| `refactor/` | Internal structure, no behavior change | `refactor/skill-loader-split` | +| `chore/` | Build, deps, housekeeping | `chore/upgrade-markdownlint` | +| `test/` | Tests only | `test/fan-out-fan-in-e2e` | + +### Commit message language + +- **Korean and English are both accepted.** Write in whichever you are more precise in. +- If the change will appear in the CHANGELOG or release notes, please also provide an English title in the PR description so downstream readers can follow. + +### PR template + +Every PR body is pre-filled from `.github/PULL_REQUEST_TEMPLATE.md`. Please fill in: + +- **Summary** (what & why, 2–4 sentences) +- **Motivation** (link issue, reference research, or 1-line rationale) +- **Scope of change** (checklist of touched surfaces) +- **Tests** (what you ran / added) +- **CHANGELOG** (did you update `CHANGELOG.md`? Y/N/NA) +- **SemVer impact** (patch / minor / major — see next section) + +### Review expectation + +- One approving review from a maintainer is required. +- We try to respond on PRs within 72h (see SLA). If you're blocked, ping. + +--- + +## Commit Message Convention + +We follow a light variant of **Conventional Commits** that maps directly to SemVer. + +``` +()!: + + + +