observability-design
Skill2 starsChanged 39 days agoMITView on GitHub
可观测性设计规范:功能与插桩同步交付、埋点前先写 on-call 问题、metrics/trace/log 三信号分工、结构化日志、AI 变更挂 gen_ai 元数据与前后对照指标。大量 AI 代码下人类把控的第三道闸门(上线后可回放)。
7 other projects use a version of this.
Adopted by
Most recently taken up by
- l-gevity/l-gevity-skillstheir own version, first seen Nov 14, 2026
- anuragsarkar97/skillstheir own version, first seen Nov 8, 2026
- SWEStash/swe-workflow-skillstheir own version, first seen Nov 8, 2026
- bingyue/fde-skillstheir own version, first seen Oct 13, 2026
- hemapriyan-rk/claude-rigor-skillstheir own version, first seen Sep 26, 2026
- zhuochun/skillstheir own version, first seen Jul 21, 2026
Other versions7 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 7
- l-gevity/l-gevity-skills★ 88same name
- bingyue/fde-skills★ 5same name
- hemapriyan-rk/claude-rigor-skills★ 1same name
- SWEStash/swe-workflow-skills★ 1same name
- zhuochun/skills★ 1same name
- anuragsarkar97/skills★ 0same name
- gclm/super-stack★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository40 other files it gives its agents.
- admin-credential-bootstrapSkill
- ai-code-review-gateSkill
- ai-debt-ledgerSkill
- android-camera-devSkill
- android-device-debuggingSkill
- arch-dev-workflowSkill
- askills-syncSkill
- async-job-sse-upload-devSkill
- branching-workflowSkill
- disk-capacity-guardSkill
- edge-offline-pipeline-devSkill
- frontend-dev-workflowSkill
- github-ci-releaseSkill
- git-identitySkill
- installer-bundle-designSkill
- installer-preflightSkill
- installer-target-executionSkill
- mqtt-device-gateway-devSkill
- ohos-media-devSkill
- onvif-rtsp-devSkill
- open-source-contributionSkill
- patent-applicationSkill
- patent-chartSkill
- patent-disclosureSkill
- patent-docketSkill
- patent-exam-policySkill
- patent-mapSkill
- patent-oaSkill
- patent-readerSkill
- patent-searchSkill
- project-brandingSkill
- redis-stream-rpcSkill
- robot-camerasSkill
- skill-distillationSkill
- skill-refreshSkill
- solution-racingSkill
- subagent-parallel-devSkill
- ui-responsive-listSkill
- user-facing-errorsSkill
- web-launch-dxSkill
The file
Files
可观测性设计规范
核心原则:无法观测的代码就是无法运维的代码。AI 时代代码产出速度远超人的理解速度,把握控力从"读完全部代码"转移到"系统行为可回放"——这是合并评审之后的人类第三道闸门。Google 的生产级 AI 代码质量研究正是靠"每行上线代码可观测"才完成的。
1. 插桩同步交付
- 新功能的插桩(日志/指标/追踪)与功能代码同一个 PR 交付,像测试一样对待——"以后补埋点"等于没有。
- 改造存量功能时,本次触及的链路至少补齐出入口日志与一个健康指标,不做全量翻新。
2. 先写问题,再写埋点
- 动手埋点前,先写下 on-call 工程师半夜被叫醒时会问的 2-4 个问题(如"上传为什么卡住""设备掉线了吗""这条命令发出去没有")。
- 每个信号必须能回答其中之一;答不任何问题的埋点删掉——为埋而埋的信号只会稀释真正的告警。
- 用户报障路径必须有对应观测面:每个对外错误码都能在日志里搜到(与 user-facing-errors 的
[CODE] cause可搜索前缀打通)。
3. 三信号分工
| 信号 | 回答的问题 | 用法 |
| metric | 出事了(that) | 聚合数值 + 阈值告警:速率、错误率、时延、队列深度;告警必须是可行动的 |
| trace | 在哪(where) | 请求/任务 ID 贯穿跨进程调用链,出入口 span 必带耗时与结果 |
| log | 为什么(why) | 事件明细,供回放与归因 |
- 跨服务调用必须传递 request id / trace id,否则排查时只能对时间戳猜。
- 告警风暴治理:同源告警聚合、边沿触发(见 edge-offline-pipeline-dev 的告警状态机)。
4. 结构化日志
- 事件用稳定事件名 + 键值字段,不用自然语言插值:
upload_retry file=x attempt=3 wait=30s而非retrying upload for x after failure——前者可 grep 可聚合。 - 分级沿用 arch-dev-workflow 的日志分层:stdout 分级(高频 debug)、关键链路出入口必须 info、持久化业务/审计日志分离。
- 禁止把高频循环内的明细打 info;禁止无字段纯文本日志进关键路径。
- 技术根因只进日志,用户只见错误码+提示(user-facing-errors);脱敏与留痕是同一件事的两面。
5. AI 变更的可观测
- AI 参与的批量改动挂元数据:遵循 OpenTelemetry GenAI 语义约定(
gen_ai.*:模型、请求/响应 token、工具调用),使"哪次行为由哪个模型在什么上下文产生"与系统运行指标在同一条 trace 可关联;无 OTel 设施时至少在审计日志里记(模型/工具、任务摘要、时间、变更范围)。 - 前后对照指标:AI 大批量改动合并后,对该区域建立前后对照——回滚率、事故/告警增量、性能(CPU/内存/时延)、静态分析新增告警数;连续观察一个周期,异常即触发复查。
- agent 自身的执行行为同样可观测:任务耗时、返工次数、验证失败的改动占比——用结果指标而非体感评估 AI 工作流(人对 AI 增益的自评系统性失真,METR RCT 实测自评 +20% 而实际 -19%)。
6. 检查清单(功能上线前)
- 出入口都有日志且带 trace/request id?
- 失败路径有日志(不只是成功路径)?
- 每个对外错误码都能在日志中搜到现场?
- 至少一个健康指标 + 可行动的告警阈值?
- 埋点能回答写下的那 2-4 个 on-call 问题?
- AI 批量改动的区域已纳入前后对照观察?
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

