ln-002-best-practices-researcher

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Best Practices Researcher

最佳实践研究员

Research industry standards and create project documentation in one workflow.

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

Purpose & Scope

目的与范围

Research via MCP Ref + Context7 for standards, patterns, versions
Create 4 types of documents from research results:
- Guide: Pattern documentation (Do/Don't/When table)
- Manual: API reference (methods/params/doc links)
- ADR: Architecture Decision Record (Q&A dialog)
- Research: Investigation document answering specific question
Return document path for linking in Stories/Tasks

通过MCP Ref + Context7研究标准、模式、版本信息
根据研究结果创建4类文档：
- 指南：模式文档（包含Do/Don't/When表格）
- 手册：API参考文档（包含方法/参数/文档链接）
- ADR：架构决策记录（问答对话形式）
- 研究报告：针对特定问题的调研文档
返回文档路径，用于在需求故事/任务中关联

Phase 0: Stack Detection

阶段0：技术栈检测

Objective: Identify project stack to filter research queries and adapt output.

Detection:

Indicator	Stack	Query Prefix	Official Docs
`.csproj` , `.sln`	.NET	"C# ASP.NET Core"	Microsoft docs
`package.json` + `tsconfig.json`	Node.js	"TypeScript Node.js"	MDN, npm docs
`requirements.txt` , `pyproject.toml`	Python	"Python"	Python docs, PyPI
`go.mod`	Go	"Go Golang"	Go docs
`Cargo.toml`	Rust	"Rust"	Rust docs
`build.gradle` , `pom.xml`	Java	"Java"	Oracle docs, Maven

Usage:

Add
```
query_prefix
```
to all MCP search queries
Link to stack-appropriate official docs

目标：识别项目技术栈，用于过滤研究查询并适配输出内容。

检测规则：

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

使用方式：

为所有MCP搜索查询添加
```
query_prefix
```
前缀
关联与技术栈匹配的官方文档

When to Use

适用场景

ln-310-story-validator detects missing documentation
Need to document a pattern, library, or decision
Replaces: ln-321-guide-creator, ln-322-adr-creator, ln-323-manual-creator

当ln-310-story-validator检测到缺失文档时
需要记录模式、库或决策时
替代工具：ln-321-guide-creator、ln-322-adr-creator、ln-323-manual-creator

Input Parameters

输入参数

Parameter	Required	Description
doc_type	Yes	"guide" / "manual" / "adr" / "research"
topic	Yes	What to document (pattern name, package name, decision title, research question)
story_context	No	Story/Task context for relevance

参数名	是否必填	描述
doc_type	是	"guide" / "manual" / "adr" / "research"
topic	是	文档主题（模式名称、包名、决策标题、研究问题）
story_context	否	需求故事/任务上下文，用于关联相关性

Research Tools

研究工具

Tool	Use Case	Query Pattern
`ref_search_documentation`	Standards, patterns, RFCs	`"[topic] RFC standard best practices 2025"`
`context7__resolve-library-id`	Get library ID for docs	`libraryName="[topic]"`
`context7__query-docs`	Library API, methods	`topic="[stack_prefix] [topic]"`
`WebSearch`	Market, competitors, versions	`"[topic] latest 2025"` or `"[topic] vs alternatives"`

Time-box: 5-10 minutes for research; skip if topic is trivial

工具	适用场景	查询模式
`ref_search_documentation`	标准、模式、RFC文档	`"[topic] RFC standard best practices 2025"`
`context7__resolve-library-id`	获取库的ID用于文档查询	`libraryName="[topic]"`
`context7__query-docs`	库API、方法查询	`topic="[stack_prefix] [topic]"`
`WebSearch`	市场、竞品、版本信息	`"[topic] latest 2025"` 或 `"[topic] vs alternatives"`

时间限制： 研究耗时5-10分钟；若主题简单可跳过

Research Methodology by Type (for doc_type="research")

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

Type	Focus	Primary Sources	Key Questions
Technical	Solution comparison	Docs, benchmarks, RFCs	"Which solution fits our use-case?"
Market	Industry landscape	Reports, blogs, articles	"What's the market size/trend?"
Competitor	How others solve it	Product pages, reviews, demos	"What features do competitors offer?"
Requirements	User needs	Feedback, support tickets, forums	"What do customers complain about?"
Feasibility	Can we build it?	PoC, prototypes, local tests	"Is it technically possible?"
Feature Demand	Feature viability	Competitor features + blogs/socials + user complaints	"Is this feature worth building?"

类型	研究重点	主要来源	核心问题
技术类	方案对比	文档、基准测试、RFC	"哪种方案符合我们的使用场景？"
市场类	行业格局	报告、博客、文章	"市场规模/趋势如何？"
竞品类	竞品解决方案	产品页面、评测、演示	"竞品提供了哪些功能？"
需求类	用户需求	反馈、支持工单、论坛	"用户抱怨的点是什么？"
可行性类	技术实现可能性	概念验证、原型、本地测试	"技术上是否可行？"
需求度类	功能可行性	竞品功能+博客/社交平台+用户反馈	"该功能是否值得开发？"

Workflow by doc_type

按文档类型划分的工作流

doc_type	Purpose	Research Source	Template	Output Path	Words
guide	Pattern with Do/Don't/When table	`ref_search` (best practices)	guide_template.md	`guides/NN-[slug].md`	300-500
manual	API/library reference	`context7__query-docs`	manual_template.md	`manuals/[pkg]-[ver].md`	300-500
adr	Architecture decision	Dialog (5 questions)	adr_template.md	`adrs/adr-NNN-[slug].md`	300-500
research	Investigation answering question	See Methodology table above	research_template.md	`research/rsh-NNN-[slug].md`	300-700

Common Workflow: Detect number (if needed) → Research → Generate from template → Validate (SCOPE, POSIX) → Save → Return path

Extract & Sections by doc_type:

guide: Extract principle, 2-3 do/don'ts, sources → Sections: Principle, Our Implementation, Patterns table, Sources, Related
manual: Extract methods, params (type/required/default), returns → Sections: Package info, Overview, Methods table, Config table, Limitations
adr: Dialog answers → Sections: Context, Decision, Rationale, Alternatives table, Consequences, Related
research: Findings by methodology → Sections: Question, Context, Methodology, Findings (tables!), Conclusions, Next Steps, Sources

Validation specifics: guide: patterns table present; manual: version in filename; adr: ISO date, status field; all: sources ≥2025

ADR Dialog (5 questions): Q1: Title? → Q2: Category (Strategic/Technical)? → Q3: Context? → Q4: Decision + Rationale? → Q5: Alternatives (2 with pros/cons)?

Output: File path for linking in Stories/Tasks; for ADR remind to reference in architecture.md; for Research suggest ADR if decision needed

doc_type	用途	研究来源	模板	输出路径	字数范围
guide	包含Do/Don't/When表格的模式文档	`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）→ 保存 → 返回路径

按文档类型提取内容与章节：

guide： 提取原则、2-3条Do/Don't规则、来源 → 章节：原则、我们的实现、模式表格、来源、相关链接
manual： 提取方法、参数（类型/是否必填/默认值）、返回值 → 章节：包信息、概述、方法表格、配置表格、局限性
adr： 对话答案 → 章节：背景、决策、理由、替代方案表格、影响、相关链接
research： 按研究方法整理的发现 → 章节：问题、背景、研究方法、发现（表格形式）、结论、下一步计划、来源

验证细节： guide：需包含模式表格；manual：文件名需包含版本号；adr：需包含ISO日期、状态字段；所有文档：来源需为2025年及以后

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

输出结果： 返回文件路径用于关联需求故事/任务；对于ADR，需提醒在architecture.md中引用；对于研究报告，若需决策则建议创建ADR

Critical Rules

核心规则

NO_CODE_EXAMPLES (ALL document types):

Forbidden	Allowed
Code snippets	Tables (params, config, alternatives)
Implementation examples	ASCII diagrams, Mermaid diagrams
Code blocks >1 line	Method signatures (1 line inline)
	Links to official docs

Format Priority (STRICT):

┌───────────────────────────────────────────────┐
│ 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            │
└───────────────────────────────────────────────┘

Content Type	Format
Parameters	Table: Name \| Type \| Required \| Default
Configuration	Table: Option \| Type \| Default \| Description
Alternatives	Table: Alt \| Pros \| Cons \| Why Rejected
Patterns	Table: Do \| Don't \| When
Workflow	ASCII diagram: `A → B → C`

Other Rules:

Research ONCE per invocation; reuse results
Cite sources with versions/dates (>=2025)
One pattern per guide; one decision per ADR; one package per manual
Preserve language (EN/RU) from story_context
Link to stack-appropriate docs (Microsoft for .NET, MDN for JS, etc.)
Do not create if target directory missing (warn instead)

所有文档类型均禁止代码示例：

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

格式优先级（严格执行）：

┌───────────────────────────────────────────────┐
│ 1. 表格 + ASCII图  ←── 最高优先级              │
│    参数、配置、替代方案、流程                  │
├───────────────────────────────────────────────┤
│ 2. 列表（仅枚举类型）                          │
│    枚举项、文件列表、工具                      │
├───────────────────────────────────────────────┤
│ 3. 文本（最后选择）                           │
│    仅当无法用表格表达时使用                    │
└───────────────────────────────────────────────┘

内容类型	格式要求
参数	表格：名称 \| 类型 \| 是否必填 \| 默认值
配置	表格：选项 \| 类型 \| 默认值 \| 描述
替代方案	表格：方案 \| 优点 \| 缺点 \| 被否决原因
模式	表格：Do \| Don't \| 适用场景
工作流	ASCII图： `A → B → C`

其他规则：

每次调用仅执行一次研究；复用研究结果
引用来源时需包含版本/日期（2025年及以后）
每个指南对应一个模式；每个ADR对应一个决策；每个手册对应一个包
保留story_context中的语言（英文/俄文）
关联与技术栈匹配的官方文档（.NET关联Microsoft，JS关联MDN等）
若目标目录不存在，请勿创建文档并发出警告

Definition of Done

完成标准

Research completed (standards/patterns/versions extracted) - for guide/manual
Dialog completed (5 questions answered) - for ADR
Document generated with all required sections; no placeholders
Standards validated (SCOPE, maintenance, POSIX)
File saved to correct directory with proper naming
Path returned; README updated if placeholder present

研究完成（提取标准/模式/版本信息）- 适用于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/DOCUMENTATION_STANDARDS.md
```
(if exists)

Version: 3.0.0 Last Updated: 2025-12-23

指南模板：
```
shared/templates/guide_template.md
```
手册模板：
```
shared/templates/manual_template.md
```
ADR模板：
```
shared/templates/adr_template.md
```
研究报告模板：
```
shared/templates/research_template.md
```
标准文档：
```
docs/DOCUMENTATION_STANDARDS.md
```
（若存在）

版本： 3.0.0 最后更新： 2025-12-23