4.3. 스쿼드 템플릿¶

스쿼드 템플릿은 에이전트 팀을 위한 재사용 가능한 청사진입니다. 템플릿은 각 에이전트의 이름, 역할, 시스템 프롬프트, 도구 구성, 모델 설정을 담고 있어 한 번에 완전히 구성된 스쿼드를 만들 수 있습니다.

템플릿에는 두 종류가 있습니다.

내장 템플릿은 앱에 함께 제공되며, 읽기 전용이고, 현지화되어 있습니다.
사용자 템플릿은 기존 스쿼드를 저장하거나 JSON 파일을 가져와 생성합니다. 삭제, 내보내기, 가져오기를 지원합니다.

템플릿 사용하기¶

스쿼드 페이지를 열고 새 스쿼드를 클릭하면 템플릿 갤러리가 나타납니다. 내장 템플릿이 먼저 표시되고, 그다음 사용자 템플릿이 표시됩니다. 카드를 클릭하면 에이전트를 미리 볼 수 있으며, 이 템플릿 사용(검토 단계로 이동) 또는 사용자 지정(에이전트 구성 단계로 이동)을 선택할 수 있습니다.

스쿼드를 템플릿으로 저장하기¶

기존 스쿼드를 사용자 템플릿으로 저장할 수 있습니다.

스쿼드 목록에서 스쿼드 카드의 템플릿으로 저장 동작을 사용합니다.
스쿼드 상세 페이지에서 헤더의 템플릿으로 저장 버튼을 사용합니다.

이름(필수), 선택적 설명, 선택적 아이콘을 입력하세요. 저장된 템플릿은 에이전트별 전체 정보를 보존합니다 — 전체 도구 구성(활성화/비활성화된 도구, 도구별 권한 재정의, 사용자 지정 도구 설정)과 전체 모델 설정(선호 모델, 최소 컨텍스트 창, 도구 호출 / 비전 요구 사항)을 모두 포함합니다. 나중에 템플릿을 적용하면 원본 스쿼드와 동일하게 마법사가 복원됩니다.

사용자 템플릿 관리¶

템플릿 갤러리에서 각 사용자 템플릿 카드에는 인라인 동작이 표시됩니다.

내보내기는 템플릿을 JSON 파일로 다운로드합니다.
삭제는 확인 후 템플릿을 제거합니다. 내장 템플릿은 삭제할 수 없습니다.

카테고리 탭 옆의 템플릿 가져오기 버튼으로 JSON 파일에서 템플릿을 가져올 수 있습니다. .json 파일을 끌어다 놓거나 클릭하여 선택하세요. 전송하기 전에 페이로드가 로컬에서 검증되며, 잘못된 파일은 인라인 오류를 표시합니다. 가져온 템플릿은 항상 사용자 템플릿으로 저장되고, 내장 템플릿과 ID가 충돌하면 자동으로 재생성됩니다.

템플릿 JSON 스키마¶

템플릿은 camelCase 필드 이름으로 JSON에 직렬화됩니다. 이 형태는 Rust 백엔드(src-tauri/src/squad/templates.rs)와 TypeScript 프런트엔드(src/types/squad/templates.ts)가 공유합니다.

{
  "schemaVersion": 1,
  "id": "user-…",
  "name": "Full-Stack Dev Team",
  "description": "A complete development team…",
  "icon": "🛠️",
  "category": "development",
  "isBuiltin": false,
  "suggestedModels": [],
  "i18nKey": {
    "name": "squad.templates.builtin.fullstackDevTeam.name",
    "description": "squad.templates.builtin.fullstackDevTeam.description"
  },
  "agents": [
    {
      "name": "Planner",
      "role": "Planner",
      "systemPrompt": "You are a technical project planner…",
      "tools": ["read_file", "write_file"],
      "toolConfig": {
        "enabledTools": ["read_file", "write_file"],
        "disabledTools": [],
        "toolPermissionOverrides": {},
        "customToolConfigs": {}
      },
      "modelPreferences": {
        "requiresToolCalling": true,
        "requiresVision": false
      },
      "memoryEnabled": true,
      "icon": "📋",
      "i18nKey": {
        "name": "squad.templates.builtin.fullstackDevTeam.agents.planner.name",
        "role": "squad.templates.builtin.fullstackDevTeam.agents.planner.role",
        "systemPrompt": "squad.templates.builtin.fullstackDevTeam.agents.planner.systemPrompt"
      }
    }
  ]
}

필드 참조¶

필드	타입	설명
`schemaVersion`	number	스키마 버전. 이 필드가 없던 템플릿은 `1`로 기본값이 적용됩니다. 향후 호환성을 깨는 변경은 이 값을 올리고 마이그레이션을 추가합니다.
`id`	string	고유 식별자. 내장은 `builtin-…`, 사용자 템플릿은 `user-…`를 사용합니다.
`name`	string	표시 이름(`i18nKey`가 설정되면 영어 대체값).
`description`	string	짧은 설명.
`icon`	string	이모지 또는 아이콘 식별자.
`category`	string	`development`, `content`, `research`, `review`, `custom` 중 하나.
`isBuiltin`	boolean	번들된 내장 템플릿이면 `true`(삭제 불가). 가져오기 시 항상 `false`로 강제됩니다.
`suggestedModels`	string[]	정보 제공용입니다.
`i18nKey`	object?	선택적 필드별 번역 키(`name`, `description`).
`agents`	array	에이전트 정의(아래).

각 에이전트:

필드	타입	설명
`name`	string	에이전트 표시 이름.
`role`	string	역할 라벨. 정규 영어 역할(`Planner`, `Developer`, `Reviewer`, `Writer`)은 알려진 역할 타입으로 매핑되고, 그 외에는 사용자 지정 역할이 됩니다.
`systemPrompt`	string	시스템 프롬프트.
`tools`	string[]	활성화된 도구 이름의 레거시 편의 목록. `toolConfig.enabledTools`가 있으면 이를 반영합니다.
`toolConfig`	object?	전체 도구 구성. 있으면 `tools`보다 우선합니다.
`modelPreferences`	object?	전체 모델 설정.
`memoryEnabled`	boolean	에이전트의 메모리 활성화 여부.
`icon`	string	이모지 또는 아이콘 식별자.
`i18nKey`	object?	선택적 필드별 번역 키(`name`, `role`, `systemPrompt`).

tools만 있고 toolConfig / modelPreferences / schemaVersion / i18nKey가 없는 이전 템플릿도 계속 로드됩니다 — 누락된 필드는 안전하게 기본값이 적용됩니다.

내장 템플릿의 국제화¶

내장 템플릿은 현지화 가능한 각 필드에 대해 i18nKey를 선언합니다. 표시 시점에 프런트엔드는 react-i18next를 통해 이 키를 해석합니다. 활성 로케일에 키가 없으면 함께 제공된 영어 문자열을 대체값으로 사용합니다. 앱 언어를 바꾸면 갤러리, 미리보기, 마법사에서 내장 템플릿의 이름, 역할, 설명, 프롬프트가 갱신됩니다.

번역 문자열은 각 로케일 파일(src/locales/<locale>/translation.json)의 squad.templates.builtin.* 아래에 있습니다.

새 내장 템플릿 추가하기¶

내장 템플릿은 코드가 아니라 데이터입니다. resources/squad-templates/builtin/*.json에 JSON 시드 파일로 존재하며 컴파일 시점에 바이너리에 임베드된 뒤, 시작 시 TemplateStorage::list()가 읽습니다. 새 내장 템플릿을 추가하는 데 Rust 변경은 필요 없습니다.

위 스키마를 따르는 새 resources/squad-templates/builtin/<your-template>.json 파일을 만드세요. isBuiltin: true로 설정하고, 고유한 builtin-… id와 schemaVersion을 부여하세요.
(선택이지만 권장) 현지화 가능한 각 필드에 i18nKey를 추가하고, 모든 로케일 파일의 squad.templates.builtin.* 아래에 해당 번역 키를 추가하세요. 최소한 영어는 제공하세요. 다른 로케일은 키가 없으면 영어로 대체됩니다.
앱을 다시 빌드하세요. 새 템플릿이 갤러리에 자동으로 나타납니다.

이 파일들은 Tauri 리소스로도 번들되므로, 재컴파일 없이 에이전트 카탈로그를 통해 추가 템플릿을 배포하기 위한 기반이 됩니다.