内容
# adr-skills
**adr-skills** 是一个适用于 Claude Code 的 MCP 服务器，能够自动捕获开发过程中的对话，并使用 Claude Opus 生成、审查和管理架构决策记录（ADRs）。
> **TL;DR:** 安装一次，每次 Claude Code 会话结束时，都会将结构化的 ADR 保存到 `~/.adr-mcp/adrs/` 目录下 — 无需手动编写。
[](https://glama.ai/mcp/servers/wooxogh/adr-mcp-setup)
## 解决了什么问题？
工程团队每周都会做出数十个架构决策，例如选择哪种数据库，如何处理身份验证，以及是否采用单体架构还是微服务架构，但很少会将这些决策记录下来。几个月后，没有人会记得为什么选择了 Redis 而不是 Memcached，或者为什么团队避免使用 GraphQL。
**adr-skills** 通过将现有的 Claude Code 对话自动转化为永久、可搜索的 ADR 文档来解决这个问题。
## 工作原理
1. 在 Claude Code 中进行正常的开发对话
2. 会话结束时，停止钩子（Stop Hook）捕获对话记录
3. Claude Opus 分析对话并提取架构决策
4. 将结构化的 Markdown ADR 保存到 `~/.adr-mcp/adrs/ADR-0001-*.md` 目录下
5. 使用 `review_adr` 评估质量，使用 `link_adrs` 映射依赖关系，使用 `check_stale_adrs` 查找过时的决策
## 功能
- **自动会话捕获** — 停止钩子（Stop Hook）在 Claude Code 退出时自动保存对话；无需手动操作
- **AI 驱动的 ADR 生成** — Claude Opus 从原始对话中提取上下文、决策和后果
- **AI 质量审查** — 评估 ADR 完整性，范围 0-100，并标记缺少的上下文、未考虑的替代方案或乐观的后果
- **重复检测** — 在保存新决策之前，警告与过去的决策重叠
- **Markdown 导出** — 每个 ADR 导出为 `ADR-NNNN-slug.md`，可与代码一起提交
- **状态生命周期** — 跟踪决策的 `Proposed → Accepted → Deprecated → Superseded` 状态变化
- **依赖图** — 使用 `related_to`、`conflicts_with`、`depends_on` 链接 ADR，并可视化关系
- **过时 ADR 警报** — 查找可能需要重新审视的旧 `Accepted` 决策
- **关键词搜索** — 按技术名称（例如 Redis、JWT、PostgreSQL）查找过去的决策
- **时间线视图** — 每个项目的完整决策历史，与 git 提交相关联
## 与现有 ADR 工具的区别
| 工具 | 自动从聊天捕获 | AI 生成 | 质量审查 | MCP 服务器 |
|---|:---:|:---:|:---:|:---:|
| **adr-skills** | ✅ | ✅ Claude Opus | ✅ | ✅ |
| adr-tools (CLI) | ❌ | ❌ | ❌ | ❌ |
| mcp-adr-analysis-server | ❌ | ✅ OpenRouter | ❌ | ✅ |
| claude-historian-mcp | ✅ | ❌ | ❌ | ✅ |
| log4brains | ❌ | ❌ | ❌ | ❌ |
现有的工具中，没有一个将自动对话捕获与 AI 驱动的 ADR 生成结合在一个 MCP 服务器中。在 Anthropic 仓库中，有一个关于原生 ADR 支持的[开放功能请求](https://github.com/anthropics/claude-code/issues/13853) — adr-skills 今天就填补了这个空白。
## 安装
```bash
git clone https://github.com/wooxogh/adr-mcp-setup.git
cd adr-mcp-setup
npm install
```
### 在 Claude Code 中注册
```bash
claude mcp add adr-skills node /absolute/path/to/adr-mcp-setup/index.js
```
### 环境设置
```bash
cp .env.example .env
# 将 ANTHROPIC_API_KEY 添加到 .env 文件中
```
> 没有 API 密钥，`generate_adr` 将退回到基于关键词的提取，而 `review_adr` 将不可用。`.env` 文件在 `.gitignore` 中 — 您的密钥永远不会被提交。
### 启用自动会话捕获（停止钩子）
添加到 `~/.claude/settings.json` 文件中：
```json
{
"hooks": {
"Stop": [{
"matcher": "",
"hooks": [{
"type": "command",
"command": "node /absolute/path/to/adr-mcp-setup/hook.js"
}]
}]
}
}
```
## 工具（共 9 个）
| 工具 | 描述 | 需要 API 密钥 |
|---|---|:---:|
| `save_session` | 将对话保存到数据库 | ❌ |
| `generate_adr` | 从会话自动生成 ADR | ❌（AI 模式：✅） |
| `review_adr` | 评估 ADR 质量并提供改进建议 | ✅ |
| `update_adr_status` | 将 ADR 状态转变为其生命周期 | ❌ |
| `link_adrs` | 在 ADR 之间创建关系 | ❌ |
| `get_adr_graph` | 可视化 ADR 依赖图 | ❌ |
| `check_stale_adrs` | 查找需要重新审视的旧 `Accepted` ADR | ❌ |
| `search_decisions` | 跨所有过去的决策进行关键词搜索 | ❌ |
| `get_timeline` | 项目的决策历史 | ❌ |
### `generate_adr` 示例输出
```markdown
# ADR-1：采用 Redis 作为缓存层
## 状态
Accepted
## 上下文
我们需要发布/订阅支持来实现实时通知。
Memcached 仅处理简单的键值缓存，无法满足此要求。
## 决策
我们采用 Redis 作为缓存和消息代理。
它支持发布/订阅、TTL 和持久性，团队已经具备相关操作经验。
## 后果
现在可以实现实时功能，无需单独的消息代理。
我们必须考虑 Redis 的操作成本，并将其视为潜在的单点故障。
```
### `review_adr` 示例输出
```
## ADR-1 审查 — 评分：62/100
良好的上下文，但决策理由和风险覆盖需要改进。
### 问题
🔴 [决策] 在选择 Redis 之前，没有考虑其他替代方案
🟡 [后果] 提到了风险，但缺少缓解策略
### 建议
1. 明确记录为什么拒绝 Memcached
2. 添加 Redis 成为瓶颈时的回滚计划
```
### `get_adr_graph` 示例输出
```
## ADR 依赖图
### 依赖于
ADR-5 "使用 JWT 进行身份验证" → ADR-2 "采用 Redis 作为缓存"
### 冲突于
ADR-7 "迁移到无状态会话" ✕ ADR-2 "采用 Redis 作为缓存"
```
## 常见问题
**问：我需要 Anthropic API 密钥吗？**
答：不需要。没有密钥，`generate_adr` 将使用关键词提取作为备用方案。有密钥时，Claude Opus 将生成更准确的 ADR，并且可以使用 `review_adr`。
**问：ADR 存储在哪里？**
答：两个地方：`~/.adr-mcp/sessions.db` 处的 SQLite 数据库和 `~/.adr-mcp/adrs/` 处的 Markdown 文件。Markdown 文件可与 git 一起提交。
**问：我可以在没有停止钩子（Stop Hook）的情况下使用此工具吗？**
答：是的。手动调用 `save_session` 和 `generate_adr` 即可。
**问：这与其他 AI 助手（除了 Claude）配合使用吗？**
答：MCP 服务器协议是开放的，但停止钩子（Stop Hook）特定于 Claude Code。数据库和 Markdown 导出与工具无关。
**问：重复检测如何工作？**
答：在生成 ADR 时，adr-skills 从标题和决策文本中提取重要关键词，并查询重叠的过去 ADR。匹配结果将作为警告显示 — 仍会保存新的 ADR。
**问：使用什么 ADR 格式？**
答：[Michael Nygard ADR 格式](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)（标题、状态、上下文、决策、后果），这是软件行业中最广泛采用的格式。
## 项目结构
```
adr-mcp-setup/
├── index.js ← MCP 服务器 — 9 个工具定义和路由
├── db.js ← SQLite CRUD（sessions、adrs、adr_relations 表）
├── adr.js ← ADR 提取和 AI 审查逻辑（Claude Opus）
├── hook.js ← Claude Code 停止钩子（自动会话捕获）
├── .env.example ← 环境变量模板
└── package.json
```
**数据库：** `~/.adr-mcp/sessions.db`
**ADR 文件：** `~/.adr-mcp/adrs/ADR-NNNN-slug.md`
## 要求
- Node.js 18+
- Claude Code CLI
- Anthropic API 密钥（可选 — AI 生成和审查所需）
