observe-it

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Observe It

Observe It 可观测性建设

Make important behavior visible in production without drowning in noise or leaking sensitive data.

Match signals to the quality regime (handbook

concepts/11-quality-regimes.md

Regime	Observe…
A — Deterministic compute	Golden signals + (for pipelines) freshness/coverage/correctness
B — Interactive product	Errors + RUM / Core Web Vitals + critical funnel events
C — Generative / high-input	Hierarchical LLM/tool/retrieval traces + quality scores / user feedback. House default: Langfuse (OTel-friendly) unless the repo already standardized elsewhere

让重要行为在生产环境中可见，同时避免被噪声淹没或泄露敏感数据。

将观测信号与质量体系匹配（手册

concepts/11-quality-regimes.md

）：

体系	观测内容
A — 确定性计算	黄金信号 + （流水线场景）新鲜度/覆盖率/正确性
B — 交互产品	错误 + RUM / Core Web Vitals + 关键漏斗事件
C — 生成式/高输入	分层 LLM/工具/检索链路追踪 + 质量评分 / 用户反馈。内部默认使用 Langfuse（兼容 OTel），除非仓库已有其他标准

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」）需要贯穿整个链路（诊断 → 修复 → 测试 → 就绪检查 → 合并）直到达成结果或遇到真正的阻塞。对于范围内、属于本仓库的工作，不要在回合结束时问「你需要我做…吗？」。
仅遇真阻塞才停止。 只有在无法继续且必须用户介入时，或者在执行以下操作前才停下询问：删除数据或未合并的工作、强制推送或改写历史、修改本仓库之外的任何内容（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:
```
前置元数据），则遵循该配置，不要额外指定模型。否则：机械搜索或盘点类任务 → 快速/低成本模型（Claude Code
```
haiku
```
）；实现和证据收集类任务 → 中等模型（
```
sonnet
```
）；规划、评审、对抗性验证 → 顶级模型（
```
opus
```
或
```
fable
```
）。在 Claude Code 中通过
```
Agent
```
工具的
```
model
```
参数或Agent前置元数据的
```
model:
```
字段设置；在 Codex 中传入生成模型或在角色配置文件中设置
```
model
```
；在 Cursor 中在
```
.cursor/agents/*.md
```
里设置
```
model:
```
（默认
```
inherit
```
）。如果执行框架无法选择模型，子Agent将继承父Agent的模型，或由执行框架选择（Cursor 内置的 Explore/Bash/Browser 子Agent会根据子任务选择）；请在状态说明中注明使用的模型。
长流程保留检查清单。 如果步骤超过约五步，或者工作涉及多个技能，在仓库根目录创建
```
TASKS.md
```
并在完成时勾选条目。除非仓库已经在跟踪该文件，否则不要提交它。
每次运行结束需包含三个标题。
```
Blocked on me
```
（我侧阻塞：真正的问题或阻塞项，没有则写「none」）；
```
Changed
```
（变更内容：文件、提交、GitHub 对象、部署等，没有则写「nothing」）；
```
Found
```
（发现内容：证据、结论，以及
```
Next: <具体调用技能>
```
）。

When to use

适用场景

"Add logging/metrics/tracing", "observe it", "how do we detect this failing?", "add Langfuse/evals online"

After

diagnose-bug

troubleshoot-app

agents analyze

when the root cause was invisible

Before
```
merge-it
```
Stage/Ship phases when release risk needs signals

「Add logging/metrics/tracing」、「observe it」、「how do we detect this failing?」、「add Langfuse/evals online」
在
```
diagnose-bug
```
/
```
troubleshoot-app
```
/
```
agents analyze
```
之后，发现根本原因无法被现有观测覆盖时
在
```
merge-it
```
的预发布/发布阶段，需要观测信号来评估发布风险时

When NOT to use

不适用场景

Fixing a known bug without needing new signals →
```
fix-it
```
/
```
diagnose-bug
```
Proving behavior in CI →
```
test-it
```
(obs complements tests; does not replace them)
Designing the agent itself →
```
agents design|optimize
```

修复已知bug且不需要新增观测信号 →
```
fix-it
```
/
```
diagnose-bug
```
在 CI 中验证行为 →
```
test-it
```
（可观测性是测试的补充，而非替代）
设计Agent本身 →
```
agents design|optimize
```

Workflow

工作流程

Done when: each named question is answerable from an emitted signal verified locally or in staging.

Name the regime and the questions ops/product must answer
- e.g. success rate, latency, auth denials, queue lag, LCP regression, eval score drift, funnel drop-off.
Discover existing stack
- Read docs,
```
.env*
```
  names, SDK imports, dashboards, alert rules, Langfuse/OTel exporters.
- Reuse current logger/tracer/metrics/analytics/eval plane — don't add a second system.
Instrument the smallest useful surface
- Logs: structured fields, correlation/request/job/trace IDs, error cause chains.
- Metrics: counters/histograms with low-cardinality labels.
- Traces: spans on external calls and critical path; for C, model + tool + retrieval spans.
- Scores (C): user feedback, heuristic, or judge scores attached to traces/sessions.
- Analytics: product events only when product already uses that bus.
- Errors: report unexpected failures to the existing error tracker.
Privacy & volume
- No secrets, tokens, raw PII, or full prompts/payloads in default logs.
- Avoid high-cardinality labels (user id as metric label).
- Sample or rate-limit chatty paths.
- Ask before changing production alert thresholds or creating paid vendor resources (legitimate gate: use the question tool with options).
Verify
- Local or staging: emit a signal and confirm it shows where expected (or document why it can't).
- Note dashboard/query stubs if the repo keeps them.
Wrap up
- Next:
```
document-it
```
  for runbooks,
```
test-it
```
  for instrumentation/eval guards,
```
merge-it
```
  (Ship phase) when ready.

完成条件：每个指定的问题都能通过已输出的观测信号回答，且信号已在本地或预发环境验证通过。

确定体系类型，以及运维/产品必须回答的问题
- 例如：成功率、延迟、鉴权拒绝数、队列延迟、LCP 退化、评估评分漂移、漏斗流失率。
调研现有技术栈
- 阅读文档、
```
.env*
```
  配置项、SDK 导入、仪表盘、告警规则、Langfuse/OTel 导出器。
- 复用现有的日志/链路追踪/指标/分析/评估平台——不要新增第二套系统。
对最小可用范围进行埋点
- 日志：结构化字段、关联/请求/任务/追踪 ID、错误原因链。
- 指标：带低基数标签的计数器/直方图。
- 链路追踪：外部调用和关键路径的 span；对于 C 类体系，包含模型 + 工具 + 检索的 span。
- 评分（C 类）：附加到链路/会话上的用户反馈、启发式评分或裁判评分。
- 分析：仅当产品已经在使用该事件总线时才上报产品事件。
- 错误：将意外故障上报到现有的错误追踪系统。
隐私与流量控制
- 默认日志中不得包含密钥、令牌、原始 PII 或完整的提示词/载荷。
- 避免高基数标签（比如将用户 ID 作为指标标签）。
- 对高频路径进行采样或限流。
- 修改生产环境告警阈值或创建付费供应商资源前需先询问用户（合理管控流程：使用提问工具并给出选项）。
验证
- 本地或预发环境：触发一次信号上报，确认它出现在预期的位置（或记录无法验证的原因）。
- 如果仓库维护了仪表盘/查询存根，要记录下来。
收尾
- 下一步：需要运行手册则调用
```
document-it
```
  ，需要埋点/评估防护则调用
```
test-it
```
  ，准备就绪则调用
```
merge-it
```
  （发布阶段）。

Guardrails

注意事项

Observability is not a substitute for tests (
```
test-it
```
) or fixes (
```
fix-it
```
).
Don't "log everything"; prefer decision points and failure boundaries.

可观测性不能替代测试（
```
test-it
```
）或修复（
```
fix-it
```
）。
不要「记录所有日志」；优先覆盖决策点和故障边界。

Output

输出格式

markdown

**Questions we can now answer**
- ...

**Stack**
- ...

**Instrumentation**
- ...

**Privacy / cardinality notes**
- ...

**How to verify**
- ...

markdown

**Questions we can now answer**
- ...

**Stack**
- ...

**Instrumentation**
- ...

**Privacy / cardinality notes**
- ...

**How to verify**
- ...

Blocked on me

none

Changed

Found

...
Next: document-it (runbook) / test-it (guards) / merge-it

undefined

...
Next: document-it (runbook) / test-it (guards) / merge-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

Signals follow quality regimes (

handbook/concepts/11-quality-regimes.md

): SRE golden signals (+ pipeline SLIs) for compute; Web Vitals/RUM for products; LLM traces + scores (Langfuse / OTel) for generative. Watch cardinality and PII.

Handbook card:

handbook/practices/observe-it.md

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

sources.md

）。

观测信号遵循质量体系规范（

handbook/concepts/11-quality-regimes.md

）：计算类场景使用 SRE 黄金信号（+ 流水线 SLI）；产品类场景使用 Web Vitals/RUM；生成式场景使用 LLM 追踪 + 评分（Langfuse / OTel）。注意基数和 PII 问题。

手册卡片：

handbook/practices/observe-it.md