research-it

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Research It

调研技能（Research It）

Replace vibes with evidence: what exists, what fits this repo, what to do next.

用实证代替主观判断：现有哪些方案、哪些适合本仓库、下一步该做什么。

Operating contract

操作契约

Shared by every DecisionNerd/dev-skills skill. Canonical copy:

handbook/concepts/14-operating-contract.md

Define done first. Before using tools, write the finish line in one or two lines: the acceptance criteria (existing issue AC, BDD scenarios, tests, or contract when they exist; otherwise propose them and say where they should live) and the evidence that will prove them. Re-check it before reporting done. Never report done on work you did not verify.
Requested scope sets the finish line. A question ("is it ready?", "why is it broken?", "what next?") ends with the answer and a
```
Next:
```
line naming the exact next invoke. An outcome request ("fix", "finish", "land", "#42") continues through the chain (diagnose → fix → test → check-readiness → merge-it) until the outcome or a real blocker. Do not end a turn with "Do you want me to…?" for in-scope, in-repo work.
Stop only for real blockers. Stop and ask only when you cannot continue without the user, or before: deleting data or unmerged work, force-push or history rewrite, changing anything outside this repository (GitHub objects, deployments, live data, production or paid resources, external services), or leaving the requested scope, unless the user's request already named that exact action. Keep the harness's permission prompts for risky commands. Otherwise keep going and put status notes in the same message as the next action.
Ask well, once. For a genuine question use the harness's structured question tool when it has one (Claude Code:
```
AskUserQuestion
```
; Codex:
```
request_user_input
```
when the current mode supports it) with concrete options; otherwise plain text with numbered options. Treat the answer as settled; do not re-open earlier verdicts, plans, or answers unless asked.
Fan out when work is parallel. Use subagents for independent reads (repo survey, evidence gathering, per-option research, per-area audits) and for independent verification (a reviewer that did not write the change). Writes stay single-owner per path set and sequential. Brief every child with goal, done-when, constraints, must-not, and return shape; verify each child's result before consolidating. Use Claude Code's
```
Workflow
```
tool only for orchestration across many subagents that truly needs it; it is expensive.
Pick the model tier per child; defer to routing config. If the harness or user config already routes subagents (Claude Code
```
CLAUDE_CODE_SUBAGENT_MODEL
```
or a CLAUDE.md rule; Codex
```
agents.default_subagent_model
```
or a role's
```
agents.<name>.config_file
```
; Cursor a custom subagent's
```
model:
```
frontmatter), follow it and do not pass a model. Otherwise: mechanical search or inventory → fast/cheap (Claude Code
```
haiku
```
); implementation and evidence gathering → mid (
```
sonnet
```
); planning, review, adversarial verification → top (
```
opus
```
or
```
fable
```
). In Claude Code set it with the
```
Agent
```
tool
```
model
```
param or agent frontmatter
```
model:
```
; in Codex pass a spawn model or set
```
model
```
in the role's config file; in Cursor set
```
model:
```
(default
```
inherit
```
) in
```
.cursor/agents/*.md
```
. Where the harness cannot choose, children inherit the parent model or the harness picks one (Cursor's built-in Explore/Bash/Browser subagents pick per subtask); say which in the status note.
Keep a checklist on long runs. For more than about five steps or work that crosses skills, keep
```
TASKS.md
```
at the repo root and tick items as they finish. Do not commit it unless the repo already tracks one.
Close every run with three headings.
```
Blocked on me
```
(the one genuine question or blocker, else "none");
```
Changed
```
(files, commits, GitHub objects, deploys, else "nothing");
```
Found
```
(evidence, verdict, and
```
Next: <exact invoke>
```
).

所有DecisionNerd/dev-skills技能共享本契约。官方版本：

handbook/concepts/14-operating-contract.md

。

先定义完成标准。 在使用工具前，用一两行写下终点：验收标准（若存在现有issue的AC、BDD场景、测试或契约则直接使用；否则提出建议并说明应存放的位置）以及证明验收通过的证据。在报告完成前重新核对。绝不要对你未验证的工作报告完成。
请求的范围决定终点。 一个问题（「准备好了吗？」、「为什么坏了？」、「接下来做什么？」）以答案和一行
```
Next:
```
结束，其中明确指出下一步要调用的具体操作。结果类请求（「修复」、「完成」、「落地」、「#42」）会沿着流程链持续推进（诊断 → 修复 → 测试 → 就绪检查 → merge-it），直到达成结果或遇到真正的阻塞。对于范围内、仓库内的工作，不要在轮次结束时问「你想让我…吗？」。
仅因真正的阻塞而停止。 仅当你无法在没有用户的情况下继续，或在以下操作之前才停下并询问：删除数据或未合并的工作、强制推送或历史重写、修改此仓库之外的任何内容（GitHub对象、部署、实时数据、生产或付费资源、外部服务），或超出请求的范围——除非用户的请求已经明确指定了该操作。对于风险命令，保留工具的权限提示。除此之外持续推进，并在同一条消息中附上状态说明和下一步操作。
一次问清楚。 对于真正需要询问的问题，若工具有结构化提问功能（Claude Code：
```
AskUserQuestion
```
；Codex：当前模式支持时使用
```
request_user_input
```
），则使用该功能并提供具体选项；否则使用带编号选项的纯文本。将答案视为最终决定；不要重新开启之前的结论、计划或答案，除非被要求。
并行工作时拆分任务。 对于独立的读取类工作（仓库调研、证据收集、按选项的研究、按领域的审计）以及独立的验证工作（未编写变更的评审者），使用子Agent。写入类工作按路径集保持单一负责人，且顺序执行。向每个子Agent简要说明目标、完成条件、约束、禁止事项和返回格式；在合并结果前验证每个子Agent的输出。仅当需要协调大量子Agent时才使用Claude Code的
```
Workflow
```
工具；它的成本很高。
为每个子Agent选择模型等级；遵循路由配置。 如果工具或用户配置已经为子Agent配置了路由（Claude Code的
```
CLAUDE_CODE_SUBAGENT_MODEL
```
或CLAUDE.md规则；Codex的
```
agents.default_subagent_model
```
或角色的
```
agents.<name>.config_file
```
；Cursor自定义子Agent的
```
model:
```
frontmatter），则遵循该配置，不要传递模型参数。否则：机械搜索或盘点类工作 → 快速/低成本（Claude Code
```
haiku
```
）；实现和证据收集 → 中等（
```
sonnet
```
）；规划、评审、对抗性验证 → 顶级（
```
opus
```
或
```
fable
```
）。在Claude Code中通过
```
Agent
```
工具的
```
model
```
参数或Agent frontmatter的
```
model:
```
设置；在Codex中传递生成模型或在角色的配置文件中设置
```
model
```
；在Cursor中在
```
.cursor/agents/*.md
```
中设置
```
model:
```
（默认
```
inherit
```
）。当工具无法选择时，子Agent继承父模型或由工具选择（Cursor内置的Explore/Bash/Browser子Agent会根据子任务选择）；在状态说明中注明使用的模型。
长时间运行时保留检查清单。 对于超过约五个步骤或跨技能的工作，在仓库根目录保留
```
TASKS.md
```
，并在完成时勾选项目。除非仓库已经在跟踪该文件，否则不要提交它。
每次运行结束时包含三个标题。
```
Blocked on me
```
（我这边的阻塞项：一个真正的问题或阻塞，否则为「none」）；
```
Changed
```
（变更内容：文件、提交、GitHub对象、部署，否则为「nothing」）；
```
Found
```
（发现内容：证据、结论，以及
```
Next: <具体调用操作>
```
）。

When to use

适用场景

"What's the best way to…?", "research it", vendor/API comparison, spike before build
Ambiguous architecture choice before
```
recon issue
```
or
```
fix-it
```
Need external docs or in-repo prior art surveyed first

「最好的方法是什么？」、「research it」、供应商/API对比、构建前的技术预研
在
```
recon issue
```
或
```
fix-it
```
之前的模糊架构决策
需要先调研外部文档或仓库内已有实践的场景

Workflow

工作流程

Done when: one recommendation tied to this repo's constraints, rejected options listed, unknowns named with what a spike would prove.

Frame the question
- Decision to make, constraints (stack, latency, cost, compliance, timeline), success criteria.
Search inward then outward
- In-repo: existing packages, patterns, ADRs, prior PRs/issues.
- External: official docs (WebFetch), reputable references; note versions/dates.
- Don't treat random blogs as authority over primary docs.
Compare options
- 2–4 viable options max. Fan out one read-only subagent per option (mid tier) with a fixed criteria table as return shape: fit, complexity, ops burden, risk, lock-in. Mark every unconfirmed claim
```
unconfirmed
```
  with its source location.
- An adversarial reviewer subagent (top tier) attacks the leading recommendation before it is finalized.
- Prefer house defaults when unconstrained: React + Next on Vercel for web; Pulumi ESC + OIDC for secrets; Langfuse for LLM obs/evals — unless the repo already standardized elsewhere.
- Call out unknowns and what a spike would prove.
Recommend
- One primary recommendation with rationale tied to this repo's constraints.
- Explicit non-goals / rejected options with why.
Next steps
- Next:
```
issues create
```
  /
```
recon issue
```
  /
```
fix-it
```
  to plan or track; a time-boxed spike checklist when unknowns remain.
- Spikes and dependency adds are a separate, asked-for step — express them as a
```
Next:
```
  statement, not a question.

完成标准：给出一个结合本仓库约束的建议，列出被否决的选项，明确未知项以及spike可验证的内容。

界定问题
- 要做的决策、约束条件（技术栈、延迟、成本、合规、时间线）、成功标准。
由内向外搜索
- 仓库内部：现有包、设计模式、ADR、历史PR/issue。
- 外部资源：官方文档（WebFetch）、可信参考资料；注明版本/日期。
- 不要将随机博客的内容视为比官方文档更权威的依据。
方案对比
- 最多选取2-4个可行方案。为每个方案分配一个只读子Agent（中等模型等级），要求返回固定格式的标准表格：适配度、复杂度、运维负担、风险、锁定程度。每个未确认的主张都需标记为
```
unconfirmed
```
  并注明来源位置。
- 安排一个对抗性评审子Agent（顶级模型等级），在最终确定前对主要建议进行质疑验证。
- 无特殊约束时优先使用内部默认方案：Web端采用Vercel部署的React + Next；密钥管理使用Pulumi ESC + OIDC；LLM可观测性/评估使用Langfuse——除非仓库已有其他标准化选型。
- 明确指出未知项，以及spike能够验证的内容。
给出建议
- 一个主要建议，其理由需与本仓库的约束条件紧密相关。
- 明确列出非目标/被否决的选项及原因。
后续步骤
- 下一步：通过
```
issues create
```
  /
```
recon issue
```
  /
```
fix-it
```
  进行规划或跟踪；若仍有未知项，给出时间限定的spike检查清单。
- spike和添加依赖是需单独申请的步骤——需将其表述为
```
Next:
```
  语句，而非疑问句。

Guardrails

护栏规则

Read-only unless the user asks to spike code or add a dep.
Cite sources (URLs/paths). Distinguish fact vs inference.
No secret keys in research notes.

除非用户要求编写spike代码或添加依赖，否则保持只读模式。
引用来源（URL/文件路径）。区分事实与推断。
研究笔记中不得包含密钥。

Output

输出格式

markdown

**Question**
- ...

**Constraints**
- ...

**Options**
| Option | Fit | Cost/complexity | Risk | Notes |
| ... |

**Recommendation**
- Primary: ...
- Why: ...
- Rejected: ...

**Open questions / spike**
- ...

markdown

**Question**
- ...

**Constraints**
- ...

**Options**
| Option | Fit | Cost/complexity | Risk | Notes |
| ... |

**Recommendation**
- Primary: ...
- Why: ...
- Rejected: ...

**Open questions / spike**
- ...

Blocked on me

none

Changed

nothing

Found

...
Next: issues create / recon issue / fix-it

undefined

...
Next: issues create / recon issue / fix-it

undefined

Grounding

理论基础

This skill's TTPs are grounded in current engineering baselines (DORA, GitHub Docs, Fowler/Beck, Google SRE & SWE book, OpenTelemetry, OWASP LLM / NIST AI RMF, Diátaxis — see handbook

sources.md

Evidence before commitment; avoid jumping to complex systems before a simple one works (Gall's Law / Beck). Prefer house defaults only when the repo has no stronger local constraint (

handbook/concepts/11-quality-regimes.md

for generative tooling;

repos

for ESC).

Handbook card:

handbook/practices/research-it.md

本技能的TTPs基于当前行业工程基准（DORA、GitHub Docs、Fowler/Beck、Google SRE & SWE 书籍、OpenTelemetry、OWASP LLM / NIST AI RMF、Diátaxis —— 详见手册

sources.md

）。

先有实证再做承诺；在简单方案可行前，不要贸然采用复杂系统（Gall's Law / Beck）。仅当仓库没有更强的本地约束时，才优先使用内部默认方案（生成式工具的约束规范见

handbook/concepts/11-quality-regimes.md

；ESC相关配置见

repos

）。

手册卡片：

handbook/practices/research-it.md

。