research-synthesis

研究综合技能

目的

在创建任何新工件（Agent、技能、工作流、钩子、架构）之前，先收集并综合研究成果。此技能可确保所有设计决策均有以下依据：

1. 来自权威来源的当前最佳实践
2. 来自真实案例的实现模式
3. 现有代码库惯例，以保持一致性
4. 风险评估，以预见问题

何时调用此技能

必须在以下操作之前调用：

• agent-creator — 研究 Agent 模式和领域专业知识
• skill-creator — 研究技能实现最佳实践
• workflow-creator — 研究编排模式
• hook-creator — 研究验证和安全模式
• schema-creator — 研究 JSON Schema 模式
• template-creator — 研究代码脚手架模式

建议用于：

• 新功能设计
• 架构决策
• 技术选型
• 集成规划

铁律

NO ARTIFACT CREATION WITHOUT RESEARCH FIRST

如果尚未执行研究流程，就不能继续创建工件。

多源冲突检测（受 Skill_Seekers unified_scraper 启发）

综合 2 个或更多来源时，应主动检测并标记矛盾，以免在无提示的情况下采纳相互冲突的建议。

需要检测的冲突类型：

冲突类型	示例	解决策略
版本不匹配	来源 A 说“使用 v2 API”，来源 B 说“必须使用 v3”	标记日期，优先采用最新信息
建议相互矛盾	来源 A 说“始终使用 ORM”，来源 B 说“为了性能使用原始 SQL”	标记双方建议及背景，由决策者选择
已弃用的模式	来源 A 推荐的模式被来源 B 标记为已弃用	标记弃用提示，优先采用来源 B
实现不兼容	来源 A 使用回调，来源 B 使用 async/await	如有迁移路径，则标记该路径

检测流程：

1. 收集所有来源的发现后，建立主张矩阵——提取各来源中的事实性主张
2. 使用语义重叠（主题相同、建议不同）逐对比较主张，检查是否存在矛盾
3. 对每项冲突，记录：{ claim_a, source_a, claim_b, source_b, conflictType, suggestedResolution }
4. 在综合报告中加入 conflicts 部分——绝不能在不说明的情况下选择一方

报告中的冲突输出：

### Conflicts Detected (2)

1. **Version requirement** — React Router docs (2026-03) say v7 required for data loading; Stack Overflow answer (2025-11) assumes v6. **Resolution:** Use v7 (docs are authoritative and more recent).

2. **State management approach** — Official docs recommend Context API for simple state; community blog recommends Zustand universally. **Resolution:** Flag for architect — depends on app complexity.

查询限制（铁律）

3-5 QUERIES MAXIMUM PER RESEARCH TASK

超过此限制会导致：

• 内存耗尽（报告超过 10 KB → 上下文窗口溢出）
• 信息过载（无法有效处理 10 个以上来源）
• 边际收益递减（质量重于数量）

按复杂度分配查询额度：

• 简单研究（事实核查、版本核查）：3 次查询
• 中等研究（功能比较、实现模式）：4 次查询
• 复杂研究（全面的最佳实践、生态概览）：5 次查询

绝不：

• 在单次研究会话中执行超过 5 次查询
• 执行不设上限的“研究所有内容”查询
• 在一次会话中合并多个无关的研究主题

多阶段模式： 如果研究需要超过 5 次查询，则将其拆分为多个研究会话（参见下文“多阶段研究模式”）。

---

报告大小限制（铁律）

10 KB MAXIMUM PER RESEARCH REPORT

为什么是 10 KB？

• 提高上下文效率（10 KB ≈ 2500 个单词，可在一个上下文窗口中阅读）
• 迫使优先排序（只包含必要的发现）
• 避免“百科全书综合征”（复制整篇文章）

格式要求：

• 使用项目符号（简洁明了）
• 引用 URL，而不是复制内容
• 每个来源的发现总结不超过 3 句话
• 去除冗余，只保留要点

接近 10 KB 时：

1. 停止添加新来源
2. 合并重复内容
3. 删除冗余细节
4. 聚焦独特见解

对于复杂主题：

• 拆分为 2-3 份小型报告（每份小于 10 KB）
• 每份报告聚焦一个方面
• 在摘要中相互链接

---

强制研究流程

步骤 0：内部记忆检索 + 上下文压力检查（强制 — 第一步）

在执行任何外部研究查询之前，先搜索项目内部记忆。 如果内部已有足够且置信度高的结果，则完全跳过外部查询。 然后，在继续之前检查上下文压力。

// Sub-step 0a: Query internal RAG for cached research on the topic
const { searchInternalContext } = require('.claude/lib/memory/internal-rag.cjs');
const internalResults = await searchInternalContext(researchTopic, { limit: 5, threshold: 0.6 });
const avgSimilarity =
  internalResults.results.length > 0
    ? internalResults.results.reduce((sum, r) => sum + (r.similarity || 0), 0) /
      internalResults.results.length
    : 0;
if (internalResults.results.length >= 3 && avgSimilarity > 0.7) {
  // High-confidence internal hit — synthesize from internal results and skip external search
  console.log(
    '[research-synthesis] Internal RAG hit (avg similarity:',
    avgSimilarity.toFixed(2),
    ') — skipping external search'
  );
}
// Otherwise proceed to external queries below

// Sub-step 0b: Context pressure check
const { checkContextPressure } = require('.claude/lib/utils/context-pressure.cjs');

// Option A — token-budget-based (if budget info available)
const pressure = checkContextPressure({
  tokenBudgetPercent: currentTokenBudgetPercent,
});

// Option B — text-based estimate (when budget % not available)
// const pressure = checkContextPressure({ text: recentContextSnapshot });

if (pressure.pressure === 'high') {
  // STOP — compress context before researching
  console.warn('[research-synthesis] High context pressure:', pressure.reason);
  console.warn('Run context-compressor skill first, then re-invoke research-synthesis.');
  // Return early without executing research queries
  process.exit(0);
}

if (pressure.pressure === 'medium') {
  // Proceed but limit to 3 queries (simple budget)
  console.warn('[research-synthesis] Medium context pressure:', pressure.reason);
  console.warn('Limiting to 3 queries. Consider compressing after research.');
}
// Low pressure → proceed normally with full query budget

执行规则：

压力	操作
high	停止 — 调用 context-compressor 技能，然后重试
medium	限制为 3 个查询，并提醒调用方
low	正常继续，使用完整查询额度（3–5 个查询）

---

步骤 1：确定研究范围并规划查询

执行查询前，先确定范围并规划查询额度：

## Research Scope Definition

**Artifact Type**: [agent | skill | workflow | hook | schema | template]
**Domain/Capability**: [What this artifact will do]

**Complexity Assessment**:

- [ ] Simple (fact-checking, version checking) → 3 queries
- [ ] Medium (feature comparison, implementation patterns) → 4 queries
- [ ] Complex (comprehensive best practices, ecosystem overview) → 5 queries

**Planned Queries** (list 3-5 BEFORE executing):

1. [Query 1: Best practices - specific question]
2. [Query 2: Implementation patterns - specific question]
3. [Query 3: Framework/AI-specific - specific question]
4. [Optional Query 4: Security/performance - specific question]
5. [Optional Query 5: Trade-offs/alternatives - specific question]

**Key Questions**:

1. What are the best practices for this domain?
2. What implementation patterns exist?
3. What tools/frameworks should be used?
4. What are the common pitfalls?

**Existing Patterns to Examine**:

- .claude/[category]/ - Similar artifacts
- .claude/templates/ - Relevant templates
- .claude/schemas/ - Validation patterns

研究前检查清单：

[ ] Complexity assessed (3, 4, or 5 queries planned)
[ ] Queries planned BEFORE executing (prevents scope creep)
[ ] Each query is specific (not "research everything about X")
[ ] Report size target set (<10 KB)
[ ] Multi-phase split considered (if >5 queries needed)

步骤 2：执行研究查询（最多 3–5 个）

严格执行 3–5 个研究查询（不得更多）。查询过多会导致记忆耗尽和上下文丢失。

查询 1：最佳实践

// Using Exa (preferred for technical content)
mcp__Exa__web_search_exa({
  query: '{artifact_type} {domain} best practices 2024 2025',
  numResults: 5,
});

// Or using WebSearch (fallback)
WebSearch({
  query: '{domain} best practices implementation guide',
});

查询 2：实现模式

// Code-focused search
mcp__Exa__get_code_context_exa({
  query: '{domain} implementation patterns examples github',
  tokensNum: 5000,
});

// Or fetch from authoritative sources
WebFetch({
  url: 'https://[authoritative-source]/docs/{topic}',
});

查询 3：Claude / AI Agent 专项

// Framework-specific patterns
mcp__Exa__web_search_exa({
  query: 'Claude AI agent {domain} {artifact_type} patterns',
  numResults: 5,
});

// Or search for MCP patterns
WebSearch({
  query: 'Model Context Protocol {domain} integration',
});

提高查询效率的技巧：

• 优先使用 2–3 个高质量查询，而不是 10 个泛泛的查询
• 将相关问题合并到一个查询中（“X 最佳实践 + 实现模式”）
• 对已知的权威来源使用 WebFetch（更快、更聚焦）
• 收集到足够的独特见解后就停止（质量胜于数量）

步骤 3：分析现有代码库

综合研究结果前，先检查代码库中的现有模式：

// Find similar artifacts
Glob({ pattern: '.claude/{artifact_category}/**/*.md' });

// Search for related implementations
Grep({ pattern: '{related_keyword}', path: '.claude/' });

// Read existing examples
Read({ file_path: '.claude/{category}/{similar_artifact}' });

需要提取的内容：

1. 命名约定 — 类似产物如何命名？
2. 结构模式 — 它们包含哪些章节？
3. 工具用法 — 类似产物使用哪些工具？
4. 技能依赖项 — 通常会分配哪些技能？
5. 输出位置 — 产物会将输出保存到哪里？

步骤 4：综合研究结果

按照 .claude/templates/reports/research-report-template.md 生成结构化研究报告：

文件位置：.claude/context/artifacts/research-reports/{topic}-research-{YYYY-MM-DD}.md

必需章节：

1. 来源信息标题：``
2. 执行摘要：用 2–3 句话概述关键发现
3. 研究方法：查询表 + 已查阅来源表
4. 详细发现：按主题整理，包含关键见解、证据和相关性
5. 学术参考文献：arXiv 论文、学术来源（即使为空也要包含）
6. 实用建议：按 P0 / P1 / P2 优先级排序
7. 风险评估：包含影响、概率和缓解措施的风险表
8. 实施路线图：后续步骤和时间线

针对产物创建类研究，还需包含：

现有代码库模式

发现的类似产物：

• {path_1} — {作用及其采用的模式}
• {path_2} — {作用及其采用的模式}

识别出的约定：

• 命名：{约定}
• 结构：{约定}
• 工具：{约定}
• 输出：{约定}

已确定的最佳实践

#	实践	来源	置信度	理由
1	{practice}	{source_url_or_name}	高	{why_applicable}
2	{practice}	{source_url_or_name}	中	{why_applicable}
3	{practice}	{source_url_or_name}	高	{why_applicable}

置信度等级：

• 高：多个权威来源一致认同
• 中：单个权威来源或多个次级来源
• 低：证据有限，需要验证

设计决策

决策	理由	来源	考虑过的替代方案
{decision_1}	{why}	{source}	{what_else_was_considered}
{decision_2}	{why}	{source}	{what_else_was_considered}
{decision_3}	{why}	{source}	{what_else_was_considered}

推荐实现方案

文件位置：.claude/{category}/{name}/

使用的模板：.claude/templates/{template}.md

要调用的技能：

• {skill_1} - {why}
• {skill_2} - {why}

所需钩子：

• {hook_type} - {purpose}

依赖项：

• 现有构件：{list}
• 外部工具：{list}

质量门槛检查清单

创建构件前，请确认：

• 已执行至少 3 次研究查询
• 至少查阅了 3 个外部来源
• 已记录现有代码库中的模式
• 所有设计决策均附有理由和来源
• 已完成风险评估并制定缓解措施
• 已记录推荐的实现路径
• 报告已按正确的命名格式保存：{topic}-research-{YYYY-MM-DD}.md
• 已包含来源标注头

后续步骤

1. 调用创建者技能：Skill({ skill: "{creator_skill}" })
2. 将此报告用作输入：参考上述决策
3. 根据清单进行验证：完成前执行

与创建者技能集成

创建前工作流

[AGENT] User requests: "Create a Slack notification skill"

[AGENT] Step 1: Research first
Skill({ skill: "research-synthesis" })

[RESEARCH-SYNTHESIS] Executing research protocol...
- Query 1: "Slack API best practices 2025"
- Query 2: "Slack MCP server integration patterns"
- Query 3: "Claude AI Slack notification skill"
- Analyzing: .claude/skills/*/SKILL.md for patterns
- Output: Research Report saved

[AGENT] Step 2: Create with research backing
Skill({ skill: "skill-creator" })

[SKILL-CREATOR] Using research report...
- Following design decisions from report
- Applying identified best practices
- Mitigating documented risks

交接格式

完成研究后，将以下交接内容提供给创建者技能：

## Research Handoff to: {creator_skill}

**Report Location**: `.claude/context/artifacts/research-reports/{artifact_name}-research.md`

**Summary**:
{2-3 sentence summary of key findings}

**Critical Decisions**:

1. {decision_1}
2. {decision_2}
3. {decision_3}

**Proceed with creation**: YES/NO
**Confidence Level**: High/Medium/Low

多阶段研究模式（适用于复杂主题）

当研究复杂度超过 5 个查询时，分阶段进行：

阶段 1：范围与定义（2 个查询）

• 该主题／技术是什么？
• 关键概念有哪些？

阶段 2：实现（2 个查询）

• 专家如何实现？
• 常见模式与最佳实践有哪些？

阶段 3：比较与权衡（1 个查询）

• 与其他方案相比如何？
• 有哪些权衡和注意事项？

优点：

• 每个阶段相互独立（减少上下文混杂）
• 可通过单独调用技能完成
• 组织结构更清晰
• 更容易复用研究结果

示例：

Session 1: Research "Rust async/await" (Phase 1: 2 queries)
Session 2: Research "Tokio patterns" (Phase 2: 2 queries)
Session 3: Research "async-trait vs manual impl" (Phase 3: 1 query)

---

考虑记忆限制的分块示例

良好 - 聚焦查询 + 分块报告：

Query: "Rust async/await best practices 2026"
Report structure:
- Definition (100 words)
- Pattern 1: Tokio (200 words)
- Pattern 2: async-trait (150 words)
- Gotchas (100 words)
- Links (10 sources)
---Total: ~550 words, ~3 KB

不良 - 无限制的研究：

Query: "everything about Rust ecosystem 2026"
Report: 50 sources, 15 KB (truncated by context limit)
---Can't use findings without context loss

良好 - 分阶段进行：

Phase 1 Report: Rust async fundamentals (3 KB)
Phase 2 Report: Tokio implementation patterns (4 KB)
Phase 3 Report: Performance comparison (2 KB)
---Total: 9 KB across 3 sessions (all usable)

不良 - 单篇超长报告：

Single Report: Comprehensive Rust async guide (25 KB)
---Truncated to 10 KB, missing critical sections

---

质量门槛

所有项目均通过后，研究才算完成：

[ ] 3-5 research queries executed (NO MORE THAN 5)
[ ] At least 3 external sources consulted (URLs or authoritative names)
[ ] Existing codebase patterns documented (at least 2 similar artifacts)
[ ] ALL design decisions have rationale AND source
[ ] Risk assessment completed (at least 3 risks with mitigations)
[ ] Recommended implementation path documented
[ ] Report saved to output location
[ ] Report size <10 KB (check file size before saving)

阻断条件：任何一项未通过，研究均视为未完成。请勿继续创建构件。

输出位置

• 研究报告：.claude/context/artifacts/research-reports/
• 临时笔记：.claude/context/tmp/research/
• 记忆更新：.claude/context/memory/learnings.md

报告命名规范（强制）

格式：{topic}-research-{YYYY-MM-DD}.md

• 主题：使用 kebab-case 的描述性名称
• 始终在日期前包含 -research- 后缀
• 日期：使用带连字符的 ISO 8601 格式（YYYY-MM-DD）

示例：

• ✓ oauth2-security-research-2026-02-09.md
• ✓ json-schema-patterns-research-2026-02-09.md
• ✓ slack-integration-best-practices-research-2026-02-09.md
• ✗ agent-keywords-core.md（缺少日期）
• ✗ oauth2-auth-2026-02-09.md（缺少 -research- 后缀）
• ✗ bmad-method-analysis-20260128-104050.md（日期格式错误）

模板：所有研究报告均使用 .claude/templates/reports/research-report-template.md

示例

示例 1：创建 Slack 技能前进行研究

// Step 1: Define scope
// Artifact: skill, Domain: Slack notifications

// Step 2: Execute queries
mcp__Exa__web_search_exa({
  query: 'Slack API webhook best practices 2025',
  numResults: 5,
});

mcp__Exa__get_code_context_exa({
  query: 'Slack notification system implementation Node.js',
  tokensNum: 5000,
});

WebSearch({
  query: 'Claude AI MCP Slack server integration',
});

// Step 3: Analyze codebase
Glob({ pattern: '.claude/skills/*notification*/SKILL.md' });
Glob({ pattern: '.claude/skills/*slack*/SKILL.md' });
Read({ file_path: '.claude/skills/skill-creator/SKILL.md' });

// Step 4: Synthesize and output report
Write({
  file_path: '.claude/context/artifacts/research-reports/slack-notifications-research.md',
  content: '## Research Report: Slack Notifications Skill...',
});

示例 2：创建数据库 Agent 前进行研究

// Research queries for database-architect agent
mcp__Exa__web_search_exa({
  query: 'database design architecture best practices 2025',
  numResults: 5,
});

WebFetch({
  url: 'https://docs.postgresql.org/current/ddl.html',
});

mcp__Exa__web_search_exa({
  query: 'AI agent database schema design automation',
  numResults: 5,
});

// Analyze existing agents
Glob({ pattern: '.claude/agents/domain/*data*.md' });
Read({ file_path: '.claude/agents/core/developer.md' });

常见研究领域

领域	关键查询	权威来源
API 集成	“REST API 设计”、“GraphQL 模式”	OpenAPI 规范、GraphQL 规范
安全	“OWASP 十大风险”、“安全最佳实践”	OWASP、NIST
数据库	“数据库设计模式”、“SQL 优化”	PostgreSQL 文档、MySQL 文档
前端	“React 模式”、“WCAG 无障碍访问”	React 文档、W3C
DevOps	“CI/CD 最佳实践”、“IaC 模式”	GitLab 文档、Terraform 文档
测试	“TDD 模式”、“测试自动化”	Testing Library、Jest 文档
AI/ML	“大模型集成模式”、“提示词工程”	Anthropic 文档、OpenAI 文档

文件放置与规范

输出位置规则

此技能的输出位置：.claude/context/artifacts/research-reports/

强制参考资料

• 文件放置：参见 .claude/docs/FILE_PLACEMENT_RULES.md
• 开发者工作流：参见 .claude/docs/DEVELOPER_WORKFLOW.md
• 产物命名：参见 .claude/docs/ARTIFACT_NAMING.md

强制执行

文件放置由 file-placement-guard.cjs hook 强制执行。 在生产模式下，系统会阻止无效的放置位置。

---

记忆协议（强制）

开始前：

cat .claude/context/memory/learnings.md

检查以下内容：

• 类似领域的既往研究
• 已知模式和惯例
• 已记录的决策

完成后：

• 新的研究发现 -> 追加到 .claude/context/memory/learnings.md
• 重要决策 -> 追加到 .claude/context/memory/decisions.md
• 发现的问题 -> 追加到 .claude/context/memory/issues.md

假定可能发生中断：你的上下文可能会重置。如果没有记录在记忆中，就等于没有发生。

工作流集成

此技能与 Creator Ecosystem 集成：

Creator	研究重点
agent-creator	领域专业知识、Agent 模式、技能依赖项
skill-creator	工具集成、MCP 模式、验证钩子
workflow-creator	编排模式、多 Agent 协作
hook-creator	验证模式、安全检查、安全关卡
schema-creator	JSON Schema 模式、验证策略
template-creator	代码脚手架、项目结构模式

完整生命周期： .claude/workflows/core/skill-lifecycle.md

---

铁律

1. 绝不在完成研究流程之前创建任何产物——缺乏充分调研就进行创建，会导致决策与现有模式冲突，并需要付出高昂的返工成本。
2. 绝不在一次研究会话中执行超过 5 个查询——超出此限制会导致内存耗尽和上下文窗口溢出，后续发现会在不知不觉中丢失。
3. 绝不撰写超过 10 KB 的研究报告——过长的报告会溢出上下文窗口，迫使系统在最关键的章节截断研究发现。
4. 始终至少分析代码库中的 2 个现有产物，然后再综合外部研究——仅凭外部最佳实践会遗漏项目特有的约定，并导致实现不一致。
5. 始终为每项设计决策记录来源和理由——没有证据支持的决策无法评估、质疑，也无法在未来重构时追溯。

反模式

反模式	失败原因	正确做法
在运行研究流程之前就开始创建产物	导致决策缺乏充分依据，与现有模式冲突，并需要返工	在调用任何创建器技能之前，始终先调用 research-synthesis 并通过质量门禁
为了“全面”而执行 10 个以上的查询	导致内存耗尽和上下文溢出；后续发现会在不知不觉中丢失	开始前准确规划 3–5 个有针对性的查询；将复杂主题拆分为独立的研究阶段
撰写超过 10 KB 的详尽研究报告	过长的报告会在上下文窗口中被截断，隐藏创建器技能最需要的章节	使用项目符号，引用 URL 而非复制内容，并将每个来源的摘要控制在 3 句话以内
未检查现有代码库就综合外部研究发现	外部最佳实践可能与既定的项目模式和命名约定冲突	撰写设计决策之前，始终先使用 glob 查找并阅读至少 2 个类似的现有产物
记录设计决策时不提供来源引用	未记录的决策无法验证、质疑，也无法在未来的重构周期中追溯	“设计决策”表格中的每一行都必须包含来源 URL 或权威参考资料的名称