AI编程-工程化

AI Agent 的六大核心能力

• Sub-Agents（子代理） 的核心思想是：一个复杂任务可以拆解给多个专职角色。
• Skills（技能） 的核心思想是：AI 应该知道什么时候用什么能力。

• Memory：解决 Agent 每次对话都"从零开始"、不理解项目背景的问题，让 AI 真正记住你的代码结构、约束和上下文。
• Sub-Agents：解决单一 Agent 角色混乱、上下文污染、又写代码又做审查的问题，通过职责拆分实现关注点分离。
• Skills：解决 Prompt 不可复用、经验无法沉淀、团队能力难以传承的问题，把个人技巧变成可组合的工程资产。
• Hooks：解决 Agent 执行过程不可控、缺乏检查点、容易"越权操作"的问题，在关键节点引入自动校验和人工兜底。
• Headless：解决 Agent 只能在 IDE 里交互、无法进入自动化流程的问题，让 AI 能在 CI/CD 中无人值守地运行。
• Agent SDK：解决只会用对话的方式使用 Agent，难以嵌入现有系统和工作流的问题，用代码驱动 Agent，构建可编排的工程流程。

Claude Code 的底层能力

分为四个层次：基础层、扩展层、集成层和编程接口层。

基础层：Memory（记忆系统）

核心文件是 CLAUDE.md

• 公司的代码风格是什么。
• Git 提交信息怎么写。
• 项目的架构是怎样的。
• 有哪些不能碰的"禁区"。

# Project: E-commerce Platform

## Tech Stack
- Frontend: React + TypeScript
- Backend: Node.js + Express
- Database: PostgreSQL

## Code Style
- Use functional components
- Prefer async/await over .then()
- Maximum line length: 100 characters

## Important Rules
- NEVER commit to main directly
- Always run tests before pushing

扩展层：四大核心组件

包含 Commands（斜杠命令）、Skills（技能）、SubAgents（子代理）、Hooks（钩子）四个核心组件

Commands（斜杠命令）

• 斜杠命令是 Claude Code 内置或用户自定义的一系列核心能力
• Commands 适合标准化操作------团队统一的 commit 格式、固定的部署流程等。

用户输入: /review

Claude 执行: 根据 .claude/commands/review.md 的指令审查代码

SubAgents（子代理）

子代理是除了 Skills 之外的另一个大杀器，用于独立完成专项任务。

Hooks（钩子）

Hooks 适合自动化检查------格式化、安全检查、日志记录等。

集成层：连接外部世界

集成层包含 Headless（无头模式）和 MCP（Model Context Protocol）两大技术。

编程接口层：Agent SDK

当配置式的扩展不够用时，你可以用代码来驱动 Claude。这种方式适合构建自定义 Agent------完全控制执行流程、自定义工具、复杂工作流。

设计一个生产系统：

• 如果你需要"每次都必须执行"的操作（比如代码格式化），你需要 100% 确定性------选择 Commands 或 Hooks。
• 如果你希望 Claude "智能判断何时使用"（比如识别到安全问题时自动深入分析），你可以接受概率性------选择 Skills。
• 如果任务可能很重，你希望"既可以手动触发，也可以让 Claude 自己决定"，你需要可控性------选择 SubAgents。

SubAgents（子代理）设计

Sub-Agents 应用场景是上下文污染 、权限边界 、高噪声干扰 、阶段性分工和可控编排。

思考步骤	问题	代码审查场景的答案
1.痛点是什么	AI 在哪个环节出了问题?	审查时顺手改了代码
2.缺失了什么	缺的是能力还是边界?	缺权限边界
3.该用什么机制	SubAgent /Skill / Hook?	SubAgent(需要独立上下文+权限隔离)
4.边界怎么画	能做什么、不能做什么?	能读不能写
5.如何验证	怎么确认边界生效?	尝试让它修改文件，观察拒绝行为

创建代码审查子代理

首先是创建.claude/agents/ 目录，然后在其中创建代码审查子代理的配置文件code-reviewer.md：

---
name: code-reviewer
description: Review code changes for quality, security, and best practices. Proactively use this after code modifications.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer with expertise in security and software engineering best practices.

## When Invoked

1. **Identify Changes**: Run `git diff` or read specified files
2. **Analyze Code**: Check against multiple dimensions
3. **Report Issues**: Categorize by severity

## Review Dimensions

### Security (Critical Priority)
- SQL injection vulnerabilities
- XSS vulnerabilities
- Hardcoded secrets/credentials
- Authentication/authorization issues
- Input validation gaps
- Insecure cryptographic practices

### Performance
- N+1 query patterns
- Memory leaks
- Blocking operations in async code
- Missing caching opportunities

### Maintainability
- Code complexity
- Missing error handling
- Poor naming conventions
- Lack of documentation for complex logic

### Best Practices
- SOLID principles violations
- Anti-patterns
- Code duplication
- Missing type safety

## Output Format

```markdown
## Code Review Report

### Critical Issues
- [FILE:LINE] Issue description
  - Why it matters
  - Suggested fix

### Warnings
- [FILE:LINE] Issue description
  - Recommendation

### Suggestions
- [FILE:LINE] Improvement opportunity

### Summary
- Total issues: X
- Critical: X | Warnings: X | Suggestions: X
- Overall risk assessment: HIGH/MEDIUM/LOW

### Guidelines
- Prioritize security issues
- Be specific about locations (file:line)
- Provide actionable fix suggestions
- Focus on the changes, not existing code (unless security-critical)
- Keep explanations concise

并行探索的设计原则

• 明确边界：每个子代理只关注自己的领域。
• 统一格式：所有子代理输出格式一致，便于综合。
• 用快模型：探索任务用 haiku 更高效。
• 只读权限：探索不需要修改任何东西。
• 验证独立性：并行前检查子任务是否真正独立------如果存在信息依赖，要么改为串行，要么在综合阶段补充跨模块分析。

流水线的设计原则如下

• 职责分离：每个阶段只做一件事。
• 权限递进：只在必要时给写权限。
• 清晰交接：每个阶段为下一阶段准备信息。
• 可中断：允许人工介入任何阶段。
• 可回滚：修复阶段要考虑回滚方案。
• 交接契约化：每个阶段的 Handoff 部分应该有明确的字段约束，而不是一句模糊的"告诉下一阶段该关注什么"。
• 失败回退到分析，而非重试执行：Verifier 失败时，回到 Analyzer 而不是让 Fixer "再试一次"。
• 在读写跨越点设置人工审批：Analyzer → Fixer 是流水线中成本最高的决策点，推荐在此处设置审批。

并行 vs 流水线：什么时候用什么

• 任务之间独立吗？→ 并行
• 任务之间有依赖吗？→ 流水线

场景	选择	原因
理解新项目的多个模块	并行	模块之间相对独立
比较多个技术方案	并行	方案之间相对独立
修复一个bug	流水线	阶段之间有依赖关系
开发一个新功能	流水线	设计->实现->测试有顺序
代码审查多个文件	并行	文件之间相对独立
重构一段复杂代码	流水线	分析->计划->执行->验证

Bug 修复流水线

• Locator：只回答"在哪"
• Analyzer：只回答 "为什么"
• Fixer：只负责 "怎么改"
• Verifier：只负责 "改对没有"

帮我修复这个 bug：用户登录后偶尔 token 验证失败。

执行方式：
1. 先让 bug-locator 定位 → 自动传给 bug-analyzer
2. bug-analyzer 分析完后 → 先给我看根因分析，我确认后再继续
3. 我确认后 → 让 bug-fixer 修复 → 自动传给 bug-verifier
4. bug-verifier 验证完给我最终报告

Skills （技能）设计

Skills 是一种可被语义触发的能力包，它包含领域知识、执行步骤、输出规范与约束条件，并在需要时渐进式加载到主 Agent 的认知空间中。

触发机制

触发方式	流程	description的角色
Claude 自动触发	用Claude读 description →>语义匹配 →加载全文 → 执行	角发器(必须精确)
用户手动触发 /skill-name args	直接加载全文 →$ARGUMENTS替换 → 执行	不参与(已跳过匹配)

Agent 生态中的四大支柱

• Tools 是行动原语。它回答的是能做什么。读文件、改代码、执行 Bash 命令......这些是操作层面的能力。
• SubAgents 是执行分工。它回答的是谁来做。当任务复杂到需要独立上下文时，子代理承担专职职责。
• Hooks 是流程规则。它回答的是什么时候检查。它们在关键节点自动触发质量校验或合规约束。
• Skills 回答的问题："怎么做，以及何时做"，它不是工具，也不是分工机制。它是一种可操作知识结构。

Skills和SubAgent的使用场景

维度	只用 Skills	只用 SubAgents	组合使用
上下文需求	需要在当前对话中应用知只	需要隔离上下文，避免污染	需要隔离 + 专业知识
生命周期	按需加载，知识留在上下	完整任务周期，完成后释放	任务周期内拥有专业知识
角色模型	同一个 Agent 扮演不同角名	不同 Agent 各司其职	专门的 Agent 配专门的知识
知识类型	领域规范、操作流程、参考资料	完整的角色定义(系统提示)	角色 + 领域知识一体化
复用性	跨项目共享(Personal/Plugin)	通常项目级定义	角色项目级，Skill 可跨项目
触发方式	语义匹配或 /command	Claude 根据任务需要委托	显式委托给专家

Skill 设计的四种模式

模板驱动模式

模板驱动模式核心是用模板强约束输出结构，让结果稳定、可对比、可自动解析。适用于报告生成、文档输出等需要格式一致性的场景。它解决的是"输出不稳定"的问题，本质是把自然语言生成转化为结构化接口。

.claude/skills/report-generating/
├── SKILL.md              # 路由 + 流程
└── templates/
    ├── weekly_report.md   # 周报模板
    ├── incident.md        # 事故报告模板
    └── review.md          # 评审报告模板

脚本增强模式

脚本增强模式的核心是把计算、匹配、数据转换等确定性逻辑交给脚本执行，而不是让 Claude 推理完成。适用于公式计算、正则匹配、指标统计等场景。它解决的是"结果不稳定"的问题，本质是把概率型推理替换为确定性执行。

.claude/skills/data-analyzing/
├── SKILL.md              # 路由 + 流程
└── scripts/
    ├── parse_csv.py       # 数据解析
    ├── calculate.py       # 指标计算
    └── visualize.py       # 生成图表 HTML

知识分层模式

知识分层模式的核心是按使用频率组织知识，高频内联，中低频按需加载。适用于规则多、领域复杂的 Skill。它解决的是"上下文膨胀"的问题，本质是通过渐进加载控制认知复杂度。

.claude/skills/security-reviewing/
├── SKILL.md              # 核心检查清单（高频，~200 行）
├── QUICKREF.md           # 常见漏洞速查（中频）
├── OWASP_TOP10.md        # OWASP 详细标准（低频）
├── reference/
│   ├── xss.md           # XSS 防护详解（按需）
│   ├── sqli.md          # SQL 注入详解（按需）
│   └── auth.md          # 认证问题详解（按需）
└── examples/
    ├── good_auth.md      # 正确实现示例（按需）
    └── bad_patterns.md   # 反模式示例（按需）

工具隔离模式

工具隔离模式的核心是通过 allowed-tools 明确能力边界，限制 Skill 可以调用的工具。适用于需要安全控制或职责划分的场景。它解决的是"越权风险"的问题，本质是把安全约束前置为结构设计。当你需要确保 Skill 不会做"不该做的事"时------这是安全设计，不是功能设计。

# 审计类 Skill：只读
# 例如：代码审查
allowed-tools: [Read, Grep, Glob]

# 生成类 Skill：只写不改
# 例如：文档生成
allowed-tools: [Read, Grep, Glob, Write]

# 分析类 Skill：只读 + 脚本
# 例如：数据分析
allowed-tools: [Read, Grep, Glob, Bash(python:*)]

# 执行类 Skill：受控执行
# 例如：测试运行
allowed-tools: [Read, Bash(npm test:*), Bash(pytest:*)]

Hooks，事件驱动自动化

Hooks 的本质------AI 时代的中间件

AI Agent 的工具调用:

用户请求 → Claude 决策 → [PreToolUse Hook] → 工具执行 → [PostToolUse Hook] → 响应
                              ↓                            ↓
                         权限检查、拦截             格式化、验证、日志

• Hooks 是 AI 助手的中间件------拦截、监控、增强每一次交互。
• Hooks 解决的核心问题是 Claude 不应该操心格式化和权限检查，它只管写好代码就行。安全防线、质量守卫、审计日志，全部由 Hooks 在"幕后"自动完成。

Hook 事件

核心事件有 PreToolUse(守门员)、PostToolUse(质量守卫)、Stop(质量门控) 三个Hook

• 控制点，能阻止的事件（PreToolUse、UserPromptSubmit、Stop、SubagentStop）：你可以通过它们改变 Claude 的执行路径------拦截危险操作、拒绝不合理的输入、强制 Claude 继续修复。它们是 Hooks 系统的肌肉。
• 接管点，替代默认行为的事件（PermissionRequest）：它不是简单地阻止，而是接管了原本由用户手动处理的权限弹窗------你的脚本可以自动批准或拒绝权限请求，替代人类的决策。它是 Hooks 系统的自动驾驶。
• 观察点，不能阻止的事件（SessionStart、PostToolUse、PostToolUseFailure、Notification、SubagentStart、PreCompact、SessionEnd）：你只能在这些时刻做记录、做反馈、做后处理，但不能改变已经发生的事情。它们是 Hooks 系统的眼睛。

Hook 配置

• 用户级（~/.claude/settings.json）：个人习惯。比如你喜欢的日志格式、桌面通知方式。这些配置只影响你自己，不需要和团队同步。
• 项目级（.claude/settings.json）：团队约定。比如代码格式化规则、敏感文件保护列表。这些配置应该提交到 git，让团队所有成员共享。
• 本地覆盖（.claude/settings.local.json）：当你需要在本地临时覆盖团队配置时使用，比如调试时关闭某个 Hook。
• 子代理 frontmatter：子代理专属的 Hook。比如 db-reader 的 SQL 注入检查------这个检查只和数据库操作相关，不应该影响其他场景。

Hook 配置实例：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./hooks/block-dangerous.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ]
  }
}

配置说明：

hooks                            ← 第一层：顶层容器
├── PreToolUse                   ← 第二层：事件类型（什么时候触发）
│   └── [第一组规则]
│       ├── matcher: "Bash"      ← 第三层：匹配器（针对哪个工具）
│       └── hooks: [...]         ← 第三层：Hook 列表（执行什么）
│           └── type: "command"
│           └── command: "..."
└── PostToolUse
    └── [第二组规则]
        ├── matcher: "Write"
        └── hooks: [...]

Hook 事件选择

纬度	Hook 事件	Matcher	功能说明
阻止危险命令	PreToolUse	Bash	黑名单匹配 rm -rf/等exit 2 拦截
保护敏感文件	PreToolUse	Write	Edit
审计日志	PostToolUse	*	记录所有工具调用到.claude/logs/
自动格式化	PostToolUse	Write	Edit
自动 Lint 检查	PostToolUse	Write	Edit

设计 Hook 方案

MCP 协议

架构与核心概念

MCP 采用经典的客户端 - 服务器架构。Claude Code 充当 MCP Client，负责发现和调用工具；MCP Server 则暴露工具和资源，作为外部服务的代理。两者之间通过 JSON-RPC 2.0 协议通信。

架构的关键组件：

组件	角色	说明
MCP Client	请求方	内置于 Claude Code，负责发现和调用工具
MCP Server	提供方	暴露工具和资源的服务程序
传输层	通言管道	stdio、SSE、HTTP 三种方式

调试与故障排除

# 列出所有配置的服务器
claude mcp list

# 查看服务器详细信息
claude mcp get my-server

# 启用调试模式查看 MCP 连接详情
claude --debug

Tools 工具系统

按功能分为六个类别：

• 文件操作类，Claude 与代码交互的最基本方式。Read 是只读的，不需要额外授权；Edit、Write、MultiEdit 会修改文件系统，因此需要用户确认。
• 搜索类，在动手之前先看清楚代码库的全貌。Glob 按文件名模式定位文件，Grep 按内容搜索定位代码行，两者都是只读操作，无需授权。
• 执行类，整个工具集里能力最强也最危险的一个。Bash 可以执行操作系统能做的一切。正因如此，它始终需要用户授权。
• 网络类，让 Claude 突破本地文件系统的边界，访问互联网上的信息。查文档、搜报错、获取 API 响应都靠这两个工具。
• 编排类，这组工具不直接操作代码，而是管理 Agent 的工作流程：把复杂任务委派给子代理、在需要时向用户提问、用任务清单跟踪多步骤进度。
• 辅助类，支撑性工具，用于管理后台任务和系统状态切换。日常使用中不常直接接触，但在自动化场景下不可或缺。

软件工程的五个原子操作

有感知（Read）、搜索（Glob/Grep）、修改（Edit/Write）、执行（Bash）、获取（WebFetch/WebSearch）。

• 你打开文件看代码 → 感知
• 你搜索某个函数在哪里被调用 → 搜索
• 你修改代码修复一个 bug → 修改
• 你运行 npm test 验证修复 → 执行
• 你上 Stack Overflow 查错误信息 → 获取

高级能力

Plugins 插件

插件规范目录：

team-toolkit/
├── .claude-plugin/
│   └── plugin.json
├── commands/
│   ├── review.md
│   ├── test.md
│   └── deploy.md
├── agents/
│   ├── security-scanner.md
│   └── quick-fix.md
├── skills/
│   └── react-patterns/
│       ├── SKILL.md
│       └── chapters/
│           ├── hooks.md
│           ├── context.md
│           └── performance.md
├── hooks/
│   ├── hooks.json
│   ├── check-bash.sh
│   └── auto-format.sh
├── .mcp.json
└── README.md

plugin.json 如下:

{
  "name": "team-toolkit",
  "version": "1.0.0",
  "description": "团队标准开发工具包：代码审查、测试、部署、安全扫描一体化",
  "author": "Platform Team",
  "repository": "https://github.com/our-company/team-toolkit",
  "license": "MIT",
  "keywords": [
    "team",
    "devops",
    "code-review",
    "testing",
    "deployment",
    "security"
  ]
}