ln-002-best-practices-researcher

路径： 文件路径（shared/、references/、../ln-*）均相对于 skills 仓库根目录。如果在 CWD 中找不到，请定位此 SKILL.md 所在目录，并向上一级找到仓库根目录。

最佳实践研究员

通过一个工作流研究行业标准并创建项目文档。

目的与范围

• 通过 MCP Ref + Context7 研究标准、模式和版本
• 根据研究结果创建 4 种类型的文档：
  • 指南：模式文档（包含“应做 / 不应做 / 适用时机”表格）
  • 手册：API 参考（方法 / 参数 / 文档链接）
  • ADR：架构决策记录（问答对话）
  • 研究：回答特定问题的调查文档
• 返回文档路径，以便在 Stories/Tasks 中引用

阶段 0：技术栈检测

目标：识别项目技术栈，以筛选研究查询并调整输出。

检测：

指示项	技术栈	查询前缀	官方文档
*.csproj、*.sln	.NET	"C# ASP.NET Core"	Microsoft 文档
package.json + tsconfig.json	Node.js	"TypeScript Node.js"	MDN、npm 文档
requirements.txt、pyproject.toml	Python	"Python"	Python 文档、PyPI
go.mod	Go	"Go Golang"	Go 文档
Cargo.toml	Rust	"Rust"	Rust 文档
build.gradle、pom.xml	Java	"Java"	Oracle 文档、Maven

用法：

• 将 query_prefix 添加到所有 MCP 搜索查询中
• 链接到适合该技术栈的官方文档

适用场景

• ln-310-multi-agent-validator 检测到缺少文档
• 需要记录模式、库或决策
• 替代：ln-321-guide-creator、ln-322-adr-creator、ln-323-manual-creator

输入参数

参数	必填	说明
doc_type	是	"guide" / "manual" / "adr" / "research"
topic	是	文档主题（模式名称、包名称、决策标题、研究问题）
story_context	否	与相关性有关的 Story/Task 上下文

研究工具

工具	用途	查询模式
ref_search_documentation	标准、模式、RFC	"[topic] RFC standard best practices {current_year}"
context7__resolve-library-id	获取文档对应的库 ID	libraryName="[topic]"
context7__query-docs	库 API、方法	topic="[stack_prefix] [topic]"
WebSearch	市场、竞争对手、版本	"[topic] latest {current_year}" 或 "[topic] vs alternatives"

时间限制： 研究 5-10 分钟；如果主题很简单，则跳过

按类型划分的研究方法（适用于 doc_type="research"）

类型	重点	主要来源	关键问题
技术	解决方案比较	文档、基准测试、RFC	"哪种解决方案适合我们的用例？"
市场	行业概况	报告、博客、文章	"市场规模 / 趋势如何？"
竞争对手	其他人如何解决问题	产品页面、评测、演示	"竞争对手提供哪些功能？"
需求	用户需求	反馈、支持工单、论坛	"客户在抱怨什么？"
可行性	我们能否实现？	PoC、原型、本地测试	"技术上是否可行？"
功能需求	功能可行性	竞争对手功能 + 博客 / 社交媒体 + 用户投诉	"这个功能值得开发吗？"

工作流

文档类型	用途	研究来源	模板	输出路径	字数
guide	包含「应做/不应做/适用时机」表格的模式	ref_search（最佳实践）	guide_template.md	guides/NN-[slug].md	300-500
manual	API/库参考	context7__query-docs	manual_template.md	manuals/[pkg]-[ver].md	300-500
adr	架构决策	对话（5 个问题）	adr_template.md	adrs/adr-NNN-[slug].md	300-500
research	回答问题的调查	参见上方的方法论表格	research_template.md	research/rsh-NNN-[slug].md	300-700

通用工作流： 检测编号（如需要）→ 研究 → 根据模板生成 → 验证（SCOPE、POSIX）→ 保存 → 返回路径

按 doc_type 提取内容和划分章节：

• guide： 提取原则、2-3 条应做/不应做事项、来源 → 章节：原则、我们的实现、模式表格、来源、相关内容
• manual： 提取方法、参数（类型/必填/默认值）、返回值 → 章节：包信息、概览、方法表格、配置表格、限制
• adr： 提取对话答案 → 章节：背景、决策、理由、替代方案表格、后果、相关内容
• research： 根据方法论整理发现 → 章节：问题、背景、方法论、发现（表格！）、结论、后续步骤、来源

验证细则： guide：必须包含模式表格；manual：文件名中必须包含版本号；adr：必须包含 ISO 日期和状态字段；所有文档：来源不得超过 1 年

ADR 对话（5 个问题）： Q1：标题？→ Q2：类别（战略/技术）？→ Q3：背景？→ Q4：决策 + 理由？→ Q5：替代方案（2 个，包含优缺点）？

输出： 返回文件路径，以便在 Stories/Tasks 中链接；对于 ADR，提醒在 architecture.md 中引用；对于 Research，如果需要做决策，则建议创建 ADR

关键规则

必须创建文件：

• 所有研究都必须以创建文件结束（guide/manual/ADR/research 文档）
• 如果目标目录不存在，则创建该目录（docs/guides/、docs/manuals/、docs/adrs/、docs/research/）
• 不得例外——每次调用都必须创建文件

NO_CODE_EXAMPLES（所有文档类型）：

禁止	允许
代码片段	表格（参数、配置、替代方案）
实现示例	ASCII 图、Mermaid 图
超过 1 行的代码块	方法签名（行内，1 行）
	官方文档链接

格式优先级（严格）：

┌───────────────────────────────────────────────┐
│ 1. TABLES + ASCII diagrams  ←── PRIORITY      │
│    Params, Config, Alternatives, Flows        │
├───────────────────────────────────────────────┤
│ 2. LISTS (enumerations only)                  │
│    Enumeration items, file lists, tools       │
├───────────────────────────────────────────────┤
│ 3. TEXT (last resort)                         │
│    Only if cannot express as table            │
└───────────────────────────────────────────────┘

内容类型	格式
参数	表格：名称 | 类型 | 必填 | 默认值
配置	表格：选项 | 类型 | 默认值 | 描述
替代方案	表格：替代方案 | 优点 | 缺点 | 拒绝原因
模式	表格：应做 | 不应做 | 适用时机
工作流	ASCII 图：A → B → C

其他规则：

• 每次调用只研究一次；重复使用研究结果
• 引用来源时注明版本/日期（不超过 1 年）
• 每篇 guide 使用一个模式；每篇 ADR 做出一个决策；每篇 manual 介绍一个包
• 保留 story_context 中的语言（EN/RU）
• 链接到适合技术栈的文档（.NET 使用 Microsoft，JS 使用 MDN 等）
• 必须： 如果目标目录不存在，则创建该目录（docs/guides/、docs/manuals/、docs/adrs/、docs/research/）；必须创建文件

完成定义

• 已完成研究（提取标准/模式/版本）——适用于 guide/manual
• 已完成对话（回答 5 个问题）——适用于 ADR
• 已生成包含所有必需章节的文档；没有占位符
• 已验证标准（SCOPE、维护要求、POSIX）
• 文件已使用正确的命名方式保存到正确目录
• 已返回路径；如果存在占位符，已更新 README

Reference Files

• Guide template: shared/templates/guide_template.md
• Manual template: shared/templates/manual_template.md
• ADR template: shared/templates/adr_template.md
• Research template: shared/templates/research_template.md
• Standards: docs/standards/DOCUMENTATION_STANDARDS.md (if exists)
• MANDATORY READ: shared/references/research_tool_fallback.md

---

Version: 3.0.1 Last Updated: 2026-02-14