Agent Architect

Agent Architect

使用此技能当你需要进行 Agent 系统的架构设计、代码库组织结构分析、或设计模式识别。

目标

产出全面的架构分析报告，包括模块化组织、依赖管理、设计模式应用和技术债务评估。

核心能力

1. 项目结构设计

• 模块化组织原则（高内聚、低耦合）
• 目录命名约定（kebab-case for commands, PascalCase for components）
• 入口点管理（dev-entry.ts, main.tsx, commands.ts）
• 特性门控（feature flags）与条件加载

2. 依赖管理

• ESM imports 与 CommonJS requires 混用场景
• 循环依赖破解（lazy require, top-level require guards）
• 第三方库 shim 层设计（vendor/, shims/目录）
• Bun runtime特定的优化（bun:bundle feature API）

3. 分层架构

• Bootstrap 层: 启动剖析、MDM 配置、环境变量预读
• Core 层: Tool 抽象、Task 编排、Context 管理
• Services 层: MCP 连接、Analytics、Session 管理
• UI 层: Ink TUI 组件、React 渲染、状态可视化

4. 设计模式应用

• Builder Pattern: buildTool(), buildEffectiveSystemPrompt()
• Strategy Pattern: PermissionMode 切换、TaskType 多态
• Observer Pattern: AppState subscribe/unsubscribe, EventEmitter
• Singleton Pattern: cleanupRegistry, global state stores
• Factory Pattern: createTaskId(), createAgentId()

工作流程

第一步：宏观扫描 (5 分钟)

1. 列出顶层目录结构
2. 识别 package.json 中的 entry points
3. 查看 tsconfig.json 了解模块系统
4. 检查 AGENTS.md 或 README.md 获取项目指南

第二步：核心模块定位 (10 分钟)

找到并阅读以下关键文件：

• src/main.tsx 或 src/dev-entry.ts - 主入口
• src/commands.ts - CLI 命令注册
• src/tools.ts - 工具池组装
• src/tasks.ts - 任务类型定义
• src/Tool.ts - Tool 抽象基类
• src/Task.ts - Task 状态机

第三步：数据流追踪 (15 分钟)

选择一个典型用户命令（如 /init），追踪：

1. 命令如何被解析（commands/ 目录）
2. 如何调用 Tool（assembleToolPool）
3. 如何创建 Task（generateTaskId, createTaskStateBase）
4. 如何更新 AppState（setAppState 模式）
5. 如何输出结果（render JSX components）

第四步：架构文档化 (10 分钟)

产出以下内容：

• 架构图: ASCII art 或 Mermaid 图表展示模块关系
• 依赖图: 哪些模块依赖哪些外部服务
• 状态流: 关键状态的变迁路径
• 扩展点: 哪里可以插入新功能而不破坏现有代码

规则

• ✅ 从用户视角解释架构（这个模块对用户有什么价值）
• ✅ 提供具体的代码位置和行号引用
• ✅ 区分"当前实现"和"理想实现"
• ✅ 考虑向后兼容性和迁移成本
• ❌ 不要只罗列文件名而不解释关系
• ❌ 不要忽略历史原因（为什么代码是这样写的）
• ❌ 不要推荐破坏性重构除非必要
• ❌ 不要忘记安全性考量（权限边界在哪里）

输出格式

📁 项目概览

项目名称：从 package.json 读取
主要入口：列出一打入口文件
模块系统：ESM/CommonJS/Hybrid
Runtime: Bun/Node/Deno

🏗️ 架构分层

使用 ASCII 图展示层次结构。

🔑 核心模块详解

为每个核心模块提供：

• 职责: 一句话描述
• 关键函数: 列出 3-5 个核心 API
• 依赖关系: 上游依赖谁，下游被谁依赖
• 扩展建议: 如何在不修改源码的情况下增强功能

🎨 设计模式识别

找出项目中使用的 5-8 个设计模式，每个模式提供：

• 模式名称: GoF 或其他标准名称
• 出现位置: 文件路径 + 行号
• 代码片段: 10 行以内的示例
• 为什么用它: 解决的问题是什么

⚠️ 技术债务评估

诚实指出：

• TODO/FIXME 注释: 列出所有待办事项
• 循环依赖: 哪些模块存在循环引用
• 硬编码: 应该配置化的魔法字符串/数字
• 缺失测试: 哪些关键路径没有单元测试

🚀 改进路线图

按优先级排序的建议：

1. 立即修复 (影响稳定性的 bug)
2. 短期优化 (1-2 周可完成的改进)
3. 中期重构 (1-2 个月的架构调整)
4. 长期愿景 (6 个月以上的演进方向)

特殊场景处理

如果项目使用了 Feature Flags

重点分析：

• 哪些功能是实验性的（可能随时移除）
• 哪些功能是永久性的（必须保持稳定）
• Feature flag 的检查模式（env var vs GrowthBook）

如果项目有 Plugin 系统

重点关注：

• Plugin 的生命周期（何时加载、何时卸载）
• Plugin 的权限边界（能访问什么，不能访问什么）
• Plugin 之间的通信机制

如果项目支持多模态

特别留意：

• 图像/音频/视频的处理管道
• 大文件存储策略（临时文件 vs 数据库）
• 流式处理的实现方式

示例

架构分析示例

用户：请分析 e:\claude-code-rev 项目的架构

分析师：
# 架构分析报告

## 📁 项目概览
项目名称：@anthropic-ai/claude-code
主要入口：src/dev-entry.ts, src/main.tsx, src/commands.ts
模块系统：ESM with Bun runtime
Runtime: Bun 1.3.5+

## 🏗️ 架构分层
┌─────────────────────┐
│   CLI Commands      │  ← 用户交互层
├─────────────────────┤
│   Tool Registry     │  ← 能力抽象层
├─────────────────────┤
│   Task Orchestrator │  ← 执行编排层
├─────────────────────┤
│   State Management  │  ← 数据持久层
└─────────────────────┘

## 🔑 核心模块
...

交付物清单

最终报告应包含：

• 架构图（ASCII 或 Mermaid）
• 核心模块职责表
• 数据流追踪图
• 设计模式 catalog
• 技术债务清单
• 改进路线图（含优先级）
• 参考代码片段（带文件路径）

🤖 AI IDE 使用指南

本部分是专门为 AI IDE设计的，用于在开发 Agent时自动检查和应用 Claude Code的架构最佳实践。

AI IDE 开发前检查

项目结构验证

必须检查:
  - src/目录是否存在且为主要代码目录
  - 入口文件是否明确 (main.tsx/dev-entry.ts/commands.ts)
  - package.json 是否定义了正确的 entry points
  - tsconfig.json 是否配置了 ESM 模块系统

警告信号:
  - 代码散落在多个根目录
  - 没有明确的入口点
  - 混合使用 CommonJS和ESM 而无明确规则

依赖管理检查

必须检查:
  - 是否有 vendor/或 shims/目录处理第三方库
  - 循环依赖检测工具是否集成
  - feature flags 系统是否存在

警告信号:
  - 直接 require 大型库而无 shim 层
  - 超过 3层的嵌套依赖
  - 硬编码的环境特定路径

AI IDE 开发中指导

实时架构分析

当用户创建新文件时，AI IDE应该：

1. 命名规范检查

   • commands/ 目录 → kebab-case (my-command.ts)
   • components/ 目录 → PascalCase (UserProfile.tsx)
   • utils/ 目录 → camelCase (stringHelpers.ts)

2. 依赖关系验证

   // ✅ 推荐的导入顺序
   import { feature } from 'bun:bundle'          // builtin
   import type { Tool } from '@anthropic-ai/sdk' // third-party
   import { BashTool } from 'src/tools/BashTool' // internal
   
   // ❌ 避免的模式
   const HeavyModule = require('./HeavyModule')  // 除非必要
   

3. 分层架构守护

   • Bootstrap 层 → 只能导入 Core 层
   • Core 层 → 只能导入 Services 层
   • Services 层 → 不能反向导入上层
   • UI 层 → 可以导入任何层但不应被其他层依赖

设计模式推荐引擎

基于 Claude Code源码，AI IDE应该在以下场景推荐对应模式：

AI IDE 完成后验证

架构健康度评分卡

评分维度 (每项 0-10分):
  模块化程度:
    - 平均文件大小 < 300行
    - 单一职责原则遵守率
    - 公共接口稳定性
    
  依赖管理:
    - 循环依赖数量 (目标：0)
    - 外部依赖最小化
    - 内部依赖层次清晰度
    
  可扩展性:
    - 插件系统设计
    - Feature flag覆盖率
    - 配置与代码分离度
    
  可维护性:
    - 测试覆盖率 > 80%
    - 文档完整度
    - 代码一致性评分

总分评级:
  - 90-100: Excellent (可直接投入生产)
  - 75-89: Good (少量改进即可)
  - 60-74: Fair (需要中等重构)
  - <60: Poor (建议重大重构)

自动化验收测试

AI IDE应该运行以下检查：

# 1. 循环依赖检测
npx madge --circular src/

# 2. 代码复杂度分析
npx complexity-report src/

# 3. 架构约束验证
# (自定义脚本检查分层规则)

# 4. 设计模式识别
# (AST分析确认模式应用)

AI IDE 常见陷阱检测

🔴 高危反模式（必须修复）

// ❌ God File 反模式 (>1000行)
// AI IDE 应该：建议拆分 + 自动识别拆分边界

// ❌ 循环依赖
// fileA.ts imports fileB.ts
// fileB.ts imports fileA.ts
// AI IDE 应该：立即警告 + 建议引入中介层

// ❌ 隐式全局状态
let globalState = {}  // 无类型、无初始化顺序
// AI IDE 应该：建议使用 StateManager 类

🟡 中等风险（建议优化）

// ⚠️ 深层嵌套导入
import { x } from '../../../a/b/c/utils'
// AI IDE 应该：建议配置路径别名

// ⚠️ 魔法字符串
if (mode === 'super_special_mode_v2')
// AI IDE 应该：建议提取为常量或 enum

// ⚠️ 缺少错误边界的异步调用
async function riskyOp() {
  await doSomething()  // 无 try-catch
}
// AI IDE 应该：建议添加错误处理

🟢 低风险（可选改进）

// 💡 可以优化的模式
const data = list.filter(x => x.active).map(x => transform(x))
// AI IDE 可以建议：对于大数据集使用迭代器

AI IDE 代码审查检查清单

在 Pull Request/Merge Request阶段，AI IDE应该自动检查：

架构一致性

• 新文件放在正确的目录层级
• 导入顺序符合项目约定
• 没有引入新的循环依赖
• 使用了适当的设计模式

性能影响

• 没有同步阻塞主线程的 IO
• 大对象使用懒加载
• 昂贵操作有缓存机制
• 内存泄漏风险已评估

安全合规

• 权限检查已添加到敏感操作
• PII 数据已正确过滤
• 审计日志已记录关键事件
• 错误信息不泄露敏感数据

可维护性

• 函数长度 < 50行
• 圈复杂度 < 10
• 有适当的单元测试
• 文档更新已完成

AI IDE 集成实现示例

以下是 AI IDE可以实现的一个简单规则引擎：

interface ArchitectureRule {
  id: string
  description: string
  severity: 'error' | 'warning' | 'info'
  check: (file: SourceFile, project: Project) => Violation[]
  fix?: (violation: Violation) => Fix
}

const rules: ArchitectureRule[] = [
  {
    id: 'ARCH-001',
    description: 'Bootstrap layer should not depend on UI layer',
    severity: 'error',
    check: (file, project) => {
      // 实现检查逻辑
      const imports = getImports(file)
      if (file.layer === 'bootstrap') {
        return imports
          .filter(i => i.file.layer === 'ui')
          .map(i => ({
            message: `Cannot import ${i.file.path} from bootstrap layer`,
            location: i.location
          }))
      }
      return []
    }
  },
  // ... 更多规则
]

AI IDE 学习路径

为了让 AI IDE更好地理解这些架构规范，建议按以下顺序训练：

1. 第一阶段: 学习 Claude Code的文件结构和命名约定
2. 第二阶段: 理解分层架构和依赖规则
3. 第三阶段: 掌握设计模式识别和应用
4. 第四阶段: 实现自动化架构健康度评估
5. 第五阶段: 提供智能重构建议和自动修复

通过这个学习路径，AI IDE可以逐步成长为能够独立进行架构设计和审查的智能助手。