Skills
skills/likaihz/tz-agent-skills/technical-research

technical-research

SKILL.md

Technical Research Skill

概述

此技能提供专业的技术调研能力，将模糊的技术问题转化为结构化、可执行的调研流程，输出可直接指导实现的调研文档。

核心原则

1. 简洁至上 (Concise is Key)

  • 上下文窗口是公共资源，只包含 Claude 不知道的信息
  • 每个信息点都要问："Claude 真的需要这个解释吗？"
  • 偏好简洁示例，避免冗长说明

2. 渐进式披露 (Progressive Disclosure)

采用三级加载系统：

  1. Metadata - 始终在上下文 (~100 词)
  2. SKILL.md body - 技能触发后加载 (<500 行)
  3. Bundled resources - 按需加载 (无限制)

3. 设定适当的自由度 (Set Appropriate Degrees of Freedom)

自由度 使用场景 示例
高 (文本指令) 多种方法有效、依赖上下文决策 "选择最适合的数据库"
中 (伪代码/参数化脚本) 有偏好模式、可接受变化 "使用此模板生成 API"
低 (具体脚本、少参数) 操作脆弱、一致性关键 "执行此迁移脚本"

调研流程

阶段 1: 理解需求 (5-10 分钟)

目标：将模糊问题转化为具体调研目标

关键问题：

1. 业务背景是什么？(解决什么问题)
2. 技术约束有哪些？(预算、团队技能、时间)
3. 成功标准是什么？(性能指标、成本上限)
4. 已有技术栈是什么？(需要兼容的系统)

输出：调研目标声明

## 调研目标
- 评估 X 技术在 Y 场景下的适用性
- 对比 A/B/C 三种方案的优缺点
- 确定实现 Z 功能的最优路径

阶段 2: 信息收集 (15-30 分钟)

并行收集策略：

┌─────────────────────────────────────────────────────┐
│                  信息收集矩阵                        │
├──────────────┬──────────────┬───────────────────────┤
│ 官方文档     │ GitHub 示例   │ 社区讨论              │
│ - API 参考    │ - 实际用法    │ - 痛点/陷阱           │
│ - 最佳实践   │ - 生产代码    │ - 替代方案            │
└──────────────┴──────────────┴───────────────────────┘

收集清单：

  • 官方文档核心章节
  • GitHub 高星项目实现
  • StackOverflow 高频问题
  • 技术博客/视频分享
  • 竞品/替代方案对比

阶段 3: 分析评估 (20-40 分钟)

评估维度：

# 技术评估框架
evaluation = {
    "功能性": {
        "功能覆盖率": "0-100%",
        "扩展性": "高/中/低",
        "定制能力": "强/中/弱"
    },
    "非功能性": {
        "性能": "基准测试结果",
        "可靠性": "SLA/故障率",
        "安全性": "认证/审计",
        "可维护性": "文档质量/社区活跃度"
    },
    "成本": {
        "许可成本": "免费/商业/订阅",
        "学习成本": "陡峭/平缓",
        "运维成本": "高/中/低"
    },
    "风险": {
        "技术成熟度": "实验/成熟/衰退",
        "供应商锁定": "高/中/低",
        "社区可持续性": "强/中/弱"
    }
}

阶段 4: 输出文档 (15-25 分钟)

标准输出结构：

# [技术名称] 调研报告

## 概述 (1-2 句)
[技术的核心价值和适用场景]

## 核心发现 (Bullet Points)
- [关键发现 1]
- [关键发现 2]
- [关键发现 3]

## 技术细节
[实现原理、架构设计、关键代码]

## 优缺点分析
| 优点 | 缺点 |
|------|------|
| ... | ... |

## 适用场景
- ✅ 适合：[场景列表]
- ❌ 不适合：[场景列表]

## 最佳实践
[生产环境建议]

## 参考资料
[链接列表]

阶段 5: 更新索引 (必须执行)

重要性：索引文件是调研知识库的入口，保持索引更新确保后续可检索性。

索引文件位置：research/SUMMARY.md

索引结构：

# 技术调研索引

## AI/LLM
- [RAG 架构设计](ai-llm/2026-02-22-rag-architecture.md) - 2026-02-22
- [Embedding 模型对比](ai-llm/2026-02-20-embedding-models.md) - 2026-02-20

## Frontend
- [React 状态管理方案](frontend/2026-02-15-state-management.md) - 2026-02-15

## Backend
- [API 网关选型](backend/2026-02-10-api-gateway.md) - 2026-02-10

## Database
- [时序数据库对比](database/2026-02-05-timeseries-db.md) - 2026-02-05

自动更新流程：

  1. 读取现有索引：检查 research/SUMMARY.md 是否存在
  2. 确定分类：根据文档 topic 字段归类
  3. 添加条目：按日期倒序插入到对应分类
  4. 验证链接：确保文件路径正确

执行方式：

# 方式 1: 使用自动生成脚本
python scripts/update_index.py research/

# 方式 2: 手动编辑
# 在 SUMMARY.md 对应分类下添加新行
- [文档标题](topic/YYYY-MM-DD-filename.md) - YYYY-MM-DD

自动化脚本 (scripts/update_index.py)：

见技能目录下的脚本，支持：

  • 扫描所有调研文档
  • 提取 YAML frontmatter 元数据
  • 按分类和日期排序
  • 生成标准格式索引

文档规范

YAML Frontmatter (必需)

所有调研文档必须包含：

---
title: 文档标题
date: YYYY-MM-DD
topic: [ai-llm|frontend|backend|database|devops|tools]
tags: [标签 1, 标签 2]
status: [draft|complete|archived]
related: [相关文档路径]
---

文件命名

  • 格式：YYYY-MM-DD-topic.md
  • 位置：research/{topic}/
  • 示例：research/ai-llm/2026-02-22-rag-architecture.md

标签体系

主题标签：#ai #llm #frontend #react #backend #api #database #sql #nosql #devops #docker #k8s

状态标签：#draft #complete #needs-review #archived

优先级标签：#high #medium #low

调研模式

模式 1: 技术选型调研

触发场景：需要在多个技术方案中选择

流程：

1. 明确选择标准 (权重分配)
2. 列出候选方案 (3-5 个)
3. 逐项对比评分
4. 计算加权总分
5. 给出推荐方案

输出模板：见 references/templates/selection-matrix.md

模式 2: 实现方案调研

触发场景：需要实现特定功能

流程：

1. 功能分解 (子任务列表)
2. 收集实现模式 (3+ 种)
3. 评估每种模式
4. 推荐最优实现
5. 提供代码示例

输出模板：见 references/templates/implementation-guide.md

模式 3: 架构设计调研

触发场景：需要设计系统架构

流程：

1. 需求分析 (功能/非功能)
2. 约束识别 (技术/业务)
3. 模式选择 (架构风格)
4. 组件设计 (模块划分)
5. 接口定义 (API 设计)

输出模板：见 references/templates/architecture-design.md

模式 4: 问题排查调研

触发场景：需要解决技术问题

流程：

1. 问题复现 (最小化)
2. 根因分析 (5 Why)
3. 方案收集 (社区/文档)
4. 方案评估 (风险/成本)
5. 解决实施 + 验证

输出模板：见 references/templates/troubleshooting.md

质量检查清单

在输出调研文档前，检查：

  • 核心发现是否清晰 (3-5 个 bullet points)
  • 优缺点分析是否平衡 (不偏颇)
  • 代码示例是否可运行 (已验证)
  • 参考资料是否完整 (可追溯)
  • 适用场景是否明确 (不误导)
  • YAML frontmatter 是否正确
  • 文档是否放在正确目录
  • 索引文件是否已更新 (必须完成)

调研完成标准

一份完整的调研输出必须包含：

research/
├── SUMMARY.md           # ✅ 索引已更新
└── {topic}/
    └── YYYY-MM-DD-{name}.md  # ✅ 调研文档

索引更新检查：

# 验证新文档已在索引中
grep "YYYY-MM-DD-{name}" research/SUMMARY.md

常见反模式

❌ 过度收集

表现：收集大量信息但无法提炼核心发现

解决：设定时间盒，强制输出 3 个核心发现

❌ 缺乏结论

表现：罗列信息但不给出推荐

解决：必须包含"推荐方案"和"理由"

❌ 忽略约束

表现：推荐方案不考虑实际约束

解决：明确列出技术/业务约束

❌ 代码不可运行

表现：示例代码未经验证

解决：至少验证核心代码片段

工具使用

信息收集工具

# 官方文档
webfetch <url>

# GitHub 代码搜索
grep_app_searchGitHub <pattern>

# 技术社区
task(subagent_type="librarian", prompt="...")

文档生成工具

# 使用模板
cp docs/templates/research-template.md research/ai-llm/YYYY-MM-DD-topic.md

# 更新索引 (调研完成后必须执行)
python scripts/update_index.py research/

# 验证文档
python validate.py research/ai-llm/YYYY-MM-DD-topic.md

技能资源

脚本 (scripts/)

  • update_index.py - 自动更新 SUMMARY.md 索引 (调研后必须执行)
  • validate.py - 验证调研文档完整性

参考 (references/)

  • templates/ - 各类调研文档模板
  • checklists/ - 质量检查清单
  • patterns/ - 常见调研模式

资产 (assets/)

  • evaluation-matrix.xlsx - 技术评估矩阵模板
  • decision-tree.png - 技术选型决策树

迭代改进

使用技能后，记录：

  1. 调研效率：从问题到输出的时间
  2. 决策质量：推荐方案的实际效果
  3. 文档复用：后续参考频率

基于反馈更新：

  • SKILL.md 中的流程指导
  • references/ 中的模板
  • scripts/ 中的自动化脚本

版本：1.0.0
作者：Research Team
最后更新：2026-02-22

Weekly Installs
6
Repository
likaihz/tz-agent-skills
First Seen
Feb 26, 2026
Security Audits
Gen Agent Trust HubPass
SocketPass
SnykWarn
Installed on
github-copilot6
codex6
kimi-cli6
gemini-cli6
cursor6
amp6