AI 智能体记忆与工具集成：构建更智能的 Claude Skills 工作流

大多数 AI 智能体教程止步于基础：提示 Claude，获取回复，完成。但生产工作流不同。它们跨越多个会话，调用数十个外部工具，并需要记住昨天做出的决策。本指南涵盖将玩具演示与生产级 Claude Skills 智能体区分开来的三个维度：记忆系统、工具集成模式和可扩展的架构选择。

为什么智能体记忆改变一切

无状态智能体强大但健忘。每次对话都从零开始——不了解您的代码库约定，不知道哪些任务正在进行，没有过去决策的记录。对于一次性任务这没问题。对于需要多个会话的任何事情，它很快就会崩溃。

Claude Skills 通过将记忆外化到 Claude 在每次会话开始时读取的文件中来解决这个问题。skill 文件本身就是契约：它告诉 Claude 确切要记住什么、在哪里存储以及如何使用。

考虑以下区别：

没有记忆： "审查这个 PR"——Claude 在没有关于过去审查、您团队的风格指南或您已经讨论过的问题的上下文情况下进行审查。

有记忆： "审查这个 PR"——Claude 加载 project-memory/review-history.md，看到最近审查的 10 个 PR、您团队的常见问题以及您上个月建立的约定。审查立即更加相关。

三种智能体记忆模式

模式 1：会话内积累

最简单的记忆形式。智能体在单个对话窗口中积累上下文，并在任务进展中使用它来做出更好的决策。

实现此模式的 skill 可能如下所示：

## 工作流
1. 在采取任何行动之前，列出您计划修改的所有文件及您的理由
2. 在工作记忆中维护一个运行中的决策日志：
   - 您做了什么以及为什么
   - 您尝试了什么但没有成功
   - 给用户的待解决问题
3. 最后，总结所做的决策和后续步骤

这适用于在一个会话中完成的任务——重构模块、编写功能、调试错误。局限性是显而易见的：关闭终端，记忆就消失了。

模式 2：跨会话文件记忆

对于持续数天或数周的工作，skills 可以指示 Claude 从专用记忆文件中读取和写入。该模式在社区 skill 仓库中是一致的：

## 记忆协议
**会话开始时：**
- 如果存在则读取 `AGENT_MEMORY.md`
- 读取 `project-state.json` 获取当前任务状态
- 用您上次离开时的进度摘要向用户打招呼

**会话结束时（或当用户说"保存"或"检查点"时）：**
- 用所做的关键决策更新 `AGENT_MEMORY.md`
- 用当前任务状态更新 `project-state.json`
- 列出下次会话的任何阻碍或问题

记忆文件结构很重要。扁平文件很快就会变得难以管理。一个设计良好的记忆模式将以下内容分开：

• 决策（不可变的，带时间戳）：架构选择、接受的权衡
• 状态（可变的）：当前任务、进行中的工作、开放的 PR
• 知识（演进的）：代码库约定、团队偏好、重复出现的模式

社区中的 Skills，如 levnikolaevich/claude-code-skills，使用结构化的 JSON 状态文件实现此模式，使得从 Claude 外部检查和调试智能体的记忆变得轻而易举。

模式 3：工具中介状态

最强大的方法是将记忆存储在专为此设计的系统中：数据库、键值存储或版本控制文件。智能体不管理存储格式——它调用管理存储的工具。

## 状态管理
- 读取当前冲刺状态：`gh project list --owner @me`
- 读取任务详情：`gh issue view {issue_number}`
- 写入任务更新：`gh issue comment {issue_number} -b "{update}"`
- 跟踪决策：追加到 `docs/decisions/ADR-{number}.md` 并提交

这种方法提供了完整的审计跟踪、人类可读的状态以及查询历史的能力。它还自然地与现有的团队工作流集成——智能体的记忆只是您 git 历史的另一个贡献者。

工具集成模式

记忆告诉智能体发生了什么。工具告诉它能做什么。您的工具集的丰富程度直接决定了您可以自动化的工作流的复杂性。

MCP 服务器集成

Model Context Protocol 服务器将功能作为结构化的工具定义公开，Claude 可以原生调用这些定义。集成 MCP 工具的 skill 声明其预期的服务器：

## 所需 MCP 服务器
- `filesystem`：读写项目文件
- `github`：与 PR、issues 和仓库交互
- `postgres`：查询应用数据库获取上下文

## 工具使用指南
- 当两者都可用时，优先使用 MCP 工具而非 CLI 等效工具
- MCP 工具提供结构化错误；显式处理它们
- 批量处理相关的工具调用以最小化往返次数

关键纪律：skills 应该显式声明其工具依赖。一个默默假设工具可用的智能体会产生难以调试的故障。一个在启动时检查工具并优雅降级的智能体更容易操作。

CLI 工具编排

许多最好的社区 skills 编排标准 CLI 工具，而不是要求自定义 MCP 服务器。这使它们无需任何额外设置即可立即使用：

## 代码质量检查工作流
1. 运行代码检查：`npm run lint 2>&1 | tee .agent/lint-output.txt`
2. 运行类型检查：`npx tsc --noEmit 2>&1 | tee .agent/type-errors.txt`
3. 运行测试：`npm test -- --json > .agent/test-results.json`
4. 综合分析所有输出并生成单一的优先级报告
5. 对每个关键问题，提出具体修复建议和行号

tee 模式值得强调：它让智能体捕获工具输出以供后续分析，同时仍然实时向用户显示。.agent/ 目录作为会话的临时空间——临时文件在不污染项目的情况下积累上下文。

通过 curl 进行 API 集成

对于没有 MCP 服务器或 CLI 工具的服务，skills 可以直接调用 API：

## 部署检查
每次成功测试运行后：
1. 检查当前部署状态：
   `curl -s -H "Authorization: Bearer $DEPLOY_TOKEN" https://api.example.com/deployments/latest`
2. 如果状态为 "ready"，触发部署：
   `curl -X POST -H "Authorization: Bearer $DEPLOY_TOKEN" https://api.example.com/deployments`
3. 每 30 秒轮询完成状态（最长 10 分钟）
4. 报告最终状态和 URL

使用 API 调用的 Skills 应始终指定密钥来源（环境变量，永远不要硬编码）、显式处理速率限制并定义超时行为。

实际示例：带记忆的代码审查智能体

以下是这些模式如何在真实世界的 skill 中结合使用。这个智能体记住过去的审查决策，并使用工具创建比任何单会话智能体都更丰富的审查。

Skill 文件：code-review-with-memory.md

# 带记忆的代码审查智能体

你是一个拥有此项目机构知识的代码审查者。

## 会话开始协议
1. 如果存在则读取 `.agent/review-memory.md`——包含：
   - 过去审查中发现的重复问题
   - 通过讨论建立的团队约定
   - 作者及其典型模式
2. 运行 `git log --oneline -20` 了解最近的历史
3. 运行 `gh pr list --state open` 查看还有什么在进行中

## 审查流程
对每个更改的文件：
1. 根据 `.agent/review-memory.md` 中的约定进行检查
2. 运行 `npx eslint {file} --format json` 并分析输出
3. 检查测试覆盖率：`npx jest --collectCoverageFrom='{file}' --coverage`
4. 寻找在之前审查中出现的模式

## 反馈格式
- 按严重性分组问题：阻塞性 / 重要 / 建议
- 对重复出现的问题，注明"这是我们第 3 次看到 X——考虑添加一条 lint 规则"
- 对好的模式，积极地注明——强化有效的做法

## 会话结束协议
审查完成后：
1. 用以下内容更新 `.agent/review-memory.md`：
   - 识别到的新重复模式
   - 在此会话中澄清的约定
   - 作者的优势和成长领域
2. 提交记忆文件：`git add .agent/review-memory.md && git commit -m "chore: update review memory after PR #{pr_number}"`

使用此智能体进行 10 次审查后，审查记忆文件将成为您仓库中最有价值的文档之一——您团队不断演进的标准的活跃记录。

生产部署注意事项

管理状态和调用外部工具的 Skills 比无状态脚本需要更谨慎的运营设计。

幂等性：设计工具调用使其可以安全重试。在调用工具之前写入状态，而不是之后。如果工具调用中途失败，智能体应该能够从中断处恢复。

密钥管理：Skills 永远不应包含凭据。在 skill 文件顶部定义需要哪些环境变量。使用您现有的密钥管理器（1Password CLI、AWS Secrets Manager 等）来填充它们。

范围限制：生产智能体需要防护栏。一个可以写文件、调用 API 和运行 CLI 工具的 skill 也可能造成实际损害。定义明确的边界：

## 范围约束
- 永远不要直接推送到 main 或 master 分支
- 永远不要在没有用户明确确认的情况下删除文件
- 永远不要在未先显示预估成本的情况下进行花钱的 API 调用
- 只读模式可用：在命令前加上"仅分析，不修改"

可观测性：.agent/ 临时目录模式同时充当审计日志。每个会话的工具输出、中间分析和决策理由都被保留。将 .agent/ 添加到 .gitignore 用于临时文件，但提交会话摘要以使您的团队了解智能体做了什么。

故障模式：定义当工具不可用时会发生什么。一个默默跳过工具调用的智能体会产生微妙错误的输出。一个在工具缺失时大声失败的智能体更容易修复。

值得研究的社区 Skills

Claude Skills Hub 中的几个仓库展示了这些模式的生产级质量：

• obra/superpowers-skills：展示如何构建面向任务的智能体，能够从中断处继续工作，具有干净的状态序列化。
• levnikolaevich/claude-code-skills：使用 JSON 状态文件和显式读写协议实现跨会话记忆的示例。
• mrgoonie/claudekit-skills：展示工具集成模式，具有清晰的依赖声明和工具不可用时的优雅降级。

这些仓库中的每一个都将 skill 文件视为正式规范，而不是随意的提示。这种严谨性是它们在生产环境中可靠运行的原因。

关键要点

构建更智能的 Claude Skills 智能体归结为三个纪律：

1. 显式设计记忆。预先决定智能体需要记住什么、存储在哪里以及何时更新。不要把这交给偶然。

2. 声明工具依赖。在每个 skill 的顶部列出所需的工具。在启动时检查它们。当它们缺失时大声失败。

3. 将 skill 文件视为契约。它定义行为、记忆协议、工具使用和范围限制。当出现问题时，skill 文件是您进行调试的地方。

Claude Skills Hub 中的社区 skills 是看到这些模式实际运行的最快方式。浏览仓库集合，安装几个与您的工作流匹配的 skills，并在构建您自己的之前研究它们的记忆和工具集成模式。

演示智能体和生产智能体之间的区别不在于底层模型——而在于指导它的 skill 所投入的用心程度。