software-research

软件研究

功能说明

将一个软件工程问题转化为经过验证、涵盖多个视角的交付成果。它会选择一种研究模式，模拟该模式下专家的视角，梳理各方观点的矛盾之处，综合生成一份 HTML 简报和一份 Markdown 或 ADR 记录，然后根据原始来源对每项主张进行对抗式验证，并确保版本信息准确，再交付结果。请运行完整流程，不要跳过任何阶段。

可移植性

自包含。仅使用内置工具（通用 Agent、Write、Agent 内的网络搜索／抓取工具）以及此文件夹中的文件。将此文件夹放入任意 .claude/skills/ 目录即可使用。

阶段 0：确定范围并识别模式

1. 如果 $ARGUMENTS 中有问题，就使用该问题；否则询问要研究什么。
2. 阅读 data/modes.csv。根据每行的 signals（以分号分隔的线索）匹配问题，选择最匹配的 mode_id。
   • 如果有两个或更多模式的匹配置信度相近，询问用户要选择哪种模式（列出匹配的模式及各自的一句话说明）。否则继续。
   • 如果没有匹配项，则使用 deep-research（默认模式）。
3. 说明选定的模式以及对问题的一句话解读。用户可以更改模式。
4. 根据上下文确定读者角色（开发者／技术负责人／架构师）；默认为 tech-lead。
5. 为文件名生成 kebab-case 格式的 topic-slug。
6. 关卡 1——确认范围（暂停一次）。 显示简洁的信息块，然后等待用户确认或调整范围，再启动任何 Agent：

   Mode:        <mode_id> — <one-line why this mode>
   Question:    <your one-line interpretation>
   Reader:      <developer | tech-lead | architect>
   Lenses:      <the N lens names about to run in parallel>
   Outputs:     <primary + secondary format, e.g. HTML briefing + MD>
   Then:        adversarial verification against primary sources.
   Proceed? (or correct the mode / scope)
   

   这是在投入约 9–12 个 Agent 之前，以低成本发现模式选错或范围理解有误的唯一机会。确认后，自主运行阶段 1–3（在关卡 2 之前不要再暂停）。

阶段 1：并行专家视角

打开 references/modes/{mode_id}.md——其中包含此模式的确切视角提示词。将该模式下的各个视角作为 general-purpose Agent 在同一条消息中启动，以便并发运行。向每个 Agent 提供相同的问题框架，以及：

• 其视角提示词（来自模式文件）；
• references/source-hierarchy.md 中的来源层级和验证要求（粘贴层级列表及全部 7 条规则——包括规则 7：关键主张必须能追溯到第 1–3 级来源，绝不能依赖博客或问答网站）；
• 要求严格按以下格式返回：(1) 核心观点，用 2 句话说明；(2) 最有力的证据，列出 3–5 条，每条都包含具体数据点、原始来源 URL，以及该主张适用的版本／日期；(3) 只有此视角会提出的一点。少于 400 词。只使用实际抓取到的来源——不得编造研究、数字或 URL。

每个视角返回结果后，立即将其简报追加到工作暂存文件 software-research-reports/{topic-slug}.work.md 中，并置于 ## Lens: <name> 标题下（现在就创建该文件）。简报一到就写入，可确保即使运行中途崩溃也不会丢失内容——之后可从磁盘上的现有内容继续运行。在文件顶部设置运行状态块：stepsCompleted: [0, 1]。

全部返回后，在聊天中发送 2–3 行说明：各方观点的趋同之处，以及最明显的分歧。不要在聊天中粘贴原始简报。

❌ 常见失败：

• 将博客、SO 回答或模型记忆当作证据，而不是进一步查找其背后的原始来源（规则 3 和规则 7）。博客可以帮助找到事实；原始来源才是事实本身。
• 提出没有版本信息的主张，并将其说成当前事实——例如“X 会执行 Y”，却未注明版本，则该主张未经验证（规则 1）。
• 在其他视角尚未返回前，就让某个声音较大的视角主导叙述；请等待所有 N 个视角都返回。

阶段 2：梳理矛盾（内联，不使用 Agent）

仅根据简报，确定：

1. 直接冲突 — 列出具体相互矛盾的主张。
2. 最强与最弱的证据 — 按来源级别排序（Tier 1 一手资料／规范 > Tier 2 安全／聚合平台 > Tier 3 注册表 > Tier 4 基准测试 > Tier 5 调查）。
3. 用于解决问题的问题 — 能解决最大冲突的那项单一实证测试。
4. 普遍共识 — 每个视角都确认了什么（承重性发现）。
5. 盲点 — 没有任何视角涉及的内容（缺少第 6 个视角 → 前沿问题）。

将这份梳理附加到临时文件中的 ## Contradiction map 下，并将 运行状态更新为 stepsCompleted: [0, 1, 2]。这份梳理是综合报告的原始材料，不是单独的交付成果。

阶段 3：综合输出

从 data/modes.csv 中读取模式的 primary_output 和 secondary_output。

编写任何输出之前，先加载 references/report-structure.md。 它定义了 具体性要求（具体优于泛泛：准确版本、真实命令／配置／ 代码、真实数字，并且与读者的技术栈相关——以及禁止使用的空洞套话）和 12 节深度主干结构。细节不是可有可无的填充：报告的篇幅应来自其实用性以及与读者实际情况的关联，而非对主题的泛泛综述。

• 对于 html：克隆 assets/briefing-template.html；不要重建 CSS。 填写每一个 {{TOKEN}}。它分为两层：(a) 顶部的快速浏览层—— 结论评分板、关键发现，以及（针对选项比较模式）并列对照表——让读者五秒内抓住答案；然后是 (b) 承载完整主干内容的 12 节深度正文（第 06–16 节）。按照具体性要求填写深度章节；使用组件呈现比较、数字和流程，不要用文字叙述。
• 对于 md：遵循 references/report-structure.md 的完整 12 节主干结构—— 引言／方法、全貌、实现指南、技术栈、集成、性能、安全、 建议、路线图、风险、方法，以及最后的参考资料附录。这是详细报告；每一节都要具体。在 参考资料附录中，每个来源都必须是可点击的 [标题 — 版本／日期](url) Markdown 链接（表格单元格中不要只放裸 URL——它们无法可靠地呈现为链接）。
• 对于 adr：克隆 assets/adr-template.md；填写 MADR 各章节（背景、 决策驱动因素、考虑过的选项、决策结果、后果、各选项的优缺点、更多信息）以及最后的参考资料 章节。记录被拒绝的选项及原因。ADR 应保持精简，作为决策记录——不采用 12 节主干结构—— 但仍须遵循具体性要求（注明版本、引用具体信息）。

为忙碌的工程师写作，而不是为学术期刊写作。 使用短句和简单的词，开门见山。遇到无法避免的术语，要在文中直接解释。如果读者需要查词典才能理解某条发现，就重写。

只有在有助于表达时才添加可视化内容。 assets/widgets/ 中有约 45 个可直接嵌入、零依赖的可视化组件（内联 SVG／CSS／少量原生 JavaScript）。阅读 assets/widgets/README.md——其中按用途分类列出了完整目录（比较与决策、数字与证据、解释工作原理、按时间顺序、组织与管理、行内点缀），并提供了编号的“选择哪种可视化”决策顺序。根据内容选择，而不是追求新奇；复制文件并替换其中的 FILL: 标记。几个常用组件：comparison-matrix（选项 × 标准）、 weighted-decision-matrix（ADR 评分）、metric-bars（基准测试／成本／规模）、 evidence-confidence（逐条发现的可信度）、callout（注意事项／警告）、 verdict-card（建议），以及 slider-metric（唯一的交互式“拖动”组件——每份报告最多使用一个）。 优先使用零依赖小组件：它们能即时渲染、离线运行、支持打印，也不会因 CDN 故障或运行时握手失败而显示空白。对于任何树形图、图形或示意图，小组件都使用手动放置的坐标——不要自动布局。只有在定制 SVG 不擅长的场景下才使用库：更适合用文本编写的标准流程图／时序图／ER 图 → Mermaid（固定版本，securityLevel:'strict'）；大规模真实定量数据 → Chart.js；需要语法着色的代码片段 → code-compare（它会加载固定版本并带 SRI 的 highlight.js——每份报告只需包含一次该代码块，并为每个代码片段设置 class="language-…"）。然后固定版本，并优先使用 SRI／内联，而不是裸用 CDN <script>。如果让模型生成任意小组件 JS，而不是填充模板，请将其放入沙盒（iframe 使用 sandbox="allow-scripts"，不加 allow-same-origin，CSP 阻止 connect-src）——生成的标记是不可信代码，且运行于报告的源；SRI 在此无济于事。完整规则见 assets/widgets/README.md。

将输出写入 software-research-reports/（如有必要请创建该目录）：

• HTML → {topic-slug}-briefing.html
• MD → {topic-slug}.md；ADR → ADR-{topic-slug}.md

❌ 此处常见的失败方式：

• 把建议埋在大段文字里——设置评分板和 Bottom Line，就是为了让读者先看到答案，再看细节。
• 使用学术化／晦涩的措辞，看似巧妙却没有传达信息。
• 对于 X 与 Y 的对比问题，省略对比表（读者需要并排比较）。

阶段 4：对抗性验证（必须）

关卡 2 — 验证前确认发现（暂停一次）。 综合整理好草稿后，在聊天中发布一份简明清单：建议、3–5 项关键发现，以及哪些主张是关键依据（建议依赖这些主张）。请用户确认这组发现／指出需要重点审查的内容。这是投入验证 Agent 前最后一次低成本调整方向的机会。然后运行 4a–4c。

verify_depth 来自 data/modes.csv（full = 每条引文；load-bearing = 建议所依赖的主张——仍为必做项）。

4a. 自我审查（内联）。 按可靠性（依据来源等级，而非置信度）为每项发现打 1–10 分，并说明理由。指出最薄弱的一环，以及如何验证它。进行偏见检查：哪种视角占主导？哪些内容的权重不足？说出缺失的第 6 种视角。给出诚实的总体评级。

4b. 验证引文（并行 Agent）。 在一条消息中启动 general-purpose Agent，每个引文簇（约 4–6 条）对应一个 Agent。每条提示词都应要求：根据其主要来源独立验证主张，并应用 references/source-hierarchy.md 中的全部 7 条规则（绑定版本；检查当前版本是否有效；追溯至主要来源；标注日期；通过 OSV/GHSA 和版本范围核查安全性；基准测试须有可复现的方法；关键依据主张必须达到第 1–3 级）。返回 VERDICT = CONFIRMED / PARTIALLY CONFIRMED（列出更正内容）/ UNVERIFIED / FALSE / VERSION-STALE / UNVERIFIED-LOWTIER（仅由第 5–6 级来源支持的关键依据主张——未找到主要来源）、更正后的一行引文（含版本和日期），以及 2–4 条具体信息和主要来源 URL。少于 280 个词。

4c. 应用更正。 更正错误的数字／标题／日期／版本。证据薄弱时下调置信度；将有争议、预印本、版本过时以及 UNVERIFIED-LOWTIER 的主张移至争议侧栏（缺少主要来源支持的关键依据主张不得作为发现保留）。填写验证横幅（已核查 N 项 · 更正 X 项 · 降级 Y 项 · 版本过时 Z 项）和每条引文的状态标签。填写主张安全指南（可断言／需加限定／应避免）、版本时效说明，并确认每个来源都出现在参考资料部分。将运行状态更新为 stepsCompleted: [0, 1, 2, 3, 4]。

❌ 此处常见的失败：

• 因为发现“看起来合理”就跳过验证——看似合理但实际错误，正是 LLM 小组会给出的结果；验证者就是防护措施。
• 在主要发现中保留仅有博客／Stack Overflow 答案支持的关键依据主张，而不将其降级（规则 7 → UNVERIFIED-LOWTIER）。
• 验证者凭记忆“确认”，而不是获取主要来源。

输出

1. 交付物：验证后的 HTML + MD/ADR，存放于 software-research-reports/。
2. 使用平台打开器打开 HTML：macOS open <path>、Linux xdg-open <path>、Windows start "" <path>。如果无法确定，请打印路径。
3. 聊天摘要：文件路径；验证统计；一项普遍发现；建议及其关键依据主张；前沿问题；主张安全摘要（可安全断言 vs 应避免）。内容简明。

注意事项与防护措施

• 必须进行网络搜索。 各个视角和核验器都依赖获取实时的一手来源。如果 Agent 内无法进行网络搜索或抓取，请中止并告知用户——切勿仅凭训练数据回答涉及版本或安全的软件问题；模型的记忆属于第 6 级，且会过时。
• 只做真实研究。 每个视角和引文都必须追溯到真实抓取的一手来源，并标明版本或日期。若某个数据无法核实，应降低其重要性或删除；绝不要掩盖问题。
• 优先采用官方文档，而非问答内容。 关键论断必须能追溯到第 1–3 级来源（官方文档／规范、安全数据库、注册表）。博客、Stack Overflow、Medium 和模型记忆只能作为寻找一手来源的线索，不能单独作为证据。
• 具体实用，杜绝泛泛而谈。 写明确切版本；展示真实命令／配置／代码；使用真实数据；让每条建议都与读者的技术栈、团队和规模相关。删除任何只描述类别而不陈述事实的句子（“为……提供强大的支持”“广泛使用”“有助于提升性能……”）。如果一句话不会改变读者的做法，就删除它。完整规范和正反示例见 references/report-structure.md。
• 工作文件。 {topic-slug}.work.md 保存各视角的简报和矛盾映射，便于后续继续处理；它是工作产物，不是交付物。请保留该文件（恢复处理或重新运行时可以复用）；交付物为 HTML／MD／ADR。
• 关注版本。 只有写成“……在版本 N 中”时，“X 执行 Y”才有效。标记已弃用或版本过时的论断；切勿将过时信息说成当前情况。
• 评审小组由作者组建。 请披露这一点。各视角达成一致只是有力的假设，并不代表业内共识。
• 可靠性 = 来源等级所体现的证据质量，而非信心程度。
• 成本。 每次运行约需 9–12 个 Agent（各视角加核验器）。这是预期情况。不要超出当前模式的视角数量，也不要为每个引文簇配置超过一个核验器。
• 设计。 HTML 模板的 CSS 保持原样（纯白背景、Montserrat／Roboto Mono、蓝色强调色）。