Issue Writing

让读者理解问题或目标、工作边界和如何判断完成，并使相关工作易于查找与跟踪。

先了解仓库与现有问题

• 确认目标仓库与任务，读取适用的 AGENTS.md、CONTRIBUTING.md、issue 模板及相关约定。对外部仓库，了解维护者要求和现有 issue 的语言与写法。
• 创建前搜索目标仓库的开放和已关闭 issue，使用问题、功能、模块及其同义词等多个相关关键词，检查候选的正文、状态和范围，区分真正重复、部分重叠和单纯相关。
• 已有 issue 完整覆盖且仍适用时优先复用；对已关闭 issue 核实关闭原因与当前问题是否仍相同。部分重叠时说明新问题的独立范围并链接相关 issue。更新或评论已有 issue 前确认操作在本次授权内；无法完成必要查重时说明限制，待查重后再创建。

标题与正文

• 标题使用英文，简洁说明具体问题或期望结果，遵循仓库已有标题格式，保留产品名称和标识符的原有大小写。
• 我们自己的仓库正文用中文；外部仓库明确由外国维护者为主时用英文。其他外部仓库根据维护者要求与现有交流语言判断，仍不明确时先询问。若明确要求与仓库规则冲突，说明冲突并确认处理方式。
• 正文中，中文、英文和数字相邻时必须用空格隔开，例如“使用 GitHub API 2 次”；代码、标识符和链接保持原有写法。
• 有适用模板时按模板填写；否则围绕背景、目标或问题、范围和可验证的验收条件组织，按实际规模取舍，小问题保持简短，不留空章节。
• 缺陷说明实际与预期行为、复现步骤或输入、相关版本和影响；功能或任务说明预期结果、必要边界、验收条件及相关依赖。计划、迁移或重构按需说明目标状态、必须保持的行为、阶段与验收、风险和回滚。讨论类问题写清可选方案、取舍及待决定事项。
• 区分事实、推测和未验证内容；提供可供目标读者访问的关键证据或链接，敏感数据先脱敏。详细日志和产物放在约定的任务记录中，issue 保留理解、执行和验收所需的信息。

父子关系与跟进

• 属于已有大计划、迁移或重构的工作时，确认正确的父 issue 和子任务范围，将新 issue 建立为真正的 sub-issue。拆分计划时也为拆出的独立任务建立父子关系；不需要独立跟踪的步骤可用正文任务清单。普通链接或任务清单不等同于父子关系。
• 在 GitHub 使用支持 sub-issue 的界面或工具，例如创建时使用 gh issue create --parent <parent>，或创建后使用 gh issue edit <parent> --add-sub-issue <child>。确认权限和平台限制；创建或关联受阻时保留已有结果并报告原因，不把普通链接当作已完成关联，也不覆盖已有父关系。
• 创建后回读标题、正文、链接和实际父子关系，确认与意图一致。任务进行中，按约定更新正文中的当前计划与验收条件，并用评论记录重要进展、决策和证据；复杂计划可标注当前状态及日期，方案变化时说明取代关系。更新前先读取当前远端内容，保留他人新增信息。
• 任务同时有 issue 和 PR 时双向关联：issue 记录背景、进展和验收，PR 说明代码变化及验证结论。完成或关闭时依据实际验收说明完成情况和遗留事项；发布、修改和关闭等操作均按当前任务授权执行。