架构师 AI Agent 构建能力标准与执行手册

定位：架构师 L3 达标核心能力项 —— Agent 搭建与自动化闭环
目标：从顶层设计到落地执行，完成一个可交付、可复用的 Agent 构建方案

一、架构师为什么要会建 Agent

传统架构师解决的是「系统怎么搭」的问题。AI 时代的架构师还要解决「效率系统怎么搭」的问题。

Agent 不是聊天机器人。Agent 是一个能感知上下文 → 自主决策 → 调用工具 → 输出结果 → 反馈迭代的自动化闭环系统。架构师搭 Agent，本质上是在搭一个数字员工，替代自己的重复劳动。

核心思维转变：

传统思维 Agent 思维
我来写代码 我来定义意图，Agent 来写代码
我来做 Code Review 我来定规则，Agent 来审
我来排查问题 我来搭排查流水线，Agent 来跑
我来写文档 我来搭知识工作流，文档即产出

二、架构师 Agent 构建能力标准（L3 必达）

2.1 四层能力模型

1
2
3
4
5
6
7
8
9
10
11
L3-架构师Agent能力金字塔

     ┌─────────────┐
     │  L4 自主进化  │  Agent能自我优化Prompt、更新规则
     ├─────────────┤
     │  L3 工作流闭环 │  多步骤任务编排，异常处理，结果验收 ← 你在这里
     ├─────────────┤
     │  L2 工具链集成 │  配置Hooks、调用外部API、文件系统操作
     ├─────────────┤
     │  L1 单点自动化 │  用Prompt完成单次任务（问答、补全、翻译）
     └─────────────┘

2.2 L3 达标硬性指标

# 能力项 达标标准 验收方式
1 Prompt Engineering 能编写结构化 System Prompt，包含角色定义、约束条件、输出格式、异常处理 提交至少 1 个生产级 Prompt 文件
2 工具编排 能为 Agent 配置至少 3 种工具调用能力（文件读写、命令执行、代码搜索等） 提交 Agent 配置文件（如 .claude/settings.json、MCP 配置等）
3 Hooks/触发器 能配置事件驱动的自动化流程（如提交前自动审查、部署前自动检查） 提交 Hook 配置，展示触发日志
4 多步骤任务流 能编排 3 步以上的 Agent 工作流，含条件分支和错误回退 提交工作流定义或脚本
5 结果验收 能定义验收标准，Agent 输出可被自动化验证 提交验证脚本或检查清单

三、架构师 Agent 构建方法论

3.1 设计原则：SAFER 框架

架构师设计 Agent，遵循五个原则：

原则 含义 关键问题
S - Single Responsibility 一个 Agent 只做一件事 这个 Agent 的唯一职责是什么？
A - Auditable 每一步都可审计 出了问题能追溯到哪一步？
F - Fail-safe 失败时安全降级 Agent 挂了会不会搞坏东西？
E - Explicit Boundary 边界明确，不越权 Agent 不能做什么？
R - Recoverable 可恢复、可重试 中间断了他能不能接着跑？

3.2 构建流程：六步法

1
2
3
4
5
6
Step 1: 场景定义 → 这个Agent解决什么问题？频率多高？价值多大？
Step 2: 输入输出规约 → 输入是什么？输出是什么？格式是什么？
Step 3: 工具选型 → 需要哪些工具？哪些API？哪些数据源？
Step 4: Prompt/规则编写 → System Prompt + 约束条件 + 异常处理
Step 5: 编排与集成 → 多步骤串联、条件分支、错误处理
Step 6: 验收与上线 → 自动化测试、效果度量、迭代优化

四、实战：三个架构师级别 Agent 构建方案

方案 A：AI 辅助架构审查 Agent（推荐首选）

场景：代码提交前自动进行架构合规性检查

Step 1 — 场景定义

1
2
3
4
5
问题：代码提交缺乏统一的架构层面的审查，经常出现循环依赖、分层违规、
     接口设计不合理等问题，到 Code Review 阶段才发现，返工成本高。
目标：在 git commit 阶段自动拦截架构层面的问题。
频率：每次提交。
价值：左移架构审查，降低返工率。

Step 2 — 输入输出规约

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
输入：git diff（本次提交的变更内容）
输出：架构审查报告（JSON 格式）
      {
        "passed": true/false,
        "issues": [
          {
            "rule": "分层规范",
            "severity": "error|warning",
            "file": "xxx.go",
            "line": 42,
            "message": "controller 层直接调用 dao 层，跳过了 service 层",
            "suggestion": "应通过 XxxService 接口调用"
          }
        ]
      }

Step 3 — 工具选型

工具 用途
Claude Code Pre-commit Hook 触发时机
AST 解析（Go: go/ast） 分析代码结构
Claude API / 本地模型 理解语义，判断是否违规
项目架构规范文档 作为审查依据

Step 4 — 配置实现

方案 A-1：基于 Claude Code Hooks（轻量级，5 分钟可落地）

在项目根目录 .claude/settings.json 中配置：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python scripts/arch-review.py"
          }
        ]
      }
    ]
  }
}

方案 A-2：基于 Git Pre-commit Hook（独立于 Claude Code）

创建 .git/hooks/pre-commit：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
#!/bin/bash
# 架构审查 Agent - Pre-commit Hook

echo "🔍 Running Architecture Review Agent..."

# 获取本次提交的变更文件列表
CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep -E '\.(go|java|ts)$')

if [ -z "$CHANGED_FILES" ]; then
    echo "✅ No source code changes, skipping review."
    exit 0
fi

# 获取 diff 内容
DIFF=$(git diff --cached)

# 调用 AI 审查（使用 Claude CLI）
RESULT=$(claude -p "
你是架构审查 Agent。请基于以下架构规范审查本次代码变更：

## 架构规范
1. 分层规范：Controller → Service → DAO，不允许跨层调用
2. 接口规范：Service 层必须面向接口编程
3. 依赖规范：禁止循环依赖
4. 命名规范：遵循项目既定命名约定

## 变更内容
$DIFF

## 输出要求
- 如无问题，输出：PASS
- 如有问题，输出问题列表，每个问题包含：文件、行号、违规规则、严重程度、修改建议
- 最后一行输出：RESULT: PASS 或 RESULT: FAIL
")

echo "$RESULT"

# 检查结果
if echo "$RESULT" | grep -q "RESULT: FAIL"; then
    echo "❌ Architecture review failed. Please fix the issues above."
    exit 1
fi

echo "✅ Architecture review passed."
exit 0

Step 5 — 架构审查规则文件

创建 docs/arch-rules.yaml：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
# 架构审查规则定义
rules:
  - id: layer-violation
    name: 分层规范检查
    severity: error
    description: "禁止跨层调用，Controller 不能直接调用 DAO"
    patterns:
      - from: "controller"
        forbidden_to: ["dao", "repository", "mapper"]
      - from: "handler"
        forbidden_to: ["dao", "repository"]

  - id: circular-dependency
    name: 循环依赖检查
    severity: error
    description: "包之间不允许存在循环依赖"
    check_command: "go vet ./..."

  - id: interface-missing
    name: 接口规范检查
    severity: warning
    description: "Service 层对外暴露应通过接口"
    patterns:
      - in: "service"
        should_define_interface: true

  - id: naming-convention
    name: 命名规范检查
    severity: warning
    description: "遵循 Go 命名规范"
    conventions:
      - "导出函数使用 PascalCase"
      - "私有函数使用 camelCase"
      - "接口名以 er 后缀或描述性名词结尾"

Step 6 — 验收标准

1
2
3
4
5
6
7
验收清单：
□ Hook 在 git commit 时自动触发
□ 能检测出至少 3 类架构违规（分层、循环依赖、接口缺失）
□ 审查结果输出结构化 JSON
□ 严重问题能阻断提交
□ 误报率 < 10%
□ 审查耗时 < 30 秒（中等规模变更）

方案 B：智能运维排障 Agent

场景：生产环境异常自动诊断与修复建议

设计概要

1
2
3
4
5
6
7
8
触发：监控告警 / 手动触发
输入：错误日志 + 系统状态 + 近期变更记录
处理流程：
  1. 日志模式识别 → 分类异常类型
  2. 上下文关联 → 查询近期部署、配置变更
  3. 根因分析 → 基于知识库匹配历史相似案例
  4. 修复建议 → 输出诊断报告 + 推荐操作
输出：结构化诊断报告（Markdown）

核心编排脚本

创建 scripts/diagnose-agent.sh：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
#!/bin/bash
# 智能运维排障 Agent

set -e

LOG_FILE=${1:-""}
KNOWLEDGE_BASE="docs/troubleshooting/"
OUTPUT="diagnosis-report-$(date +%Y%m%d-%H%M%S).md"

if [ -z "$LOG_FILE" ]; then
    echo "Usage: ./diagnose-agent.sh <error-log-file>"
    exit 1
fi

echo "🔍 Diagnosing..."

# Step 1: 提取关键错误信息
ERROR_PATTERNS=$(claude -p "
从以下日志中提取关键错误信息，包括：错误类型、发生时间、涉及模块、调用链。
只输出结构化 JSON，不要解释。

日志内容：
$(cat $LOG_FILE)
")

echo "📋 Error patterns extracted."

# Step 2: 关联近期变更
RECENT_CHANGES=$(git log --since="24 hours ago" --oneline --no-merges 2>/dev/null || echo "Not a git repo")

# Step 3: 匹配知识库
HISTORY_MATCH=$(claude -p "
基于以下错误模式，从知识库中查找相似案例和已知解决方案：

错误模式：
$ERROR_PATTERNS

知识库目录：$KNOWLEDGE_BASE
")

# Step 4: 生成诊断报告
claude -p "
你是运维架构诊断 Agent。请生成一份结构化的诊断报告。

## 错误分析
$ERROR_PATTERNS

## 近期变更
$RECENT_CHANGES

## 历史案例匹配
$HISTORY_MATCH

## 输出格式
# 诊断报告

## 1. 问题概述
[一句话描述]

## 2. 根因分析
[分析链条]

## 3. 影响范围
[受影响的模块/服务]

## 4. 推荐操作
- 立即：[紧急处理步骤]
- 短期：[根治方案]
- 长期：[预防措施]

## 5. 历史相似案例
[引用知识库中的案例]

## 6. 置信度
[高/中/低，及原因]
" > "$OUTPUT"

echo "✅ Diagnosis report generated: $OUTPUT"

知识库目录结构

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
docs/troubleshooting/
├── database/
│   ├── connection-pool-exhaustion.md
│   ├── slow-query-diagnosis.md
│   └── replication-lag.md
├── network/
│   ├── dns-resolution-failure.md
│   ├── service-mesh-timeout.md
│   └── load-balancer-misconfig.md
├── kubernetes/
│   ├── pod-crashloopbackoff.md
│   ├── resource-limit-oom.md
│   └── certificate-expiry.md
└── application/
    ├── yaml-type-panic.md          ← 你的实际案例
    ├── memory-leak-patterns.md
    └── goroutine-leak.md

方案 C：架构文档自动生成 Agent

场景：代码变更后自动同步更新架构文档

设计概要

1
2
3
4
5
6
7
8
触发：Git push / 手动触发
输入：代码变更 diff + 现有架构文档
处理流程：
  1. 解析变更 → 识别影响哪些架构组件
  2. 差异分析 → 判断文档是否需要更新
  3. 文档更新 → 自动生成/修改架构文档
  4. 提交 PR → 将文档变更提交为 PR
输出：架构文档更新 PR

配置文件 agents/doc-agent-config.yaml

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
name: "架构文档同步 Agent"
version: "1.0"
description: "监控代码变更，自动同步更新架构文档"

triggers:
  - type: "git-push"
    branches: ["main", "release/*"]

watch_paths:
  - "server/**"        # 后端代码变更
  - "web/**"           # 前端代码变更
  - "docs/arch/**"     # 架构文档目录

output:
  format: "markdown"
  directory: "docs/arch/"
  pr_target: "main"
  pr_labels: ["auto-generated", "doc-sync"]

templates:
  component_doc: |
    # {{component_name}}

    ## 概述
    {{summary}}

    ## 模块结构
    {{module_structure}}

    ## 接口定义
    {{api_definitions}}

    ## 依赖关系
    {{dependencies}}

    ## 变更记录
    {{change_log}}

rules:
  - "API 接口变更时，必须同步更新接口文档"
  - "新增模块时，必须补充模块说明和依赖关系"
  - "删除模块时，必须标记为废弃并更新引用关系"
  - "配置项变更时，必须同步更新配置文档"

五、Agent 构建工具链速查

5.1 推荐工具矩阵

场景 工具 适合架构师的程度
代码 Agent（日常开发） Claude Code CLI ★★★★★ 直接集成到工作流
代码 Agent（IDE内） Cursor / Copilot ★★★★☆ 适合编码阶段
自定义 Agent 框架 Claude Agent SDK ★★★★★ 完全可编程
工作流编排 n8n / Dify ★★★☆☆ 可视化但灵活性低
MCP Server 扩展 自建 MCP Server ★★★★☆ 扩展 Agent 能力边界
Hook 自动化 Claude Code Hooks ★★★★★ 零代码，事件驱动

5.2 Claude Code Agent 能力扩展点

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
                Claude Code Agent 架构
┌──────────────────────────────────────────┐
│              System Prompt               │  ← 定义 Agent 人格和能力边界
│  (CLAUDE.md / .claude/instructions.md)   │
├──────────────────────────────────────────┤
│              Tools (内置)                 │
│  Read / Write / Edit / Bash / Grep / ... │  ← Agent 的"手"
├──────────────────────────────────────────┤
│           MCP Servers (扩展)             │  ← 扩展 Agent 能力
│  GitHub / Playwright / Context7 / ...    │
├──────────────────────────────────────────┤
│             Hooks (触发器)               │  ← 事件驱动的自动化
│  PreToolUse / PostToolUse / ...          │
├──────────────────────────────────────────┤
│           SubAgents (子Agent)            │  ← 任务分解与并行
│  Explore / Plan / Code-Review / ...      │
└──────────────────────────────────────────┘

5.3 架构师 Agent 配置文件模板

.claude/settings.json（项目级 Agent 配置）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "permissions": {
    "allow": [
      "Read",
      "Grep",
      "Glob",
      "Bash(git *)",
      "Bash(go vet *)",
      "Bash(go test *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "echo '[$(date)] File modified: $CLAUDE_FILE_PATH' >> .claude/change-log.txt"
          }
        ]
      }
    ]
  }
}

CLAUDE.md（项目级 Agent 指令）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# Project: pangee-cluster

## Architecture
- Go backend (server/) + Vue frontend (web/)
- Based on Kubeclipper, manages Kubernetes clusters
- YAML config files parsed via gopkg.in/yaml.v2

## Coding Standards
- Follow Go standard project layout
- Service layer must define interfaces
- Error handling: use fmt.Errorf with %w for wrapping
- All exported functions must have doc comments

## Agent Rules
- Before modifying any file in server/, run: go vet ./server/...
- After code changes, run relevant tests: go test ./server/...
- Never modify vendor/ directory directly
- For architecture changes, update docs/arch/ first, then implement

六、执行路线图

第一周：基础搭建

1
2
3
4
5
6
7
8
9
10
11
12
13
14
Day 1-2: 配置 Claude Code 工作环境
         - 安装 Claude Code CLI
         - 配置项目级 CLAUDE.md
         - 配置 settings.json（权限 + Hooks）

Day 3-4: 实现方案 A（架构审查 Agent）
         - 编写 arch-review.py 或 pre-commit hook
         - 定义架构规则文件
         - 测试验证

Day 5:   内部试运行
         - 在 feature 分支上测试
         - 收集误报/漏报数据
         - 迭代规则

第二周：扩展深化

1
2
3
4
5
6
7
8
9
10
11
12
13
Day 6-7: 实现方案 B（排障 Agent）
         - 搭建知识库目录
         - 编写排障脚本
         - 用历史故障验证效果

Day 8-9: 整合与自动化
         - 将多个 Agent 编排为统一入口
         - 配置 CI/CD 集成

Day 10:  产出交付
         - 编写 Agent 使用文档
         - 录制演示视频/截图
         - 提交 L3 达标案例

七、案例提交 Checklist

提交 Agent 构建案例时，确保以下材料齐全：

  • 设计文档：Agent 的场景定义、输入输出规约、架构图
  • 配置文件：settings.json / CLAUDE.md / Hook 配置 / 规则文件
  • 可执行脚本：审查脚本、排障脚本、文档生成脚本
  • 运行证据：执行截图、输出日志、前后对比
  • 效率数据：人工耗时 vs Agent 耗时对比
  • 可复用模板：其他团队可以直接拿去用的配置模板

本文档为架构师岗位 AI Agent 构建能力达标的执行手册，与《架构师L3标准与AI案例.md》配套使用。