ln-001-standards-researcher

**路径：**文件路径（shared/、references/、../ln-*）相对于技能仓库根目录。如果在当前工作目录中未找到，请定位此 SKILL.md 目录，并向上一级找到仓库根目录。

标准研究员（工作者）

此技能使用 MCP Ref 研究行业标准和架构模式，为 Story 技术说明生成标准研究内容。

目的

针对给定的 Epic/Story 领域研究行业标准、RFC 和架构模式。生成标准研究章节（表格 + 链接，不含代码），以便插入 Story 技术说明。

何时使用此技能

在以下情况下应使用此技能：

• 在生成 Story 之前需要研究标准和模式（确保任务遵循行业最佳实践）
• Epic 技术说明提及需要记录的特定标准（OAuth、OpenAPI、WebSocket）
• 防止任务使用过时模式或违反 RFC 合规要求
• 可复用于任何需要标准研究的技能

工作流

此技能遵循一个专注于标准和架构模式的 7 阶段工作流。

Stack Detection → Identify → Ref Research → Existing Guides → Generate Research → Save to File → Return

阶段 0：技术栈检测

目标：在研究之前确定项目技术栈，以筛选查询内容。

检测：

指标	技术栈	查询前缀
*.csproj、*.sln	.NET	"C# ASP.NET Core"
package.json + tsconfig.json	Node.js	"TypeScript Node.js"
requirements.txt、pyproject.toml	Python	"Python"
go.mod	Go	"Go Golang"
Cargo.toml	Rust	"Rust"
build.gradle、pom.xml	Java	"Java"

流程：

1. 如果提供了 context_store.TECH_STACK，则直接使用
2. 否则：在项目根目录中使用 Glob 查找指标文件
3. 存储 detected_stack.query_prefix，供阶段 2–3 使用

输出：detected_stack = {language, framework, query_prefix}

跳过条件：如果未检测到技术栈，则不使用前缀继续执行（通用查询）

---

阶段 1：识别库

目标：从 Epic/Story 中解析库和技术关键词。

流程：

1. 阅读 Epic/Story 描述（作为输入提供）

   • 解析 Epic 技术说明中提及的库/框架
   • 解析 Epic 范围中的技术关键词（身份验证、速率限制、支付等）
   • 根据 Epic 目标陈述识别 Story 领域（例如，“添加速率限制” → 领域 = “速率限制”）

2. 提取库列表：

   • 主要库（明确提及）
   • 推断出的库（例如，“REST API” → FastAPI，“缓存” → Redis）
   • 排除 API 稳定且广为人知的库（例如 requests、urllib3）

3. 确定 Story 领域：

   • 从 Epic 目标或 Story 标题中提取
   • 示例：速率限制、身份验证、支付处理、文件上传

输出：库列表（最多 3–5 个库）+ Story 领域

跳过条件：

• Epic 中未提及任何库 → 输出空的研究摘要
• 使用知名库的简单 CRUD 操作 → 输出空的研究摘要
• Epic 明确指出“无需研究” → 跳过

---

阶段 2：MCP Ref 研究

目标：获取行业标准和架构模式。

流程：

1. 重点研究标准/RFC：

   • 调用 mcp__Ref__ref_search_documentation(query="[detected_stack.query_prefix] [story_domain] RFC standard specification")
   • 示例："C# ASP.NET Core rate limiting RFC standard specification"
   • 提取：RFC/规范引用（OAuth 2.0 RFC 6749、OpenAPI 3.0、WebSocket RFC 6455）

2. 重点研究架构模式：

   • 调用 mcp__Ref__ref_search_documentation(query="[detected_stack.query_prefix] [story_domain] architectural patterns best practices")
   • 示例："TypeScript Node.js authentication architectural patterns best practices"
   • 提取：中间件、依赖注入、装饰器模式

**输出：**标准合规性表格 + 架构模式列表

---

Phase 3：MCP Ref 研究

目标：了解行业标准和最佳实践。

流程：

1. 对每个库 + Story 领域组合：

   • 调用 mcp__Ref__ref_search_documentation(query="[detected_stack.query_prefix] [library] [domain] best practices {current_year}")
   • 调用 mcp__Ref__ref_search_documentation(query="[detected_stack.query_prefix] [domain] industry standards RFC")
   • 示例："C# ASP.NET Core Polly rate limiting best practices {current_year}"

2. 从结果中提取（不含代码——仅文本/表格）：

   • 行业标准（RFC/规范参考：OAuth 2.0、REST API、OpenAPI 3.0）
   • 常见模式（描述应做/不应做的事项，以及需要避免的反模式）
   • 集成方法（中间件、依赖注入、装饰器）
   • 安全注意事项（符合 OWASP 要求、漏洞缓解）
   • 官方文档 URL（链接到适用于技术栈的权威来源）

3. 保存结果，用于编制研究摘要

输出：标准合规表（RFC/标准名称、如何合规）+ 最佳实践列表

---

Phase 4：扫描现有指南

目标：在 docs/guides/ 目录中查找相关模式指南。

流程：

1. 扫描指南目录：

   • 使用 Glob 查找 docs/guides/*.md
   • 读取指南文件名

2. 将指南与 Story 领域匹配：

   • 匹配关键词（例如，为限流 Story 查找限流指南）
   • 模糊匹配（例如，“authentication”匹配“auth.md”、“oauth.md”）

3. 收集指南路径，以便在技术说明中建立链接

输出：现有指南列表（相对于项目根目录的路径）

---

Phase 5：生成标准研究

目标：将研究结果汇编为标准研究，供 Story 技术说明子章节使用。

**NO_CODE 规则：**不得包含代码片段。仅使用表格和官方文档链接。

格式优先级：

┌─────────────────────────────────────┐
│ 1. TABLES + ASCII diagrams ← Priority │
│ 2. Lists (enumerations only)        │
│ 3. Text (last resort)               │
└─────────────────────────────────────┘

输出格式（表格优先）：

## Standards Research

**Standards compliance:**

| Standard | Requirement | How to Comply | Reference |
|----------|-------------|---------------|-----------|
| RFC 6749 | OAuth 2.0 | Use PKCE for public clients | [RFC 6749](url) |
| RFC 6585 | Rate Limiting | Return 429 + Retry-After | [RFC 6585](url) |

**Architectural patterns:**

| Pattern | When to Use | Reference |
|---------|-------------|-----------|
| Middleware | Request interception | [Official docs](url) |
| Decorator | Cross-cutting concerns | [Official docs](url) |

**Existing guides:**
- [guide_path.md](guide_path.md) - Brief description

**输出：**标准研究（Markdown 字符串），用于插入 Story 技术说明子章节

重要说明：

• 仅关注标准和模式（不涉及库的详细信息——库在任务级别研究）
• 优先使用官方文档和 RFC 标准，而非博客文章
• 链接到适用于技术栈的文档（.NET 使用 Microsoft 文档，JS 使用 MDN 等）
• 如果标准研究为空（没有标准/模式）→ 跳过 Phase 6，返回“无需标准研究”

---

Phase 6：将研究保存到文件

目标：将标准研究保存到独立文件，以便复用并纳入知识库。

强制要求：所有研究都必须保存到文件，即使已作为字符串返回给调用方。

流程：

1. 确定下一个研究编号：

   • 使用 Glob 查找 docs/research/rsh-*.md 文件
   • 提取编号并找出最大值
   • 下一个编号 = 最大值 + 1（如果没有文件，则为 001）

2. 生成文件名：

   • 格式：rsh-{number:03d}-{slug}.md
   • 根据 story_domain 生成 slug（例如，“rate-limiting”、“oauth-authentication”）
   • 示例：rsh-042-rate-limiting.md

3. 使用模板创建研究文档：

# Standards Research: {Story Domain}

**Created:** {ISO date}
**Epic:** {Epic ID if available}
**Research Type:** Standards & Architectural Patterns

## Question

What industry standards and architectural patterns apply to {story_domain}?

## Context

{Brief description from Epic/Story}

## Methodology

- **Standards:** MCP Ref search for RFCs and specifications
- **Patterns:** MCP Ref search for architectural patterns and best practices
- **Stack:** {detected_stack.language} {detected_stack.framework}

## Findings

{Insert Standards Research content from Phase 5 here}

## Conclusions

{1-2 sentences summarizing key standards/patterns that must be followed}

## Next Steps

- Reference this research in Story Technical Notes
- Link from architecture.md if patterns affect system design
- Create ADR if architectural decision needed

## Sources

{List of all MCP Ref search URLs with dates}

4. 保存文件：

   • 写入 docs/research/{filename}
   • 如果 docs/research/ 不存在：创建目录
   • 验证文件是否已成功保存

5. 更新 README（如果存在）：

   • 检查 docs/research/README.md
   • 如果文件存在且包含 ``：追加研究条目
   • 格式：- [{filename}]({filename}) - {one-line summary}

输出：文件路径（例如，docs/research/rsh-042-rate-limiting.md）

跳过条件：

• 标准研究为空 → 不创建文件
• 目标目录不存在且无法创建 → 警告用户，跳过创建文件

阶段 7：返回结果

返回给调用技能（ln-220、ln-310）：

1. 标准研究字符串（Markdown），用于插入 Story Technical Notes
2. 文件路径（字符串），用于链接：docs/research/rsh-{NNN}-{slug}.md

格式：

{
  "standards_research": "<markdown string>",
  "file_path": "docs/research/rsh-042-rate-limiting.md"
}

如果调用技能只需要字符串，则仅返回标准研究字符串。无论如何都会创建文件。

---

集成

依赖项：

• MCP Ref（ref_search_documentation）——行业标准和模式
• Glob（扫描 docs/guides/）

输入参数：

• epic_description（字符串）——Epic Technical Notes + Scope In + Goal
• story_domain（字符串，可选）——Story 领域（例如，“速率限制”）

输出格式：

• 主要内容： Markdown 字符串（用于 Story Technical Notes 子章节的标准研究）
• 次要内容： 文件路径（字符串）：docs/research/rsh-{NNN}-{slug}.md
• 内容： 标准 + 模式（在 Task 级别调研的库）
• 注意： 始终创建文件（阶段 6）

---

时间限制与性能

时间限制： 每个 Epic 最多 15-20 分钟

性能：

• 每个 Epic 只调研一次
• 所有 Story 都会复用结果（5-10 个 Story 受益于一次调研）
• 尽可能并行调用 MCP（Context7 + Ref）

Token 效率：

• Context7：每个库最多 3000 个 Token
• 总计：典型 Epic 约 10,000 个 Token（3-4 个库）

---

关键规则

• 必须创建文件： 所有调研内容都必须保存到 docs/research/rsh-{NNN}-{slug}.md 文件（阶段 6）；无一例外
• NO_CODE： 输出仅包含表格和官方文档链接；不包含代码片段
• 格式优先级： 优先使用表格 + ASCII 图，其次是列表，最后才使用文本
• 考虑技术栈的查询： 所有 MCP Ref 调用都必须包含检测到的 query_prefix（例如，“C# ASP.NET Core”）
• 标准优先于库： 重点关注 RFC 和架构模式；库的详情在 Task 级别调研
• 时间限制： 每个 Epic 最多 15-20 分钟；每个 Epic 只调研一次，并由所有 Story 复用

完成定义

• 已检测到技术栈（若无法检测则跳过），并设置了 query_prefix
• 已从 Epic/Story 描述中提取库和 Story 领域
• 已完成 MCP Ref 调研，涵盖标准/RFC 和架构模式
• 已扫描并匹配 docs/guides/ 中的现有指南
• 已生成 Markdown 格式的标准研究输出（表格 + 链接，不含代码）
• 已将调研内容保存到文件：创建 docs/research/rsh-{NNN}-{slug}.md，并包含所有必需章节
• 已更新 README（如果 docs/research/README.md 存在且含有占位内容）
• 已将输出返回给调用技能：标准研究字符串 + 文件路径

参考文件

工具：

• mcp__Ref__ref_search_documentation() ——搜索最佳实践和标准
• Glob ——扫描 docs/guides/ 目录

指南：

• 必须阅读： 加载 references/research_guidelines.md——调研质量指南（优先选择官方文档而非博客文章，优先采用 LTS 版本）

• 必须阅读： 加载 shared/references/research_tool_fallback.md

---

版本： 3.1.0 最后更新： 2026-02-14