name: research description: “为Aha Loop故事进行深度技术研究。在实施涉及不熟悉库或架构决策的故事之前使用。触发条件：研究这个、调查、探索选项、比较替代方案。”

深度研究技能

在实施前进行彻底的技术研究，以确保高质量、明智的决策。

工作空间模式说明

在工作空间模式下运行时，所有路径都相对于.aha-loop/目录：

研究报告：.aha-loop/research/（非scripts/aha-loop/research/）
知识库：.aha-loop/knowledge/（非knowledge/）
供应商目录：.aha-loop/.vendor/（非.vendor/）

编排器将在提示上下文中提供实际路径。

工作内容

从当前故事的researchTopics字段中识别研究主题
如果需要，获取第三方库源代码
搜索文档和最佳实践
分析和比较替代方案
生成研究报告
用发现更新知识库
在prd.json中标记researchCompleted: true

研究过程

步骤1：识别研究内容

从prd.json中读取当前故事并提取：

researchTopics – 明确的研究主题
验收标准中提到的依赖项
描述中引用的模式

同时检查：

先前故事的learnings字段，了解后续研究需求
knowledge/project/gotchas.md，了解相关已知问题

步骤2：获取库源代码（如果需要）

对于任何第三方库研究，获取源代码：

# 获取特定库
./scripts/aha-loop/fetch-source.sh rust tokio 1.35.0

# 或从项目依赖中获取所有
./scripts/aha-loop/fetch-source.sh --from-deps

获取后，源代码将在.vendor/<ecosystem>/<name>-<version>/中

库版本选择

始终优先使用最新稳定版本

在研究或推荐库时，始终检查并优先使用最新稳定版本，除非有特定的兼容性原因不这样做。

版本研究过程

查询包注册表获取最新版本：

# Rust（crates.io）
curl -s "https://crates.io/api/v1/crates/tokio" | jq '.crate.max_stable_version'

# 或使用cargo
cargo search tokio --limit 1

# Node.js（npm）
npm view react version

# Python（PyPI）
pip index versions requests 2>/dev/null | head -1

验证稳定性：
- 至少已发布1-2周（非前沿版本）
- 检查GitHub问题中的关键错误
- 审查变更日志以了解破坏性更改
检查兼容性：
- 与现有项目依赖项兼容
- 兼容项目的最小支持语言版本
- 无已知冲突

版本文档

始终记录版本决策：

## 版本决策：[库名称]

**选定的版本：** X.Y.Z
**最新可用版本：** X.Y.Z（截至YYYY-MM-DD）
**原因：** [为什么选择此版本]

**兼容性说明：**
- 与[其他依赖项] v[X.Y]兼容
- 需要[语言] v[X.Y]+

何时使用旧版本

仅在以下情况下使用旧版本：

最新版本有关键错误
与必需依赖项不兼容
破坏性更改需要大量重构
项目明确限制版本

始终记录原因在knowledge/project/decisions.md中：

### ADR：使用[库] v[旧]而非v[新]

**上下文：** [为什么我们不使用最新版本]
**决策：** 固定到v[旧]
**后果：** [我们错过什么，何时重新审视]

步骤3：战略性阅读源代码

阅读顺序（最重要的优先）：

README.md – 理解设计意图和快速入门示例
入口点文件：
- Rust：src/lib.rs、src/main.rs
- TypeScript/JS：src/index.ts、index.js
- Python：__init__.py、main.py
模块结构 – 扫描mod.rs文件或目录结构
类型定义 – 查找核心结构、接口、类型
目标功能 – 定位所需的特定功能
测试 – 从测试文件中学习正确的使用模式

阅读技巧：

使用语义搜索查找相关代码部分
专注于公共API，除非需要，跳过内部实现
查找examples/目录以获取使用模式
检查tests/了解边缘情况和正确用法

步骤4：网络搜索获取上下文

搜索：

官方文档
最佳实践和常见模式
已知问题和陷阱
性能考虑
替代库

使用MCP工具如context7获取最新文档。

步骤5：比较替代方案（如果适用）

当存在多个解决方案时，创建比较：

标准	选项A	选项B	选项C
性能	…	…	…
API人体工程学	…	…	…
维护状态	…	…	…
包大小	…	…	…
学习曲线	…	…	…

包括带有推理的推荐。

研究报告模板

保存到：scripts/aha-loop/research/[故事ID]-research.md

# 研究报告：[故事ID] – [故事标题]

**日期：** YYYY-MM-DD
**状态：** 完成 | 需要后续跟进

## 研究主题

1. [来自researchTopics数组的主题]
2. ...

## 发现

### 主题1：[名称]

**摘要：** 对研究问题的简要回答

**源代码分析：**
- 库：[名称] v[版本]
- 关键文件：`.vendor/rust/tokio-1.35.0/src/runtime/mod.rs`
- 相关代码：第123-189行
- 观察到的模式：[描述]

**文档笔记：**
- [来自文档的关键洞察]
- [另一个洞察]

**代码示例：**
```[语言]
// 来自源代码或文档的示例

主题2：[名称]

…

替代方案比较

标准	选项A	选项B	推荐
…	…	…	…

推荐： [选项X]，因为[推理]

实施建议

基于研究，故事应如下实施：

[具体的实施指导]
[遵循的模式]
[避免的陷阱]

需要的后续研究

[ ] [需要深入研究的主题]
[ ] [研究过程中出现的问题]

知识库更新

应添加到知识库的内容：

到knowledge/project/patterns.md：

[特定于此项目的模式]

到knowledge/domain/[主题]/：

[关于库或技术的可重用知识]


---

## 更新知识库

### 项目知识（`knowledge/project/`）

添加特定于此项目的模式：
- 此代码库如何使用库
- 发现的特定于项目的约定
- 此代码库特有的陷阱

### 领域知识（`knowledge/domain/`）

添加可重用的技术知识：
- 库使用模式（适用于任何项目）
- 比较文档
- 最佳实践

**根据需要创建新主题目录：**

knowledge/domain/ └── [主题名称]/ ├── README.md # 概述 ├── patterns.md # 常见模式 ├── gotchas.md # 已知问题 └── examples/ # 代码示例


---

## 源代码阅读报告

阅读库源代码时，记录发现：

```markdown
## 源代码分析：[库] v[版本]

### 模块结构

src/ ├── lib.rs # 主要入口，导出公共API ├── runtime/ # 异步运行时实现 │ ├── mod.rs # 模块导出 │ └── scheduler.rs # 任务调度 └── sync/ # 同步原语


### 关键类型

- `Runtime`（src/runtime/mod.rs:45） – 主运行时结构
- `Handle`（src/runtime/handle.rs:23） – 用于生成的运行时句柄

### 关键函数

- `Runtime::new()`（L89-L120） – 用默认配置创建新运行时
- `spawn()`（L156-L189） – 生成新的异步任务

### 来自测试的使用模式

来自`tests/runtime.rs:34`：
```rust
let rt = Runtime::new().unwrap();
rt.block_on(async {
    // ...
});

重要说明

线程安全：Runtime是Send + Sync
性能：对CPU密集型任务使用spawn_blocking
陷阱：不要从异步上下文中调用block_on


---

## 清单

在研究完成前检查：

- [ ] 所有`researchTopics`已调查
- [ ] 库源代码已获取并阅读关键文件（如果适用）
- [ ] 已执行网络搜索以获取文档和最佳实践
- [ ] 替代方案已比较（如果存在多个选项）
- [ ] 研究报告已保存到`scripts/aha-loop/research/`
- [ ] 知识库已用可重用发现更新
- [ ] 实施建议已记录
- [ ] 在prd.json中设置`researchCompleted: true`