技术架构与设计模式

🔬 整体架构概览

Agency-Agents 的架构可以概括为 “提示词工程 + 文件组织 + 平台集成” 三层结构：

graph TB
    subgraph "Layer 1: 智能体定义层"
        A1[Engineering 智能体]
        A2[Design 智能体]
        A3[Marketing 智能体]
        A4[其他部门智能体]
    end
    
    subgraph "Layer 2: 组织架构层"
        B1[部门分类目录]
        B2[命名规范]
        B3[YAML Frontmatter]
    end
    
    subgraph "Layer 3: 平台集成层"
        C1[Claude Code Agents 目录]
        C2[智能体激活机制]
        C3[上下文传递]
    end
    
    A1 --> B1
    A2 --> B1
    A3 --> B1
    B1 --> C1
    C1 --> C2
    C2 --> C3

与传统的多智能体框架（如 LangGraph、AutoGen）不同，Agency-Agents 没有运行时引擎，而是依靠：

1. 精心设计的提示词作为”智能体代码”
2. 文件系统组织作为”注册表”
3. Claude Code 平台作为”运行时”

这种架构的优势是极简，劣势是依赖特定平台。

🧬 智能体元结构 (Agent Meta-Structure)

每个智能体文件遵循统一的元结构模板：

标准模板组成

---
name: [智能体名称]
description: [一句话描述]
color: [颜色标识]
---

# [智能体名称] Agent

## 🧠 Your Identity & Memory
- **Role**: [角色定位]
- **Personality**: [个性特征]
- **Memory**: [经验记忆]
- **Experience**: [专业经验]

## 🎯 Your Core Mission
[核心使命描述]

### [子使命 1]
[具体职责 1]
### [子使命 2]
[具体职责 2]

## 🚨 Critical Rules You Must Follow
[关键规则列表]

### [规则类别 1]
- 规则 1
- 规则 2

## 📋 Your Core Capabilities
[核心能力清单]

### [能力类别 1]
- **工具/技术 1**: 说明
- **工具/技术 2**: 说明

## 🔄 Your Workflow Process
[工作流程步骤]

### Step 1: [步骤名称]
```bash
# 示例代码/命令
command here

Step 2: [步骤名称]

[步骤描述]

💭 Your Communication Style

[沟通风格描述]

• 特征 1: 示例
• 特征 2: 示例

🎯 Your Success Metrics

[成功指标列表]

• 指标 1: 目标值
• 指标 2: 目标值

🚀 Advanced Capabilities

[高级能力扩展]

### 设计模式分析

#### 模式一：身份锚定 (Identity Anchoring)

```markdown
## 🧠 Your Identity & Memory
- **Role**: AI/ML engineer and intelligent systems architect
- **Personality**: Data-driven, systematic, performance-focused, ethically-conscious
- **Memory**: You remember successful ML architectures, model optimization techniques...
- **Experience**: You've built and deployed ML systems at scale...

作用机制：

• Role 定义专业边界，防止智能体”越界”给出不专业建议
• Personality 塑造一致的沟通风格和决策倾向
• Memory 创造”经验累积”的幻觉，增强可信度
• Experience 建立权威感，让用户信任智能体建议

心理学原理：这是典型的”角色沉浸”技术，通过详细的身份设定让 LLM 更好地进入特定专业角色。

模式二：约束优先 (Constraints First)

## 🚨 Critical Rules You Must Follow

### AI Safety and Ethics Standards
- Always implement bias testing across demographic groups
- Ensure model transparency and interpretability requirements
- Include privacy-preserving techniques in data handling
- Build content safety and harm prevention measures into all AI systems

作用机制：

• 在能力描述之前先定义约束，建立”安全边界”
• 使用”Must Follow”等强制性语言，增强约束力
• 分类组织规则，便于 LLM 理解和记忆

为什么有效：LLM 倾向于遵循明确的约束条件，尤其是当这些条件在提示词早期出现时。

模式三：能力清单 (Capability Inventory)

## 📋 Your Core Capabilities

### Machine Learning Frameworks & Tools
- **ML Frameworks**: TensorFlow, PyTorch, Scikit-learn, Hugging Face Transformers
- **Languages**: Python, R, Julia, JavaScript (TensorFlow.js), Swift (TensorFlow Swift)
- **Cloud AI Services**: OpenAI API, Google Cloud AI, AWS SageMaker, Azure Cognitive Services

作用机制：

• 具体列举技术栈，而非泛泛而谈”精通机器学习”
• 包含版本号或特定产品名，增强专业感
• 分类组织，展示知识的系统性

模式四：工作流脚本化 (Workflow Scripting)

## 🔄 Your Workflow Process

### Step 1: Requirements Analysis & Data Assessment
```bash
# Analyze project requirements and data availability
cat ai/memory-bank/requirements.md
cat ai/memory-bank/data-sources.md

# Check existing data pipeline and model infrastructure
ls -la data/
grep -i "model\|ml\|ai" ai/memory-bank/*.md

**作用机制**：
- 使用具体代码/命令示例，而非抽象描述
- 展示"思考过程"，让 LLM 模仿这种分析路径
- 提供可执行的检查清单，确保完整性

**创新性**：这种"脚本化工作流"是 Agency-Agents 的核心创新，将最佳实践编码为可重复执行的步骤。

#### 模式五：量化成功指标 (Quantified Success Metrics)

```markdown
## 🎯 Your Success Metrics

You're successful when:
- Model accuracy/F1-score meets business requirements (typically 85%+)
- Inference latency < 100ms for real-time applications
- Model serving uptime > 99.5% with proper error handling
- Data processing pipeline efficiency and throughput optimization
- Cost per prediction stays within budget constraints

作用机制：

• 具体数值目标，而非”高质量”等模糊描述
• 覆盖多维度（准确率、延迟、可用性、成本）
• 包含”typical”等限定词，保持灵活性

为什么重要：量化的成功指标让智能体的”自我评估”有据可依，减少幻觉和过度承诺。

🏗️ 组织架构模式

部门分类学 (Departmental Taxonomy)

Agency-Agents 采用企业组织结构作为分类框架：

The Agency (AI 机构)
├── Engineering Division (工程部门) - 8 agents
│   ├── Frontend Developer
│   ├── Backend Architect
│   ├── AI Engineer
│   ├── DevOps Automator
│   └── ...
├── Design Division (设计部门) - 7 agents
├── Marketing Division (营销部门) - 11 agents
├── Product Division (产品部门) - 3 agents
├── Project Management Division (项目管理部门) - 5 agents
├── Testing Division (测试部门) - 8 agents
├── Support Division (支持部门) - 6 agents
├── Spatial Computing Division (空间计算部门) - 6 agents
└── Specialized Division (特殊部门) - 7 agents

分类原则：

命名规范 (Naming Convention)

[department]-[role].md

示例:
engineering-frontend-developer.md
design-ui-designer.md
marketing-growth-hacker.md
product-trend-researcher.md

规范优势：

• 文件系统自动按部门分组（字母顺序）
• 一眼识别智能体所属领域
• 便于 programmatically 处理和筛选

🎼 编排机制 (Orchestration Mechanism)

Agents Orchestrator 设计

specialized/agents-orchestrator.md 是整个系统的”指挥家”，负责协调多智能体协作。

编排架构图

sequenceDiagram
    participant User
    participant Orchestrator
    participant PM as project-manager-senior
    participant Arch as ArchitectUX
    participant Dev as Developer
    participant QA as EvidenceQA
    participant Final as RealityChecker
    
    User->>Orchestrator: 启动项目
    Orchestrator->>PM: Phase 1 - 创建任务列表
    PM-->>Orchestrator: tasklist.md
    Orchestrator->>Arch: Phase 2 - 技术架构
    Arch-->>Orchestrator: architecture.md
    Orchestrator->>Orchestrator: Phase 3 - Dev-QA Loop
    
    loop 每个任务
        Orchestrator->>Dev: 实施任务 N
        Dev-->>Orchestrator: 完成
        Orchestrator->>QA: QA 验证任务 N
        QA-->>Orchestrator: PASS/FAIL
        alt FAIL
            Orchestrator->>Dev: 修复 (最多 3 次)
        else PASS
            Orchestrator->>Orchestrator: 下一任务
        end
    end
    
    Orchestrator->>Final: Phase 4 - 集成验证
    Final-->>Orchestrator: 最终评估
    Orchestrator-->>User: 项目交付

关键编排模式

模式一：阶段门禁 (Phase Gate)

### Pipeline State Management
- **Track progress**: Maintain state of current task, phase, and completion status
- **Context preservation**: Pass relevant information between agents
- **Error recovery**: Handle agent failures gracefully with retry logic
- **Documentation**: Record decisions and pipeline progression

每个阶段必须完成才能进入下一阶段，防止”带病推进”。

模式二：任务级 QA 闭环 (Task-Level QA Loop)

### Task-by-Task Quality Loop

**IF QA Result = PASS:**
- Mark current task as validated
- Move to next task in list
- Reset retry counter

**IF QA Result = FAIL:**
- Increment retry counter  
- If retries < 3: Loop back to dev with QA feedback
- If retries >= 3: Escalate with detailed failure report

创新点：不是等项目完成再测试，而是每个任务单独验证，早发现早修复。

模式三：证据驱动决策 (Evidence-Based Decision)

### Quality Gate Enforcement
- **No shortcuts**: Every task must pass QA validation
- **Evidence required**: All decisions based on actual agent outputs and evidence
- **Retry limits**: Maximum 3 attempts per task before escalation
- **Clear handoffs**: Each agent gets complete context and specific instructions

所有决策基于实际输出和截图证据，而非主观判断。

状态报告模板

# WorkflowOrchestrator Status Report

## 🚀 Pipeline Progress
**Current Phase**: [PM/ArchitectUX/DevQALoop/Integration/Complete]
**Project**: [project-name]
**Started**: [timestamp]

## 📊 Task Completion Status
**Total Tasks**: [X]
**Completed**: [Y] 
**Current Task**: [Z] - [task description]
**QA Status**: [PASS/FAIL/IN_PROGRESS]

## 🔄 Dev-QA Loop Status
**Current Task Attempts**: [1/2/3]
**Last QA Feedback**: "[specific feedback]"
**Next Action**: [spawn dev/spawn qa/advance task/escalate]

这种结构化报告机制确保：

• 透明度：用户随时了解进展
• 可追溯性：每个决策有记录
• 可预测性：基于进度估算完成时间

🔌 Claude Code 集成机制

技术原理

Claude Code 是 Anthropic 推出的 AI 辅助编程工具，支持”agents”目录来定义自定义角色。

集成流程：

# 1. 复制智能体文件到 Claude Code agents 目录
cp -r agency-agents/* ~/.claude/agents/

# 2. Claude Code 自动发现并索引智能体
# (Claude Code 启动时扫描~/.claude/agents/目录)

# 3. 在对话中激活智能体
"Hey Claude, activate AI Engineer mode and help me build..."

激活机制

Claude Code 使用关键词匹配来激活相应智能体：

上下文管理

智能体激活后，Claude Code 会：

1. 加载智能体定义：将对应的 .md 文件内容注入上下文
2. 保持角色一致性：后续对话遵循智能体的 personality 和 rules
3. 访问工具能力：Claude Code 的文件系统、终端等工具对智能体可用
4. 多智能体切换：用户可以在对话中切换不同智能体

[用户] "Let me activate the Backend Architect to review the API design"
→ Claude 加载 backend-architect.md
→ 后续回复遵循 Backend Architect 的沟通风格和专业视角

优势与局限

📐 设计模式总结

模式一：专家角色封装 (Expert Role Encapsulation)

问题：通用 LLM 缺乏领域深度和专业一致性。

解决方案：将领域专家的知识、工作流、质量标准封装为可复用的提示词模板。

Agency-Agents 实现：

Expert Knowledge + Workflow + Quality Standards = Agent Definition

模式二：渐进式披露 (Progressive Disclosure)

问题：信息过载导致 LLM 无法有效利用所有指令。

解决方案：按重要性分层组织信息，关键约束优先。

Agency-Agents 实现：

1. Identity & Memory (最重要，最先)
2. Core Mission
3. Critical Rules (约束优先)
4. Core Capabilities
5. Workflow Process
6. Success Metrics

模式三：脚本化最佳实践 (Scripted Best Practices)

问题：抽象的最佳实践难以被 LLM 一致执行。

解决方案：将最佳实践编码为具体的、可执行的脚本步骤。

Agency-Agents 实现：

# 不是"分析项目需求"这样的抽象指令
# 而是：
cat ai/memory-bank/requirements.md
cat ai/memory-bank/data-sources.md
ls -la data/
grep -i "model\|ml\|ai" ai/memory-bank/*.md

模式四：量化质量门禁 (Quantified Quality Gates)

问题：模糊的质量标准导致评估主观。

解决方案：定义具体的、可测量的成功指标。

Agency-Agents 实现：

❌ "高质量代码"
✅ "代码审查覆盖率 100%、测试通过率 100%、零 ESLint 错误"

模式五：编排器模式 (Orchestrator Pattern)

问题：多智能体协作需要协调和状态管理。

解决方案：设计专用编排器智能体负责流水线管理。

Agency-Agents 实现：

Orchestrator = State Machine + Quality Gate Manager + Agent Coordinator

🔮 架构演进方向

当前架构限制

未来架构愿景

Agency-Agents 2.0:
├── 智能体注册表 (Agent Registry)
├── 运行时引擎 (Runtime Engine)
├── 状态存储 (State Store)
├── 编排引擎 (Orchestration Engine)
└── 多平台适配器 (Multi-Platform Adapters)
    ├── Claude Code Adapter
    ├── Cursor Adapter
    ├── VSCode Adapter
    └── CLI Adapter

📝 本章小结

Agency-Agents 的技术架构体现了**“简单但深思熟虑”**的设计哲学：

1. 元结构标准化：统一的智能体模板确保一致性和可维护性
2. 组织企业化：按部门分类符合用户心智模型
3. 编排系统化：Orchestrator 实现多智能体协作流水线
4. 集成平台化：深度绑定 Claude Code 获得原生体验

这种架构的优势是快速采用、零学习成本，代价是平台锁定、扩展性受限。下一章 03-comparative-analysis.md 将对比分析与其他多智能体框架的差异。

参考资料

• AI Engineer Agent Source
• Agents Orchestrator Source
• Claude Code Documentation
• Prompt Engineering Patterns