diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index e6d0b9a..ea35850 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "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용 팀 아키텍처 팩토리: 도메인 한 문장을 에이전트 팀과 스킬 세트로 변환하는 메타 스킬.", + "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용 팀 아키텍처 팩토리: 도메인 한 문장을 에이전트 팀과 스킬 세트로 변환하는 메타 스킬. Nhà máy kiến trúc đội cho Claude Code: meta-skill chuyển một câu mô tả lĩnh vực thành đội agent và bộ skill, với 6 mẫu kiến trúc đội định nghĩa sẵn (Pipeline, Fan-out/Fan-in, Expert Pool, Producer-Reviewer, Supervisor, Hierarchical Delegation).", "version": "1.2.0", "author": { "name": "robin", diff --git a/CHANGELOG.md b/CHANGELOG.md index 1be8060..8b87a0e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,18 +1,18 @@ # Changelog -이 프로젝트는 [Semantic Versioning](https://semver.org/)을 따릅니다. +Dự án này tuân theo [Semantic Versioning](https://semver.org/). ## [Unreleased] ### Added -- 신규 에이전트/스킬 생성 전 중복 검토 단계 (Phase 3-0, Phase 4-0) -- `references/agent-design-patterns.md` "에이전트 재사용 설계" 섹션 -- `references/skill-writing-guide.md` §9 "스킬 재사용 설계" +- Bước kiểm tra trùng lặp trước khi tạo agent/skill mới (Phase 3-0, Phase 4-0) +- Mục "Thiết kế tái sử dụng agent" trong `references/agent-design-patterns.md` +- §9 "Thiết kế tái sử dụng skill" trong `references/skill-writing-guide.md` ### Changed -- Phase 선택 매트릭스에 3-0/4-0 명시 -- Phase 2-3에 재사용 검토 단계 포인터 추가 -- 산출물 체크리스트에 재사용 검토 항목 2개 추가 +- Bổ sung rõ 3-0/4-0 vào ma trận chọn Phase +- Thêm con trỏ tới bước kiểm tra tái sử dụng vào Phase 2-3 +- Thêm 2 hạng mục kiểm tra tái sử dụng vào checklist đầu ra --- @@ -20,85 +20,85 @@ ### 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 참조) +- **Đồng bộ tính nhất quán phiên bản** — Badge của README.md / README_KO.md / README_JA.md ghi `v1.0.1`, `.claude-plugin/marketplace.json` ghi `1.1.0`, `.claude-plugin/plugin.json` ghi `1.2.0` → lệch nhau ba chỗ → thống nhất tất cả về **v1.2.0** (theo plugin.json) +- **Chuẩn bị giải quyết tình trạng 0 tagged release** — Lập kế hoạch gắn tag truy hồi v1.0.0 / v1.0.1 / v1.1.0 / v1.2.0 (xem `_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 응답 정책** — 커뮤니티 이슈에 대한 공식 응답 템플릿 및 트리아지 프로세스 추가 +- **Tuyên bố định vị: "nhà máy harness" (harness factory)** — Đưa câu tự định nghĩa danh mục lên đầu README. Chiếm lĩnh danh mục với "nhà máy harness chuyên đúc agent + skill theo từng lĩnh vực" (tạo khác biệt so với các framework đơn agent/prompt) +- **CONTRIBUTING.md** — Hướng dẫn đóng góp và quy định SLA (phản hồi PR lần đầu trong 72h, phân loại Issue trong 48h). Giải quyết rào cản onboarding cộng đồng +- **Thư mục docs/** — Tạo không gian mới để di chuyển tài liệu dài hạn (kiến trúc, migration, danh mục pattern). Tránh README quá dài và tăng khả năng tìm kiếm +- **Chính sách phản hồi Issue #3** — Thêm template phản hồi chính thức và quy trình phân loại cho issue từ cộng đồng ### 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종 추가) +- Version trong `.claude-plugin/marketplace.json`: `1.1.0` → `1.2.0` +- Badge README (cả 3 bản EN/KO/JA): `Version-1.0.1` → `Version-1.2.0` +- **Viết lại description trong `.claude-plugin/plugin.json`** — `"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..."` (song ngữ EN+KO, phản ánh định vị L3 Meta-Factory) +- **Mở rộng keywords trong `.claude-plugin/plugin.json`** — từ 5 lên 17 (`harness-factory`, `team-architecture-factory`, `claude-code-plugin`, `agent-scaffolding`, `multi-agent`, thêm 6 keyword cho 6 mẫu kiến trúc) ## [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 오케스트레이터 역할 분담표 삭제** — 포인터 정책으로 단순화되어 표 자체가 불필요해짐 +- **Đơn giản hóa chính sách đăng ký CLAUDE.md (loại bỏ trùng lặp)** — Chuyển Phase 5-4 "đăng ký ngữ cảnh" thành "đăng ký con trỏ". Loại bỏ danh sách agent, danh sách skill, cấu trúc thư mục, chi tiết quy tắc thực thi khỏi CLAUDE.md, chỉ giữ lại **quy tắc trigger + lịch sử thay đổi**. Danh sách agent/skill được quản lý tập trung tại `.claude/agents/`, `.claude/skills/` và skill orchestrator +- **Xóa bước đồng bộ tạm thời ở Phase 3/4** — Loại bỏ chỉ thị đồng bộ tạm thời ở Phase 3/4 để giảm gánh nặng đồng bộ CLAUDE.md. Đăng ký con trỏ cuối cùng chỉ thực hiện một lần tại Phase 5-4 +- **Định nghĩa lại nguyên tắc cốt lõi số 3** — "Đăng ký ngữ cảnh harness vào CLAUDE.md" → "Đăng ký con trỏ harness vào CLAUDE.md" +- **Xóa bảng phân chia vai trò CLAUDE.md vs orchestrator** — Không còn cần thiết do chính sách con trỏ đã đơn giản hóa ### Added -- **Phase 2-1: 하이브리드 실행 모드** — 에이전트 팀 / 서브 에이전트에 더해 Phase별로 모드를 섞는 하이브리드 패턴 추가. 자주 쓰이는 조합(병렬 수집→합의 통합, 팀 생성→검증, Phase 간 팀 재구성) 명시 -- **Phase 2-1 실행 모드 비교표** — 팀/서브/하이브리드 3종 특성 및 의사결정 순서 3단계 제공 -- **Phase 5-0 하이브리드 오케스트레이터 패턴** — 하이브리드 구성 시 각 Phase 상단에 실행 모드를 명시하는 규칙 -- **Phase 5-1 반환값 기반 데이터 전달** — 서브 에이전트 모드 전용 데이터 전달 전략 추가 (기존 메시지/태스크/파일 + 반환값) -- **Phase 5-1 권장 조합 (서브/하이브리드)** — 팀 모드 외 서브 모드와 하이브리드에서의 데이터 전달 권장 조합 명시 +- **Phase 2-1: Chế độ thực thi lai (hybrid)** — Bổ sung mẫu lai trộn chế độ theo từng Phase, ngoài agent team / subagent. Quy định rõ các tổ hợp thường dùng (thu thập song song → hợp nhất đồng thuận, tạo team → kiểm định, tái cấu trúc team giữa các Phase) +- **Bảng so sánh chế độ thực thi Phase 2-1** — Cung cấp đặc điểm của 3 chế độ team/sub/hybrid và quy trình quyết định 3 bước +- **Mẫu orchestrator lai ở Phase 5-0** — Quy tắc ghi rõ chế độ thực thi ở đầu mỗi Phase khi cấu hình lai +- **Truyền dữ liệu dựa trên giá trị trả về ở Phase 5-1** — Thêm chiến lược truyền dữ liệu riêng cho chế độ subagent (bên cạnh message/task/file hiện có) +- **Tổ hợp khuyến nghị Phase 5-1 (sub/hybrid)** — Quy định rõ tổ hợp truyền dữ liệu khuyến nghị cho chế độ sub và hybrid, ngoài chế độ team ## [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 템플릿에 후속 작업 키워드 패턴 포함 +- **Phase 0: Kiểm tra hiện trạng** — Khi trigger, kiểm tra trạng thái harness hiện có trước, sau đó định tuyến vào 1 trong 3 nhánh: xây mới / mở rộng harness có sẵn / vận hành-bảo trì +- **Ma trận chọn Phase cho mở rộng harness có sẵn** — Bảng quyết định chỉ rõ Phase cần thiết theo từng trường hợp thêm agent/thêm skill/đổi kiến trúc +- **Đồng bộ tạm thời CLAUDE.md ở Phase 3/4** — Cập nhật ngay vào CLAUDE.md sau khi tạo agent/skill (chịu được gián đoạn phiên làm việc) +- **Phase 5-4: Đăng ký ngữ cảnh harness vào CLAUDE.md** — Ghi lại cấu trúc đội agent, danh sách skill, quy tắc thực thi, cấu trúc thư mục, lịch sử thay đổi. Bao gồm bảng phân chia vai trò CLAUDE.md vs orchestrator +- **Phase 5-5: Hỗ trợ công việc tiếp theo** — Description của orchestrator phải có từ khóa tiếp nối, dùng bước kiểm tra ngữ cảnh ở Phase 0 để tự phân biệt giữa khởi tạo/chạy lại một phần/chạy mới +- **Đường mở rộng orchestrator ở Phase 5** — Hướng dẫn sửa orchestrator có sẵn thay vì tạo mới khi mở rộng +- **Phase 7: Cơ chế tiến hóa harness** — Thu thập phản hồi sau khi thực thi → ánh xạ loại phản hồi sang đối tượng cần sửa → ghi lịch sử thay đổi → trigger tiến hóa tự động +- **Phase 7-5: Quy trình vận hành/bảo trì** — 4 bước: kiểm tra hiện trạng → sửa từng phần → đồng bộ CLAUDE.md → xác minh thay đổi +- **Trigger vận hành/bảo trì trong description** — Từ khóa 'kiểm tra harness', 'audit harness', 'hiện trạng harness', 'đồng bộ agent/skill' +- **Tăng cường checklist đầu ra** — Thêm hạng mục hoàn tất đồng bộ CLAUDE.md, ghi lịch sử thay đổi, kiểm tra ngữ cảnh Phase 0 +- Thêm Phase 0 (kiểm tra ngữ cảnh) vào template orchestrator — áp dụng cho cả chế độ agent team và subagent +- Thêm mẫu từ khóa công việc tiếp theo vào template description của orchestrator ### Changed -- 핵심 원칙 2개 → 4개로 확장 (CLAUDE.md 등록, 진화 시스템 추가) -- **"진화 로그" → "변경 이력" 통일** — 이름과 스키마(4컬럼: 날짜/변경내용/대상/사유)를 전 섹션에서 일원화 -- **Phase 1 Step 3** — Phase 0 감사 결과를 기반으로 충돌 분석하도록 변경 (중복 제거) -- **5-4 CLAUDE.md 템플릿 코드 블록** — 중첩 렌더링 깨짐 수정 (3백틱→4백틱) -- **역할 분담표 확장** — 스킬 목록, 디렉토리 구조, 변경 이력 행 추가 -- **오케스트레이터 템플릿** — Phase 0 컨텍스트 확인 단계, 후속 작업 키워드 가이드 추가 +- Mở rộng nguyên tắc cốt lõi từ 2 lên 4 (thêm đăng ký CLAUDE.md, hệ thống tiến hóa) +- **Thống nhất "nhật ký tiến hóa" → "lịch sử thay đổi"** — Đồng nhất tên và schema (4 cột: ngày/nội dung thay đổi/đối tượng/lý do) trên toàn bộ section +- **Phase 1 Step 3** — Đổi sang phân tích xung đột dựa trên kết quả kiểm tra Phase 0 (loại bỏ trùng lặp) +- **Code block template CLAUDE.md ở 5-4** — Sửa lỗi vỡ render lồng nhau (3 backtick → 4 backtick) +- **Mở rộng bảng phân chia vai trò** — Thêm dòng danh sách skill, cấu trúc thư mục, lịch sử thay đổi +- **Template orchestrator** — Thêm bước kiểm tra ngữ cảnh Phase 0, hướng dẫn từ khóa công việc tiếp theo ## [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 포인터 +- Loại bỏ nội dung trùng lặp giữa SKILL.md ↔ references (330 dòng → 285 dòng) + - Phase 2-1: Bảng so sánh/bullet chế độ thực thi → nguyên tắc cốt lõi + con trỏ tới agent-design-patterns.md + - Phase 2-3: Bullet tiêu chí tách agent → tổng hợp 4 trục + con trỏ tới agent-design-patterns.md + - Phase 3: Code block template định nghĩa agent → liệt kê section bắt buộc + con trỏ references + - Phase 5-2: Bảng xử lý lỗi 5 dòng → nguyên tắc cốt lõi + con trỏ tới orchestrator-template.md ## [1.0.0] - 2026-03-27 ### Added -- 6 Phase 워크플로우 기반 하네스 구성 메타 스킬 -- 6가지 에이전트 아키텍처 패턴 (파이프라인, 팬아웃/팬인, 전문가 풀, 생성-검증, 감독자, 계층적 위임) -- 에이전트 팀 / 서브 에이전트 실행 모드 지원 -- Progressive Disclosure 기반 스킬 생성 가이드 -- 오케스트레이터 템플릿 (에이전트 팀 모드 + 서브 에이전트 모드) -- QA 에이전트 통합 가이드 (실제 프로젝트 7개 버그 사례 기반) -- 스킬 테스트/평가 방법론 (With-skill vs Without-skill 비교) -- 실전 팀 구성 예시 5종 (리서치, 소설, 웹툰, 코드리뷰, 마이그레이션) +- Meta-skill cấu hình harness dựa trên quy trình 6 Phase +- 6 mẫu kiến trúc agent (pipeline, fan-out/fan-in, expert pool, producer-reviewer, supervisor, hierarchical delegation) +- Hỗ trợ chế độ thực thi agent team / subagent +- Hướng dẫn sinh skill dựa trên Progressive Disclosure +- Template orchestrator (chế độ agent team + chế độ subagent) +- Hướng dẫn tích hợp agent QA (dựa trên 7 case bug thực tế từ dự án thật) +- Phương pháp kiểm thử/đánh giá skill (so sánh With-skill vs Without-skill) +- 5 ví dụ cấu hình đội thực chiến (nghiên cứu, tiểu thuyết, webtoon, code review, migration) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f30728b..9a00f12 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,154 +1,154 @@ -# Contributing to Harness +# Đóng góp cho Harness -Thanks for considering a contribution to **Harness** — a Claude Code meta-skill factory that designs agent teams and generates skills. +Cảm ơn bạn đã xem xét đóng góp cho **Harness** — một nhà máy meta-skill của Claude Code chuyên thiết kế đội agent và sinh skill. -This document covers: response SLAs, how to contribute, development setup, PR conventions, commit message rules, code of conduct, and maintainer list. +Tài liệu này bao gồm: SLA phản hồi, cách đóng góp, thiết lập môi trường phát triển, quy ước PR, quy tắc commit message, code of conduct, và danh sách maintainer. --- -## Response SLA (commitments) +## SLA phản hồi (cam kết) -These are the maintainer response targets for this repository. They are **conservative** so that a small maintainer team can realistically keep them while scaling. +Đây là mục tiêu phản hồi của maintainer cho repo này. Các chỉ số này được đặt **bảo thủ** để một team maintainer nhỏ có thể thực hiện được khi quy mô tăng lên. -| Surface | Target | Notes | +| Bề mặt | Mục tiêu | Ghi chú | |---------|--------|-------| -| 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. | +| PR — phản hồi lần đầu | **< 72h** | Ngày làm việc. "Phản hồi lần đầu" nghĩa là tối thiểu một label + một comment xác nhận đã nhận PR. | +| Phân loại & gắn label Issue | **< 48h** | Mọi issue mới sẽ được bỏ label `needs-triage` và gắn label loại (`bug` / `enhancement` / `question` / `discussion`) trong 48h. | +| Xử lý bug (P0 / P1) | **< 14 ngày** | P0 = mất dữ liệu / an ninh / cài đặt bị hỏng. P1 = luồng phổ biến bị hỏng. P2/P3 theo dõi trên roadmap, không có SLA cứng. | +| Báo cáo bảo mật | **< 7 ngày** | Xác nhận ban đầu trong 7 ngày. Mục tiêu patch trong 30 ngày. Xem mục **Security** dưới đây cho kênh riêng tư. | +| Nhịp release | **mỗi 2 tuần** | Gắn tag hai tuần một lần, trừ khi không có gì để release. Fix P0 có thể phát hành patch ngoài lịch. | -If we miss an SLA, please feel free to ping the issue/PR — that is not rude, it is the agreed feedback loop. +Nếu chúng tôi trễ SLA, hãy ping vào issue/PR — điều đó không hề thất thố, đó là vòng phản hồi đã được thống nhất. --- -## How to Contribute +## Cách đóng góp -Different kinds of contributions go through different entry points. Pick the one that fits. +Mỗi loại đóng góp đi qua một điểm vào khác nhau. Chọn loại phù hợp. -### Bug report +### Báo cáo lỗi (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. +- Mở issue dùng form **Bug report** (`.github/ISSUE_TEMPLATE/bug_report.yml`). +- Bắt buộc: phiên bản Claude Code, trạng thái flag `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS`, bước tái hiện lỗi, kỳ vọng vs thực tế, OS. +- Tái hiện ngắn (< 30 dòng) là lý tưởng nhất. Nếu cần cả project để tái hiện, hãy link một fork công khai. -### Feature request +### Yêu cầu tính năng (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?). +- Mở issue dùng form **Feature request**. +- Chúng tôi mong có một đoạn ngắn "vấn đề này giải quyết điều gì". Nếu có đề xuất, hãy trình bày ở dạng sẵn sàng đưa vào PR (đề xuất này mở rộng/thay thế mẫu kiến trúc nào trong 6 mẫu?). -### Question +### Câu hỏi -- 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. +- Mở issue dùng form **Question**, **hoặc** mở thread trong [GitHub Discussions](https://github.com/revfactory/harness/discussions) nếu vấn đề còn mở. -### Discussion (RFC-sized ideas) +### Thảo luận (ý tưởng cỡ RFC) -- Prefer GitHub Discussions. Only promote to an issue once there is rough consensus on direction. +- Ưu tiên GitHub Discussions. Chỉ nâng lên issue khi đã có đồng thuận cơ bản về hướng đi. ### Pull Request -- See **Pull Request Guidelines** below. -- Small PRs merge faster. Anything > 400 lines of diff should probably have been a Discussion first. +- Xem **Hướng dẫn Pull Request** dưới đây. +- PR nhỏ được merge nhanh hơn. Diff > 400 dòng nên được thảo luận trước qua Discussion. -### Security +### Bảo mật -- 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). +- **Không** mở issue công khai cho bất kỳ điều gì có thể bị lợi dụng. +- Email: `robin.hwang@kakaocorp.com` với tiền tố subject `[harness-security]`. +- Chúng tôi cố gắng xác nhận trong 7 ngày (xem bảng SLA). --- -## Development Setup +## Thiết lập môi trường phát triển -### Prerequisites +### Yêu cầu trước -- Claude Code `v2.x` (Agent Teams API required) -- Node.js `>= 18` (for local tooling used in CI) +- Claude Code `v2.x` (cần Agent Teams API) +- Node.js `>= 18` (cho tooling cục bộ dùng trong CI) - Git -### Environment flag +### Cờ môi trường -Harness currently requires Claude Code's experimental Agent Teams feature. Set the flag in your shell profile or per-session: +Hiện tại Harness yêu cầu tính năng Agent Teams thử nghiệm của Claude Code. Đặt cờ này trong shell profile hoặc theo phiên: ```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). +Chúng tôi theo dõi phụ thuộc này tại `docs/experimental-dependency.md` (nếu Anthropic chuyển cờ này thành stable, chúng tôi sẽ cập nhật README trong 72h theo SLA trên). -### Local plugin link +### Link plugin cục bộ -To test your changes in a local Claude Code session without publishing to the marketplace: +Để kiểm thử thay đổi của bạn trong một phiên Claude Code cục bộ mà không cần publish lên marketplace: ```bash -# From your checkout +# Từ checkout của bạn claude plugin link ./harness -# Verify +# Kiểm tra claude plugin list | grep harness ``` -Unlink with `claude plugin unlink harness` when you're done. +Unlink bằng `claude plugin unlink harness` khi xong. -### Running the meta-skill +### Chạy 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. +Agent và skill được scaffold sẽ nằm dưới `.claude/agents/` và `.claude/skills/` trong project đích. -### Tests & lints +### Test & lint - Markdown lint: `npx markdownlint '**/*.md'` -- YAML lint (issue templates & workflows): `npx yaml-lint .github/` -- Skill metadata validation: `python scripts/validate_skills.py` (if present) +- YAML lint (issue template & workflow): `npx yaml-lint .github/` +- Kiểm định metadata skill: `python scripts/validate_skills.py` (nếu có) -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. +CI chạy các bước này trên mọi PR. Khuyến khích chạy cục bộ nhưng không bắt buộc — chúng tôi sẽ không chặn merge với các lỗi CI phát hiện nhưng dễ sửa. --- -## Pull Request Guidelines +## Hướng dẫn Pull Request -### Branch naming +### Đặt tên branch -Use the `type/short-description` shape: +Dùng cấu trúc `type/short-description`: -| Prefix | Use for | Example | +| Tiền tố | Dùng cho | Ví dụ | |--------|---------|---------| -| `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` | +| `feat/` | Tính năng mới hiển thị với người dùng | `feat/expert-pool-variance-mode` | +| `fix/` | Sửa lỗi | `fix/agent-teams-flag-detection` | +| `docs/` | Chỉ thay đổi docs | `docs/quickstart-gemini-section` | +| `refactor/` | Tái cấu trúc nội bộ, không đổi hành vi | `refactor/skill-loader-split` | +| `chore/` | Build, dependency, dọn dẹp | `chore/upgrade-markdownlint` | +| `test/` | Chỉ test | `test/fan-out-fan-in-e2e` | -### Commit message language +### Ngôn ngữ commit message -- **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. +- **Cả tiếng Hàn và tiếng Anh đều được chấp nhận.** Viết bằng ngôn ngữ bạn diễn đạt chính xác hơn. +- Nếu thay đổi sẽ xuất hiện trong CHANGELOG hoặc release notes, vui lòng cũng cung cấp title tiếng Anh trong PR description để người đọc sau có thể theo dõi. -### PR template +### Template PR -Every PR body is pre-filled from `.github/PULL_REQUEST_TEMPLATE.md`. Please fill in: +Mọi nội dung PR được điền sẵn từ `.github/PULL_REQUEST_TEMPLATE.md`. Vui lòng điền: -- **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) +- **Tóm tắt** (cái gì & vì sao, 2–4 câu) +- **Động lực** (link issue, tham chiếu nghiên cứu, hoặc lý do 1 dòng) +- **Phạm vi thay đổi** (checklist các bề mặt bị ảnh hưởng) +- **Test** (bạn đã chạy/thêm gì) +- **CHANGELOG** (đã cập nhật `CHANGELOG.md` chưa? Y/N/NA) +- **Tác động SemVer** (patch / minor / major — xem mục tiếp theo) -### Review expectation +### Kỳ vọng review -- One approving review from a maintainer is required. -- We try to respond on PRs within 72h (see SLA). If you're blocked, ping. +- Cần ít nhất một review chấp thuận từ maintainer. +- Chúng tôi cố gắng phản hồi PR trong 72h (xem SLA). Nếu bị chặn, hãy ping. --- -## Commit Message Convention +## Quy ước Commit Message -We follow a light variant of **Conventional Commits** that maps directly to SemVer. +Chúng tôi theo một biến thể nhẹ của **Conventional Commits**, ánh xạ trực tiếp sang SemVer. ``` ()!: @@ -158,54 +158,54 @@ We follow a light variant of **Conventional Commits** that maps directly to SemV