shipit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shipit

Ship the current changes. Only run when the user explicitly invokes

/shipit

. Never start this process proactively.

交付当前变更内容。仅在用户显式调用

/shipit

命令时执行，切勿主动启动此流程。

Two modes

两种模式

/shipit

ships whatever the current work is. First detect which case you are in:

PR-merge mode — the current branch is NOT the default branch and has an open PR (typically from a
```
/engineer
```
the user ran manually). Here the user's
```
/shipit
```
is their human sign-off: merge the PR once CI is green (Step 0).
```
/engineer
```
deliberately stops at In Review for a separate reviewer; but when the user personally picked up the ticket and says ship it, that review gate is satisfied by them, so merging is authorized.
Direct-to-main mode — the default: uncommitted/unpushed work on the default branch. Validate, run the relevant tests, commit, and push (Steps 1-4).

/shipit

会交付当前所有工作内容。首先判断当前处于哪种情况：

PR合并模式 — 当前分支不是默认分支，且存在已打开的PR（通常来自用户手动执行的
```
/engineer
```
命令）。此时用户调用
```
/shipit
```
即表示人工确认：在CI验证通过后合并该PR（步骤0）。
```
/engineer
```
命令会特意停留在"审核中"状态等待其他审核者；但如果用户亲自处理工单并要求交付，则该审核环节已由用户完成，因此合并操作是被授权的。
直接提交至主分支模式 — 默认模式：默认分支上存在未提交/未推送的工作内容。执行验证、运行与变更相关的测试，然后提交并推送（步骤1-4）。

Step 0 — PR-merge mode (only when the branch has an open PR)

步骤0 — PR合并模式（仅当分支存在已打开的PR时）

Detect with

gh pr view --json number,state,headRefName,mergeable,mergeStateStatus

on the current branch. If there is an OPEN PR for it, this is the whole job:

Require green CI on the head SHA.
```
gh pr checks <n>
```
— every required check must be
```
pass
```
and the PR
```
mergeable
```
/
```
mergeStateStatus: CLEAN
```
. If CI is still pending, wait for it (
```
gh run watch
```
); if anything is failing or the PR conflicts, STOP and report — do not merge.
Merge the way the repo merges (match its history; squash is the common default):
```
gh pr merge <n> --squash --delete-branch
```
.
Sync and close out.
```
git checkout <default> && git pull
```
, delete the local feature branch. If the tracker did not auto-advance the ticket on merge, set it to Done (the GitHub↔Linear/Projects integration usually does this for you).
Report the merge commit SHA and that the PR + ticket are shipped. Then STOP — skip Steps 1-5. The PR's green CI is the gate; there is nothing uncommitted to validate and nothing to commit to
```
main
```
.

Only fall through to Steps 1-5 below when there is no open PR for the branch.

通过在当前分支执行

gh pr view --json number,state,headRefName,mergeable,mergeStateStatus

命令进行检测。如果存在对应的已打开PR，则只需完成以下工作：

要求头部SHA的CI验证通过。执行
```
gh pr checks <n>
```
— 所有必填检查必须显示
```
pass
```
，且PR处于
```
mergeable
```
状态、
```
mergeStateStatus: CLEAN
```
。如果CI仍在运行，则等待其完成（
```
gh run watch
```
）；如果任何检查失败或PR存在冲突，则停止操作并上报，切勿合并。
按照仓库的合并方式执行合并（匹配历史记录；通常默认使用 squash 合并）：
```
gh pr merge <n> --squash --delete-branch
```
。
同步并收尾。执行
```
git checkout <default> && git pull
```
，删除本地特性分支。如果跟踪系统未在合并后自动推进工单状态，则将其设置为完成（GitHub与Linear/Projects的集成通常会自动完成此操作）。
上报合并提交的SHA值，以及PR和工单已交付的状态。然后停止操作 — 跳过步骤1-5。PR的CI验证通过即为交付门槛；此时没有未提交内容需要验证，也无需向
```
main
```
分支提交任何内容。

仅当分支不存在已打开的PR时，才继续执行以下步骤1-5。

Workflow (direct-to-main mode)

工作流程（直接提交至主分支模式）

Step 1 — Validate

步骤1 — 验证

Run the project's validation pipeline and require all of them to pass before continuing. Detect the package manager from lockfile /

packageManager

field (

bun

pnpm

npm

). Order is signal-first: a real defect (types, tests) surfaces before cosmetics (lint) and packaging (build). Typical pipeline:

```
<pm> run typecheck
```
the change-relevant tests — Step 2 defines the scoping; run them at this point
```
<pm> run lint
```
```
<pm> run build
```

If any step fails, STOP and report the failure. Do not commit.

Note on local build env: some projects keep an empty credential var exported in the shell that shadows

.env.local

(Next.js gives

process.env

precedence). If the build fails on an env var that is actually present in

.env.local

, retry the build with that var unset, e.g.

env -u ANTHROPIC_API_KEY <pm> run build

. Only do this for local validation — never bake it into the committed build script.

运行项目的验证流水线，要求所有步骤通过后才能继续。从锁文件或

packageManager

字段检测包管理器（

bun

、

pnpm

、

npm

）。执行顺序优先排查关键问题：真实缺陷（类型错误、测试失败）应在格式检查（lint）和打包（build）之前被发现。典型流水线如下：

```
<pm> run typecheck
```
与变更相关的测试 — 步骤2定义了测试范围；在此阶段运行这些测试
```
<pm> run lint
```
```
<pm> run build
```

如果任何步骤失败，则停止操作并上报失败原因，切勿提交代码。

关于本地构建环境的注意事项：部分项目会在shell中导出空的凭据变量，覆盖

.env.local

中的值（Next.js中

process.env

优先级更高）。如果构建因某个实际存在于

.env.local

中的环境变量而失败，则取消该变量后重试构建，例如

env -u ANTHROPIC_API_KEY <pm> run build

。此操作仅用于本地验证 — 切勿将其写入已提交的构建脚本中。

Step 2 — Run the tests relevant to the change (NOT the full suite)

步骤2 — 运行与变更相关的测试（而非完整测试套件）

This is gate 2 of Step 1's pipeline (after typecheck, before lint/build). Run the unit/component and e2e tests that exercise the files this change touched — not the whole suite. The goal is to catch regressions inside the diff's blast radius without paying for an unrelated full run. The full suite is CI's job; here we run what the change can break.

Find the touched files — union of uncommitted and committed-but-unpushed:

bash

git status --porcelain | awk '{print $2}'
git diff --name-only origin/<default-branch>...HEAD

Unit / component (Vitest): let the module graph pick the dependent tests — Vitest runs every test that transitively imports a changed file, including the colocated
```
*.test.ts(x)
```
:
bash
```
<pm>x vitest related --run <changed .ts/.tsx files…>
```
Pass the changed source files (test files are fine too). If the project has no Vitest, fall back to running each changed module's colocated test file. This is fast — it's the primary gate.
E2E / visual (Playwright), only when relevant:
- Always run any touched spec:
```
<pm>x playwright test <changed *.spec.ts>
```
  .
- For touched source files, run the e2e specs that exercise that surface — map by feature dir / route / component name (grep the specs for the route or symbol). If nothing clearly maps, say so and skip. Never fall back to the full e2e suite here.
- Reuse a running dev server if one is up, or set
```
E2E_BASE_URL
```
  ; the Playwright config may already
```
reuseExistingServer
```
  .
- If a touched UI surface changed appearance and a visual/snapshot spec covers it, run it — and if the baseline legitimately changed, regenerate it (
```
--update-snapshots
```
  ) and include the new baseline in the commit.
Everything selected must pass before commit — same stop condition as Step 1. A failure here means fix or report, do not ship.

这是步骤1流水线的第二个门槛（类型检查之后，lint/build之前）。运行与变更文件相关的单元/组件测试和端到端测试 — 不要运行完整测试套件。目标是在不花费时间运行无关测试的前提下，捕获变更影响范围内的回归问题。完整测试套件由CI负责；此处仅运行变更可能影响的测试。

找出变更文件 — 未提交文件和已提交但未推送文件的合集：

bash

git status --porcelain | awk '{print $2}'
git diff --name-only origin/<default-branch>...HEAD

单元/组件测试（Vitest）：让模块图自动选择依赖测试 — Vitest会运行所有间接导入变更文件的测试，包括同目录下的
```
*.test.ts(x)
```
文件：
bash
```
<pm>x vitest related --run <changed .ts/.tsx files…>
```
传入变更的源文件（测试文件也可以）。如果项目未使用Vitest，则退化为运行每个变更模块对应的同目录测试文件。此操作速度快 — 是主要的验证门槛。
端到端/视觉测试（Playwright），仅在相关时运行：
- 始终运行任何被修改的测试用例：
```
<pm>x playwright test <changed *.spec.ts>
```
  。
- 对于被修改的源文件，运行涉及该功能表面的端到端测试用例 — 按功能目录/路由/组件名称匹配（在测试用例中搜索路由或符号）。如果没有明确匹配的用例，则说明情况并跳过。切勿退化为运行完整端到端测试套件。
- 如果已有运行中的开发服务器，则复用它，或设置
```
E2E_BASE_URL
```
  ；Playwright配置可能已启用
```
reuseExistingServer
```
  。
- 如果被修改的UI表面外观发生变化，且有视觉/快照测试覆盖该区域，则运行该测试 — 如果基准内容确实需要更新，则重新生成基准（
```
--update-snapshots
```
  ）并将新基准包含在提交中。
所有选中的测试必须通过才能提交 — 与步骤1的停止条件相同。此处测试失败意味着需要修复或上报，切勿交付。

Step 3 — Design-rules check on touched UI

步骤3 — 对变更的UI进行设计规则检查

After the tests pass, hold the UI the diff touched to the design-rules rulebook — the same blast-radius scoping as Step 2, craft instead of behaviour. No UI in the diff → skip to Step 4.

Find the touched UI files — from the same touched-files set as Step 2, keep what renders user-facing UI (
```
*.tsx
```
/
```
*.jsx
```
,
```
*.css
```
, files under
```
components/
```
or
```
app/
```
); drop
```
app/api/*
```
,
```
*/route.ts(x)
```
, server-only modules, and
```
*.test.*
```
/
```
*.spec.*
```
. If none remain, say so and skip to Step 4.
Invoke the
design-rules
skill and review each touched surface against it: every element earns its place; hierarchy by size/contrast/spacing; 3 fonts / 3 colors and 60/30/10; calm and whitespace; CTA prominence; and the mobile rules (no side-by-side, no hover-only affordances, thumb-sized touch targets). For a public landing/marketing surface, run
```
/landing-audit
```
rather than eyeballing.
Fix cheap, clear breaks in passing; flag the rest for the user. Mobile correctness at 390px gates the ship; a desktop-only cosmetic issue does not (CLAUDE.md mobile-first).

测试通过后，对变更涉及的UI进行设计规则检查 — 与步骤2的影响范围相同，关注设计而非功能。如果变更未涉及UI，则跳过至步骤4。

找出变更的UI文件 — 从步骤2的变更文件集中筛选出渲染用户界面的文件（
```
*.tsx
```
/
```
*.jsx
```
、
```
*.css
```
、
```
components/
```
或
```
app/
```
目录下的文件）；排除
```
app/api/*
```
、
```
*/route.ts(x)
```
、仅服务端模块以及
```
*.test.*
```
/
```
*.spec.*
```
文件。如果没有符合条件的文件，则说明情况并跳过至步骤4。
调用
design-rules
技能，对照规则检查每个变更的界面元素：每个元素都有存在的意义；通过尺寸/对比度/间距体现层级；使用3种字体/3种颜色并遵循60/30/10原则；保持简洁并留足空白；突出CTA按钮；遵循移动端规则（无并排布局、无仅悬停交互、触摸目标符合拇指操作尺寸）。对于公开的落地页/营销页面，运行
```
/landing-audit
```
而非人工检查。
快速修复明显的问题；标记其余问题供用户处理。移动端在390px尺寸下的正确性是交付门槛；仅桌面端的 cosmetic 问题不影响交付（参考CLAUDE.md的移动端优先原则）。

Step 4 — Session log

步骤4 — 会话日志

If the project keeps

notes/session-log.md

, append a short entry: what changed, decisions made, gotchas, and anything worth promoting to CLAUDE.md.

如果项目维护

notes/session-log.md

文件，则添加一条简短记录：变更内容、做出的决策、注意事项以及任何值得写入CLAUDE.md的内容。

Step 5 — Commit and push

步骤5 — 提交并推送

This is a solo operation: commit directly on
main
and push. No feature branches, no PRs. (Only create a branch / open a PR if the user explicitly asks for a review step.)

Stage the relevant changes, write a clear conventional-commit message.
End the commit message with the project's required trailer if one exists:
```
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
```
Commit on
```
main
```
and
```
git push origin main
```
. Pushing
```
main
```
is what triggers the production deploy (and any deploy notifications).

这是独立操作：直接在
main
分支提交并推送。无需特性分支，无需PR。（仅当用户明确要求审核步骤时，才创建分支/打开PR。）

暂存相关变更，编写清晰的符合约定式提交（conventional-commit）规范的提交信息。
如果项目要求提交信息末尾添加特定 trailer，则按要求添加：
```
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
```
在
```
main
```
分支提交代码并执行
```
git push origin main
```
。推送
```
main
```
分支会触发生产环境部署（以及任何部署通知）。

Rules

规则

Validation and the relevant tests (Step 2) must be green before any commit. No exceptions.
"Relevant" means the diff's blast radius — Vitest
```
related
```
for unit/component plus any touched or surface-matching e2e specs. Don't run the full suite to ship; don't skip the relevant slice either.
When the diff touches UI, run the design-rules check (Step 3) on the touched UI files before commit — same blast-radius scoping as the tests, for craft.
Do not commit secrets or
```
.env*
```
files.
Report the commit SHA and what was pushed when done.

验证和相关测试（步骤2）必须全部通过才能提交代码，无例外。
"相关"指变更的影响范围 — 单元/组件测试使用Vitest的
```
related
```
模式，加上任何被修改或匹配功能表面的端到端测试用例。交付时不要运行完整测试套件；也不要跳过相关的测试部分。
如果变更涉及UI，则在提交前对变更的UI文件执行设计规则检查（步骤3） — 与测试的影响范围相同，关注设计质量。
切勿提交密钥或
```
.env*
```
文件。
完成后上报提交的SHA值以及推送的内容。