pr-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PR Workflow

PR工作流

When to Invoke

触发时机

After completing any change you intend to merge — fix, feature, refactor, docs, chore
When the user says "open PR", "make a PR", "push and PR", "ship this"
After a debug-widget fix is applied and verified
Never invoke for local-only experiments the user hasn't asked to ship

完成任何计划合并的变更后——修复、功能开发、重构、文档更新、杂项任务
当用户提及“打开PR”“创建PR”“推送并创建PR”“交付此变更”时
应用并验证debug-widget修复后
对于用户未要求交付的本地实验内容，绝不要触发此流程

Required Inputs

必填输入项

FluentBoards card number · one-line change summary · whether

src/

was touched (build needed?) · whether shared Pro/Lite code changed (Pro coordination flag). Missing card number → ask before doing anything.

FluentBoards卡片编号 · 一行变更摘要 · 是否修改了

src/

目录（是否需要构建？）· 是否修改了Pro/Lite共享代码（Pro协作标记）。若缺少卡片编号，需先询问用户再进行操作。

Phase 1 — Pre-check

阶段1 — 预检查

bash

git status                           # working-tree state
git branch --show-current            # current branch
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'   # default branch (don't assume "main")
gh auth status                       # confirm gh CLI logged in

If working tree is dirty with unrelated changes → stop, list them, ask: stash / branch / abandon. Don't bundle unrelated work into one PR.

bash

git status                           # 工作区状态
git branch --show-current            # 当前分支
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'   # 默认分支（不要默认假设为"main"）
gh auth status                       # 确认gh CLI已登录

如果工作区存在无关变更→停止操作，列出这些变更，询问用户：暂存/新建分支/放弃。不要将无关工作合并到同一个PR中。

Phase 2 — Branch Setup

阶段2 — 分支设置

Naming:

<card-number>

— only the FluentBoards card number, nothing else. No slug, no type prefix.

Example	Valid?
`1234`	✅
`1234-fix`	❌ slug not allowed
`fix/1234`	❌ prefix not allowed

Branch creation:

bash

undefined

命名规则：

<card-number>

— 仅使用FluentBoards卡片编号，无其他内容。不允许添加短描述前缀、类型前缀。

示例	是否合规？
`1234`	✅
`1234-fix`	❌ 不允许添加短描述
`fix/1234`	❌ 不允许添加类型前缀

分支创建：

bash

undefined

If currently on default branch → create feature branch

若当前处于默认分支→创建功能分支

git checkout -b <number>

If already on a feature branch matching the card → continue

若已处于与卡片编号匹配的功能分支→继续操作

If on a different feature branch → stop, ask the user which branch this work belongs to

若处于其他功能分支→停止操作，询问用户此工作应归属哪个分支

undefined

undefined

Phase 3 — Stage Selectively

阶段3 — 选择性暂存

bash

git diff                              # review all unstaged changes
git diff --stat                       # file list with line counts
git add <specific-file> ...           # stage by name — never `-A` or `.`
git diff --cached                     # confirm staged diff matches intent

Reject staging if you spot:

.env

*.key

credentials*

, large unrelated binaries, OS artifacts (

.DS_Store

), or files outside the change's scope.

bash

git diff                              # 查看所有未暂存变更
git diff --stat                       # 查看文件列表及行计数
git add <specific-file> ...           # 按文件名暂存——绝不使用`-A`或`.`
git diff --cached                     # 确认暂存的变更符合预期

若发现以下文件，拒绝暂存：

.env

、

*.key

、

credentials*

、大型无关二进制文件、系统生成文件（

.DS_Store

）或超出变更范围的文件。

Phase 4 — Build If Needed

阶段4 — 按需构建

If anything under

src/

was modified, before commit:

bash

npm run build

Per .claude/rules/asset-pipeline.md, the repo tracks compiled assets. Source-only commit without build = drift on production.

After build, also stage the regenerated

assets/front-end/**/*.min.{css,js}

and

languages/*.pot

if they changed.

如果

src/

目录下的内容有修改，提交前需执行：

bash

npm run build

根据.claude/rules/asset-pipeline.md，仓库会跟踪编译后的资源文件。仅提交源码而不构建会导致生产环境代码不一致。

构建完成后，若

assets/front-end/**/*.min.{css,js}

和

languages/*.pot

文件有更新，也需将其暂存。

Phase 5 — Commit Atomically

阶段5 — 原子化提交

Message format:

<type>: <imperative summary, ≤72 chars>

<body — explain WHY, not WHAT (the diff already shows what)>

Refs: #<card-number>

Types:

fix

feat

refactor

docs

chore

perf

test

style

Husky pre-commit hook runs

npx lint-staged

. If it fails:

Read the lint output
Fix the root cause (don't
```
--no-verify
```
)
Re-stage the corrected files
New commit — never
```
git commit --amend
```
after a hook failure (the failed commit didn't happen; amending would modify the previous commit, destroying its history)

提交信息格式：

<类型>: <命令式摘要，≤72字符>

<正文——解释变更原因，而非变更内容（差异已显示内容）>

Refs: #<card-number>

类型可选值：

fix

、

feat

、

refactor

、

docs

、

chore

、

perf

、

test

、

style

Husky预提交钩子会执行

npx lint-staged

。若钩子执行失败：

阅读lint输出信息
修复根本问题（不要使用
```
--no-verify
```
跳过）
重新暂存修正后的文件
创建新提交——钩子失败后绝不要使用
```
git commit --amend
```
（失败的提交并未完成；修改会覆盖上一次提交，破坏历史记录）

Phase 6 — Push the Branch

阶段6 — 推送分支

bash

git push -u origin <number>     # first push
git push                        # subsequent pushes

Hard refusal: if the resolved branch name equals the default branch (main / master / trunk), do not push. Output:

REFUSED: Cannot push to default branch (<name>).
This skill enforces feature-branch-only workflow. Create a feature branch first.

Also refuse

git push --force

to any shared branch.

--force-with-lease

to your own feature branch is OK only with explicit user request.

bash

git push -u origin <number>     # 首次推送
git push                        # 后续推送

严格禁止： 如果解析后的分支名称与默认分支（main/master/trunk）一致，禁止推送。输出提示：

拒绝操作：无法推送到默认分支(<name>)。
此技能强制要求使用功能分支工作流，请先创建功能分支。

同时禁止向共享分支执行

git push --force

。仅当用户明确要求时，才可向自己的功能分支执行

--force-with-lease

。

Phase 7 — Create the PR

阶段7 — 创建PR

bash

gh pr create --title "<type>: <summary>" --body "$(cat <<'EOF'

bash

gh pr create --title "<type>: <summary>" --body "$(cat <<'EOF'

Summary

摘要

<1–3 bullets — what changed and why>

<1–3条要点——变更内容及原因>

Test Plan

测试计划

<manual test step on http://localhost:8888>
```
npm run test:e2e
```
green
Visually verified <widget / area> on test site

<在http://localhost:8888执行手动测试步骤>
```
npm run test:e2e
```
执行通过
在测试站点上视觉验证<组件/区域>

Breaking Changes

破坏性变更

<无——或列出变更并提供迁移说明，若钩子/控制ID/渲染类有变更>

Pro Repo Coordination

Pro仓库协作

<无——或：修改了共享特性/类/钩子。Pro PR：#XXXX>

关联内容

FluentBoards card: https://projects.startise.com/wp-admin/admin.php?page=fluent-boards#/boards/30 (card #<card-number>) EOF )"


After creation: return the PR URL to the user. Do not auto-assign reviewers, do not add labels (unless user asks).

FluentBoards卡片：https://projects.startise.com/wp-admin/admin.php?page=fluent-boards#/boards/30 (卡片#<card-number>) EOF )"


创建完成后：将PR链接返回给用户。不要自动分配审核人，不要添加标签（除非用户要求）。

Hard "Never" Rules

严格“禁止”规则

❌ Never do	Why
`git push origin <default-branch>`	Skill's primary contract — feature-branch only
`git push --force` to a shared branch	Destructive, history rewrite for others
`git commit --no-verify`	Pre-commit hooks exist for a reason; failure = real lint/format issue
`git add -A` / `git add .`	Sensitive file leak risk
`git commit --amend` after a pushed commit	Rewrites shared history
`git config <anything>`	Per CLAUDE.md, never touch git config
Skip `npm run build` after `src/` change	Repo tracks compiled assets
Bundle unrelated changes into one PR	Hard to review, hard to revert

❌ 绝不要做	原因
`git push origin <default-branch>`	技能核心约定——仅允许功能分支工作流
向共享分支执行 `git push --force`	具有破坏性，会覆盖他人的历史记录
`git commit --no-verify`	预提交钩子存在是有原因的；失败意味着存在真实的lint/格式问题
`git add -A` / `git add .`	存在敏感文件泄露风险
推送提交后执行 `git commit --amend`	会修改共享历史记录
`git config <anything>`	根据CLAUDE.md，绝不修改git配置
修改 `src/` 后跳过 `npm run build`	仓库会跟踪编译后的资源文件
将无关变更合并到同一个PR	难以审核，难以回滚

Edge Cases

边缘场景处理

Situation	Handling
User-uncommitted unrelated changes	Stop. List them. Ask: stash / commit-to-different-branch / abandon
Branch already exists on remote	Ask: continue on existing, or new branch with `-v2` suffix
Pre-commit hook fails	Show output, fix lint root cause, re-stage, new commit
Merge conflict during rebase	Stop. Show conflict files. User resolves manually — never auto-pick a side
`gh` not authenticated	`gh auth status` — instruct user to `gh auth login`
Card number unknown / not given	Refuse to create branch — ask the user; the FluentBoards link is the source of truth
Diff > 500 lines, mixed concerns	Suggest splitting into multiple atomic PRs before pushing

场景	处理方式
用户存在未提交的无关变更	停止操作。列出变更。询问用户：暂存/提交到其他分支/放弃
远程仓库已存在同名分支	询问用户：继续使用现有分支，还是创建带 `-v2` 后缀的新分支
预提交钩子执行失败	显示输出信息，修复lint根本问题，重新暂存，创建新提交
变基时出现合并冲突	停止操作。显示冲突文件。由用户手动解决——绝不自动选择某一方
`gh` 未认证	执行 `gh auth status` ——指导用户执行 `gh auth login`
卡片编号未知/未提供	拒绝创建分支——询问用户；FluentBoards链接是唯一可信来源
差异超过500行，包含混合关注点	建议在推送前拆分为多个原子化PR

Operating Rules

操作规则

Default branch is sacred. Hard refusal of any push there. No exceptions, including hotfixes — hotfixes still go through PR.
Card number required. Every branch name and PR
```
Related
```
section ties back to FluentBoards. No card → no branch.
Pre-commit hooks honored. Failure means fix the issue, not skip the hook.
One PR, one logical change. Mixed concerns → split before pushing.
Branch name is card-number-only. Slugs, prefixes, or any extra suffix are rejected.

默认分支不可侵犯。严格禁止任何推送到默认分支的操作。无例外，包括热修复——热修复仍需通过PR流程。
必须提供卡片编号。每个分支名称和PR的“关联内容”部分都需关联到FluentBoards。无卡片编号→不创建分支。
遵守预提交钩子。失败意味着需要修复问题，而非跳过钩子。
一个PR对应一个逻辑变更。混合关注点→推送前拆分。
分支名称仅为卡片编号。拒绝添加短描述、前缀或任何额外后缀。

pr-workflow

Original

Translation

PR Workflow

PR工作流

When to Invoke

触发时机

Required Inputs

必填输入项

Phase 1 — Pre-check

阶段1 — 预检查

Phase 2 — Branch Setup

阶段2 — 分支设置

If currently on default branch → create feature branch

若当前处于默认分支→创建功能分支

If already on a feature branch matching the card → continue

若已处于与卡片编号匹配的功能分支→继续操作

If on a different feature branch → stop, ask the user which branch this work belongs to

若处于其他功能分支→停止操作，询问用户此工作应归属哪个分支

Phase 3 — Stage Selectively

阶段3 — 选择性暂存

Phase 4 — Build If Needed

阶段4 — 按需构建

Phase 5 — Commit Atomically

阶段5 — 原子化提交

Phase 6 — Push the Branch

阶段6 — 推送分支

Phase 7 — Create the PR

阶段7 — 创建PR

Summary

摘要

Test Plan

测试计划

Breaking Changes

破坏性变更

Pro Repo Coordination

Pro仓库协作

Related

关联内容

Hard "Never" Rules

严格“禁止”规则

Edge Cases

边缘场景处理

Operating Rules

操作规则