ticket-creator

Ticket Creator

创建结构清晰的 Linear 工单，便于 AI Agent（Claude Code）实现。遵循模式优先、模板驱动的工作流，确保实现 Agent 无需做开放式架构决策即可规划和执行。请参阅 references/guidelines.md，了解详细的质量标准和写作指南。

核心原则：模式优先

决定工单成败的最重要因素，是实现 Agent 能否从现有模式中复制并调整。每个工单都必须引用现有代码模式，或明确指出这是首次采用的模式，需要提供更详细的规格说明。

AskUserQuestion 的使用

只有在无法从当前对话上下文、代码库或先前回复中推断答案时，才调用 AskUserQuestion。如果信息已提供或可以推断，就直接继续，无需提问。这适用于所有阶段——分类、去重、信息收集、反模式处理、拆分和确认。

工作流

开始时使用 TaskCreate 规划工作流步骤，并在完成每一步后使用 TaskUpdate 标记完成。这样可以让进度清晰可见，并在 /compact 后保留。

1. 收集上下文并分类

在提问前，从当前对话中尽可能提取信息。如果已经讨论过相关工作，请利用上下文预填工单详情。

对工单分类：

• 普通（功能、改进、重构）→ references/template-normal.md
• Bug（错误、行为异常）→ references/template-bug.md

根据上下文或关键词确定领域：

领域	关键词
UI	页面、组件、布局、前端、表格、表单、模态框、侧边栏
Backend	服务端操作、API、端点、数据库、架构、查询、迁移、任务
Data-Engine	采集器、actor、流水线、抓取工具、PDF、Python、data-engine

如果无法明确分类，请使用 AskUserQuestion 进行确认。

2. 检查重复工单

使用 Task，并将 subagent_type 设为 general-purpose，在 Linear 中搜索类似的现有工单。将工单描述、关键词和领域作为上下文传入，并附上 references/duplicate-checker.md 中的说明。子 Agent 负责处理所有 list_issues 调用，并返回简洁摘要。

如果子 Agent 找到匹配的工单，请展示给用户，并询问是继续创建、更新现有工单，还是将其关联为相关工单。

3. 加载模板并收集信息

从 references/ 加载合适的模板。按以下优先顺序，以对话方式收集缺失的必需信息，每次提问 1～2 个：

1. 我们要构建或修复什么？原因是什么？范围是什么？
2. 是否有可遵循的现有模式？（最关键）
3. 技术细节——类型、契约、文件路径
4. 副作用、集成点、权限
5. 验收标准和验证提示

对于 Bug 工单：如果提供了 Sentry 问题 ID 或 URL，请使用 Task，并将 subagent_type 设为 general-purpose，以获取 Sentry 错误详情。指示子 Agent 仅返回工单所需的字段：错误消息、受影响的文件/行号、根本原因（如可确定）、发生频率/用户影响，以及任何相关的面包屑。完整字段列表请参阅 references/template-bug.md。这样可以避免冗长的 Sentry 数据（堆栈跟踪、原始面包屑）占满主上下文。

4. 发现模式

使用 Task，并将 subagent_type 设为 Explore，搜索代码库中的以下内容：

• 可作为模式参考的现有实现
• 相关的 Claude Code 技能（扫描 .claude/ 目录中的 SKILL.md 文件）

将发现的模式填入工单的“要遵循的现有模式”字段。将发现的技能按以下格式填入 Implementation Toolkit 部分：skills: [skill-name-1, skill-name-2]

5. 质量检查

运行 references/anti-patterns.md 中的所有反模式检查。指出所有警告，并在继续之前与用户一起解决。

评估该工单是否应该拆分（见下文“工单拆分”）。

6. 起草并确认

使用已加载的模板编写工单。提供简洁预览——标题、摘要、关键字段、验收标准，而非完整工单正文。

在创建工单前，请用户确认或提出修改要求。

7. 在 Linear 中创建

使用 create_issue 创建工单，并填写：团队（"Sylla Tech"）、标题、描述、优先级。只有用户指定负责人时才设置负责人。

如果存在依赖项，请使用 blockedBy 或 blocks 字段。去重时发现的相关工单，请使用 relatedTo 关联。

创建后，将工单链接分享给用户。

工单拆分

拆分工单时，使用 TaskCreate 和 blockedBy 建模拆分工单之间的依赖顺序（例如，后端先于 UI）。使用 TaskList 查看进度，并使用 TaskUpdate 跟踪每张工单在阶段 3-7 的进展。

按类别拆分

如果工作涉及多个领域（例如 UI + Backend + Data-Engine），请为每个领域分别创建一张关联工单。在每张工单上运行阶段 3-7，并沿用共享上下文（优先级、描述、相关工单）。使用 relatedTo 交叉关联工单。

按文件拆分

如果一张工单需要修改超过 8 个文件，请建议将其拆分成更小、更专注的工单。每张拆分后的工单都应能独立实施。

标题规范

类型	格式
功能	Implement [thing] for [purpose]
UI 页面	Create [page name] page at [route]
UI 组件	Add [component] to [location]
API/端点	Add [method] [endpoint] endpoint
重构	Refactor [what] to [improvement]
Bug	Fix [symptom] in [location]

参考文件

文件	用途
references/template-normal.md	功能、改进和重构的模板（包含按需填写的 UI/Backend/Data-Engine 部分）
references/template-bug.md	Bug 修复模板（集成 Sentry MCP）
references/anti-patterns.md	创建工单前运行的反模式检测规则
references/guidelines.md	质量标准、写作指南和验证规则
references/layout-patterns.md	UI 布局模式决策表和组件参考
references/duplicate-checker.md	用于 Linear 重复项搜索的子 Agent 提示词（在步骤 2 中使用）

工单示例

请参考以下真实工单示例，以掌握结构和详细程度：

示例	领域	依据
examples/backend-ticket.md	Backend（服务端操作 + API）	S-1176
examples/bug-ticket.md	Bug 修复（已知根本原因）	S-1222
examples/data-engine-ticket.md	Data-Engine 收集器	S-1149
examples/ui-ticket.md	UI 页面创建	S-1163

质量测试

创建前，请确认：“实施该工单的 Agent 能否据此制定完整计划，而无需自行做出任何开放式架构决策？”

如果答案是否定的，请找出模糊之处并询问用户。完整的质量检查清单请参见 references/guidelines.md。