agent-notes — AI Agent 配置管理器（Claude Code / OpenCode / Copilot）

技能简介

agent-notes 是一款面向 AI 编程助手（Claude Code、OpenCode、GitHub Copilot）的配置管理工具，通过一套精心设计的 subagent 团队和 on-demand skill 库，让 AI 编程助手在复杂项目中保持更高的稳定性和更强的工作能力。

它默认管理 19 个专业化 subagent（覆盖 Opus 推理、Sonnet 执行、Haiku 探索三个模型层级）和 25 个按需加载的 skill（涵盖 Rails、Docker、Git、Kamal、进程管理等开发场景），并通过全局规则（guardrails）确保 AI 的输出符合团队规范——包括禁止在 commit/PR 中进行 AI 自我归属（AI self-attribution）等安全约束。

agent-notes 支持本地文件、Obsidian 笔记库和 Wiki 三种记忆存储方式，适配个人开发者和团队协作场景。

核心能力

agent-notes 提供以下核心能力：

1. 19 个专业化 subagent 编排 — Opus 负责复杂推理规划，Sonnet 负责代码执行，Haiku 负责信息探索，三个层级协同处理不同复杂度任务。

2. 25 个按需 skill — 覆盖 Rails、Docker、Git、Kamal、进程管理等高频开发场景，AI 在需要时主动调用，无需手动配置。

3. 全局规则与 guardrails — 内置团队规范（如禁止 AI 自我归属 commit），确保 AI 输出符合企业安全要求。

4. 多记忆存储后端 — 支持 Local（本地文件）、Obsidian（知识库）和 Wiki 三种记忆模式，适应不同工作流。

5. 多 IDE 支持 — 支持 Claude Code、OpenCode 和 GitHub Copilot 三种主流 AI 编程助手。

6. 交互式安装向导 — agent-notes install 提供交互式引导，自动完成配置和集成。

7. 健康检查工具 — agent-notes doctor 命令检测环境问题，帮助快速定位配置故障。

安装配置

环境要求

• Python 3.8+
• pipx（推荐）或 uv 工具
• 支持 macOS、Linux、Windows

安装步骤

方式一：pipx 安装（推荐，隔离环境）

pipx install agent-notes
agent-notes install    # 交互式安装向导
agent-notes doctor     # 检查环境健康状态

方式二：uv 工具安装（轻量替代）

uv tool install agent-notes
agent-notes install

方式三：venv + pip（自行管理环境）

python -m venv .venv && source .venv/bin/activate
pip install agent-notes
agent-notes install

升级方法：

# 正常升级（pipx）
pipx upgrade agent-notes && agent-notes install

# 全新重装（从旧版本升级）
pipx uninstall agent-notes && pipx install agent-notes && agent-notes install

使用步骤

步骤一：完成安装并运行健康检查

安装完成后，运行以下命令确保环境配置正确：

agent-notes doctor

根据输出修复报告的问题（如 API Key 缺失、路径错误等）。

步骤二：初始化项目配置

在需要使用 agent-notes 的项目目录下，运行：

agent-notes install

交互式向导会引导你完成：

• 选择使用的 AI 编程助手（Claude Code / OpenCode / Copilot）
• 配置 subagent 模型层级
• 选择记忆存储后端
• 设置全局规则和 guardrails

步骤三：在 AI 编程助手中触发 skill

agent-notes 提供的 skill 在需要时由 AI 自动调用，无需手动激活。例如：

• 当 AI 需要操作 Docker 容器时，自动调用 Docker skill
• 当 AI 需要执行 Git 操作时，自动调用 Git skill
• 当 AI 需要管理 Rails 资源时，自动调用 Rails skill

步骤四：配置团队规则（如需团队使用）

agent-notes 支持自定义全局规则，编辑配置文件中的 guardrails 部分即可。示例规则：

guardrails:
  ban_ai_self_attribution: true  # 禁止 AI 在 commit 中声明自己
  require_code_review: true      # 要求所有 PR 经过人工审核

适用场景

agent-notes 适用于以下场景：

1. 复杂多服务项目开发 — 多 subagent 协作处理微服务架构、前后端分离等复杂项目。

2. 团队 AI 编程规范管理 — 通过全局规则确保所有团队成员使用的 AI 输出风格一致。

3. 个人效率提升 — 将高频重复操作（Rails CRUD、Docker 操作等）封装为可复用的 skill。

4. 多 IDE 统一配置 — 在 Claude Code、OpenCode、Copilot 之间共享同一套配置和工作流。

5. 知识管理整合 — 通过 Obsidian 或 Wiki 后端将 AI 生成的内容整合到个人知识库。

适用人群

• AI 编程深度用户 — 每天使用 Claude Code 或 OpenCode 处理复杂任务的开发者。
• 技术团队负责人 — 需要在团队中推广 AI 编程同时保证输出质量和安全合规。
• 独立开发者 — 希望将重复性开发工作自动化，提升个人效率。
• DevOps 工程师 — 需要在 AI 辅助下管理 Docker、Kamal 等基础设施。

工作原理

agent-notes 的架构分为三层：

配置管理层：统一管理所有 AI 编程助手的配置文件（Claude Code config.yml、OpenCode config、Copilot settings），提供一致性接口。

Subagent 编排层：19 个 subagent 按模型能力分级（Opus / Sonnet / Haiku），复杂推理任务由 Opus 处理，执行任务由 Sonnet 承担，探索任务由 Haiku 负责。调度器根据任务复杂度自动分配。

Skill 执行层：25 个 skill 以插件形式按需加载，每个 skill 定义特定领域的操作规范和工具集。AI 在执行任务时根据上下文自动调用相关 skill，无需人工干预。

记忆层：agent-notes 的记忆系统支持三种后端。Local 后端将记忆存储为本地 JSON 文件，适合个人使用；Obsidian 后端将记忆写入笔记库，便于知识积累；Wiki 后端支持团队共享知识库。

官方链接

• PyPI：https://pypi.org/project/agent-notes/
• GitHub：https://github.com/rubioj (需访问项目页确认)
• 关键词：claude, claude-code, opencode, ai-agent, agent, configuration, claude-cli, github-copilot