From f744e4805b8814468c3c125e0d638baf5f51290e Mon Sep 17 00:00:00 2001 From: apple Date: Mon, 15 Jun 2026 00:22:05 +0800 Subject: [PATCH] feat: allow per-task model tiering instead of forcing opus Replace "always opus" with reasoning (opus) vs mechanical (sonnet) tiers across SKILL.md, agent-design-patterns, and orchestrator template. Closes #29. Co-authored-by: Cursor --- CHANGELOG.md | 6 ++++++ skills/harness/SKILL.md | 14 ++++++++++++-- skills/harness/references/agent-design-patterns.md | 7 ++++++- skills/harness/references/orchestrator-template.md | 8 ++++---- 4 files changed, 28 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1be8060..ecbbc5f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,13 @@ ## [Unreleased] ### Added +- 모델 tier 가이드 (reasoning→opus, mechanical→sonnet) — closes #29 - 신규 에이전트/스킬 생성 전 중복 검토 단계 (Phase 3-0, Phase 4-0) + +### Changed +- SKILL.md / agent-design-patterns / orchestrator-template: "always opus" → task-tier model selection +- 산출물 체크리스트: model tier 일치 검증 +- Phase 선택 매트릭스에 3-0/4-0 명시 - `references/agent-design-patterns.md` "에이전트 재사용 설계" 섹션 - `references/skill-writing-guide.md` §9 "스킬 재사용 설계" diff --git a/skills/harness/SKILL.md b/skills/harness/SKILL.md index 83a09c3..8dd7fcd 100644 --- a/skills/harness/SKILL.md +++ b/skills/harness/SKILL.md @@ -90,7 +90,17 @@ description: "하네스를 구성합니다. 전문 에이전트를 정의하며, 빌트인 타입(`general-purpose`, `Explore`, `Plan`)을 사용하더라도 에이전트 정의 파일은 생성한다. 빌트인 타입은 Agent 도구의 `subagent_type` 파라미터로 지정하고, 에이전트 정의 파일에는 역할·원칙·프로토콜을 담는다. -**모델 설정:** 모든 에이전트는 `model: "opus"`를 사용한다. Agent 도구 호출 시 반드시 `model: "opus"` 파라미터를 명시한다. 하네스의 품질은 에이전트의 추론 능력에 직결되며, opus가 최고 품질을 보장한다. +**모델 설정:** 에이전트 역할에 맞는 model tier를 사용한다. Agent 도구 호출 시 `model` 파라미터를 **반드시 명시**한다. + +| Tier | model | 적합한 역할 | +|------|-------|------------| +| **Reasoning** | `opus` | 설계·아키텍처·코드 생성·복잡한 분석·교차 검증·창작 | +| **Mechanical** | `sonnet` | 로그 파싱·포맷 변환·정적 파일 검사·배포 스크립트 실행·단순 수집 | + +- 기본값은 **Reasoning(opus)**. QA·writer·architect·validator는 opus 유지. +- IO 위주 collector·formatter·deploy-runner는 sonnet으로 비용/지연을 줄인다. +- 각 에이전트 `.md` frontmatter 또는 본문에 `model: opus|sonnet`을 명시한다. +- 오케스트레이터 TeamCreate/Agent 호출의 model은 에이전트 정의와 일치해야 한다. **팀 재구성:** 에이전트 팀은 세션당 한 팀만 활성화할 수 있지만, Phase 간에 팀을 해체하고 새 팀을 구성할 수 있다. 파이프라인 패턴처럼 Phase별로 다른 전문가 조합이 필요하면, 이전 팀의 산출물을 파일로 저장한 뒤 팀을 정리하고 새 팀을 생성한다. @@ -434,7 +444,7 @@ Phase마다 다른 모드를 섞어 구성한다. 자주 쓰이는 조합: - [ ] `프로젝트/.claude/skills/` — 스킬 파일들 (SKILL.md + references/) - [ ] 오케스트레이터 스킬 1개 (데이터 흐름 + 에러 핸들링 + 테스트 시나리오 포함) - [ ] 실행 모드 명시 (에이전트 팀 / 서브 에이전트 / 하이브리드 중 선택, 하이브리드면 Phase별 모드 기재) -- [ ] 모든 Agent 호출에 `model: "opus"` 파라미터 명시 +- [ ] 각 Agent/TeamCreate 호출의 **model이 역할 tier와 일치** (reasoning→opus, mechanical→sonnet) - [ ] 신규 에이전트 생성 전 기존 에이전트 중복 검토 완료 (Phase 3-0) - [ ] 신규 스킬 생성 전 기존 스킬 중복 검토 완료 (Phase 4-0) - [ ] `.claude/commands/` — 아무것도 생성하지 않음 diff --git a/skills/harness/references/agent-design-patterns.md b/skills/harness/references/agent-design-patterns.md index 08d91b9..6eb9c15 100644 --- a/skills/harness/references/agent-design-patterns.md +++ b/skills/harness/references/agent-design-patterns.md @@ -210,7 +210,12 @@ Phase별로 다른 전문가 조합이 필요하면, 이전 팀의 산출물을 **원칙:** 모든 에이전트는 반드시 `.claude/agents/{name}.md` 파일로 정의한다. 빌트인 타입이라도 에이전트 정의 파일을 생성하여 역할·원칙·프로토콜을 명시한다. 파일로 존재해야 다음 세션에서 재사용 가능하고, 팀 통신 프로토콜이 명시되어야 협업 품질이 보장된다. -**모델:** 모든 에이전트는 `model: "opus"`를 사용한다. Agent 도구 호출 시 반드시 `model: "opus"` 파라미터를 명시한다. +**모델:** 역할에 맞는 tier를 사용한다. Agent 도구 호출 시 `model` 파라미터를 명시한다. + +| Tier | model | 예시 역할 | +|------|-------|----------| +| Reasoning | `opus` | 설계, 코드, 교차 검증, 창작 | +| Mechanical | `sonnet` | 수집, 포맷 변환, 로그/배포 스크립트 | ## 에이전트 정의 구조 diff --git a/skills/harness/references/orchestrator-template.md b/skills/harness/references/orchestrator-template.md index df5023b..c60ad6d 100644 --- a/skills/harness/references/orchestrator-template.md +++ b/skills/harness/references/orchestrator-template.md @@ -59,8 +59,8 @@ description: "{도메인} 에이전트 팀을 조율하는 오케스트레이터 TeamCreate( team_name: "{domain}-team", members: [ - { name: "{teammate-1}", agent_type: "{type}", model: "opus", prompt: "{역할 설명 및 작업 지시}" }, - { name: "{teammate-2}", agent_type: "{type}", model: "opus", prompt: "{역할 설명 및 작업 지시}" }, + { name: "{teammate-1}", agent_type: "{type}", model: "{opus|sonnet}", prompt: "{역할 설명 및 작업 지시}" }, + { name: "{teammate-2}", agent_type: "{type}", model: "{opus|sonnet}", prompt: "{역할 설명 및 작업 지시}" }, ... ] ) @@ -196,8 +196,8 @@ description: "{도메인} 에이전트를 조율하는 오케스트레이터. { | 에이전트 | 입력 | 출력 | model | run_in_background | |---------|------|------|-------|-------------------| -| {agent-1} | {소스} | `_workspace/{phase}_{agent}_{artifact}.md` | opus | true | -| {agent-2} | {소스} | `_workspace/{phase}_{agent}_{artifact}.md` | opus | true | +| {agent-1} | {소스} | `_workspace/{phase}_{agent}_{artifact}.md` | opus or sonnet | true | +| {agent-2} | {소스} | `_workspace/{phase}_{agent}_{artifact}.md` | opus or sonnet | true | ### Phase 3: 통합 1. 각 에이전트의 반환값 수집