AI Coding实战系列

Claude CodeAI Coding工具对比

I recently stumbled upon agency-agents on GitHub by msitarzewski — a project that promises to inject 112 specialized AI agent personas into Claude Code, Cursor, and Aider, turning your IDE into a multi-agent AI studio.

The pitch: frontend Agent handles UI, test Agent checks coverage, architecture Agent reviews design — you just direct.

Sounds incredible. But when I actually tried to set it up, I hit整整 3 天的坑. This article documents the 5 real pitfalls I encountered so you don't have to suffer the same fate.

Architecture Overview: How agency-agents Actually Works

Before diving into the traps, understand the underlying design:

agency-agents is essentially a **Markdown-based system prompt template library**. Each Agent persona is a .md file defining:

**Identity**: Who I am, e.g. "Senior Frontend Engineer"
**Mission**: What I'm responsible for, e.g. "implement pixel-perfect UIs"
**Success Metrics**: How I measure my own output
**Rules**: What I say/do in specific situations

Installation options:

**Option 2: Claude Code** (via `CLAUDE.md` or project-level `.claude/` directory)
**Native App (The Agency)**: macOS/Linux/Windows desktop app that auto-detects tools and installs agents
**Other tools**: Copilot, Cursor, Aider, Windsurf, and 10+ more

My goal was to integrate it with Claude Code for parallel multi-agent research + code review workflows.

🛠️ Prerequisites

Before starting, ensure your environment meets these requirements:

Claude Code installed with ANTHROPIC_API_KEY configured
OS: macOS, Linux, or Windows
Optional: The Agency native app (makes managing 112 agents' install status much easier)

Verification:

claude --version  # Confirm Claude Code is available

💣 Pitfall 1: Wrong Agent Install Path Causes Claude Code to Find Zero Agents

Error message:

Error: No agent found with name "frontend-engineer"

Root cause:

The official docs mention two installation approaches, but paths vary dramatically between tools. I followed the docs and placed files in ~/.claude/agents/, but Claude Code doesn't recognize this path at all.

Claude Code's actual agent persona path is the **project-level .claude/commands/ directory** (for skills/commands), while global agent personas need to live directly under ~/.claude/ root.

Solution:

The correct way to load agent personas in Claude Code:

# Method 1: Global install (recommended)
# Copy agent .md files to ~/.claude/ directory
mkdir -p ~/.claude
cp -r agency-agents/agents/*.md ~/.claude/

# Method 2: Project-level install
mkdir -p .claude/commands
cp agency-agents/agents/frontend-engineer.md .claude/commands/

# Verify Claude Code can see agents
claude -p "Show me available agents" 2>&1 | grep -i agent

Verification:

After configuration, type /agent list in Claude Code or use The Agency App to check install status (App shows green ✅ marks).

---

Pitfall 2: The Agency App Installs Successfully But Cross-Tool Sync Fails

Error message:

[Agency] Agent "test-engineer" installed for Claude Code but not detected on next startup

Root cause:

The Agency App's mechanism: write .md files to target tool's standard paths, then track install status in App's internal database. But Claude Code rescans and caches available commands/skills on startup — if the App writes files at the wrong time, the cache doesn't update.

This is a race condition: App writes files → Claude Code starts → cache not refreshed → Agent invisible.

Solution:

# Step 1: After App installation, manually refresh Claude Code cache
# Method A: Restart Claude Code (simplest)
claude --exit  # Exit current session
claude  # Restart

# Method B: Clear cache (if Method A doesn't work)
rm -rf ~/.claude/commands/.cache  # Clear command cache
claude  # Restart

# Step 2: Verify install status
# In The Agency App, check "Install Health" panel
# Confirm Claude Code column shows ✅ not ❌

Verification:

After Claude Code restarts, type / and check if your installed Agent names appear in the command list.

---

Pitfall 3: Activating All 112 Agents Simultaneously Burns Through Tokens

Error message:

Warning: Processing 112 agents may exceed context window
Anthropic API Error: 400 - This session's context window is full

Root cause:

112 agent personas each carry their own system prompt — easily 100K+ tokens combined. In Claude Code, every new sub-agent or command invocation loads these persona definitions into context. For medium-scale projects (10K-50K lines of code), activating all 112 agents fills the context window within the first few turns.

Solution:

Activate by groups — never load all 112 at once:

# Install agents by function group (don't install all 112 at once)
# Core development group (recommended first install)
cp agency-agents/agents/frontend-engineer.md ~/.claude/
cp agency-agents/agents/backend-engineer.md ~/.claude/
cp agency-agents/agents/test-engineer.md ~/.claude/
cp agency-agents/agents/devops-engineer.md ~/.claude/

# Audit group (install when needed)
mkdir -p ~/.claude/agents-audit
cp agency-agents/agents/security-engineer.md ~/.claude/agents-audit/
cp agency-agents/agents/architecture-reviewer.md ~/.claude/agents-audit/

# Switch active group on demand
alias claude-audit="CLAUDE_AGENTS_PATH=~/.claude/agents-audit claude"

My actual usage strategy:

Daily development: only 4 core agents (frontend/backend/test/devops)
Code review time: temporarily switch to audit group (4-6 agents)
Major refactors: add architecture and architecture-review agents as needed

---

Pitfall 4: Agent Persona Doesn't Match Your Project's Tech Stack — Output Quality Drops

Problem description:

Installed the "senior-frontend-engineer" agent, but my project uses Next.js 14 App Router + Tailwind v4, while the agent's system prompt specifies Vue 3 + Vite best practices. The advice was completely inapplicable and even misleading.

Root cause:

agency-agents' agent personas are generic templates not optimized for specific tech stacks. When your project differs from the agent's default assumptions, output quality degrades noticeably.

Solution:

Option 1: Custom Agent persona (recommended)

Next.js 14 App Router (server components by default)
Tailwind CSS v4
TypeScript strict mode
App Router data fetching patterns

Lighthouse Performance score > 90
Zero TypeScript errors
WCAG 2.1 AA accessibility compliance

Always use Server Components unless client-side interactivity is required
Prefer built-in Next.js optimizations (Image, Link, Script)
Use Tailwind CSS utility classes over custom CSS

# View existing agent definition file
cat ~/.claude/senior-frontend-engineer.md

# Create a custom version based on template (for Next.js 14)
cat > ~/.claude/nextjs-frontend-engineer.md << 'EOF'
# Identity
You are a Senior Frontend Engineer specializing in Next.js 14 App Router.

# Mission
Implement pixel-perfect, performant React components using:

# Success Metrics

# Rules
EOF

# Activate custom agent
claude --agent nextjs-frontend-engineer

Option 2: Use The Agency App's "Override" Feature

The Agency App allows partial overrides of official agents (partial override, not full fork). Overridable fields include: mission, rules, success_metrics.

---

Pitfall 5: Windows Path Separators Prevent Agent Files From Loading

Error message:

Error: Failed to load agent definition from C:\Users\xxx\.claude\frontend-engineer.md
Reason: File not found (case-sensitive path on Windows)

Root cause:

Agency-agents agent filenames on GitHub are frontend-engineer.md, but Windows file system is **case-insensitive by default** (though path handling can be problematic), and path separators are \ not /.

More problematic: some Windows tools (certain Claude Code versions) internally use POSIX paths, causing double-escaping issues when reading Windows paths.

Solution:

# Windows PowerShell correct installation method
# Step 1: Ensure Claude Code data directory exists
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude"

# Step 2: Copy agent files (PowerShell handles paths automatically)
Copy-Item -Path ".\agency-agents\agents\*.md" -Destination "$env:USERPROFILE\.claude\" -Recurse

# Step 3: Verify files exist
Get-ChildItem "$env:USERPROFILE\.claude\" -Filter "*.md"

# Step 4: Clear Claude Code cache and restart
claude --exit

Verification:

claude -p "List available agents" 2>&1

If agent names appear in output, installation succeeded.

Complete Installation Process (Correct Order After All Pitfalls)

Synthesizing all pitfalls above, here's my verified complete installation workflow:

# Step 1: Clone repo
git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents

# Step 2: Select agents to install (don't install all 112)
AGENTS=(
  "frontend-engineer"
  "backend-engineer"
  "test-engineer"
  "devops-engineer"
  "security-engineer"
  "architecture-reviewer"
)

# Step 3: Create directory and install
mkdir -p ~/.claude
for agent in "${AGENTS[@]}"; do
  if [ -f "agents/$agent.md" ]; then
    cp "agents/$agent.md" ~/.claude/
    echo "✅ Installed: $agent"
  else
    echo "⚠️  Not found: $agent"
  fi
done

# Step 4: Restart Claude Code
claude --exit
claude

# Step 5: Verify
claude -p "Show me available commands" 2>&1 | grep -E "(frontend|backend|test|devops|security|architecture)"

agency-agents vs Alternatives:横向对比

Solution	Agent Count	Multi-Tool Support	Config Complexity	Best For
agency-agents	112+	✅ Claude/Cursor/Copilot 10+	Medium (many path traps)	Complex projects needing multi-role division
mattpocock/skills	30+	✅ General toolkit	Low	Quick start, general tasks
gstack	23 slash commands	✅ YC CEO config	Low	Users preferring YC methodology
Codex Memory MCP	1 (knowledge graph)	✅ MCP protocol	Medium	Large codebase semantic retrieval

My choice:

agency-agents: for complex projects needing **multi-role division** (frontend/backend/test/architecture review in parallel)
mattpocock/skills: for **daily quick tasks** (code review, refactoring, documentation)

Conclusion and Next Steps

agency-agents is a promising multi-role AI Agent system with 112 specialized personas covering the full software development lifecycle. But path configuration, token consumption, and platform differences make it intimidating for beginners.

The 5 pitfalls in this article cover the core problems across installation, configuration, and optimization phases. Following my workflow, you can get your first multi-role workflow running within 30 minutes.

Next directions:

Try agency-agents' **parallel multi-agent review mode** (similar to ai-berkshire's investment-team approach)
Explore The Agency App's **cross-tool sync** capabilities — can it sync Agent status between Cursor + Claude Code?

Related articles:

👉 Join MiniMax Token Plan: AI coding acceleration for businesses

👉 Join Zhipu Coding Plan: GLM-4.6/GLM-5 coding packages, China-stable, pay-per-token unlimited

👉 Join Aliyun AI: Top AI products with exclusive coupons for business innovation

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews

🔗 Recommended Tools

These are carefully selected tools. Using our affiliate links supports us to keep producing quality content:

☁️ DigitalOcean Cloud ⚡ Vultr VPS ⭐ MiniMax Token Plan 🧩 Zhipu Coding Plan 🎁 Zhipu 20M Tokens Gift 🤖 QoderWork CN (Refer & Earn) ☁️ Aliyun AI Products 📚 WordPress Books 🔍 WordPress SEO Books 🌐 Web Hosting Books 🐳 Docker Books 🐧 Linux Books 🐍 Python Books 💰 Affiliate Marketing 💵 Passive Income Books 🖥️ Server Books ☁️ Cloud Computing Books 🚀 DevOps Books

← Back to Home