# Cx Plan

> CX 工作流 — 任务规划与契约下沉。当用户提到"规划任务"、"制定计划"、 "plan"、"拆分任务"时触发。读取设计文档（小功能则读取 PRD）， 生成任务分解，创建子任务文件并将契约下沉到任务中。 产物保存到本地 开发文档/CX工作流/功能/{feature_title}/任务/。

- Skill: `m19803261706/cx-plan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add m19803261706/cx-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/m19803261706/cx-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: m19803261706 (https://skillmd.com/u/m19803261706)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/m19803261706/cx-plan

---


# cx-plan: 任务规划与契约下沉

把需求或设计真正变成能执行的任务图，而不是再写一层描述文档。

先阅读：

- `${CLAUDE_PLUGIN_ROOT}/core/workflow/README.md`
- `${CLAUDE_PLUGIN_ROOT}/core/workflow/protocols/plan.md`

## 强制规则

**所有文件读写必须使用绝对路径。** 禁止使用 `../` 相对路径。先用 `git rev-parse --show-toplevel` 获取绝对路径。

## Worktree 检测（强制）

<HARD-GATE>
禁止在主分支（main/master）上执行规划阶段。必须在 feature worktree 中。
</HARD-GATE>

执行前检测：

```bash
check_output=$(bash ${CLAUDE_PLUGIN_ROOT}/scripts/cx-worktree.sh check \
  --feature "{feature-slug}" \
  --project-root "$(git rev-parse --show-toplevel)" 2>&1) || true
```

如果返回 `on_main=true`：
- 提示用户先运行 `/cx:cx-prd` 创建 worktree，或手动进入已有 worktree
- 用 `AskUserQuestion` 列出可用 worktree 供选择
- **不要继续执行规划阶段**

## 使用方法

```text
/cx:cx-plan {功能名}
/cx:cx-plan
```

## 规划原则

- 默认轻量，普通功能直接拆任务
- 仅当 PRD 明显引入新技术时，才进入技术识别和 skill 准备支线
- 任务目录使用中文显示名，状态关联始终用稳定 `slug`
- Claude Code 侧规划属于 runner `cc` 的 adapter 行为；共享 core 被 `codex` 持有时先建议 handoff
- 允许在用户明确确认“进入规划阶段”后，由工作流自动衔接到本 skill

## 核心步骤

### Step 0: 定位 feature 目录

```bash
PROJECT_ROOT=$(git rev-parse --show-toplevel)
CX_DOCS_DIR="$PROJECT_ROOT/开发文档/CX工作流"
FEATURE_TITLE="{功能标题}"
FEATURE_SLUG="{feature-slug}"
FEATURE_DIR="$CX_DIR/功能/$FEATURE_TITLE"
TASK_DIR="$FEATURE_DIR/任务"

mkdir -p "$TASK_DIR"
```

### Step 1: 选择规划输入

- 小功能：直接读取 `需求.md`
- 中大功能：读取 `设计.md`，必要时参考 `需求.md`

不再要求手工传 `--skip-design` 才能走轻量路径。

### Step 2: 新技术判断

仅当 PRD 明显引入新技术时，额外执行：

- 技术栈识别
- 现有项目兼容性检查
- 必要 skill 或外部文档准备

普通功能跳过这条支线，直接进入任务拆分。

### Step 3: 生成共享契约（跨层任务时 MUST）

**当任务图涉及 2 个及以上层级（前端+后端、后端+数据库等）时，
必须（MUST）先生成共享契约文件，再拆任务。**

契约文件位置：

```text
开发文档/CX工作流/功能/{功能标题}/契约.md
```

契约至少包含：

```markdown
## API 契约

| 接口 | 方法 | 路径 | 请求体 | 响应体 |
|------|------|------|--------|--------|
| 分类树 | GET | /api/case-volume-category/tree | - | CategoryTree[] |
| 案例列表 | GET | /api/historical-case/list | QueryParams | PageResult |

## 数据模型契约

| 字段 | 类型 | 说明 |
|------|------|------|
| id | number | 主键 |

## 状态/枚举契约

| 枚举名 | 值 | 说明 |
|--------|-----|------|
```

契约来源优先级：
1. 后端已有的路由/Controller → 读代码提取真实路径
2. Design 文档中定义的接口 → 直接引用
3. 都没有 → 在契约文件中新定义，前后端任务共同引用

**禁止前后端任务各自猜测 API 路径。**

### Step 4: 生成任务 DAG

每个任务至少包含：

- `number`
- `title`
- `phase`
- `depends_on`
- `parallel`
- 验收标准
- **引用的契约条目**（哪些 API、哪些数据模型）

跨层依赖规则：
- 前端任务依赖后端任务时，`depends_on` 必须显式声明
- 前端任务文档中必须写明引用的 API 路径（来自契约文件），不能自行定义
- 后端任务完成后，如果实际路径与契约不一致，必须先更新契约再继续

### Step 5: 写入任务文档

任务文件统一为：

```text
开发文档/CX工作流/功能/{功能标题}/任务/任务-1.md
开发文档/CX工作流/功能/{功能标题}/任务/任务-2.md
```

任务文档里要同时保留：

- 可见中文标题
- 稳定 `slug`
- 目标文件范围
- **引用的契约条目（精确到路径和字段）**
- 验收标准

### Step 5: 更新 feature 级状态

feature 级 `状态.json` 至少包含：

```json
{
  "feature": "功能标题",
  "slug": "feature-slug",
  "status": "planned",
  "tasks": [
    {
      "number": 1,
      "title": "建立接口骨架",
      "status": "pending"
    }
  ],
  "worktree": {
    "preferred_branch": "codex/vector-memory",
    "preferred_worktree_path": "/worktrees/vector-memory",
    "binding_status": "recommended"
  },
  "docs": {
    "prd": "需求.md",
    "design": "设计.md",
    "summary": "总结.md"
  }
}
```

### Step 6: 输出执行建议

规划完成后默认建议：

```text
下一步：/cx:cx-exec
执行开始时会询问：创建独立工作区 or 当前分支直接开始
```

如果任务图中存在清晰并行组，再在状态中标注 `parallel_group`，供 `/cx:cx-exec --all` 使用。