# 三件套 《Issue 模板》 Bug 专用模板（可选）  《PR 模板》 《Projects 字段设计表》

下面给你一套可以直接落到仓库里的三件套，格式已经按 GitHub 官方推荐的模板/字段写好，你可以按需微调后直接放到 `.github/` 目录和 Projects 中使用。 [docs.github](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository)

***

## 一、《Issue 模板》

### 1. 使用方式说明

建议使用 GitHub 的 Issue Forms（YAML）形式，这样可以强制结构化输入。模板文件需要放在仓库的 `.github/ISSUE_TEMPLATE` 目录下，并以 `*.yml` 命名。 [rewind](https://rewind.com/blog/best-practices-for-using-github-issues/)
可以为不同类型任务配置多种模板，例如「功能需求」「缺陷报告」「技术债/重构」，下面示例以通用研发团队为主。 [github](https://github.com/stevemao/github-issue-templates)

### 2. 通用 Issue 表单模板（YAML）

文件路径示例：`.github/ISSUE_TEMPLATE/general.yml`。 [youtube](https://www.youtube.com/watch?v=hNs5Gg_fEEs)

```yml
name: 通用任务 / General Task
description: 创建功能需求、技术任务或运维任务
title: "[feat] 标题：请简要概括任务目标"
labels: ["triage"]
assignees: []
body:
  - type: dropdown
    id: type
    attributes:
      label: 任务类型 / Type
      description: 请选择任务类型
      options:
        - Feature
        - Bug
        - Tech Debt
        - Ops
    validations:
      required: true

  - type: input
    id: background
    attributes:
      label: 背景 / Background
      description: 请简要说明当前问题或业务背景
      placeholder: 当前存在什么问题或机会？
    validations:
      required: true

  - type: textarea
    id: goal
    attributes:
      label: 目标与结果 / Goal & Outcome
      description: 需要达到什么目标？期望的可观察结果是什么？
      placeholder: 明确描述交付完成后，应看到什么可验证结果
    validations:
      required: true

  - type: textarea
    id: acceptance
    attributes:
      label: 验收标准 / Acceptance Criteria
      description: 列出可验证的验收点
      placeholder: |
        - [ ] 条件 1
        - [ ] 条件 2
        - [ ] 条件 3
    validations:
      required: true

  - type: textarea
    id: impact
    attributes:
      label: 影响范围 / Impact Scope
      description: 该任务影响哪些系统、模块、用户？
      placeholder: 列出受影响的服务、模块、接口或用户类型
    validations:
      required: false

  - type: textarea
    id: dependencies
    attributes:
      label: 依赖与前置条件 / Dependencies
      description: 该任务依赖哪些其他任务、决策或资源？
      placeholder: 例如：依赖某接口、其他团队、配置、第三方服务
    validations:
      required: false

  - type: input
    id: due_date
    attributes:
      label: 期望完成时间 / Expected Due Date
      description: 如有明确交付承诺，请填写 YYYY-MM-DD
      placeholder: 2026-07-31
    validations:
      required: false

  - type: textarea
    id: extra
    attributes:
      label: 备注 / Notes
      description: 其他需要说明的事项（包括风险、备选方案等）
      placeholder: 补充说明、风险、补充链接、参考文档等
    validations:
      required: false
```

### 3. Bug 专用模板（可选）

文件路径示例：`.github/ISSUE_TEMPLATE/bug.yml`。 [github](https://github.com/orgs/community/discussions/147722)

```yml
name: 缺陷报告 / Bug Report
description: 报告系统缺陷或异常行为
title: "[bug] 标题：简要描述异常现象"
labels: ["bug", "triage"]
assignees: []
body:
  - type: textarea
    id: description
    attributes:
      label: 问题描述 / Description
      description: 清晰简洁地描述问题
      placeholder: 出现了什么问题，与预期有什么差异？
    validations:
      required: true

  - type: textarea
    id: steps
    attributes:
      label: 复现步骤 / Steps to Reproduce
      description: 列出复现问题的具体步骤
      placeholder: |
        1. 步骤一
        2. 步骤二
        3. ...
    validations:
      required: true

  - type: textarea
    id: expected
    attributes:
      label: 期望行为 / Expected Behavior
      description: 说明你期望发生什么
    validations:
      required: true

  - type: textarea
    id: actual
    attributes:
      label: 实际行为 / Actual Behavior
      description: 说明实际发生了什么
    validations:
      required: true

  - type: textarea
    id: env
    attributes:
      label: 环境信息 / Environment
      description: 包括操作系统、浏览器/客户端版本、分支、版本号等
      placeholder: |
        - OS:
        - Browser/Client:
        - Branch/Version:
    validations:
      required: true

  - type: textarea
    id: logs
    attributes:
      label: 日志与截图 / Logs & Screenshots
      description: 请粘贴相关日志、错误信息或上传截图（脱敏后）
    validations:
      required: false
```

这些模板可以根据团队偏好进一步扩展，例如添加「安全等级」「模块」「Story Points」等字段。 [unicef.github](https://unicef.github.io/inventory/dpg-indicators/8/project-management/issue-templates/)

***

## 二、《PR 模板》

### 1. 使用方式说明

PR 模板建议放置在 `.github/PULL_REQUEST_TEMPLATE.md` 文件，GitHub 会自动在新建 PR 时预填内容，便于规范化信息。 [graphite](https://graphite.com/guides/comprehensive-checklist-github-pr-template)
模板应包括：关联工作项、变更说明、验证步骤、风险、回滚策略和检查项等。 [microsoft.github](https://microsoft.github.io/code-with-engineering-playbook/code-reviews/pull-request-template/)

### 2. 标准 PR 模板（Markdown）

文件路径：`.github/PULL_REQUEST_TEMPLATE.md`。 [microsoft.github](https://microsoft.github.io/code-with-engineering-playbook/code-reviews/pull-request-template/)

```markdown
# 关联 Issue / Related Issues

- 关闭/关联的 Issue：
  - Closes #123
  - Relates to #456

# 变更说明 / Description

> 简要说明本次变更的目的、背景和主要内容。

- 背景：
- 主要变更点：
  - xxx
  - xxx

# 影响范围 / Impact

> 说明本次变更影响到的模块、系统或用户。

- 受影响模块：
- 受影响接口/服务：
- 兼容性说明：

# 验证与测试 / Testing

> 列出已经执行的测试以及结果。

- [ ] 单元测试
- [ ] 集成测试
- [ ] 手工验证
- 测试说明：
  - 环境：
  - 测试步骤：
  - 结果摘要：

# 回滚方案 / Rollback Plan

> 如果上线后出现问题，如何快速回滚？

- 回滚方式：
- 回滚依赖：
- 回滚风险：

# 安全与风险 / Security & Risks

> 是否涉及安全、权限、数据迁移或大规模变更？

- [ ] 涉及权限变更
- [ ] 涉及数据结构/迁移
- [ ] 涉及第三方服务
- 风险说明：
- 缓解措施：

# Checklist

> 提交前请自检以下项目。

- [ ] 代码通过本地编译/构建
- [ ] 通过基础自动化测试（CI）
- [ ] 已自查并修复明显警告/代码味道
- [ ] 变更范围尽可能小且聚焦
- [ ] 文档/配置已更新（如适用）
- [ ] 未包含敏感信息（密钥、密码等）

# 其他信息 / Additional Context

> 任何有助于 Reviewer 理解本次变更的信息、链接或截图。

- 设计文档/需求文档链接：
- 截图：
- 其他：
```

可根据不同项目增加模块字段，如「前端/后端」「服务名称」「数据库类型」「feature flag 名称」等，使 Reviewer 能快速建立上下文。 [reddit](https://www.reddit.com/r/ExperiencedDevs/comments/142n5ea/what_do_you_think_should_be_the_standard_for_pull/)

***

## 三、《Projects 字段设计表》

### 1. 字段设计原则

GitHub Projects 支持通过自定义字段为 Issues 和 PR 添加迭代、优先级、故事点、日期、备注等元数据，用于在表格、看板和路线图视图中筛选、分组和排序。 [docs.github](https://docs.github.com/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects)
字段要尽量少而关键，保证所有团队成员理解一致，避免同类信息重复出现在多个字段。 [docs.github](https://docs.github.com/enterprise-cloud@latest/issues/planning-and-tracking-with-projects/learning-about-projects/best-practices-for-projects)

### 2. 推荐字段列表

下面是一份可直接用于团队 Project 的字段设计表，你可以在 Project 的「Settings → Fields」中按表创建。 [docs.github](https://docs.github.com/enterprise-cloud@latest/issues/planning-and-tracking-with-projects/learning-about-projects/best-practices-for-projects)

| 字段名 | 类型 | 示例值 | 用途说明 |
|---|---|---|---|
| Status | 单选（枚举） | Backlog / Ready / In Progress / Review / Blocked / Done | 统一任务状态流转 |
| Priority | 单选（枚举） | P0 / P1 / P2 / P3 | 控制任务优先级 |
| Iteration | 单选（枚举）或迭代 | 2026-W27 / 2026.07-Sprint1 | 绑定迭代或版本 |
| Type | 单选（枚举） | Feature / Bug / Tech Debt / Ops | 区分任务类型 |
| Owner | 用户 | @username | 任务主负责人 |
| Story Points | 数字 | 1 / 2 / 3 / 5 / 8 | 估算工作量（可选） |
| Component | 单选（枚举） | Web / API / DB / Infra | 模块/组件归类 |
| Due Date | 日期 | 2026-07-31 | 承诺交付日期 |
| Created At | 系统字段 | 自动 | 初始创建日期 |
| Updated At | 系统字段 | 自动 | 最近更新时间 |
| Risk Level | 单选（枚举） | Low / Medium / High | 风险等级（可选） |
| Block Reason | 文本 | 等待接口 / 需求不明等 | 阻塞说明（可选） |

其中 Status、Priority、Iteration、Owner 是强建议必配，Story Points 和 Component 可根据团队敏捷实践程度选择是否启用。 [github](https://github.com/features/issues)

### 3. 视图建议

利用上述字段，可以在 Projects 中创建多个视图，以支持不同角色使用： [docs.github](https://docs.github.com/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects)

- Backlog 视图：过滤 Status = Backlog / Ready，按 Priority 降序排序。
- 迭代视图：过滤特定 Iteration，按 Status 分组，适合迭代执行跟踪。
- 看板视图：按 Status 分组，限制 In Progress 列的 WIP（通过团队约定执行）。
- 路线图视图：使用表格或路线图 layout，按 Due Date 排序，看版本级目标。
- 风险视图：过滤 Risk Level = High 或 Blocked，供负责人重点关注。

Project 视图可以按用户、模块或类型进行过滤和分组，用于不同层级管理：例如「按 Owner 分组的个人待办视图」「按 Type 分组的 Bug/Feature 列表」等。 [github](https://github.com/features/issues)

***

如果你愿意，我可以帮你把这三件套再组合成一个仓库根目录的 `CONTRIBUTING.md` 示例，把“怎么提 Issue / 怎么提 PR / 怎么在 Project 中看自己任务”写成一份面向开发同事的使用指南。