pma

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PMA - Project Management Assistant

PMA - 项目管理助理

Run delivery work with clear gates, minimal diffs, and explicit task/plan tracking.

通过清晰的审批关卡、最小化变更、明确的任务/计划跟踪来推进交付工作。

Hard Rules

硬性规则

Use one project content language for docs, task files, and commit messages (follow user preference, otherwise follow existing project language).
Read before write: inspect call chains, related config/tests, and recent changelog context before editing logic.
Make only the minimal requested changes; do not add unrequested refactors or features.
Never use plan mode (
```
EnterPlanMode
```
,
```
mode: "plan"
```
). Manage plans in
```
docs/plan/
```
files only.
Do not implement before explicit confirmation (
```
proceed
```
).
Use English filenames only, even when project content is Chinese (for example:
```
architecture.md
```
,
```
changelog.md
```
).

文档、任务文件和提交消息统一使用同一种项目内容语言（遵循用户偏好，否则沿用现有项目的语言）。
先读再改：编辑逻辑前先梳理调用链、相关配置/测试用例，以及近期的变更日志上下文。
仅做需求明确要求的最小变更，不要添加未被要求的重构或功能。
绝对不要使用计划模式（
```
EnterPlanMode
```
、
```
mode: "plan"
```
），仅通过
```
docs/plan/
```
下的文件管理计划。
未获得明确确认（
```
proceed
```
）前不要执行开发。
即使项目内容是中文，也仅使用英文文件名（例如：
```
architecture.md
```
、
```
changelog.md
```
）。

Three-Phase Workflow

三阶段工作流

Phase 1: Investigation

阶段1：调研

Trace upstream/downstream call chains, symbol references, and types.
Search related code, config, tests, migrations, and docs.
Read the tail of
```
docs/changelog.md
```
for recent context.
Find or create the matching task in
```
docs/task/index.md
```
and claim it (
```
[-]
```
).

Non-trivial task rule:

If the change touches
```
>=3
```
files or crosses modules, create
```
docs/plan/PLAN-NNN.md
```
and write findings to the context section.

梳理上下游调用链、符号引用和类型定义。
检索相关代码、配置、测试用例、数据迁移脚本和文档。
阅读
```
docs/changelog.md
```
的末尾内容了解近期项目上下文。
在
```
docs/task/index.md
```
中找到或创建匹配的任务，并进行认领（标记为
```
[-]
```
）。

非 trivial 任务规则：

如果变更涉及
```
≥3
```
个文件或跨模块，需要创建
```
docs/plan/PLAN-NNN.md
```
，并将调研结果写入上下文部分。

Phase 2: Proposal

阶段2：提案

Output these items, then stop for approval:

Current state
Proposal
Risks
Scope
Alternatives (if multiple approaches exist)

For non-trivial tasks:

Complete remaining sections in
```
PLAN-NNN.md
```
.
Append one line to
```
docs/plan/index.md
```
with
```
[ ]
```
.
Wait for user annotations and address all of them before implementation.

输出以下内容后暂停，等待审批：

当前现状
提案方案
潜在风险
影响范围
替代方案（如果存在多种实现思路）

对于非 trivial 任务：

完成
```
PLAN-NNN.md
```
中剩余的所有章节。
在
```
docs/plan/index.md
```
中追加一行记录，标记为
```
[ ]
```
。
等待用户批注，处理完所有批注后再进入开发阶段。

Phase 3: Implement -> Verify -> Record

阶段3：执行→验证→记录

Only after approval:

If a plan exists, set plan index marker to
```
[-]
```
and detail
```
status
```
to
```
implementing
```
.
Implement step by step according to the approved proposal.
Run focused self-verification.
Set task index marker to
```
[x]
```
and task detail
```
status
```
to
```
completed
```
.
If a plan exists, set plan index marker to
```
[x]
```
and plan detail
```
status
```
to
```
completed
```
.
Update changelog as needed.

仅在获得审批后执行：

如果存在对应计划，将计划索引的标记设为
```
[-]
```
，并将详情中的
```
status
```
设为
```
implementing
```
。
按照审批通过的提案逐步执行开发。
执行针对性的自验证。
将任务索引的标记设为
```
[x]
```
，并将任务详情的
```
status
```
设为
```
completed
```
。
如果存在对应计划，将计划索引的标记设为
```
[x]
```
，并将计划详情的
```
status
```
设为
```
completed
```
。
按需更新变更日志。

Task and Plan Files

任务和计划文件

Use these canonical references instead of redefining formats in-place:

Task format: docs/task-format.md
Plan format: docs/plan-format.md

Required structure:

```
docs/task/index.md
```
: one-line task entries
```
docs/task/PREFIX-NNN.md
```
: task detail files
```
docs/plan/index.md
```
: one-line plan entries
```
docs/plan/PLAN-NNN.md
```
: plan detail files

使用以下标准规范，不要临时自定义格式：

任务格式：docs/task-format.md
计划格式：docs/plan-format.md

要求的目录结构：

```
docs/task/index.md
```
：单行任务条目列表
```
docs/task/PREFIX-NNN.md
```
：任务详情文件
```
docs/plan/index.md
```
：单行计划条目列表
```
docs/plan/PLAN-NNN.md
```
：计划详情文件

Claim-Before-Work (Multi-Agent Safety)

先认领再工作（多Agent安全机制）

Before writing any implementation code:

Read
```
docs/task/index.md
```
; for
```
[-]
```
items, read detail
```
owner
```
.
If another agent owns the in-progress task, skip it.
Claim atomically:
- Update task index
```
[ ] -> [-]
```
- Update task detail
```
status -> in_progress
```
  , set
```
owner
```
- Call
```
TaskUpdate(status: "in_progress", owner: "<agent>")
```
  if task tools are available
Start implementation only after the claim is fully written.

On completion:

Set task index
```
[-] -> [x]
```
Set task detail
```
status -> completed
```
Call
```
TaskUpdate(status: "completed")
```
if task tools are available

On close/won't do:

Set task index to
```
[~]
```
Set task detail
```
status -> closed
```
and record reason
Call
```
TaskUpdate(status: "deleted")
```
if task tools are available

编写任何实现代码前：

阅读
```
docs/task/index.md
```
；对于标记为
```
[-]
```
的条目，查看详情中的
```
owner
```
字段。
如果另一个Agent是该进行中任务的负责人，跳过该任务。
原子化认领：
- 将任务索引标记从
```
[ ]
```
  更新为
```
[-]
```
- 将任务详情的
```
status
```
  更新为
```
in_progress
```
  ，设置
```
owner
```
  字段
- 如果有可用的任务工具，调用
```
TaskUpdate(status: "in_progress", owner: "<agent>")
```
仅在认领操作完全写入后再开始开发。

任务完成时：

将任务索引标记从
```
[-]
```
更新为
```
[x]
```
将任务详情的
```
status
```
更新为
```
completed
```
如果有可用的任务工具，调用
```
TaskUpdate(status: "completed")
```

任务关闭/不做时：

将任务索引标记设为
```
[~]
```
将任务详情的
```
status
```
更新为
```
closed
```
并记录原因
如果有可用的任务工具，调用
```
TaskUpdate(status: "deleted")
```

Sync Rules

同步规则

Task status updates are immediate, never deferred.

Primary source is files in
```
docs/task/
```
and
```
docs/plan/
```
.
If
```
TaskCreate
```
/
```
TaskUpdate
```
tools are available, keep tool state in sync with file state.
If task tools are unavailable, continue with file-only sync and state this in the progress update.

Session checklist:

Session start: read
```
docs/task/index.md
```
, active task details, and
```
docs/plan/index.md
```
.
New task: create detail file first, then append index line.
Before work: complete Claim-Before-Work.
Session end: verify statuses are written and update index header date.

任务状态更新需要立即执行，不得延迟。

状态的唯一可信来源是
```
docs/task/
```
和
```
docs/plan/
```
下的文件。
如果有可用的
```
TaskCreate
```
/
```
TaskUpdate
```
工具，需要保持工具状态与文件状态同步。
如果没有可用的任务工具，继续仅通过文件同步状态，并在进度更新中说明该情况。

会话检查清单：

会话开始时：读取
```
docs/task/index.md
```
、活跃任务详情和
```
docs/plan/index.md
```
。
新增任务时：先创建详情文件，再在索引中追加条目。
开发前：完成「先认领再工作」流程。
会话结束时：确认所有状态已写入，并更新索引头部的日期。

Documentation System

文档体系

Canonical structure:

text

docs/
├── task/
│   ├── index.md
│   └── PREFIX-NNN.md
├── plan/
│   ├── index.md
│   └── PLAN-NNN.md
├── architecture.md
└── changelog.md

Use English sections for English-language projects.
Use Chinese template sections for Chinese-language projects while keeping filenames in English.
Write investigation findings into the plan context section.
Do not create extra report files; temporary files go to
```
./tmp/
```
.

标准结构：

text

docs/
├── task/
│   ├── index.md
│   └── PREFIX-NNN.md
├── plan/
│   ├── index.md
│   └── PLAN-NNN.md
├── architecture.md
└── changelog.md

英文项目使用英文章节。
中文项目使用中文模板章节，但文件名保持英文。
调研结果写入计划的上下文章节。
不要创建额外的报告文件，临时文件存入
```
./tmp/
```
目录。

Changelog Conventions

变更日志规范

Entry format:

markdown

undefined

条目格式：

markdown

undefined

YYYY-MM-DD HH:MM [tag]

[content]


Recommended tags:
- `[progress]`, `[BUG-P0]`, `[BUG-P1]`, `[pitfall]`, `[decision]`

[content]


推荐标签：
- `[progress]`、`[BUG-P0]`、`[BUG-P1]`、`[pitfall]`、`[decision]`

Project Initialization

项目初始化

On first use in a project:

Ensure
```
CLAUDE.md
```
contains a
```
## Project Development
```
section that references
```
/pma
```
and the three-phase workflow.
Ensure
```
AGENTS.md
```
contains the same section.
Ensure
```
docs/task/index.md
```
exists (initialize from docs/task-format.md).
Ensure
```
docs/plan/index.md
```
exists (initialize from docs/plan-format.md).
Ensure core docs exist (
```
architecture.md
```
+
```
changelog.md
```
), and keep content language aligned with the project.

在项目中首次使用时：

确保
```
CLAUDE.md
```
包含
```
## Project Development
```
章节，引用
```
/pma
```
和三阶段工作流。
确保
```
AGENTS.md
```
包含相同的章节。
确保
```
docs/task/index.md
```
存在（从docs/task-format.md初始化）。
确保
```
docs/plan/index.md
```
存在（从docs/plan-format.md初始化）。
确保核心文档存在（
```
architecture.md
```
+
```
changelog.md
```
），并保持内容语言与项目对齐。

Tools and Security

工具与安全

Prefer semantic code navigation tools for architecture understanding.
Check official docs (e.g., Context7) before using third-party APIs.
Use code/web search tools for examples and troubleshooting when needed.
Verify UI behavior after UI edits.
Keep secrets in
```
.env
```
; never hardcode or log secrets.
Mark risky commands with an explicit warning comment.

优先使用语义代码导航工具理解架构。
使用第三方API前查阅官方文档（例如Context7）。
需要时使用代码/网页搜索工具查找示例和排查问题。
UI编辑后验证UI行为是否符合预期。
密钥存储在
```
.env
```
中，绝对不要硬编码或打印密钥。
给高风险命令添加明确的警告注释。