workitem-driven-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

工作项驱动的 Git 工作流

Work Item-Driven Git Workflow

触发条件：任务带 PingCode 工作项编号

#<Identifier>

（如

#ABC-42

），且用户要求开发、修复、实现、继续、评审或合并。没有编号的普通代码修改不要套用本 skill 的认领、评论、分支命名规则，按仓库自身规范执行。

PingCode 操作全部依赖 use-pingcode-cli
skill：先按它预检

pc

与登录，再使用本流程；不要臆造

pc

命令或参数。本 skill 只规定流程和 Git/文档规范，API 细节以

use-pingcode-cli

为准。

详细子流程、Feature 拆解、提交类型和反模式见

reference.md

。

Trigger condition: The task includes a PingCode work item identifier

#<Identifier>

(e.g.

#ABC-42

), and the user asks to develop, fix, implement, continue, review, or merge it. Do not apply this skill's claim, comment, or branch naming rules to ordinary code changes without an identifier; follow the repository's own conventions instead.

All PingCode operations depend entirely on the use-pingcode-cli
skill: first perform its

pc

and login prechecks, then use this workflow; do not invent

pc

commands or parameters. This skill defines only the workflow and Git/documentation standards; refer to

use-pingcode-cli

for API details.

Detailed sub-workflows, Feature breakdown, commit types, and anti-patterns are documented in

reference.md

硬规则

Hard Rules

不在集成分支（常见
```
develop
```
/
```
main
```
，以仓库实际保护规则为准）直接改文件、提交或推送；一切变更走工作分支 + PR。
不主动
```
commit
```
/
```
push
```
/ 合并 PR；除非用户明确要求。
危险操作（
```
reset --hard
```
、
```
restore
```
、
```
clean -fd
```
、
```
stash drop
```
、对已推送历史 rebase/amend、任何
```
push --force*
```
）执行前必须说明影响并征得确认；任何情况下都不对集成分支强制推送。
不声称执行过未实际运行的检查；CI 失败或缺失要如实说明。
需要长期保留的文档统一沉淀到
```
docs/
```
，不散落在源码目录、个人笔记或聊天记录里。

Never modify files, commit, or push directly on an integration branch (commonly
```
develop
```
/
```
main
```
, subject to the repository's actual protection rules); all changes must go through a work branch and PR.
Do not proactively
```
commit
```
,
```
push
```
, or merge a PR unless the user explicitly requests it.
Before performing dangerous operations (
```
reset --hard
```
,
```
restore
```
,
```
clean -fd
```
,
```
stash drop
```
, rebasing/amending already-pushed history, or any
```
push --force*
```
), explain the impact and obtain confirmation; never force-push to an integration branch under any circumstances.
Do not claim to have run checks that were not actually executed; report CI failures or missing checks honestly.
Long-term documentation must be centralized under
```
docs/
```
, not scattered across source directories, personal notes, or chat histories.

0. 识别编号与预检

0. Identify the Identifier and Perform Prechecks

从用户消息提取
```
#<Identifier>
```
，例如
```
#ABC-42
```
。调用
```
pc
```
时去掉
```
#
```
：
```
ABC-42
```
；分支名和 PR 标题保留
```
#
```
。
加载
```
use-pingcode-cli
```
，按它执行
```
pc doctor
```
；退出码非 0 时按失败项修复，不要继续。
用
```
pc whoami --json
```
确认当前用户：登录名取
```
identity.user.name
```
，用户 ID 取
```
identity.user.id
```
。后续“当前用户”都以此为准。
记录仓库文件夹名，供缓存和临时 worktree 使用：
bash
```
REPO_NAME="$(basename "$(git rev-parse --show-toplevel)")"
```

Extract
```
#<Identifier>
```
from the user's message, for example
```
#ABC-42
```
. Remove the
```
#
```
when invoking
```
pc
```
:
```
ABC-42
```
; retain the
```
#
```
in branch names and PR titles.
Load
```
use-pingcode-cli
```
and run
```
pc doctor
```
as specified by it; if the exit code is non-zero, resolve the failed checks and do not continue.
Use
```
pc whoami --json
```
to confirm the current user: use
```
identity.user.name
```
as the login name and
```
identity.user.id
```
as the user ID. The
```
current user
```
refers to this user throughout the rest of the workflow.
Record the repository folder name for use with the cache and temporary worktrees:
bash
```
REPO_NAME="$(basename "$(git rev-parse --show-toplevel)")"
```

1. 取工作项详情

1. Retrieve Work Item Details

bash

pc pjm workitem get ABC-42

必须用完整编号 get，不要用全局
```
pc pjm workitem list --identifier <数字>
```
取详情；不带
```
--project-id
```
时会跨项目命中同号工作项，结果有歧义。只有手里只有数字、拼不出完整编号时，才退回
```
pc pjm workitem list --project-id <pid> --identifier <n>
```
做项目内精确查询。

同时拉取评论与附件：

bash

pc comments list --principal-type workitem --principal-id <工作项id>

记录返回体的
```
id
```
、
```
project.id
```
、
```
type.id
```
、
```
state.id
```
、
```
assignee.id
```
、
```
parent_id
```
；后续类型/状态解析和写操作都用这些 id。
```
parent_id
```
非空时，拉父工作项的标题和描述，理解上层背景。
用
```
pc pjm workitem list --project-id <项目ID> --parent-id <工作项ID>
```
查子项：先只读标题掌握全貌，再按需读相关子项详情，不要一次拉全部。
Feature 拆解时，用
```
pc pjm workitem-relation list <工作项ID>
```
查关联工作项，按需读取。

bash

pc pjm workitem get ABC-42

Always use
get
with the full identifier. Do not use the global
```
pc pjm workitem list --identifier <number>
```
command to retrieve details; without
```
--project-id
```
, it may match work items with the same number across projects, resulting in ambiguity. Only fall back to
```
pc pjm workitem list --project-id <pid> --identifier <n>
```
for an exact project-scoped lookup when only the number is available and the full identifier cannot be reconstructed.

Fetch comments and attachments at the same time:

bash

pc comments list --principal-type workitem --principal-id <工作项id>

Record
```
id
```
,
```
project.id
```
,
```
type.id
```
,
```
state.id
```
,
```
assignee.id
```
, and
```
parent_id
```
from the response; use these IDs for subsequent type/state resolution and write operations.
When
```
parent_id
```
is not empty, retrieve the parent work item's title and description to understand the broader context.
Use
```
pc pjm workitem list --project-id <项目ID> --parent-id <工作项ID>
```
to query child work items: read titles only first to understand the full scope, then retrieve the details of relevant child work items as needed instead of fetching everything at once.
During Feature breakdown, use
```
pc pjm workitem-relation list <工作项ID>
```
to find related work items and retrieve them as needed.

2. 判断工作项类型

2. Determine the Work Item Type

用

pc pjm workitem-type list-for-project --project-id <项目ID>

解析项目内真实类型，按名称匹配，不要硬编码类型 id 或

story

bug

标签。

是 Feature / 产品需求：不要直接认领或开发，转入
```
reference.md
```
的「Feature 拆解流程」，先拆出可独立交付的用户故事。
不是 Feature（用户故事、任务、缺陷等执行类工作项）：继续第 3 步。

Use

pc pjm workitem-type list-for-project --project-id <项目ID>

to resolve the actual types within the project and match them by name. Do not hard-code type IDs or

story

bug

labels.

Feature / product requirement: Do not directly claim or develop it. Move to the
```
Feature Breakdown Process
```
in
```
reference.md
```
and first break it down into independently deliverable user stories.
Not a Feature (an executable work item such as a user story, task, or defect): Continue to Step 3.

3. 状态与负责人检查

3. Check the Status and Assignee

状态不是“打开/待处理”类初始状态时，向用户提示并询问是否继续，不自行继续。状态 id 用
```
pc pjm workitem-state list-for-project --project-id <pid> --workitem-type-id <type-id>
```
解析，按名称识别，不硬编码。
已设置负责人且不是当前用户时，向用户提示并询问是否继续。
需求、方案、验收标准不明确时不猜测，向用户提问直到明确。

If the status is not an initial state such as
```
Open
```
/
```
Pending
```
, notify the user and ask whether to continue; do not proceed on your own. Resolve state IDs using
```
pc pjm workitem-state list-for-project --project-id <pid> --workitem-type-id <type-id>
```
and identify them by name rather than hard-coding them.
If an assignee is already set and is not the current user, notify the user and ask whether to continue.
If the requirements, solution, or acceptance criteria are unclear, do not guess; ask the user until they are clear.

4. 认领（幂等）

4. Claim the Work Item (Idempotent)

负责人不是当前用户时，把负责人设为当前用户；状态不在“进行中”时，把状态置为进行中。目标值已就位就跳过对应写入，不要对当前状态重复发起流转（会报“工作项状态不能流转到当前状态”）。

bash

pc pjm workitem update <工作项id> --data '{"assignee_id":"<当前用户ID>"}'
pc pjm workitem update <工作项id> --data '{"state_id":"<进行中状态ID>"}'

写操作前先读工作项；写后重新
```
get
```
验证。
403/scope 不足时停下交用户处理，不要反复重试。

If the assignee is not the current user, set the assignee to the current user. If the state is not

In Progress

, transition it to

In Progress

. If the target value is already in place, skip the corresponding write and do not attempt to transition the current state again, because this causes a

work item state cannot transition to its current state

error.

bash

pc pjm workitem update <工作项id> --data '{"assignee_id":"<当前用户ID>"}'
pc pjm workitem update <工作项id> --data '{"state_id":"<进行中状态ID>"}'

Read the work item before performing a write operation, then run
```
get
```
again to verify it afterward.
On a 403 or insufficient scope, stop and ask the user to resolve it; do not retry repeatedly.

5. 理解、拆分与方案先行

5. Understand, Break Down, and Plan First

读标题、描述、评论、附件，结合父/子/关联工作项理解验收意图。
工作量较大（跨模块、多阶段、可并行）时，先提示用户是否创建子工作项（类型为任务），用户同意后再创建；再询问是否按顺序逐个领取执行。
先把方案与要改的文件告知用户，不要落盘；用户确认后才开始改代码。
沟通中明确的关键结论、范围边界、实施进展、完成总结，及时以纯文本评论发到工作项：
- 用换行分段、
```
-
```
  /
```
1.
```
  列点，不要写 HTML 标签。
- 需要 @ 人时用
```
[@<用户ID>|<登录名>]
```
  （用户 ID 经
```
pc organization user list
```
  解析）；只写
```
@登录名
```
  不会触发提及。
- 过程信息只留在工作项评论，不在本地另存副本。

Read the title, description, comments, and attachments, and use the parent, child, and related work items to understand the intended acceptance criteria.
If the work is substantial (cross-module, multi-stage, or parallelizable), first ask the user whether to create child work items of type
```
Task
```
. Create them only after the user agrees, then ask whether to claim and execute them one by one in order.
First present the proposed solution and the files to be changed to the user, without writing anything to disk; begin changing the code only after the user confirms.
Promptly post key conclusions, scope boundaries, implementation progress, and completion summaries to the work item as a plain-text comment:
- Use paragraph breaks and
```
-
```
  /
```
1.
```
  lists; do not use HTML tags.
- To mention someone, use
```
[@<用户ID>|<登录名>]
```
  (resolve the user ID with
```
pc organization user list
```
  ); writing only
```
@登录名
```
  will not trigger a mention.
- Keep process information only in work item comments; do not save a separate local copy.

6. 创建工作分支

6. Create a Work Branch

按顺序执行，任一步不满足就停下问用户：

bash

git rev-parse --abbrev-ref HEAD     # 应在集成分支
git status --porcelain              # 应为空
git fetch origin
git pull --ff-only                  # 落后时
git checkout -b '#ABC-42/(feat)user-login'

分支名格式：

#<Identifier>/(<type>)<kebab-简述>

，如

#ABC-42/(feat)user-login

、

#ABC-42/(fix)retry-timeout

。

Identifier 与分支名之间用
```
/
```
，不要用冒号；
```
#
```
可以出现在分支名中。
分支名先给用户确认；拿不准时
```
git check-ref-format --branch '<name>'
```
验证。
不在集成分支时不要自行切换；工作区不干净时让用户决定提交、stash 或丢弃。
所有修改与提交都在工作分支进行；切换分支需用户确认。

Run the following commands in order. Stop and ask the user if any precondition is not met:

bash

git rev-parse --abbrev-ref HEAD     # 应在集成分支
git status --porcelain              # 应为空
git fetch origin
git pull --ff-only                  # 落后时
git checkout -b '#ABC-42/(feat)user-login'

Branch naming format:

#<Identifier>/(<type>)<kebab-summary>

, for example

#ABC-42/(feat)user-login

#ABC-42/(fix)retry-timeout

Use
```
/
```
between the identifier and the branch name, not a colon;
```
#
```
is allowed in branch names.
Ask the user to confirm the branch name first; when uncertain, validate it with
```
git check-ref-format --branch '<name>'
```
.
If the current branch is not an integration branch, do not switch branches on your own; if the working tree is dirty, ask the user to choose whether to commit, stash, or discard the changes.
Make all changes and commits on the work branch; ask the user before switching branches.

7. 提交与 PR

7. Commit and Open a PR

提交前运行仓库文档或 CI 定义的验证；按受影响包/模块跑 lint、typecheck、test、build；不能运行要说明原因。
只暂存本任务相关文件；提交前看
```
git status
```
、
```
git diff
```
。

commit message 用 Conventional Commits：

<type>[optional scope]: <description>

，如

feat: #ABC-42 user-login

的拆分提交可写

feat(auth): add login form

。

PR 标题格式：

<type>: #<Identifier> <简述>

，如

feat: #ABC-42 user-login

。

经用户确认再
```
git push -u origin <branch>
```
并开 PR 到集成分支；PR 描述写清变更、原因、验证、风险与回滚。

默认 squash 合并：

gh pr merge <n> --squash --delete-branch

；不用

--merge

--rebase

--auto

，不用

--admin

绕过保护。

PR 落后 base（BEHIND）时：
```
git fetch origin
```
后 rebase 到
```
origin/<集成分支>
```
；不要用
```
--admin
```
，也不要把集成分支 merge 进工作分支。rebase 后复跑验证，经用户确认再
```
git push --force-with-lease
```
。
合并后确认 PR 为 MERGED，再切回集成分支
```
git pull --ff-only
```
并删除本地工作分支。

Before committing, run the validations defined by the repository's documentation or CI; run lint, typecheck, test, and build for each affected package or module, and explain why any check could not be run.
Stage only files relevant to this task; inspect
```
git status
```
and
```
git diff
```
before committing.
Use Conventional Commits for the commit message:
```
<type>[optional scope]: <description>
```
. For example, a split commit for
```
feat: #ABC-42 user-login
```
may use
```
feat(auth): add login form
```
.

PR title format:

<type>: #<Identifier> <summary>

, for example

feat: #ABC-42 user-login

After user confirmation, run
```
git push -u origin <branch>
```
and open a PR targeting the integration branch. The PR description must clearly state the changes, rationale, validation, risks, and rollback plan.
Use squash merging by default:
```
gh pr merge <n> --squash --delete-branch
```
; do not use
```
--merge
```
/
```
--rebase
```
/
```
--auto
```
, and do not use
```
--admin
```
to bypass protections.
If the PR is behind its base (
```
BEHIND
```
), run
```
git fetch origin
```
and rebase onto
```
origin/<integration-branch>
```
; do not use
```
--admin
```
, and do not merge the integration branch into the work branch. Rerun validation after rebasing and, after user confirmation, run
```
git push --force-with-lease
```
.
After merging, confirm that the PR is
```
MERGED
```
, switch back to the integration branch, run
```
git pull --ff-only
```
, and delete the local work branch.

8. 合并后收尾

8. Post-Merge Wrap-Up

复查工作项状态：已是完成态（如“已修复”/“已完成”，常由 PR 合并自动化流转）则不要重复设置，仅核对结果；否则才把状态置为完成态。
无论是否改状态，都追加一条纯文本总结评论：交付内容、验证结果、后续衔接。
不把过程信息另存本地；需要长期保留的经验按第 10 节沉淀。

Recheck the work item status: if it is already in a completed state (such as
Fixed
or
Completed
, often transitioned automatically by PR merge automation), do not set it again; only verify the result. Otherwise, transition it to the completed state.
Regardless of whether the status was changed, append a plain-text summary comment covering the delivered work, validation results, and any follow-up work.
Do not store process information locally; preserve long-term lessons according to Step 10.

9. Code Review（按需）

9. Code Review (As Needed)

对

#<Identifier>

或指定 PR 做评审时：

先查工作项状态与评论，确认没有进行中的评审或已有结论；有则停下告知用户，除非用户明确要求重新评审。
先发一条纯文本评论，注明当前用户开始 Code Review 与 PR 地址，作为占用标记。
在系统临时目录建独立只读 worktree，例如
```
<临时目录>/${REPO_NAME}-pr<n>
```
；不要在当前工作区执行 git 或构建操作。
只做代码与规范检查；是否运行 lint/test/构建按仓库评审策略，未运行不要声称运行过，CI 结果引用 PR status checks。
结论只用「通过 / 拒绝 / 不确定」并附理由，交用户选择。
PR 侧只发评审意见，不合并、不推送、不改作者分支；工作项侧只评论，不认领、不改状态、不改负责人。
结束移除 worktree 和临时分支。

When reviewing

#<Identifier>

or a specified PR:

First check the work item status and comments to confirm that there is no ongoing review or existing conclusion. If there is, stop and notify the user unless they explicitly request a new review.
First post a plain-text comment stating that the current user has started the Code Review and include the PR URL as an occupancy marker.
Create an isolated, read-only worktree in the system temporary directory, for example
```
<temp-dir>/${REPO_NAME}-pr<n>
```
; do not run Git or build operations in the current working tree.
Review only the code and standards compliance; whether to run lint, tests, or builds depends on the repository's review policy. Do not claim to have run checks that were not executed; cite PR status checks for CI results.
Conclusions must use only
```
Pass
```
/
```
Reject
```
/
```
Uncertain
```
, with reasons, and the user must choose the outcome.
On the PR side, only submit review comments; do not merge, push, or modify the author's branch. On the work item side, only comment; do not claim the work item or change its status or assignee.
When finished, remove the worktree and temporary branch.

10. 文档分层与信息沉淀

10. Documentation Layering and Knowledge Capture

docs/
是唯一的长期文档根目录。按主题建子目录：

目录	内容
`docs/product/`	产品目标、用户与场景、需求与交互决策
`docs/tech/`	跨包/跨组件的架构与技术决策，建议 `DESIGN_<主题>.md`
`docs/guide/`	新人上手指南、操作手册、排障手册
`docs/decisions/`	需要长期保留的决策记录（ADR）

文档解释 why，不复制接口 schema、字段表或代码可推导的事实；接口事实保持单一事实源。
每篇设计文档标注状态、上游文档与修订记录；推翻旧结论时追加修订记录，不静默改写。
包/模块
```
README.md
```
只保留最小入口与用法并链接
```
docs/
```
；不要在
```
src/
```
下建深层 docs 目录。
代码行为变化时，同 PR 更新受影响的
```
docs/
```
；文档未同步视为任务未完成。

信息分三类：

类型	去向	是否提交
可再发现的引用数据（ID、名称映射、状态值）	本机缓存，仅作提示	否
有团队价值的经验、结论、排障套路	询问用户确认后写入 `docs/` ，走 PR	是
任务过程信息（澄清、进展、总结）	工作项评论	否

缓存目录动态使用当前仓库文件夹名，不要写死：

bash

REPO_NAME="$(basename "$(git rev-parse --show-toplevel)")"
CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/$REPO_NAME"

按 host 分文件，条目带
```
fetchedAt
```
；默认 TTL 7 天。
API 实时结果永远优先；引用失效、状态不能流转、ID 找不到时，丢弃条目重新拉取并重试一次。
缓存损坏（非法 JSON）时忽略并重建；token、密钥、个人隐私不得写入。
收尾时主动盘点是否产生可复用知识，但写入前必须询问用户；用户拒绝则不保存，不得静默落盘。

docs/
is the only root directory for long-term documentation. Create subdirectories by topic:

Directory	Contents
`docs/product/`	Product goals, users and scenarios, requirements, and interaction decisions
`docs/tech/`	Cross-package or cross-component architecture and technical decisions; `DESIGN_<topic>.md` is recommended
`docs/guide/`	New developer onboarding guides, operation manuals, and troubleshooting guides
`docs/decisions/`	Decision records that need long-term retention (ADRs)

Documentation should explain why, not duplicate API schemas, field tables, or facts that can be derived from code; interface facts must have a single source of truth.
Every design document must indicate its status, upstream documents, and revision history. When an earlier conclusion is overturned, append a revision record rather than silently rewriting it.
Package/module
```
README.md
```
files should contain only a minimal entry point and usage instructions and link to
```
docs/
```
; do not create deeply nested docs directories under
```
src/
```
.
When code behavior changes, update the affected
```
docs/
```
in the same PR; documentation that is out of sync means the task is incomplete.

Information is divided into three categories:

Type	Destination	Committed?
Re-discoverable reference data (IDs, name mappings, state values)	Local cache, for reference only	No
Team-valuable lessons, conclusions, and troubleshooting patterns	Ask the user, then write to `docs/` and submit through a PR	Yes
Task process information (clarifications, progress, summaries)	Work item comments	No

The cache directory dynamically uses the current repository folder name and must not be hard-coded:

bash

REPO_NAME="$(basename "$(git rev-parse --show-toplevel)")"
CACHE_DIR="${XDG_CACHE_HOME:-$HOME/.cache}/$REPO_NAME"

Split files by host, include
```
fetchedAt
```
in each entry, and use a default TTL of 7 days.
Real-time API results always take precedence; if a reference has expired, a state cannot transition, or an ID cannot be found, discard the entry, fetch it again, and retry once.
If the cache is corrupted (invalid JSON), ignore it and rebuild it; never write tokens, secrets, or personal privacy data.
During wrap-up, proactively assess whether reusable knowledge was produced, but you must ask the user before writing it. If the user declines, do not save it, and never write it silently.