diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 65aeb38..6e5e737 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -10,13 +10,13 @@ "name": "harness", "source": "./", "description": "에이전트 팀 & 스킬 아키텍트. 도메인/프로젝트에 맞는 하네스를 구성하고, 전문 에이전트를 정의하며, 에이전트가 사용할 스킬을 생성하는 메타 스킬.", - "version": "1.3.0" + "version": "1.3.1" }, { "name": "zio-harness", "source": "./plugins/zio-harness", "description": "React + Spring Boot + Mobile App 풀스택 개발 하네스. orchestrator·analyst·bot·agent 에이전트 팀이 기능 개발·테스트·배포를 파이프라인으로 처리. PROJECT_MAP.md로 폴더 구조를 세션 간 기억.", - "version": "1.0.0" + "version": "1.0.1" } ] } diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 7b55545..7c8d4f2 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "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.3.0", + "version": "1.3.1", "author": { "name": "ythong", "url": "https://git.zioinfo.co.kr/ythong" diff --git a/plugins/zio-harness/.claude-plugin/plugin.json b/plugins/zio-harness/.claude-plugin/plugin.json index a632fe8..7a3f612 100644 --- a/plugins/zio-harness/.claude-plugin/plugin.json +++ b/plugins/zio-harness/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "zio-harness", "description": "React + Spring Boot + Mobile App 풀스택 개발 하네스. orchestrator·analyst·bot·agent 에이전트 팀이 기능 개발·테스트·배포를 파이프라인으로 처리. PROJECT_MAP.md로 폴더 구조를 세션 간 기억.", - "version": "1.0.0", + "version": "1.0.1", "author": { "name": "ythong", "url": "https://git.zioinfo.co.kr/ythong" diff --git a/plugins/zio-harness/skills/zio-harness/SKILL.md b/plugins/zio-harness/skills/zio-harness/SKILL.md index a834c10..1e4da92 100644 --- a/plugins/zio-harness/skills/zio-harness/SKILL.md +++ b/plugins/zio-harness/skills/zio-harness/SKILL.md @@ -66,50 +66,61 @@ _workspace/ 존재 여부 확인 ### Phase 2: 팀 구성 +> **요구사항:** 팀 도구(`TeamCreate`/`SendMessage`/`TaskCreate`)는 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 플래그가 켜진 세션에서만 사용 가능하다. + +`TeamCreate`는 **빈 팀**을 만든다(`members` 인자 없음). 팀원은 `Agent` 도구로 `team_name`·`name`·`subagent_type`을 지정해 spawn한다. 오케스트레이터(이 스킬 세션)가 곧 팀 리더이며, 별도 팀원으로 만들지 않는다. + +1) 빈 팀 생성: + ``` -TeamCreate( - team_name: "zio-dev-team", - members: [ - { name: "analyst", agent_type: "analyst", model: "opus", - prompt: "PROJECT_MAP.md를 읽고 요청 분석 후 _workspace/00_analysis.md 작성. 구현 계획과 영향 파일 목록 포함." }, - { name: "agent", agent_type: "general-purpose", model: "opus", - prompt: "analyst의 계획을 읽고 코드 구현. React/Spring Boot/Mobile 스택에 맞는 컨벤션 준수." }, - { name: "bot", agent_type: "general-purpose", model: "opus", - prompt: "구현 완료 후 테스트 실행, 린트, 빌드 검증. 결과를 _workspace/02_bot_report.md에 기록." } - ] -) +TeamCreate(team_name: "zio-dev-team", description: "React+Spring Boot+Mobile 풀스택 개발") +``` + +2) 팀원 spawn (커스텀 에이전트 타입 analyst/agent/bot 사용): + +``` +Agent(subagent_type: "analyst", team_name: "zio-dev-team", name: "analyst", + prompt: "PROJECT_MAP.md를 읽고 요청 분석 후 _workspace/00_analysis.md 작성. 구현 계획과 영향 파일 목록 포함.") +Agent(subagent_type: "agent", team_name: "zio-dev-team", name: "agent", + prompt: "analyst의 계획을 읽고 코드 구현. React/Spring Boot/Mobile 스택에 맞는 컨벤션 준수.") +Agent(subagent_type: "bot", team_name: "zio-dev-team", name: "bot", + prompt: "구현 완료 후 테스트 실행·린트·빌드 검증. 결과를 _workspace/02_bot_report.md에 기록.") ``` 작업 유형별 팀 조정: -- **Analysis/DocMap**: analyst만 실행 (팀 불필요) -- **Test**: bot만 실행 +- **Analysis/DocMap**: analyst만 spawn (팀 불필요) +- **Test**: bot만 spawn - **Feature/Bug**: 전체 팀 파이프라인 ### Phase 3: 작업 등록 및 실행 +태스크는 **한 번에 하나씩** 생성한다(`subject`/`description`). 소유자는 `TaskUpdate`의 `owner`로, 의존성은 `blockedBy`로 지정한다: + ``` -TaskCreate(tasks: [ - { title: "프로젝트 분석 및 구현 계획 수립", assignee: "analyst", - description: "PROJECT_MAP.md 기반으로 영향 범위 파악. _workspace/00_analysis.md 작성." }, - { title: "코드 구현", assignee: "agent", - description: "_workspace/00_analysis.md 읽고 해당 스택 컨벤션으로 구현.", - depends_on: ["프로젝트 분석 및 구현 계획 수립"] }, - { title: "테스트 및 검증", assignee: "bot", - description: "구현 코드 테스트 실행. _workspace/02_bot_report.md 작성.", - depends_on: ["코드 구현"] } -]) +t1 = TaskCreate(subject: "프로젝트 분석 및 구현 계획 수립", + description: "PROJECT_MAP.md 기반으로 영향 범위 파악. _workspace/00_analysis.md 작성.") +TaskUpdate(task: t1, owner: "analyst") + +t2 = TaskCreate(subject: "코드 구현", + description: "_workspace/00_analysis.md 읽고 해당 스택 컨벤션으로 구현.") +TaskUpdate(task: t2, owner: "agent", blockedBy: [t1]) + +t3 = TaskCreate(subject: "테스트 및 검증", + description: "구현 코드 테스트 실행. _workspace/02_bot_report.md 작성.") +TaskUpdate(task: t3, owner: "bot", blockedBy: [t2]) ``` -팀원 간 통신 프로토콜: -- analyst → agent: `SendMessage` ("분석 완료. `_workspace/00_analysis.md` 참조. 구현 시작.") -- agent → bot: `SendMessage` ("구현 완료. 테스트 실행 요청.") -- bot → orchestrator: `SendMessage` ("검증 완료. `_workspace/02_bot_report.md` 참조.") +팀원 간 통신 프로토콜 — `SendMessage`는 `{to, summary, message}` 형식이며, 작업 완료는 `TaskUpdate`로 `completed` 처리하면 리더에게 자동 통지된다: +- analyst → agent: `SendMessage(to: "agent", summary: "분석 완료", message: "_workspace/00_analysis.md 참조. 구현 시작.")` +- agent → bot: `SendMessage(to: "bot", summary: "구현 완료", message: "테스트 실행 요청.")` +- 각 팀원: 작업 끝나면 `TaskUpdate(task, status: "completed")` → 리더(오케스트레이터)가 태스크 완료 알림과 `_workspace/` 파일로 진행 파악 (별도 보고 메시지 불필요) ### Phase 4: 결과 종합 및 PROJECT_MAP 업데이트 -1. `_workspace/02_bot_report.md` 확인 — 실패 항목 있으면 agent에 재작업 지시 +1. `_workspace/02_bot_report.md` 확인 — 실패 항목 있으면 agent에 재작업 지시(`SendMessage`) 2. 새 파일·폴더가 생성된 경우 `PROJECT_MAP.md` 업데이트 (`references/folder-map.md` 참조) 3. 변경 사항 요약을 사용자에게 보고 +4. 모든 작업 완료 후 팀원 종료(`SendMessage(to, message: {type: "shutdown_request"})`) → `TeamDelete`로 팀·태스크 정리 --- diff --git a/skills/harness/SKILL.md b/skills/harness/SKILL.md index 83a09c3..e6f6fc8 100644 --- a/skills/harness/SKILL.md +++ b/skills/harness/SKILL.md @@ -189,15 +189,16 @@ Phase 2-1에서 선택한 실행 모드에 따라 오케스트레이터 패턴 #### 5-0. 오케스트레이터 패턴 (모드별) **에이전트 팀 패턴 (기본):** -오케스트레이터가 `TeamCreate`로 팀을 구성하고, `TaskCreate`로 작업을 할당한다. 팀원들은 `SendMessage`로 직접 통신하며 자체 조율한다. 리더(오케스트레이터)는 진행 상황을 모니터링하고 결과를 종합한다. +오케스트레이터가 `TeamCreate`로 **빈 팀**을 만들고(`members` 인자 없음), `Agent` 도구로 `team_name`·`name`·`subagent_type`을 지정해 팀원을 spawn한다. 작업은 `TaskCreate`(개별 `subject`)로 만들고 `TaskUpdate`의 `owner`로 할당, `blockedBy`로 의존성을 건다. 팀원들은 `SendMessage`로 직접 통신하며 자체 조율한다. 리더(오케스트레이터)는 진행 상황을 모니터링하고 결과를 종합한다. (팀 도구는 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 필요.) ``` [오케스트레이터/리더] - ├── TeamCreate(team_name, members) - ├── TaskCreate(tasks with dependencies) + ├── TeamCreate(team_name) # 빈 팀 생성 + ├── Agent(subagent_type, team_name, name) ×N # 팀원 spawn + ├── TaskCreate(subject) + TaskUpdate(owner, blockedBy) # 작업 생성·할당·의존성 ├── 팀원들이 자체 조율 (SendMessage) ├── 결과 수집 및 종합 - └── 팀 정리 + └── SendMessage(shutdown_request) → TeamDelete # 팀 정리 ``` **서브 에이전트 패턴 (대안):** diff --git a/skills/harness/references/orchestrator-template.md b/skills/harness/references/orchestrator-template.md index df5023b..fb4cd45 100644 --- a/skills/harness/references/orchestrator-template.md +++ b/skills/harness/references/orchestrator-template.md @@ -54,29 +54,37 @@ description: "{도메인} 에이전트 팀을 조율하는 오케스트레이터 ### Phase 2: 팀 구성 -1. 팀 생성: + > **요구사항:** 팀 도구는 `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` 세션에서만 사용 가능. + +1. 빈 팀 생성 (`TeamCreate`는 `members` 인자를 받지 않음): ``` - TeamCreate( - team_name: "{domain}-team", - members: [ - { name: "{teammate-1}", agent_type: "{type}", model: "opus", prompt: "{역할 설명 및 작업 지시}" }, - { name: "{teammate-2}", agent_type: "{type}", model: "opus", prompt: "{역할 설명 및 작업 지시}" }, - ... - ] - ) + TeamCreate(team_name: "{domain}-team", description: "{팀 목적}") ``` -2. 작업 등록: +2. 팀원 spawn (`Agent` 도구에 `team_name`·`name`·`subagent_type` 지정): ``` - TaskCreate(tasks: [ - { title: "{작업1}", description: "{상세}", assignee: "{teammate-1}" }, - { title: "{작업2}", description: "{상세}", assignee: "{teammate-2}" }, - { title: "{작업3}", description: "{상세}", depends_on: ["{작업1}"] }, - ... - ]) + Agent(subagent_type: "{type}", team_name: "{domain}-team", name: "{teammate-1}", + prompt: "{역할 설명 및 작업 지시}") + Agent(subagent_type: "{type}", team_name: "{domain}-team", name: "{teammate-2}", + prompt: "{역할 설명 및 작업 지시}") + ... + ``` + > 오케스트레이터 자신이 팀 리더이므로 팀원으로 spawn하지 않는다. + +3. 작업 등록 — **한 번에 하나씩** 생성하고, 소유자는 `TaskUpdate.owner`, 의존성은 `TaskUpdate.blockedBy`로 지정: + ``` + t1 = TaskCreate(subject: "{작업1}", description: "{상세}") + TaskUpdate(task: t1, owner: "{teammate-1}") + + t2 = TaskCreate(subject: "{작업2}", description: "{상세}") + TaskUpdate(task: t2, owner: "{teammate-2}") + + t3 = TaskCreate(subject: "{작업3}", description: "{상세}") + TaskUpdate(task: t3, owner: "{teammate-1}", blockedBy: [t1]) + ... ``` - > 팀원당 5~6개 작업이 적정. 의존성이 있는 작업은 `depends_on`으로 명시. + > 팀원당 5~6개 작업이 적정. 의존성은 `TaskUpdate`의 `blockedBy`로 명시. ### Phase 3: {주요 작업 — 예: 조사/생성/분석} diff --git a/skills/harness/references/team-examples.md b/skills/harness/references/team-examples.md index 3c2850c..564ac90 100644 --- a/skills/harness/references/team-examples.md +++ b/skills/harness/references/team-examples.md @@ -36,18 +36,16 @@ Phase 1: 준비 - _workspace/ 생성 Phase 2: 팀 구성 - - TeamCreate(team_name: "research-team", members: [ - { name: "official", prompt: "공식 채널 조사..." }, - { name: "media", prompt: "미디어/투자 동향 조사..." }, - { name: "community", prompt: "커뮤니티 반응 조사..." }, - { name: "background", prompt: "배경/경쟁 환경 조사..." } - ]) - - TaskCreate(tasks: [ - { title: "공식 채널 조사", assignee: "official" }, - { title: "미디어 동향 조사", assignee: "media" }, - { title: "커뮤니티 반응 조사", assignee: "community" }, - { title: "배경 환경 조사", assignee: "background" } - ]) + - TeamCreate(team_name: "research-team", description: "다각도 리서치") # 빈 팀 + - Agent(subagent_type: "Explore", team_name: "research-team", name: "official", prompt: "공식 채널 조사...") + Agent(subagent_type: "Explore", team_name: "research-team", name: "media", prompt: "미디어/투자 동향 조사...") + Agent(subagent_type: "Explore", team_name: "research-team", name: "community", prompt: "커뮤니티 반응 조사...") + Agent(subagent_type: "Explore", team_name: "research-team", name: "background", prompt: "배경/경쟁 환경 조사...") + - 작업은 하나씩 생성 후 owner로 할당: + t = TaskCreate(subject: "공식 채널 조사"); TaskUpdate(task: t, owner: "official") + t = TaskCreate(subject: "미디어 동향 조사"); TaskUpdate(task: t, owner: "media") + t = TaskCreate(subject: "커뮤니티 반응 조사"); TaskUpdate(task: t, owner: "community") + t = TaskCreate(subject: "배경 환경 조사"); TaskUpdate(task: t, owner: "background") Phase 3: 조사 수행 - 4명의 팀원이 독립적으로 조사 @@ -151,8 +149,9 @@ description: "SF 소설의 세계관을 구축하는 전문가. 물리 법칙, ### 팀 워크플로우 상세 ``` -Phase 1: TeamCreate(team_name: "novel-team", members: [worldbuilder, character-designer, plot-architect]) - TaskCreate([세계관 구축, 캐릭터 설계, 플롯 구조]) +Phase 1: TeamCreate(team_name: "novel-team") # 빈 팀 + → Agent로 worldbuilder/character-designer/plot-architect spawn (team_name·name·subagent_type) + → 작업을 하나씩 TaskCreate(subject) + TaskUpdate(owner)로 등록 (세계관 구축/캐릭터 설계/플롯 구조) → 팀원들이 자체 조율하며 병렬 작업 → worldbuilder가 사회 구조 완성 시 character-designer에게 SendMessage → character-designer가 주인공 설정 시 plot-architect에게 SendMessage @@ -161,7 +160,7 @@ Phase 2: Phase 1 팀 정리 → prose-stylist를 서브 에이전트로 호출 ( prose-stylist가 _workspace/의 3개 산출물을 Read하여 집필 → 결과를 _workspace/02_prose_draft.md에 저장 -Phase 3: 새 팀 생성 — TeamCreate(team_name: "review-team", members: [science-consultant, continuity-manager]) +Phase 3: 새 팀 생성 — TeamCreate(team_name: "review-team") → Agent로 science-consultant·continuity-manager spawn (세션당 한 팀만 활성이지만, Phase 1 팀을 정리했으므로 새 팀 생성 가능) → 두 리뷰어가 draft를 검토, 서로 발견을 공유 → science-consultant가 물리 오류 발견 시 continuity-manager에게도 알림