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:

ScenarioCharacteristicsWorkflowSimple IssueChange color, text, spacing, config valuesSimplified: Read code → Change directlyBug FixFix errors, exceptions, unexpected behaviorMust analyze cause. Simple bugs use simplified workflow, complex bugs use full workflowComplex IssueNew features, logic optimization, multi-file changes, architecture involvedFull 5-step workflowRefactoringCore flow changes, large-scale code adjustmentsFull 5-step workflow

---

Scenario 1: Simple Issue (Simplified Workflow)#

What Counts as Simple Issue#

• UI adjustments: change color, font size, spacing, borders
• Text modifications: change copy, hints, labels
• Config modifications: change defaults, parameters
• Single-file small changes: doesn't affect other modules

Simplified Workflow#

text

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:

• Read button code → Find color setting → Change to blue → Done

---

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

text

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

text

Follow the full 5-step workflow

Judgment Criteria#

Simple BugComplex BugClear error message, can locate directlyCause unclear, needs investigationSmall change scope, 1-2 placesInvolves multiple files/modulesDoesn't affect other featuresMay cause chain reactionsDoesn't involve core logicNeeds to change core flow

---

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

What Counts as Complex Issue#

• Adding new features
• Optimizing logic/performance
• Changes involving multiple files
• Architecture adjustments
• Requires design proposals

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:

text

## 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:

text

## 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

• Optimization should be incremental, not a rewrite
• Keep core logic and data flow
• Only make local improvements

Output Format:

text

## 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:

text

## 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:

• Keep communication, ask user for important decisions
• Complete one step before starting next
• If plan needs adjustment, ask user first

---

Scenario 4: Refactoring (Full 5-Step Workflow)#

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

Characteristics of refactoring:

• Changes to core flow
• Large-scale code adjustments
• Involves multiple modules
• May affect existing features

---

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#

• UI layout adjustments (spacing, colors, fonts)
• Simple logic changes (conditionals, parameter adjustments)
• Already familiar API usage
• Similar implementation exists in project for reference

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#

ScenarioWorkflowSimple IssueRead code → Change directlySimple BugAnalyze cause → Fix directlyComplex BugFull 5 stepsComplex IssueFull 5 stepsRefactoringFull 5 steps

Full 5 Steps#

StepActionOutput1Understand globallyProject overview2Analyze current stateStrengths/bottlenecks/weaknesses3Propose planOptimization points/what not to change4List plan and askStep list + confirmation questions5Execute after confirmationDevelop 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.