---
name: doc-driven-development
description: 文档驱动开发规范，要求 Agent 在生成代码或修复 bug 前先查阅官方文档与示例，包含 API 验证流程、搜索策略与 MCP 调用规则。适用于接入第三方库、排查 API 报错、版本变更等场景。
---

# 文档驱动开发规范

> 在生成代码或修复 bug 时，先看官方文档与示例，再动手实现。

---

## ⚠️ 核心强制要求

### 必须查文档的场景

- 落地新功能、接第三方库 API、或排查 API 报错时，**先查官方文档**
- 遇到 `AttributeError` / `TypeError` / 版本变更不确定时，**必须验证 API 定义与示例**
- 对项目自带封装的内部 API，可酌情跳过

### Agent 执行步骤

1. **停止猜测**：明确要查的 API/模块名称和版本
2. **查阅文档**：优先使用 `Context7` 获取官方文档；若不可用再用 `DuckDuckGo` 搜索官方来源并二次核验
3. **基于文档实现**：依据文档的参数、返回值和示例实现或修复代码

### MCP 调用基线（文档查阅场景）

- 文档/API 问题优先使用 `Context7`，最新公告或入口信息再使用 `DuckDuckGo`
- 单轮最多调用一种外部服务；确需多工具时串行并说明理由
- 查询保持最小必要（关键词、结果数、时间窗、tokens）
- 发生 429/限流时，退避 20 秒并缩小范围后重试
- 输出中附“工具调用简报”（工具、输入摘要、参数、时间、来源、重试）
- 默认离线优先，不上传敏感信息，遵守 robots/ToS 与隐私约束

---

## AI Agent 行为要求

### 问题识别

| 问题类型 | 特征 | 处理方式 |
|----------|------|----------|
| API 不存在 | `AttributeError: 'X' has no attribute 'Y'` | 查找正确的 API |
| 参数错误 | `TypeError: unexpected keyword argument` | 查找正确的参数 |
| 行为异常 | 结果不符合预期 | 查找正确的用法 |
| 版本问题 | 某版本后 API 变更 | 查找版本差异 |

### 收集错误信息

必须收集：
- 完整的错误堆栈
- 相关代码片段
- 使用的库/框架版本

### 基于文档实现（禁止猜测）

```python
# 错误：基于猜测实现
index.query(question, top_k=10)  # 可能参数名不对

# 正确：基于文档实现
# 查阅文档后确认正确的参数名
index.query(question, similarity_top_k=10)
```

### 修复后验证

- [ ] 运行测试确认修复
- [ ] 检查是否引入新问题
- [ ] 验证在不同场景下的表现

---

## 参考资料

- `references/api-verification.md` - API 验证流程详细说明（问题识别、文档查阅、实施修复）
- `references/search-strategy.md` - 文档搜索策略与提问指引
- `references/mcp-usage-rules.md` - MCP 调用规则（工具选择、速率限制、安全边界、失败降级与可追溯输出）