# Write PR

在 kimi-code 仓库里创建或更新 PR 时使用：如何写出让 reviewer 只读描述就能从逻辑和架构上理解改动的 PR...

- Repository: https://github.com/MoonshotAI/kimi-code (8095 stars)
- Category: Design
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add MoonshotAI/kimi-code --skill write-pr -g -a claude-code -y`
Codex: `npx skills add MoonshotAI/kimi-code --skill write-pr -g -a codex -y`
Cursor: `npx skills add MoonshotAI/kimi-code --skill write-pr -g -a cursor -y`
Gemini CLI: `npx skills add MoonshotAI/kimi-code --skill write-pr -g -a gemini-cli -y`

## Description

在 kimi-code 仓库里创建或更新 PR 时使用：如何写出让 reviewer 只读描述就能从逻辑和架构上理解改动的 PR 描述，包括核心思路与结构图、"行为变化与受影响人群"表、可视化大纲，以及 UI/UX 变化的截图和录屏。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 写 PR 描述

为当前分支创建或更新 PR。目标是 reviewer 只读描述，就能从逻辑和架构上理解这个改动：为什么存在、核心思路是什么、改完后系统长什么样、现有用户会失去什么，以及该从哪里开始看代码。

## 工作流

1. 读 PR 模板：

   `Read(.github/pull_request_template.md)`

2. 找到或创建 PR：
   - 先查当前分支有没有 PR：`gh pr view --json url,number,title,state 2>/dev/null`。
   - 没有的话，看 `git status --short --branch` 和当前分支上的提交。
   - 提交剩余改动，带 upstream 推送分支，用 `gh pr create` 创建 PR。
   - 遵守仓库的 git 安全规范。

3. 收集解释改动所需的上下文：
   - 读关联的 issue 和相关任务产物。
   - 读完整 diff（`git diff main...HEAD`）和足够的周边代码，理解行为与归属。
   - PR 已存在时，用 `gh pr view` 拿元数据和改动文件列表。
   - 改动让用户看到的界面或输出变了的，准备视觉证据，见"UI/UX 变化的视觉证据"。

4. 按模板各节写描述。描述用用户当前使用的语言，行为变化表也一样；只有三样固定：PR 标题保持英文 Conventional Commit，changeset 保持英文（见 `gen-changesets` skill），节标题沿用模板原文。
   - **Requirement or Bug**：两三句话讲清谁遇到了什么问题、这个 PR 之后能做到什么；有 issue 的写 `Resolve #<number>`，再补一句背景。解决办法留给 Code Changes。
   - **Bug Reproduction Steps**：只有 bug 类 PR 需要；feature 写 `N/A`。步骤已在 issue 里的写 `See linked issue`。
   - **Root Cause**：只有 bug 类 PR 需要；feature 写 `N/A`。说明根因，以及这是根本修复还是绕过。机制要靠时序或状态才说得清的，用图，见"代码变更的可视化大纲"。
   - **Code Changes**：先判断要不要先建立整体理解，再讲具体变化，见"讲清楚改动"。
   - **Screenshots / Recordings**：模板里没有这一节。有可见的 UI/UX 变化时加在 Code Changes 后面，没有就不加，见"UI/UX 变化的视觉证据"。
   - **Behavior Changes and Affected Users**：先填行为变化表，再列受影响模块与测试覆盖，见"行为变化与受影响人群"。验证只写结论：覆盖了哪些场景、哪些没验证；测试文件清单、全量运行结果和修复过程放进折叠块。
   - **Checklist**：勾上所有适用的项。

5. 发布描述：
   - 描述里有图片的，先按"UI/UX 变化的视觉证据"上传，换成真实链接。
   - 先存到临时文件，再 `gh pr edit <number> --body-file <path>` 或 `gh pr create --body-file <path>`。
   - 确认更新成功。

## 行为变化与受影响人群

这一节回答一个问题：合入之后，现有用户会失去什么。这个仓库过去的回归大多来自没人回答这个问题，而不是逻辑错误。

判据：**改动前能工作的任何输入（配置键、环境变量、命令行参数、provider 响应形态、旧版本写的会话数据、客户端请求、hook 载荷）改动后必须行为不变，除非这里明确声明了变化并给出退路。**

写法：

1. 列出 diff 改变的每一个可观测行为，一行一个。包括你认为"不变"但分支条件挪动了的：新增的条件会不会先于旧条件命中既有输入；删除或收窄的分支改动前谁在走。内部包会打进 CLI 发布包，"内部"不等于用户无感。表格用 PR 描述的语言，下面的示例用英文只是示意形状：

The rest: https://github.com/MoonshotAI/kimi-code/blob/HEAD/.agents/skills/write-pr/SKILL.md