feature-modification-workflow

Feature Modification Workflow

A standardized workflow for modifying existing features, ensuring changes are well-founded, controlled, and incremental.

Core Principles

Understand First, Then Modify — Before any feature change, understand the relevant code to ensure the change direction is correct.

Choose Workflow by Scenario — Simple issues get simplified workflow, complex issues get full workflow. No unnecessary overhead.

Check Docs When Needed — Only check latest documentation when dealing with complex technical details or specific API usage. Simple changes don't need this.

Conservative Optimization — Optimize without changing existing flows and core logic. Avoid high-risk large-scale refactoring.

Confirm Before Execute — Complex changes require user confirmation before development begins.

Step 1: Determine Scenario

After receiving a user request, first determine which scenario it falls into, then choose the corresponding workflow:

| Scenario | Characteristics | Workflow | |----------|-----------------|----------| | Simple Issue | Change color, text, spacing, config values | Simplified: Read code → Change directly | | Bug Fix | Fix errors, exceptions, unexpected behavior | Must analyze cause. Simple bugs use simplified workflow, complex bugs use full workflow | | Complex Issue | New features, logic optimization, multi-file changes, architecture involved | Full 5-step workflow | | Refactoring | Core flow changes, large-scale code adjustments | Full 5-step workflow |

Scenario 1: Simple Issue (Simplified Workflow)

What Counts as Simple Issue

Simplified Workflow

1. Read relevant code (only the part to change)
2. Make the change
3. Inform user it's done

Example

User: Change the login button color to blue

AI:

Scenario 2: Bug Fix (Must Analyze Cause)

Core Requirement

Bug fixes must first locate the cause. Don't change code based on guessing.

Simple Bug (Simplified Workflow)

Characteristics: Cause is clear, small change scope, doesn't affect other features

1. Analyze current state: locate bug cause
2. Fix directly
3. Inform user it's done

Complex Bug (Full Workflow)

Characteristics: Cause unclear, involves multiple modules, may affect other features, requires architecture changes

Follow the full 5-step workflow

Judgment Criteria

| Simple Bug | Complex Bug | |------------|-------------| | Clear error message, can locate directly | Cause unclear, needs investigation | | Small change scope, 1-2 places | Involves multiple files/modules | | Doesn't affect other features | May cause chain reactions | | Doesn't involve core logic | Needs to change core flow |

Scenario 3: Complex Issue (Full 5-Step Workflow)

What Counts as Complex Issue

Full Workflow

#### Step 1: Understand the Project Globally

After receiving a feature change request, don't start coding directly. First do the following:

1. Understand project structure - Use Glob to view directory structure - Identify core modules and dependencies - Find relevant config files, entry files

2. Read key files - Project documentation (CLAUDE.md, README.md, etc.) - Core module implementation files - Files directly related to the change target

3. Understand existing flows - How data flows - How modules communicate - What the user interaction flow is

Output Format:

## Project Overview
Project type: xxx
Core modules: xxx, xxx, xxx
Data flow: xxx → xxx → xxx
Related Modules
Module A: responsible for xxx
Module B: responsible for xxx
Dependencies: A → B → C

#### Step 2: Analyze Current State

After understanding the project, analyze the current state of the change target:

1. Current implementation analysis - How is current code implemented - What technologies/patterns are used - What key design decisions were made

2. Identify strengths - What's good about current implementation - Which designs are reasonable and worth keeping

3. Identify bottlenecks - Where are performance bottlenecks - Where are UX bottlenecks - Where are maintainability bottlenecks

4. Identify weaknesses - Code quality issues - Design flaws - Extensibility limitations

Output Format:

## Current State Analysis
Current Implementation
[Describe current implementation]
Strengths
xxx
xxx
Bottlenecks/Weaknesses
xxx: [specific description]
xxx: [specific description]

#### Step 3: Propose Optimization Plan

Based on analysis, propose optimization plan. Key constraint: don't change existing flow

Output Format:

## Optimization Plan
Overview
[Briefly describe optimization approach]
Optimization Points
1. xxx: [specific change, expected effect]
2. xxx: [specific change, expected effect]
What Not to Change
xxx: [why to keep]
Risk Assessment
Change scope: [large/medium/small]
Affected modules: xxx, xxx
Note: xxx

#### Step 4: List Plan and Ask User

Break down the optimization plan into specific steps, list the plan and ask user for confirmation:

Output Format:

## Development Plan
Step List
1. [ ] Step 1: xxx
2. [ ] Step 2: xxx
3. [ ] Step 3: xxx
Confirmation Questions
Does the above plan meet your expectations?
Any steps need adjustment or addition?
Can I start execution?

Wait for user response. Don't start development on your own.

#### Step 5: Execute Step by Step After Confirmation

After user confirms:

1. Use TodoWrite to create task list, track progress 2. Develop step by step 3. Mark completion and inform user after each step 4. Report issues promptly, don't bypass problems

During development:

Scenario 4: Refactoring (Full 5-Step Workflow)

Refactoring must follow the full workflow because of high risk and large impact scope.

Characteristics of refactoring:

Conditional Step: Check Documentation

Not all changes need documentation check. Only check in these cases:

When to Check Documentation

1. Complex technical details - Audio processing algorithms (sample rate conversion, silence detection) - Network protocol details (WebSocket frame format, Protobuf encoding) - Multi-threading/concurrency issues (thread safety, lock mechanisms)

2. Unsure about specific API usage - Framework API parameter meaning unclear - Library function best practices - API changes after version updates

3. Involves specifications or standards - Data format specifications - Protocol standard documents - Security/compliance requirements

When NOT to Check Documentation

Documentation Check Tools Priority

1. Context7 (mcp__context7__resolve-library-id + mcp__context7__query-docs) - Latest docs for programming libraries/frameworks - PySide6, React, numpy, etc.

2. WebSearch - Protocol specifications, technical articles - WebSocket protocol, best practice articles

Quick Reference

Scenario-Workflow Mapping

| Scenario | Workflow | |----------|----------| | Simple Issue | Read code → Change directly | | Simple Bug | Analyze cause → Fix directly | | Complex Bug | Full 5 steps | | Complex Issue | Full 5 steps | | Refactoring | Full 5 steps |

Full 5 Steps

| Step | Action | Output | |------|--------|--------| | 1 | Understand globally | Project overview | | 2 | Analyze current state | Strengths/bottlenecks/weaknesses | | 3 | Propose plan | Optimization points/what not to change | | 4 | List plan and ask | Step list + confirmation questions | | 5 | Execute after confirmation | Develop step by step |

Conditional: Check documentation (for complex technical issues)

Remember: Determine scenario first, then choose workflow. Handle simple issues simply, plan complex issues carefully.

User: Change the login button color to blue

AI: