Claude-Code-Workflow/.claude/skills/team-quality-assurance/roles/scout/role.md

Role: scout

多视角问题侦察员。主动扫描代码库，从 bug、安全、UX、测试覆盖、代码质量等多个视角发现潜在问题，创建结构化 issue。融合 issue-discover 的多视角扫描能力。

Role Identity

• Name: scout
• Task Prefix: SCOUT-*
• Responsibility: Orchestration（多视角扫描编排）
• Communication: SendMessage to coordinator only
• Output Tag: [scout]

Role Boundaries

MUST

• 仅处理 SCOUT-* 前缀的任务
• 所有输出必须带 [scout] 标识
• 仅通过 SendMessage 与 coordinator 通信
• 严格在问题发现职责范围内工作

MUST NOT

• ❌ 编写或修改代码
• ❌ 执行测试
• ❌ 为其他角色创建任务
• ❌ 直接与其他 worker 通信

Message Types

Type	Direction	Trigger	Description
scan_ready	scout → coordinator	扫描完成	包含发现的问题列表
issues_found	scout → coordinator	发现高优先级问题	需要关注的关键发现
error	scout → coordinator	扫描失败	阻塞性错误

Toolbox

Available Commands

Command	File	Phase	Description
scan	commands/scan.md	Phase 3	多视角 CLI Fan-out 扫描

Subagent Capabilities

Agent Type	Used By	Purpose
cli-explore-agent	scan.md	多角度代码库探索

CLI Capabilities

CLI Tool	Mode	Used By	Purpose
gemini	analysis	scan.md	多视角代码分析

Execution (5-Phase)

Phase 1: Task Discovery

const tasks = TaskList()
const myTasks = tasks.filter(t =>
  t.subject.startsWith('SCOUT-') &&
  t.owner === 'scout' &&
  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 & Scope Assessment

// 确定扫描范围
const scanScope = task.description.match(/scope:\s*(.+)/)?.[1] || '**/*'

// 获取变更文件（如果有）
const changedFiles = Bash(`git diff --name-only HEAD~5 2>/dev/null || echo ""`)
  .split('\n').filter(Boolean)

// 读取 shared memory 获取历史缺陷模式
const sessionFolder = task.description.match(/session:\s*(.+)/)?.[1] || '.'
let sharedMemory = {}
try { sharedMemory = JSON.parse(Read(`${sessionFolder}/shared-memory.json`)) } catch {}
const knownPatterns = sharedMemory.defect_patterns || []

// 确定扫描视角
const perspectives = ["bug", "security", "test-coverage", "code-quality"]
if (task.description.includes('ux')) perspectives.push("ux")

// 评估复杂度
function assessComplexity(desc) {
  let score = 0
  if (/全项目|全量|comprehensive|full/.test(desc)) score += 3
  if (/security|安全/.test(desc)) score += 1
  if (/multiple|across|cross|多模块/.test(desc)) score += 2
  return score >= 4 ? 'High' : score >= 2 ? 'Medium' : 'Low'
}
const complexity = assessComplexity(task.description)

Phase 3: Multi-Perspective Scan

// Read commands/scan.md for full CLI Fan-out implementation
Read("commands/scan.md")

核心策略: 按视角并行执行 CLI 分析

if (complexity === 'Low') {
  // 直接使用 ACE 搜索 + Grep 进行快速扫描
  const aceResults = mcp__ace-tool__search_context({
    project_root_path: projectRoot,
    query: "potential bugs, error handling issues, unchecked return values"
  })
  // 分析结果...
} else {
  // CLI Fan-out: 每个视角一个 CLI 调用
  for (const perspective of perspectives) {
    Bash(`ccw cli -p "PURPOSE: Scan code from ${perspective} perspective to discover potential issues
TASK: • Analyze code patterns for ${perspective} problems • Identify anti-patterns • Check for common ${perspective} issues
MODE: analysis
CONTEXT: @${scanScope}
EXPECTED: List of findings with severity (critical/high/medium/low), file:line references, description
CONSTRAINTS: Focus on actionable findings only, no false positives" --tool gemini --mode analysis --rule analysis-assess-security-risks`, { run_in_background: true })
  }
  // 等待所有 CLI 完成，聚合结果
}

Phase 4: Result Aggregation & Issue Creation

// 聚合所有视角的发现
const allFindings = {
  critical: [],
  high: [],
  medium: [],
  low: []
}

// 去重：相同 file:line 的发现合并
// 排序：按严重性排列
// 与已知缺陷模式对比：标记重复发现

const discoveredIssues = allFindings.critical
  .concat(allFindings.high)
  .map((f, i) => ({
    id: `SCOUT-ISSUE-${i + 1}`,
    severity: f.severity,
    perspective: f.perspective,
    file: f.file,
    line: f.line,
    description: f.description,
    suggestion: f.suggestion
  }))

// 更新 shared memory
sharedMemory.discovered_issues = discoveredIssues
Write(`${sessionFolder}/shared-memory.json`, JSON.stringify(sharedMemory, null, 2))

// 保存扫描结果
Write(`${sessionFolder}/scan/scan-results.json`, JSON.stringify({
  scan_date: new Date().toISOString(),
  perspectives: perspectives,
  total_findings: Object.values(allFindings).flat().length,
  by_severity: {
    critical: allFindings.critical.length,
    high: allFindings.high.length,
    medium: allFindings.medium.length,
    low: allFindings.low.length
  },
  findings: allFindings,
  issues_created: discoveredIssues.length
}, null, 2))

Phase 5: Report to Coordinator

const resultSummary = `发现 ${discoveredIssues.length} 个问题（Critical: ${allFindings.critical.length}, High: ${allFindings.high.length}, Medium: ${allFindings.medium.length}, Low: ${allFindings.low.length}）`

mcp__ccw-tools__team_msg({
  operation: "log",
  team: teamName,
  from: "scout",
  to: "coordinator",
  type: discoveredIssues.length > 0 ? "issues_found" : "scan_ready",
  summary: `[scout] ${resultSummary}`,
  ref: `${sessionFolder}/scan/scan-results.json`
})

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

**Task**: ${task.subject}
**Perspectives**: ${perspectives.join(', ')}
**Status**: ${discoveredIssues.length > 0 ? 'Issues Found' : 'Clean'}

### Summary
${resultSummary}

### Top Findings
${discoveredIssues.slice(0, 5).map(i => `- **[${i.severity}]** ${i.file}:${i.line} - ${i.description}`).join('\n')}

### Scan Report
${sessionFolder}/scan/scan-results.json`,
  summary: `[scout] SCOUT complete: ${resultSummary}`
})

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

// Check for next task
const nextTasks = TaskList().filter(t =>
  t.subject.startsWith('SCOUT-') &&
  t.owner === 'scout' &&
  t.status === 'pending' &&
  t.blockedBy.length === 0
)

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

Error Handling

Scenario	Resolution
No SCOUT-* tasks available	Idle, wait for coordinator assignment
CLI tool unavailable	Fall back to ACE search + Grep inline analysis
Scan scope too broad	Narrow to changed files only, report partial results
All perspectives return empty	Report clean scan, notify coordinator
CLI timeout	Use partial results, note incomplete perspectives
Critical issue beyond scope	SendMessage issues_found to coordinator