Opik 项目 Jira Ticket 创建全流程指南从信息收集到 HOW 注释的标准工作流【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm本文系统讲解 Opikcomet-llm仓库中 AI Agent 创建 Jira 工单的标准命令规范create-jira-ticket它定义了在OPIK项目中从对话式信息收集、Parent Epic 匹配、WHY/WHAT 描述结构、MCP 字段映射到创建后的状态流转与 HOW 注释发布的一整套可复用流程。读完本文你将掌握如何借助 Jira MCP 工具与AskUserQuestion交互在 OPIK 项目中产出一张结构合规、字段完整、可直接进入开发排期的标准工单并理解它与 work-on-jira-ticket、share-progress-in-jira 等相邻命令如何构成完整的“建单—开工—汇报”闭环。命令定位与前置条件create-jira-ticket是仓库 .agents/commands/comet/ 目录下的一组 Agent 命令之一服务于 Opik 开源 LLM 可观测平台的研发流程。其核心目标不是机械地调用创建接口而是在创建前把工单的“动机WHY”“范围WHAT”“实施要点HOW”三层次信息梳理清楚保证工单进入看板后任何开发者和 QA 都能独立理解并产出测试用例。执行该命令的前置条件Jira MCP 可用核心工具是mcp__Jira__home___jira_create_issue配套还有jira_get_sprints_from_board、jira_search、jira_get_issue、jira_transition_issue、jira_add_comment、jira_edit_comment。MCP 服务在 .agents/mcp.json 中通过mcp-atlassianuvx mcp-atlassian依赖.env.local中的环境变量接入。用户交互工具AskUserQuestion用于让用户以编号方式选择 Epic、确认 Pod 标签等。项目约定项目 Key 固定为OPIKSprint 从 board ID524查询并要求带Opik Sprint前缀。提示若 Jira MCP 未配置可参考 .agents/docs/ 下相关 MCP 文档并运行仓库根目录 Makefile 中的make cursorCursor或make claudeClaude CLI同步 Agent 配置后重试。第一步通过对话收集 8 项必填/可选信息创建前必须先收集以下信息缺一不可标注“可选”的除外#字段取值/格式说明1Summary/Title一句话标题必须自带[区域前缀]标题应独立传达WHAT不读描述也能明白工单做什么标题是 WHAT 的一行版二者范围必须一致2Issue TypeStory / Task / Bug / Epic四选一3PriorityLow / Medium / High / Highest四选一4Labels如frontend、backend、sdk、playground、traces、ux-improvement反映工作领域5Story PointsFibonacci 序列1、2、3、5、8、13用户未提供时基于范围与复杂度估算并提交确认估算达到 21 及以上时禁止创建应建议拆分为 2 张 ≤13 点的小工单6Sprintactive sprint 或 next sprint询问用户用jira_get_sprints_from_boardboard ID524查询按Opik Sprint前缀过滤7Due DateYYYY-MM-DD询问今天 / 明天 / 一周后 / 不设置按当前日期计算8Assignee可选用户名谁来做关键约束Story Points 上限估算 ≥21 意味着工单体量超出单点交付能力正确做法是帮助用户规划拆分而不是强行创建。这一约束直接保障了看板中每张工单的可交付性与可估算性。第二步Parent Epic 的确定逻辑Task/Story 必选规则规定每张 Task 或 Story 都必须挂载 Parent Epic按以下优先级判断用户显式指定如提示中给出“under OPIK-1234”直接使用。技术债自动归位当工单明显属于重构、清理、技术债偿还、移除 workaround 时自动使用OPIK-670Tech debt无需询问。否则帮用户选择用mcp__Jira__home___jira_search查询开放 EpicJQLproject OPIK AND issuetype Epic AND status ! Done ORDER BY updated DESC以表格呈现列为#编号、Key、Summary、Status根据工单描述推荐最合适的 Epic并提供兜底选项“Skip for now”跳过则创建无父级工单用AskUserQuestion让用户按编号选择。设置父级时通过additional_fields传入parent: OPIK-XXXX注意是纯字符串而非对象。更宏观的“季度战略 Epic”由独立的 create-initiative-epic 命令负责它从 Notion PRD 与 Figma 设计中综合生成与本命令形成“Epic 先行、子任务随后”的分工。第三步Assignee 的 Pod 标签规则选定 Assignee 后必须同步添加该成员所属的pod-name标签已知 Podpod-whale、pod-frontier、pod-andromeda、pod-air、pod-iberi。若已确定来自记忆、同领域历史工单或用户资料自动添加、不再询问。不确定时用AskUserQuestion让用户从上述列表选择并提供“Skip (no pod label)”兜底。未设置 Assignee 则跳过此步绝不添加 Pod 标签。同一工单最多只能有一个pod-*标签。该规则的价值在于看板可按 Pod 维度过滤负载、追踪团队工作分布同时避免重复/冲突标签污染统计。第四步描述结构——WHY / WHAT 分离HOW 另立注释这是整个规范中最核心的设计决策工单描述只包含 WHY 和 WHAT 两个部分实现细节HOW不进描述而是在建单后以独立 Jira 注释发布。三者的分工WHY回答“这张工单为什么存在”。阅读后读者应理解动机、要解决的问题、实现者容易遗漏的上下文。WHAT回答“要做什么”。描述粒度要使 QA 能据此推导测试用例验收标准Acceptance Criteria就放在这里。HOW独立注释低层实现线索可选、可能过时、刻意不具权威性。标题与 WHAT 必须一致草拟完描述后把标题和 WHAT 首句并排重读若两者描述的不是同一件事必须修正其一——WHAT 不得引入标题未承诺的范围标题也不得承诺 WHAT 未覆盖的内容。描述模板## WHY [Why this ticket needs to exist. The motivation, the problem being solved, the context the implementer would otherwise miss. 2-6 sentences usually. Long enough to be clear, short enough that a reviewer doesnt skim past it.] ## WHAT [High-level description of what needs to be implemented. Phrased so QA can derive test cases. Must describe the same thing the ticket title promises — title and WHAT are two views of the same scope. Avoid implementation specifics here — those belong in the HOW comment.] ### Functional Requirements (optional) [Include when the WHAT has more than a couple of distinct behaviors worth enumerating, or when the acceptance criteria alone wont carry the full picture for a reader. Skip for simple tickets where the WHAT prose already says everything.] - [What the system should DO] - [Another behavior] ### Non-Functional Requirements (optional) [Include when the ticket has performance, security, scalability, accessibility, or compatibility constraints that dont naturally fit in acceptance criteria. Skip when there are none worth calling out.] - [Performance / security / scalability / accessibility / compatibility constraint] ### Acceptance Criteria - [ ] [Criterion 1 — observable behavior or outcome] - [ ] [Criterion 2] - [ ] [Criterion 3] - [ ] No lint errors or TypeScript errors (if applicable) - [ ] Unit tests added (if applicable) - [ ] Documentation updated (if applicable) ### Out of Scope (optional) - [Things the reader might assume are in scope but arent]模板要点描述使用纯 Markdown##标题、-列表、反引号内联代码Jira 会渲染为真实格式验收标准用- [ ]复选框语法默认包含“无 lint/TS 错误”“补充单元测试”“更新文档”三项通用验收标准按实际适用性保留。第五步标准对话流程11 步命令将建单过程编排为一次结构化的对话询问“Whats this ticket about?一两句话——要发生什么、为什么”据此草拟WHY动机与WHAT高层描述 验收标准先展示草稿征求修改意见再继续。询问 Issue TypeStory/Task/Bug/Epic。询问 PriorityLow/Medium/High/Highest。询问 Labels如 frontend、backend、sdk。呈现Story Points 估算并请求确认或允许用户覆盖。Parent Epic若尚未确定非技术债、无显式指定搜索开放 Epic、呈现表格、推荐最佳匹配让用户选择或跳过。询问“加入active sprint还是next sprint”询问“设置 Due Date今天 / 明天 / 一周后 / 不设置”询问“是否分配给某人”若选定 Assignee确定其 Pod 并添加对应pod-name标签不确定则按已知 Pod 列表询问。注意第 2 步的节奏设计先给草稿、再继续避免在信息未对齐时就消耗后续步骤这与“标题与 WHAT 一致”的约束共同保证了最终描述的质量。第六步调用 Jira MCP 创建工单全部信息齐备后调用创建工具mcp__Jira__home___jira_create_issue( project_keyOPIK, summary[PREFIX] Title of the ticket, issue_typeStory|Task|Bug|Epic, description[Formatted description using template above], additional_fields{ priority: {name: Medium}, labels: [label1, label2], customfield_10028: fibonacci_number, customfield_10020: sprint_id, duedate: YYYY-MM-DD, parent: OPIK-670 // only for tech debt tickets without another epic } )Field Reference字段映射表字段MCP 传参关键细节Story Pointscustomfield_10028必须直接使用该 customfieldstory_points别名在创建时不生效Sprintcustomfield_10020传 sprint ID纯数字先经jira_get_sprints_from_boardboard524查询按Opik Sprint前缀过滤再按用户选择取 active 或 next sprintDue Dateduedate格式YYYY-MM-DD相对今天计算Parentparent: OPIK-XXX纯字符串而非对象这些字段名customfield_10028、customfield_10020是 Jira 实例级的定制字段 ID直接写死可避免别名在创建接口失效的问题——这是该规范沉淀下来的实战经验。第七步创建后的状态流转创建成功不代表结束还有两步收尾等待自动化短暂等待后用mcp__Jira__home___jira_get_issue检查状态Jira 自动化会把工单自动移入BACKLOG。询问是否进入 TO DO确认状态为 BACKLOG 后必须用AskUserQuestion工具而非内联文本询问“The ticket is now in Backlog. Would you like me to move it toTO DO?”若用户确认用mcp__Jira__home___jira_transition_issue执行流转。这一设计把“机器可做的”自动化入 Backlog与“需要人拍板的”是否立即进入开发队列分开避免 Agent 擅自改变工单在开发队列中的位置。第八步HOW 注释可选但讲究时机状态流转完成后判断是否发布 HOW 注释——HOW 放在 Jira 注释中而不是描述里。什么情况下值得发只有当存在“实现者仅靠 WHAT 和读代码无法获得”的实质内容时才发没有就跳过。缺失的 HOW 优于凑数的 HOW且 work-on-jira-ticket 命令能优雅处理无 HOW 的情况。值得写的内容包括实现者容易遗漏的稳定地标架构接缝、长期存在的服务类、应落地的正确包值得照搬而非重造代码库中已有模式可复用构件共享 record、既有 DAO、既有事件WHAT 表面看不出的约束如“workspace 作用域在 DAO 层强制”创建者不确定的开放问题——以问题而非决策的口吻提出。禁止包含分步实现清单与代码片段、重复的验收标准那是 WHAT 的职责、把可选设计包装成唯一选择应呈现权衡而非替实现者拍板、复述 WHAT 的长列表。长度服从实质两句话的真知灼见胜过十五行泛泛脚手架。如何发布用mcp__Jira__home___jira_add_commentbody 首行以# HOW开头纯 Markdown#、##、反引号、-会被 Jira 渲染为真实格式。示例假设工单为“新增实验批量删除端点”# HOW Pieces likely still relevant: - Traces and spans already have batch-delete endpoints — mirror that shape. - Shared BatchDelete record in com.comet.opik.api is reused by other batch endpoints. - Workspace scoping is enforced at the DAO layer across this area — keep that invariant. - Cascading deletes touch experiment_items; existing DAO code already handles that relationship. Open questions for the implementer: - Feedback scores: traces null them out on delete; do experiments need the same treatment? - Partial-failure semantics: 404 if any id is missing, or best-effort delete of valid ones?对已有工单重跑时的去重规则若对已有工单再次运行/comet:create-jira-ticket例如更新 HOW优先编辑旧 HOW 注释而非堆积新注释用jira_get_issuecomment_limit大于 0拉取评论找到 body 匹配^#\s*HOW\b大小写不敏感且author.email与当前认证用户一致的最新评论找到则jira_edit_comment更新未找到无旧 HOW或仅有他人发布的 HOW才jira_add_comment新增。作者校验至关重要jira_edit_comment在 MCP 层不强制所有权最终由 Jira 权限决定若不校验作者拥有 “Edit All Comments” 权限的用户可能覆盖队友的 HOW。Title 前缀规范Summary 必须按工作领域带前缀[FE]- 前端改动[BE]- 后端改动[SDK]- SDK 改动Python 或 TypeScript[DOCS]- 文档更新[INFRA]- 基础设施/DevOps 改动这一前缀体系与 git-workflow.mdc 中定义的提交信息规范[OPIK-1234] [BE] feat: ...完全同构——Jira Key 与组件前缀会一路贯穿到分支名、首条提交与 PR 标题保证从工单到代码合入的全程可追溯。确认输出工单 Key 必须以可点击链接展示创建成功后确认消息必须把工单 Key 渲染为可点击的 Markdown 链接[OPIK-{number}](https://comet-ml.atlassian.net/browse/OPIK-{number})例如工单 Key 为OPIK-5316时输出[OPIK-5316](https://comet-ml.atlassian.net/browse/OPIK-5316)。严禁以纯文本展示工单 Key——链接化是硬性要求便于用户一键跳转。与相邻命令的协同建单只是起点create-jira-ticket并非孤立命令它与 .agents/commands/comet/ 下的兄弟命令构成完整研发闭环work-on-jira-ticket按链接抓取工单、构建上下文含扫描最新^#\s*HOW\b注释作为实现建议、按{USERNAME}/OPIK-{N}-{SUMMARY}约定建分支、可选迁移 In Progress、生成实现计划。它在读取 HOW 时明确“当前代码状态优先HOW 只是建单时的提示而非契约”。share-progress-in-jira从分支名提取工单号用三点 diffgit diff main...HEAD对比 main生成“Release Notes给 PM Technical Details给开发”双段式进度评论回写到工单。create-initiative-epic为季度战略倡议创建 Epic描述使用 Jira wiki markup与本文工单的 Markdown 不同供本命令的 Parent Epic 选择使用。由此形成标准动作链Epic 立项 → 子工单创建本文→ 抓单开工 → 推送进度 → PR 关联全程保持 Jira 状态、标签、描述三要素的纪律性。小结create-jira-ticket规范的价值不在于“能建单”而在于通过强制流程把混乱的研发诉求收敛为结构化的可执行工单WHY/WHAT 分离保证动机清晰、范围可控Story Points 上限与 Parent Epic 规则控制单点规模与目标对齐Pod 标签与区域前缀让看板可过滤、可统计HOW 注释则以“克制”为原则在不过时、不越权的前提下为实现者留下最有价值的线索。对任何希望用 Agent 高效管理 Jira 工单的团队这套流程都是一份可直接借鉴的落地模板其完整实现可继续研读 create-jira-ticket.md 原文及 MCP 配置。【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考