在工程实现新功能前或审计埋点时…

为产品与工程之间建立分析埋点契约，明确追踪哪些事件、何时触发、带哪些属性，防止漏埋或埋点不一致。

适用场景

解决思路

1. 定义分析目标：先列出需要回答的问题、要测量的内容以及这些数据将支持哪些决策，以避免过度埋点同时确保不遗漏关键项。
2. 识别要追踪的事件：列出每个应被追踪的用户行为或系统事件，遵循一致的命名约定（通常为 snake_case 的 noun_verb 或 verb_noun），每个事件应代表一个独立且有意义的动作。
3. 明确事件触发时机：为每个事件精确描述其触发条件，例如区分「用户点击 Submit 按钮时」与「表单成功提交时」，二者是含义不同的两个事件。
4. 定义事件属性：列出附加到每个事件的属性，包含属性名、数据类型、描述和示例值，属性提供让事件有用的上下文。
5. 记录用户属性：识别应关联到所有事件的持久性用户级属性（如订阅层级、账号创建日期），以便在分析中做分群。
6. 处理 PII 与隐私：标记任何包含个人身份信息的属性，并记录 PII 的处理方式——哈希、加密或排除。当捕获任何模型输入、输出、检索上下文或工具调用时，将本节扩展到 trace：触发条件是「捕获」而非「编写」，无论敏感文本来自用户输入、租户文档检索、系统提示、工具参数与返回、上传文件或批处理作业读取，还是模型自身生成，都适用；即使功能没有直接用户输入，也可能把客户合同文本写入 trace 存储。trace 不是 event：event 携带你预先选定的属性，而 trace 携带可包含任何内容的自由文本，包括属性 schema 未预料到的数据。需决定并记录：捕获的数据类别（明确命名：用户文本、检索文档、系统提示、工具参数与结果、文件内容、模型输出，「trace」本身不是答案）；两个边界上的最小化（在 trace 离开进程之前丢弃或脱敏什么，以及在存储之前丢弃什么；仅在存储层运行的脱敏器已经让原始文本上了网络）；访问权限（谁能读取 trace，读取是否被记录；trace 存储通常是功能处理的最敏感数据中治理最差的副本）；保留与删除（保留多久、由什么删除、删除请求如何触达已被复制进评估集的 trace）；同意与退出（数据主体是否同意，以及其拒绝时功能如何处理）；采样（捕获比例及样本选择方式；均匀采样不适合发现罕见失败，若 trace 用于诊断不良输出，应对被标记案例过采样并说明）。
7. 创建测试清单：定义 QA 如何验证埋点实现正确，包括验证事件在正确时机以正确属性触发的步骤。
8. 使用 references/TEMPLATE.md 中的模板组织输出，完整规格需填写模板的每个部分：Overview、Event Inventory、User Properties、PII & Privacy Considerations、Implementation Notes 和 Testing Checklist。
9. 定稿前按质量清单核验：事件名遵循一致命名约定；每个事件有清晰无歧义的触发条件；属性包含数据类型和示例值；PII 已识别并记录处理方式；事件映射到需要回答的分析问题；测试清单支持 QA 验证；若捕获任何模型输入、输出、检索上下文或工具调用，则数据类别已命名，出口与存储两个边界的最小化、访问与读取日志、保留与删除、同意、采样均已决定而非推迟。

适用边界 · 注意事项

• 你要指定的是基于这些事件构建的仪表盘，应使用 measure-dashboard-requirements
• 你需要的是实验专属指标与变体而非产品级追踪，应使用 measure-experiment-design
• 功能本身尚未定义（没有可埋点的流程），应先使用 deliver-prd
• 你要分析已经收集的数据，应使用 measure-experiment-results 或 measure-survey-analysis