cx-design

cx-design: technical design and execution contract

Lock down the key decisions, interface contracts, and testing priorities of medium-to-large features before moving into task planning.

Read first:

• ${CLAUDE_PLUGIN_ROOT}/core/workflow/README.md
• ${CLAUDE_PLUGIN_ROOT}/core/workflow/protocols/design.md

Mandatory rules

All file reads and writes must use absolute paths. Do not use ../ relative paths. First use git rev-parse --show-toplevel to get the absolute path.

Worktree detection (mandatory)

Detect before execution:

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

If it returns on_main=true：

• Prompt the user to first run /cx:cx-prd to create a worktree, or manually enter an existing worktree
• Use AskUserQuestion to list available worktrees for selection
• Do not continue with the design phase

How to use

/cx:cx-design {功能名}
/cx:cx-design

Design principles

• Only serves medium-to-large features; S-scale is skipped by default
• The design document is an execution contract, not a lengthy essay
• Prioritize locking down APIs, state enums, field mappings, risk points, and testing priorities
• Claude Code is an cc adapter on the shared cx core, and must not bypass leases to directly overwrite other runners' features
• After the user explicitly confirms "enter the design phase", the workflow is allowed to automatically hand off to this skill

Core steps

Step 0: Locate project-level truth

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"
PRD_FILE="$FEATURE_DIR/需求.md"
DESIGN_FILE="$FEATURE_DIR/设计.md"

Internal references always use slug, while directory display uses Chinese titles.

Step 1: Read requirements and existing implementation

• Read 需求.md
• Scan adjacent modules, interface conventions, DTO/VO, state enums
• Identify reusable code and boundaries that must change

Step 2: Generate the execution contract

The design document must contain at least these sections:

1. Architecture boundaries and module decomposition
2. API interface contracts
3. State enum comparison table
4. VO/DTO field mappings
5. Risk points and testing priorities

Step 3: Confirm key contracts with checkbox Q&A

Have the user confirm these high-risk items:

• Interface paths and response structures
• Database or state model changes
• Compatibility and migration risks

Ordinary implementation details do not need frequent interruptions.

Step 4: Write to project documents and update status

Prefer calling the shared runner:

bash ${CLAUDE_PLUGIN_ROOT}/scripts/cx-workflow-design.sh \
  --feature <feature-slug> \
  --runner cc \
  --session-id <session-id>

Write to:

开发文档/CX工作流/功能/{功能标题}/设计.md

At the same time, advance the feature status to a plannable stage, for example:

{
  "slug": "feature-slug",
  "status": "planned",
  "docs": {
    "prd": "需求.md",
    "design": "设计.md"
  }
}

When an ADR is needed

Only when these situations arise should entering /cx:cx-adr：

• Clearly introduces new technology
• Storage or communication solutions involve substantive trade-offs
• Major architectural adjustments
• Reversibility cost or rollback cost is very high