Claude Code多智能体工作流系统

claude-sage

"Analyze First, Fix Later" — Workflow system for Claude Code CLI

An agent-based workflow system for Claude Code that emphasizes careful analysis, strategic planning, and controlled implementation. No more quick fixes that become technical debt.

A quick note before you start

MCP Servers - Seriously, install these: I highly recommend setting up the MCP servers (especially Context7 and Exa). They're what make the horizon-explorer agent so powerful. Without them, you're missing out on:

• Exa: Real-world code examples, API documentation, web search
• Context7: Up-to-date library documentation

Trust me, these aren't optional nice-to-haves—they're game-changers.

Tip: A local install (claude mcp add exa -- npx -y exa-mcp-server) is the safest choice for subagents. claude.ai connectors also work in recent Claude Code versions, but a connector that still "needs authentication" is invisible to the agents, so check claude mcp list first.

Core Philosophy

Stop rushing into fixes. Start building right.

This system replaces the "quick fix" mentality with a structured, multi-agent approach:

1. Analyze the problem deeply (no code changes)
2. Architect the solution strategically (ultrathink mode)
3. Explore alternative perspectives (when stuck)
4. Fix carefully with explicit approval (test-driven)

Quick Start

Option 1 — Plugin install:

/plugin marketplace add arikusi/arikusi-marketplace
/plugin install claude-sage@arikusi-marketplace

Option 2 — Tell Claude to install it for you:

# Open Claude Code CLI
claude

# Then say:
"Add the marketplace and install claude-sage:
/plugin marketplace add arikusi/arikusi-marketplace
/plugin install claude-sage@arikusi-marketplace"

That's it! Claude will set everything up for you.

The Agent Team

1. problem-analyst

• Role: Forensic investigator
• Tools: Read, Grep, Glob, Bash (read-only)
• Powers: Cannot write/edit code
• Purpose: Deep root cause analysis, impact assessment, reporting

When to use: /analyze [problem description]

2. solution-architect

• Role: Strategic architect
• Model: your session model at effort: high
• Tools: Read, Grep, Glob, Bash (read-only for code)
• Powers: Cannot write/edit code — produces detailed plans that end in a numbered task list
• Purpose: Architecture decisions, trade-off analysis, 3+ alternative approaches

When to use: /architect [architectural decision]

3. horizon-explorer

• Role: Lateral thinker
• Tools: everything the session has except Write/Edit, so any Exa or Context7 server you configured is available
• Powers: Cannot write/edit code, Research superpowers
• Purpose: Alternative perspectives, unconventional solutions, "are we looking in the right place?"

When to use: /explore [stuck problem]

4. controlled-fixer

• Role: Careful surgeon
• Tools: Read, Grep, Glob, Edit, Write, Bash
• Powers: Can modify code (ONLY with explicit approval, in isolated worktree)
• Purpose: Test-driven, reversible, minimal-impact fixes in a separate git branch

When to use: /fix (after analysis and approval)

5. code-reviewer

• Role: Independent quality gate
• Model: your session model at effort: high
• Tools: Read, Grep, Glob, Bash (read-only)
• Powers: Cannot modify code — produces APPROVED / NEEDS CHANGES / BLOCKED
• Purpose: Security (OWASP), logic correctness, edge cases, test coverage, and scope: does the diff match what was approved?

Claude Code ships its own /code-review. Use that for a quick look at any diff. Use /claude-sage:review when the change came through the sage pipeline, because this agent reads the analysis and the plan and rejects work that wandered outside them.

When to use: /review (after /fix, before merging)

Quick Commands

Standard Workflows

Workflow 1: Simple Bug Fix

1. /analyze "npm test failing on auth module"
   → problem-analyst: detailed analysis + root cause

2. You: "Okay, proceed with the fix"
   → /fix
   → controlled-fixer: test-driven fix in isolated worktree

3. /review
   → code-reviewer: APPROVED

4. git merge [branch]

Workflow 2: Critical Architectural Decision

1. /analyze "should we migrate to microservices?"
   → problem-analyst: current state analysis

2. /architect "microservices migration strategy"
   → solution-architect: 3+ approaches, trade-offs, risks

3. You: decide which approach

4. /fix [chosen approach]
   → controlled-fixer: careful implementation in worktree

5. /review
   → code-reviewer: review + merge decision

Workflow 3: Stuck for Hours

1. /explore "we can't solve the race condition in our queue"
   → horizon-explorer: alternative patterns, different tech stacks
   → "Are we looking in the right place?"

2. /analyze [new perspective]
   → problem-analyst: re-analyze with new insights

3. /architect [solution]
   → solution-architect: strategic plan

4. /fix → /review → merge

Best Practices

DO

1. Always start with /analyze - Never skip understanding
2. Use /architect for critical changes - Get strategic guidance
3. Call /explore when stuck - Fresh perspective
4. Approve before /fix - Controlled changes only
5. Request "ultrathink" - For complex decisions

DON'T

1. Skip analysis - Understanding > Speed
2. Quick fixes - Today's shortcut = Tomorrow's debt
3. Single perspective - Use /explore when uncertain
4. Untested production changes - controlled-fixer enforces tests
5. Breaking changes without warning - Agents will flag

Features

Model choice

Every agent uses model: inherit, so the team runs on whatever your session runs on. If you want the architect and reviewer on a heavier model than the rest, edit the frontmatter in agents/ and set model: opus (or any model id --model accepts).

Permissions that actually match

{
  "allow": ["Bash(git:*)", "Bash(npm:*)"],
  "deny": ["Bash(rm -rf:*)", "Bash(git push --force:*)"]
}

The pattern is Bash(<command prefix>:*). Colons inside the prefix (rm:-rf) do not mean "argument", they are literal text, and a rule written that way never fires.

Post-Tool Hooks

Hooks receive the tool call as JSON on stdin. To act on the edited file:

{
  "PostToolUse": [{
    "matcher": "Edit|Write",
    "hooks": [{"type": "command", "command": "jq -r .tool_input.file_path | xargs prettier --write"}]
  }]
}

Effort instead of thinking tokens

solution-architect and code-reviewer set effort: high in their frontmatter. That replaces the old MAX_THINKING_TOKENS env var; set effortLevel in your settings if you want the whole session to run that way.

See settings.template.json for a complete starting point.

MCP Integration

The workflow system is significantly more powerful with MCP servers:

• Exa: Real-world code examples, API documentation, web search
• Context7: Up-to-date library documentation

Without MCPs: Basic workflow works, but horizon-explorer loses 80% of its research capabilities. With MCPs: Full-powered alternative research, fresh code examples, and comprehensive documentation.

Local servers are the safer choice for subagents; a claude.ai connector works too as long as it shows "Connected" in claude mcp list. horizon-explorer picks up whichever you have, under whatever name you gave it.

Documentation

• WORKFLOW-GUIDE.md: Comprehensive workflow documentation
• Agent files: Each agent has detailed instructions
• Command files: Slash command definitions

Agent Decision Matrix

Advanced Usage

Custom Agents

Add your own agents to ~/.claude/agents/:

---
name: your-agent
description: What it does
tools: Read, Grep
disallowedTools: Write, Edit
model: sonnet
---

# Your Agent Instructions

...

"Quick fix today, big problem tomorrow."

Understand the problem first. Fix it once, fix it right.

📜 License

MIT