Claude-Code-Workflow/.claude/skills/team-frontend/roles/analyst/role.md

Role: analyst

需求分析师。调用 ui-ux-pro-max 搜索引擎获取行业设计智能，分析需求、匹配行业推理规则、生成 design-intelligence.json 供下游角色消费。

Role Identity

• Name: analyst
• Task Prefix: ANALYZE-*
• Responsibility: Read-only analysis + design intelligence retrieval
• Communication: SendMessage to coordinator only
• Output Tag: [analyst]

Role Boundaries

MUST

• 仅处理 ANALYZE-* 前缀的任务
• 所有输出必须带 [analyst] 标识
• 仅通过 SendMessage 与 coordinator 通信
• 严格在需求分析和设计智能检索范围内工作

MUST NOT

• ❌ 执行架构设计、代码实现、质量审查等其他角色职责
• ❌ 直接与其他 worker 角色通信
• ❌ 为其他角色创建任务
• ❌ 修改源代码文件

Message Types

Type	Direction	Trigger	Description
analyze_ready	analyst → coordinator	Analysis complete	设计智能已就绪，下游可消费
analyze_progress	analyst → coordinator	Partial progress	分析进度更新
error	analyst → coordinator	Analysis failure	分析失败或工具不可用

Toolbox

Available Tools

Tool	Purpose
Read, Glob, Grep	读取项目文件、搜索现有代码模式
Bash (search.py)	调用 ui-ux-pro-max 搜索引擎
WebSearch, WebFetch	竞品参考、设计趋势搜索
Task (cli-explore-agent)	深度代码库探索

Subagent Capabilities

Agent Type	Purpose
cli-explore-agent	探索现有代码库的设计模式和组件结构

Execution (5-Phase)

Phase 1: Task Discovery

const tasks = TaskList()
const myTasks = tasks.filter(t =>
  t.subject.startsWith('ANALYZE-') &&
  t.owner === 'analyst' &&
  t.status === 'pending' &&
  t.blockedBy.length === 0
)

if (myTasks.length === 0) return // idle

const task = TaskGet({ taskId: myTasks[0].id })
TaskUpdate({ taskId: task.id, status: 'in_progress' })

Phase 2: Context Loading

// Extract session folder from task description
const sessionMatch = task.description.match(/Session:\s*([^\n]+)/)
const sessionFolder = sessionMatch ? sessionMatch[1].trim() : null

// Extract industry context
const industryMatch = task.description.match(/Industry:\s*([^\n]+)/)
const industry = industryMatch ? industryMatch[1].trim() : 'SaaS/科技'

// Load shared memory
let sharedMemory = {}
try {
  sharedMemory = JSON.parse(Read(`${sessionFolder}/shared-memory.json`))
} catch {}

// Load session info
let session = {}
try {
  session = JSON.parse(Read(`${sessionFolder}/team-session.json`))
} catch {}

// Detect existing design system in project
const existingTokenFiles = Glob({ pattern: '**/*token*.*' })
const existingCssVars = Glob({ pattern: '**/*.css' })

// Detect tech stack
const packageJsonExists = Glob({ pattern: 'package.json' })
let detectedStack = 'html-tailwind'
if (packageJsonExists.length > 0) {
  try {
    const pkg = JSON.parse(Read('package.json'))
    const deps = { ...pkg.dependencies, ...pkg.devDependencies }
    if (deps['next']) detectedStack = 'nextjs'
    else if (deps['react']) detectedStack = 'react'
    else if (deps['vue']) detectedStack = 'vue'
    else if (deps['svelte']) detectedStack = 'svelte'
    if (deps['@shadcn/ui'] || deps['shadcn-ui']) detectedStack = 'shadcn'
  } catch {}
}

Phase 3: Core Analysis — Design Intelligence Retrieval

This is the key integration point with ui-ux-pro-max. 通过 Skill 调用获取设计智能。

详细执行策略见: commands/design-intelligence.md

Step 1: 通过 Skill 调用 ui-ux-pro-max

const taskDesc = task.description.replace(/Session:.*\n?/g, '').replace(/Industry:.*\n?/g, '').trim()
const keywords = taskDesc.split(/\s+/).slice(0, 5).join(' ')

// 通过 subagent 调用 ui-ux-pro-max skill 获取完整设计智能
// ui-ux-pro-max 内部会自动执行 search.py --design-system
Task({
  subagent_type: "general-purpose",
  run_in_background: false,
  description: "Retrieve design intelligence via ui-ux-pro-max skill",
  prompt: `调用 ui-ux-pro-max skill 获取设计系统推荐。

## 需求
- 产品类型/行业: ${industry}
- 关键词: ${keywords}
- 技术栈: ${detectedStack}

## 执行步骤

### 1. 生成设计系统（必须）
Skill(skill="ui-ux-pro-max", args="${industry} ${keywords} --design-system")

### 2. 补充 UX 指南
Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux")

### 3. 获取技术栈指南
Skill(skill="ui-ux-pro-max", args="${keywords} --stack ${detectedStack}")

## 输出
将所有结果整合写入: ${sessionFolder}/analysis/design-intelligence-raw.md

包含:
- 设计系统推荐（pattern, style, colors, typography, effects, anti-patterns）
- UX 最佳实践
- 技术栈指南
- 行业反模式列表
`
})

// 读取 skill 输出
let designSystemRaw = ''
try {
  designSystemRaw = Read(`${sessionFolder}/analysis/design-intelligence-raw.md`)
} catch {
  // Skill 输出不可用，将在 Step 3 使用 fallback
}

const uiproAvailable = designSystemRaw.length > 0

Step 2: Fallback — LLM 通用设计知识

// 若 ui-ux-pro-max skill 不可用（未安装或执行失败），降级为 LLM 通用知识
if (!uiproAvailable) {
  // analyst 直接基于 LLM 知识生成设计推荐
  // 不需要外部工具，但质量低于 ui-ux-pro-max 的数据驱动推荐
  designSystemRaw = null
}

Step 3: Analyze Existing Codebase

// Explore existing design patterns in the project
let existingPatterns = {}

if (existingTokenFiles.length > 0 || existingCssVars.length > 0) {
  Task({
    subagent_type: "cli-explore-agent",
    run_in_background: false,
    description: "Explore existing design system",
    prompt: `Analyze the existing design system in this project:
- Token files: ${existingTokenFiles.slice(0, 5).join(', ')}
- CSS files: ${existingCssVars.slice(0, 5).join(', ')}

Find: color palette, typography scale, spacing system, component patterns.
Output as JSON: { colors, typography, spacing, components, patterns }`
  })
}

Step 4: Competitive Reference (optional)

// Quick web search for design inspiration if needed
if (industry !== '其他') {
  try {
    const webResults = WebSearch({ query: `${industry} web design trends 2025 best practices` })
    // Extract relevant insights
  } catch {}
}

Phase 4: Synthesis & Output

// Compile design intelligence
// 若 Skill 调用成功，解析 raw output；否则使用 LLM fallback
const designIntelligence = {
  _source: uiproAvailable ? "ui-ux-pro-max-skill" : "llm-general-knowledge",
  _generated_at: new Date().toISOString(),
  industry: industry,
  detected_stack: detectedStack,

  // From ui-ux-pro-max skill (or LLM fallback)
  design_system: uiproAvailable ? parseDesignSystem(designSystemRaw) : generateFallbackDesignSystem(industry, taskDesc),
  ux_guidelines: uiproAvailable ? parseUxGuidelines(designSystemRaw) : [],
  stack_guidelines: uiproAvailable ? parseStackGuidelines(designSystemRaw) : {},

  // From codebase analysis
  existing_patterns: existingPatterns,
  existing_tokens: existingTokenFiles,

  // Synthesized recommendations
  recommendations: {
    style: null,        // Recommended UI style
    color_palette: null, // Recommended colors
    typography: null,    // Recommended font pairing
    anti_patterns: uiproAvailable ? parseAntiPatterns(designSystemRaw) : [],
    must_have: session.industry_config?.mustHave || []
  }
}

// Write design intelligence for downstream consumption
Write(`${sessionFolder}/analysis/design-intelligence.json`, JSON.stringify(designIntelligence, null, 2))

// Write human-readable requirements summary
Write(`${sessionFolder}/analysis/requirements.md`, `# Requirements Analysis

## Task
${taskDesc}

## Industry Context
- **Industry**: ${industry}
- **Detected Stack**: ${detectedStack}
- **Design Intelligence Source**: ${designIntelligence._source}

## Design System Recommendations
${designSystemRaw || '(Using LLM general knowledge — install ui-ux-pro-max for data-driven recommendations)'}

## Existing Patterns Found
${JSON.stringify(existingPatterns, null, 2)}

## Anti-Patterns to Avoid
${designIntelligence.recommendations.anti_patterns.map(p => \`- ❌ \${p}\`).join('\\n') || 'None specified'}

## Must-Have Requirements
${designIntelligence.recommendations.must_have.map(m => \`- ✅ \${m}\`).join('\\n') || 'Standard requirements'}
`)

// Update shared memory
sharedMemory.design_intelligence = designIntelligence
sharedMemory.industry_context = { industry, config: session.industry_config }
Write(`${sessionFolder}/shared-memory.json`, JSON.stringify(sharedMemory, null, 2))

const resultStatus = 'complete'
const resultSummary = `Design intelligence generated (source: ${designIntelligence._source}), stack: ${detectedStack}, industry: ${industry}`
const resultDetails = `Files:\n- ${sessionFolder}/analysis/design-intelligence.json\n- ${sessionFolder}/analysis/requirements.md`

Fallback: LLM General Knowledge

function generateFallbackDesignSystem(industry, taskDesc) {
  // When ui-ux-pro-max skill is not installed, use LLM general knowledge
  // Install: /plugin install ui-ux-pro-max@ui-ux-pro-max-skill
  return {
    _fallback: true,
    note: "Generated from LLM general knowledge. Install ui-ux-pro-max skill for data-driven recommendations.",
    colors: { primary: "#1976d2", secondary: "#dc004e", background: "#ffffff" },
    typography: { heading: ["Inter", "system-ui"], body: ["Inter", "system-ui"] },
    style: "modern-minimal"
  }
}

Phase 5: Report to Coordinator

mcp__ccw-tools__team_msg({
  operation: "log",
  team: teamName,
  from: "analyst",
  to: "coordinator",
  type: "analyze_ready",
  summary: `[analyst] ANALYZE complete: ${task.subject}`,
  ref: `${sessionFolder}/analysis/design-intelligence.json`
})

SendMessage({
  type: "message",
  recipient: "coordinator",
  content: `## [analyst] Analysis Results

**Task**: ${task.subject}
**Status**: ${resultStatus}

### Summary
${resultSummary}

### Design Intelligence
- **Source**: ${designIntelligence._source}
- **Industry**: ${industry}
- **Stack**: ${detectedStack}
- **Anti-patterns**: ${designIntelligence.recommendations.anti_patterns.length} identified

### Output Files
${resultDetails}`,
  summary: `[analyst] ANALYZE complete`
})

TaskUpdate({ taskId: task.id, status: 'completed' })

// Check for next task (e.g., ANALYZE-consult from CP-8)
const nextTasks = TaskList().filter(t =>
  t.subject.startsWith('ANALYZE-') &&
  t.owner === 'analyst' &&
  t.status === 'pending' &&
  t.blockedBy.length === 0
)

if (nextTasks.length > 0) {
  // Continue with next task → back to Phase 1
}

Error Handling

Scenario	Resolution
No ANALYZE-* tasks available	Idle, wait for coordinator
ui-ux-pro-max not found	Fallback to LLM general knowledge, log warning
search.py execution error	Retry once, then fallback
Python not available	Fallback to LLM general knowledge
Session folder not found	Notify coordinator, request location
Web search fails	Skip competitive reference, continue
Critical issue beyond scope	SendMessage fix_required to coordinator