feature-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Feature Design Skill

Purpose

目的

Transform a feature idea into a structured design document through collaborative dialogue. This is Phase 1 of the feature lifecycle pipeline (design → plan → implement → validate → release).

通过协作对话将功能想法转化为结构化的设计文档。这是功能生命周期流水线的第一阶段（设计→规划→实现→验证→发布）。

Operator Context

操作者上下文

Hardcoded Behaviors (Always Apply)

硬编码行为（始终适用）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before design
Over-Engineering Prevention: Design only what's requested. Don't add speculative requirements.
State Management via Script: All state operations go through
```
python3 ~/.claude/scripts/feature-state.py
```
Gate Enforcement: Check gate status before proceeding past decision points
Design Doc Required: Phase CANNOT complete without a design document artifact in
```
.feature/state/design/
```
ADR for Design Decisions: Write an ADR to
```
adr/{feature-name}.md
```
documenting architectural decisions made during design exploration. Register the ADR session (
```
python3 ~/.claude/scripts/adr-query.py register --adr adr/{name}.md
```
) so sub-phase skills (feature-plan, feature-implement) receive design context via hook injection.
Branch Safety: Create feature branch via worktree, never work on main

CLAUDE.md 合规性：设计前需阅读并遵循仓库中的CLAUDE.md
防止过度设计：仅设计所需内容，不要添加推测性需求
通过脚本管理状态：所有状态操作需通过
```
python3 ~/.claude/scripts/feature-state.py
```
执行
关卡强制执行：在决策点前进前需检查关卡状态
必须生成设计文档：若
```
.feature/state/design/
```
中无设计文档工件，本阶段无法完成
设计决策的ADR记录：编写ADR文档至
```
adr/{feature-name}.md
```
，记录设计探索过程中做出的架构决策。注册ADR会话（
```
python3 ~/.claude/scripts/adr-query.py register --adr adr/{name}.md
```
），以便子阶段技能（feature-plan、feature-implement）通过钩子注入获取设计上下文。
分支安全：通过工作区创建功能分支，绝不要在主分支上工作

Default Behaviors (ON unless disabled)

默认行为（默认开启，除非禁用）

Collaborative Dialogue: Ask clarifying questions before committing to an approach
Multiple Approaches: Generate 2-3 approaches with trade-offs before selecting
Context Loading: Read L0 and L1 context at phase start

协作对话：在确定方案前提出澄清问题
多方案对比：生成2-3种方案并分析权衡点后再做选择
上下文加载：阶段开始时加载L0和L1上下文

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，除非启用）

Auto-approve gates: Skip human approval for design gates (requires config)

自动批准关卡：跳过设计关卡的人工审批（需配置）

What This Skill CAN Do

本技能可实现的功能

Facilitate design discussion with the user
Produce structured design documents
Initialize feature state and worktree
Load and update feature context hierarchy

促进与用户的设计讨论
生成结构化的设计文档
初始化功能状态和工作区
加载和更新功能上下文层级

What This Skill CANNOT Do

本技能不可实现的功能

Skip design and go straight to code
Produce implementation plans (that's feature-plan)
Write code (that's feature-implement)
Modify published context directly (retro loop only)

跳过设计直接进入编码阶段
生成实现计划（该功能属于feature-plan）
编写代码（该功能属于feature-implement）
直接修改已发布的上下文（仅可通过回溯循环修改）

Instructions

操作步骤

Phase 0: PRIME

阶段0：准备（PRIME）

Goal: Initialize feature state and load context.

Initialize feature state:

bash

python3 ~/.claude/scripts/feature-state.py init "FEATURE_NAME"

Load L0 context:

bash

python3 ~/.claude/scripts/feature-state.py context-read "" L0

Load L1 design context:

bash

python3 ~/.claude/scripts/feature-state.py context-read "" L1 --phase design

If existing L2 context is relevant, load on-demand:

bash

python3 ~/.claude/scripts/feature-state.py context-read "" L2 --phase design

Surface relevant seeds (ADR-075): Check
```
.seeds/index.json
```
for dormant seeds whose trigger conditions match the current feature. Compare the feature name and description against each seed's
```
trigger
```
field using fuzzy keyword overlap. If matches are found, present them:
```
## Relevant Seeds (N matched)

### seed-YYYY-MM-DD-slug [Scope]
Trigger: "trigger condition"
Rationale: Why this matters...
Action: What to do when triggered
Breadcrumbs: file1.go, file2.py

> Incorporate into current design? [yes/no/defer]
```
- yes: Include the seed's action and rationale as a design input for Phase 1. Mark seed as
```
active
```
  in index.json.
- no: Dismiss the seed (move to
```
.seeds/archived/
```
  , status
```
dismissed
```
  ).
- defer: Leave the seed dormant for future surfacing.
If
```
.seeds/
```
does not exist or contains no dormant seeds, skip this step silently.

Gate: Feature state initialized. Context loaded. Seeds surfaced (if any). Proceed to Execute.

目标：初始化功能状态并加载上下文。

初始化功能状态：

bash

python3 ~/.claude/scripts/feature-state.py init "FEATURE_NAME"

加载L0上下文：

bash

python3 ~/.claude/scripts/feature-state.py context-read "" L0

加载L1设计上下文：

bash

python3 ~/.claude/scripts/feature-state.py context-read "" L1 --phase design

若现有L2上下文相关，按需加载：

bash

python3 ~/.claude/scripts/feature-state.py context-read "" L2 --phase design

展示相关种子（ADR-075）：检查
```
.seeds/index.json
```
中触发条件与当前功能匹配的休眠种子。使用模糊关键词匹配，将功能名称和描述与每个种子的
```
trigger
```
字段对比。若找到匹配项，展示如下：
```
## 相关种子（共N个匹配）

### seed-YYYY-MM-DD-slug [范围]
触发条件: "触发条件内容"
理由: 为何此种子相关...
操作: 触发时需执行的动作
关联文件: file1.go, file2.py

> 是否将其纳入当前设计？[是/否/延后]
```
- 是：将种子的操作和理由作为设计输入纳入阶段1。在index.json中将种子标记为
```
active
```
  。
- 否：驳回种子（移至
```
.seeds/archived/
```
  ，状态设为
```
dismissed
```
  ）。
- 延后：保留种子为休眠状态，供后续展示。
若
```
.seeds/
```
不存在或无休眠种子，静默跳过此步骤。

关卡：功能状态已初始化，上下文已加载，种子已展示（若有）。进入执行阶段。

Phase 1: EXECUTE (Design Dialogue)

阶段1：执行（设计对话）

Goal: Collaborative exploration of the feature requirements and approach.

Step 1: Understand Requirements

Check gate:

python3 ~/.claude/scripts/feature-state.py gate FEATURE design.intent-discussion

If gate mode is

human

Ask clarifying questions about the feature, one at a time
Prefer multiple-choice when possible
Establish success criteria
Identify constraints

If gate mode is

auto

Derive intent from the feature description
Document assumptions explicitly

Step 2: Explore Approaches

Check gate:

python3 ~/.claude/scripts/feature-state.py gate FEATURE design.approach-selection

Generate 2-3 approaches:

markdown

undefined

目标：协作探索功能需求与实现方案。

步骤1：明确需求

检查关卡：

python3 ~/.claude/scripts/feature-state.py gate FEATURE design.intent-discussion

若关卡模式为

human

：

逐个提出关于功能的澄清问题
尽可能使用选择题形式
确定成功标准
识别约束条件

若关卡模式为

auto

：

从功能描述中推导意图
明确记录假设条件

步骤2：探索实现方案

检查关卡：

python3 ~/.claude/scripts/feature-state.py gate FEATURE design.approach-selection

生成2-3种实现方案：

markdown

undefined

Approach 1: [Name]

方案1: [名称]

Pros: [advantages] Cons: [disadvantages] Complexity: Low/Medium/High Risk: Low/Medium/High Domain agents needed: [which agents from our system would implement this]


If gate is `human`: present approaches and ask user to select.
If gate is `auto`: select the approach that best balances simplicity and completeness.

**Step 3: Draft Design Document**

Create the design document:

```markdown

优势: [优点] 劣势: [缺点] 复杂度: 低/中/高风险: 低/中/高 所需领域Agent: [系统中需负责实现此方案的Agent]


若关卡模式为`human`：展示方案并请用户选择。
若关卡模式为`auto`：选择平衡简洁性与完整性的最佳方案。

**步骤3：起草设计文档**

创建设计文档：

```markdown

Design: [Feature Name]

设计: [功能名称]

Problem Statement

问题陈述

[What problem does this solve?]

[此功能解决什么问题？]

Requirements

需求

Requirement 1
Requirement 2

需求1
需求2

Selected Approach

选定方案

[Which approach and why]

[选择的方案及理由]

Components

组件

[What needs to be built/modified]

[需要构建/修改的内容]

Domain Agents

领域Agent

[Which agents from our system will handle implementation]

[系统中负责实现的Agent]

Open Questions

未解决问题

[Anything unresolved]

[任何未确定的事项]

Trade-offs Accepted

已接受的权衡

[What we're giving up and why]


**Gate**: Design document drafted. Proceed to Validate.

[我们做出的妥协及理由]


**关卡**：设计文档已起草。进入验证阶段。

Phase 2: VALIDATE

阶段2：验证

Goal: Verify design document is complete.

Check gate:

python3 ~/.claude/scripts/feature-state.py gate FEATURE design.design-approval

Validation checklist:

Problem statement is clear
Requirements are enumerable (not vague)
Approach is selected with rationale
Components are identified
Domain agents are identified
Open questions are listed (even if empty)

If gate is

human

: present design to user for approval. If gate is

auto

: verify checklist passes.

Gate: Design approved. Proceed to Checkpoint.

目标：验证设计文档的完整性。

检查关卡：

python3 ~/.claude/scripts/feature-state.py gate FEATURE design.design-approval

验证清单：

问题陈述清晰明确
需求可枚举（非模糊表述）
已选择方案并说明理由
已识别组件
已识别领域Agent
已列出未解决问题（即使为空）

若关卡模式为

human

：将设计文档提交给用户审批。若关卡模式为

auto

：验证清单是否全部通过。

关卡：设计文档已批准。进入 checkpoint 阶段。

Phase 3: CHECKPOINT

阶段3：CHECKPOINT

Goal: Save artifacts, run retro pipeline, advance.

Save design document:

bash

echo "DESIGN_CONTENT" | python3 ~/.claude/scripts/feature-state.py checkpoint FEATURE design

Record learnings — if this phase produced non-obvious insights, record them:

bash

python3 ~/.claude/scripts/learning-db.py record TOPIC KEY "VALUE" --category design

Advance to plan phase:

bash

python3 ~/.claude/scripts/feature-state.py advance FEATURE

Suggest next step:

Design complete. Run /feature-plan to break this into implementation tasks.

Gate: Artifacts saved. Retro complete. Phase finished.

目标：保存工件，运行回溯流水线，推进至下一阶段。

保存设计文档：

bash

echo "DESIGN_CONTENT" | python3 ~/.claude/scripts/feature-state.py checkpoint FEATURE design

记录经验 — 若本阶段产生非显而易见的见解，记录如下：

bash

python3 ~/.claude/scripts/learning-db.py record TOPIC KEY "VALUE" --category design

推进至规划阶段：

bash

python3 ~/.claude/scripts/feature-state.py advance FEATURE

建议下一步操作：

设计已完成。运行 /feature-plan 将其拆解为实现任务。

关卡：工件已保存，回溯已完成。本阶段结束。

Error Handling

错误处理

Error	Cause	Solution
Feature already exists	`init` called twice	Use `status` to check, work with existing state
Gate returns exit 2	Human input required	Present decision to user, wait for response
No design doc produced	Skipped design dialogue	Return to Phase 1, complete all steps

错误	原因	解决方案
功能已存在	重复调用 `init`	使用 `status` 检查状态，基于现有状态继续工作
关卡返回退出码2	需要人工输入	将决策提交给用户，等待响应
未生成设计文档	跳过了设计对话	返回至阶段1，完成所有步骤

Anti-Patterns

反模式

Anti-Pattern	Why Wrong	Do Instead
Skip design, go straight to code	Undesigned features require rework	Complete design dialogue first
Design everything at once	Over-engineering	Design only what's needed for this feature
Ignore existing context	Loses previous learnings	Load L0/L1 at prime

反模式	问题所在	正确做法
跳过设计直接编码	未经设计的功能需要返工	先完成设计对话
一次性设计所有内容	过度设计	仅设计当前功能所需的内容
忽略现有上下文	丢失之前的经验	在准备阶段加载L0/L1上下文

References

参考资料

Gate Enforcement
Anti-Rationalization
Retro Loop
State Conventions
Plant Seed — seed-based deferred work surfaced in Phase 0 (ADR-075)

关卡强制执行
反合理化
回溯循环
状态约定
Plant Seed — 在阶段0中展示的基于种子的延迟工作（ADR-075）