feature-qa

Feature-level QA Health Score evaluation and baseline regression tracking

항목	내용
Invoke	/feature-qa
Aliases	/qa, /quality-check
Category	kobic-development
Complexity	moderate

/feature-qa — 기능 품질 건강검진#

한마디로#

완성한 기능을 건강검진하듯 5개 항목으로 점수 매기고 A~F 등급을 매기는 도구입니다. 지난번 점수와 비교해서 "예전보다 나빠진 곳"이 있는지도 알려줍니다.

누가·언제 쓰나요#

개발자가 기능을 다 만든 직후 품질이 괜찮은지 확인하고 싶을 때
PR(코드 제출)을 올리기 전 마지막 점검(품질 게이트)으로
이미 있던 기능이 예전보다 나빠지지 않았는지 다시 확인하고 싶을 때

무엇을 해주나요#

기능을 5가지 관점으로 채점해 100점 만점 점수와 A~F 등급을 줍니다.
- 기능 완성도(30%), 화면/UX(20%), 접근성(20%), 성능(15%), 다국어(15%)
결과를 한눈에 보이는 점수판(막대그래프) 으로 보여주고, 발견된 문제를 표로 정리합니다.
채점 결과를 .qa-baseline/{기능이름}.json 파일에 자동 저장해 기준점(baseline) 으로 삼습니다.
다음번 검사 때 이 기준점과 비교해 좋아졌는지·나빠졌는지(회귀) 리포트를 만들어 줍니다.

어떻게 쓰나요#

# 기본: 기능 폴더 경로를 지정해 검사
/feature-qa feature/auth/

# 지난번 기준점과 비교 (좋아졌나 나빠졌나)
/feature-qa feature/auth/ --regression

# 빠른 점검 (기능 완성도만)
/feature-qa feature/auth/ --quick

# 특정 항목만 집중 검사
/feature-qa feature/auth/ --focus ui,a11y

# 5개 항목 동시 검사 (Agent Teams 필요, 더 빠름)
/feature-qa feature/auth/ --parallel

맨 앞의 기능 경로(feature/auth/ 등)는 반드시 필요합니다.
--focus에 넣을 수 있는 항목: ui(화면), a11y(접근성), perf(성능), i18n(다국어), func(기능).
기준점 저장은 기본적으로 자동입니다. 저장하지 않으려면 --no-save를 붙이세요.

안에서 무슨 일이 벌어지나요#

지정한 기능을 5개 관점으로 채점합니다 — 기능 완성도, 화면/UX, 접근성, 성능, 다국어.
각 항목 점수에 비중을 곱해 더하고, 심각한 문제 1건당 10점씩 깎아 총점과 등급(A~F) 을 계산합니다.
결과를 점수판과 문제 목록으로 보여주고, .qa-baseline/ 폴더에 기준점 파일로 저장합니다.
--regression을 쓰면 저장돼 있던 지난 기준점과 비교해 항목별 증감 리포트를 만들어 줍니다.
--parallel을 쓰면 항목들을 여러 팀이 동시에 검사해 더 빠르게 끝냅니다. (불가능하면 자동으로 순차 검사로 전환)

⚙️ 상세 옵션·실행 명세 (개발자 / AI 에이전트용)

Triggers#

After feature implementation for quality verification
As a quality gate before PR creation
To check quality regression of existing features

Usage#

# Basic usage: QA by feature path
/feature-qa feature/auth/

# Regression comparison (against previous baseline)
/feature-qa feature/auth/ --regression

# Quick check (functional completeness only)
/feature-qa feature/auth/ --quick

# Specific axis only
/feature-qa feature/auth/ --focus ui,a11y

# Parallel evaluation (Agent Teams)
/feature-qa feature/auth/ --parallel

Parameters#

Parameter	Required	Description	Example
`feature_path`	✅	Feature module path	`feature/auth/`
`--regression`	❌	Compare against previous baseline
`--quick`	❌	Quick check (functional completeness only)
`--focus`	❌	Focus on specific axes	`ui`, `a11y`, `perf`, `i18n`, `func`
`--parallel`	❌	5-axis parallel evaluation (requires Agent Teams)
`--save-baseline`	❌	Save baseline (default: auto-save)
`--no-save`	❌	Do not save baseline

5-Axis Evaluation System#

Functional Completeness — Weight 30%#

Item	Points	Inspection Method
Acceptance Criteria met	30	Map issue AC to implementation code
Edge case handling	25	Check null/empty/boundary handling
Error handling	25	try-catch, ErrorState, user messages
Test coverage	20	UseCase 100%, BLoC 80%+ target

Inspection Items:

Are all ACs mapped to implementation code
Is null safety handled properly
Is there user feedback on network errors
Is empty list state (EmptyState) handled
Is loading state displayed

UI/UX (Visual) — Weight 20%#

Item	Points	Inspection Method
Correct CoUI component usage	30	Verify component API compliance
Layout consistency	25	Gap/Insets constants used, alignment
Color system compliance	25	appColors/colorScheme used
Typography compliance	20	context.textStyles used

Inspection Items:

Are CoUI component APIs used correctly (features parameter, etc.)
Are Gap/Insets constants used (no hardcoded values)
Are colors accessed via context.appColors / context.colorScheme
Are text styles accessed via context.textStyles
Are non-existent APIs like ButtonSize.medium not used

Accessibility — Weight 20%#

Item	Points	Inspection Method
Semantic Labels	35	Labels present on images, icons, buttons
Touch target size	30	Minimum 48x48 verified
Color contrast	20	WCAG AA criteria
Screen reader order	15	Logical tab order

Inspection Items:

Do Image/Icon have semanticLabel
Are touchable elements at least 48x48
Is text-background color contrast 4.5:1 or above
Are widgets arranged in a meaningful order

Performance — Weight 15%#

Item	Points	Inspection Method
const widget usage	30	Check const-eligible widgets
BlocBuilder optimization	25	buildWhen/listenWhen usage
Image optimization	25	cacheWidth/cacheHeight applied
Resource cleanup	20	dispose/cancel verified

Inspection Items:

Are const-eligible widgets declared as const
Is buildWhen applied to BlocBuilder
Do network images have cacheWidth/cacheHeight
Are Stream subscriptions cancelled in dispose
Is BLoC isClosed checked in async handlers

Internationalization (i18n) — Weight 15%#

Item	Points	Inspection Method
Translation key usage	40	context.t.* pattern used
No hardcoded strings	30	UI text hardcoding detection
Pluralization handling	15	plural/ordinal applied
Dynamic value parameterization	15	Parameters instead of string interpolation

Inspection Items:

Do all UI texts use context.t.*
Are there no hardcoded Korean/English strings
Is pluralization handled for texts containing numbers
Are dynamic values passed as parameters

Health Score Calculation#

Score Computation#

Total = Sum(each axis score x weight) - (Critical issue count x 10)

Each axis score = Sum(item scores) / 100 x 100

Grade Criteria#

Grade	Score Range	Meaning
A	90-100	Excellent — production ready
B	80-89	Good — minor improvements needed
C	70-79	Average — improvements recommended
D	60-69	Insufficient — improvements required
F	0-59	Poor — must fix before PR creation

Baseline Storage and Regression Comparison#

Baseline Storage#

Automatically saved to .qa-baseline/{feature-name}.json on QA execution:

{
   " feature " :  " auth " ,
   " date " :  " 2026-03-13T10:30:00Z " ,
   " grade " :  " B " ,
   " totalScore " : 85,
   " scores " : {
     " functional " : {  " score " : 90,  " weight " : 0.30,  " weighted " : 27.0 },
     " visual " : {  " score " : 80,  " weight " : 0.20,  " weighted " : 16.0 },
     " accessibility " : {  " score " : 75,  " weight " : 0.20,  " weighted " : 15.0 },
     " performance " : {  " score " : 85,  " weight " : 0.15,  " weighted " : 12.75 },
     " i18n " : {  " score " : 90,  " weight " : 0.15,  " weighted " : 13.5 }
  },
   " criticalIssues " : 0,
   " penalty " : 0,
   " issues " : [
    {
       " axis " :  " accessibility " ,
       " severity " :  " warning " ,
       " message " :  " semantic label missing " ,
       " file " :  " lib/src/presentation/widget/author_card.dart " ,
       " line " : 42
    }
  ]
}

Regression Comparison#

When using the --regression option, compares against the previous baseline:

## Regression Report: auth

| Axis | Previous | Current | Change |
|------|----------|---------|--------|
| Functional Completeness | 90 | 92 | ✅ +2 |
| UI/UX | 80 | 80 | ➡️ 0 |
| Accessibility | 75 | 70 | ⚠️ -5 |
| Performance | 85 | 88 | ✅ +3 |
| i18n | 90 | 90 | ➡️ 0 |
| **Total** | **85 (B)** | **84 (B)** | ⚠️ -1 |

### Regression Items (score decrease)
- ♿ Accessibility -5 points: semanticLabel missing on newly added ProfileImage

Output Format#

╔════════════════════════════════════════════════════════════════╗
║  Feature QA Health Score: auth                                ║
╠════════════════════════════════════════════════════════════════╣
║                                                                ║
║  Grade: B (85/100)                                             ║
║                                                                ║
║  🧪 Functional     ████████████████████░░  90/100 (×0.30 = 27.0) ║
║  🎨 UI/UX          ████████████████░░░░░░  80/100 (×0.20 = 16.0) ║
║  ♿ Accessibility   ███████████████░░░░░░░  75/100 (×0.20 = 15.0) ║
║  ⚡ Performance     ████████████████░░░░░░  85/100 (×0.15 = 12.8) ║
║  🌐 i18n           ████████████████████░░  90/100 (×0.15 = 13.5) ║
║                                                                ║
║  Critical: 0 items | Penalty: 0 points                         ║
║  Baseline: Saved (.qa-baseline/auth.json)                      ║
║                                                                ║
╚════════════════════════════════════════════════════════════════╝

### Issues Found (5 items)

| # | Axis | Severity | Issue | File |
|---|------|----------|-------|------|
| 1 | ♿ Accessibility | ⚠️ | semantic label missing | author_card.dart:42 |
| 2 | ⚡ Performance | ⚠️ | cacheWidth not specified | author_image.dart:15 |
| 3 | 🌐 i18n | 💡 | hardcoded string | author_list_page.dart:28 |
| 4 | 🎨 UI/UX | 💡 | SizedBox used instead of Gap | author_form.dart:55 |
| 5 | 🧪 Functional | 💡 | EmptyState not handled | author_list_bloc.dart:30 |

Parallel Evaluation (`--parallel`, Agent Teams)#

Prerequisites#

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 environment variable set
If Agent Teams unavailable, automatically falls back to sequential evaluation

Parallel Execution Flow#

When --parallel option is used:

1. Check Agent Teams availability
   helpers.md#Check-Agent-Teams-Available
   → Falls back to sequential evaluation if unavailable

2. 3-team parallel evaluation (3 Teammates)

   ├─ Teammate 1: Functional Completeness (30%)
   │   ├─ Acceptance Criteria met
   │   ├─ Edge case handling
   │   ├─ Error handling
   │   └─ Test coverage
   │
   ├─ Teammate 2: UI/UX (20%) + Accessibility (20%)
   │   ├─ Correct CoUI component usage
   │   ├─ Layout/color/typography consistency
   │   ├─ Semantic Labels
   │   ├─ Touch target size
   │   └─ Color contrast
   │
   └─ Teammate 3: Performance (15%) + i18n (15%)
       ├─ const widgets / BlocBuilder optimization
       ├─ Image optimization / resource cleanup
       ├─ Translation key usage
       └─ Hardcoded string detection

3. Lead merges results
   ├─ helpers.md#Collect-Team-Results
   ├─ Sum each axis score and apply weights
   ├─ Critical issue count x 10 point penalty
   └─ Final grade calculation (A~F)

Fallback (Sequential Evaluation)#

If Agent Teams unavailable, runs 5-axis sequential evaluation as before.

Automation#

# Run tests (for coverage verification)
melos run test:with-html-coverage -- --scope= " *auth* " 

 # Static analysis
melos run analyze -- --scope= " *auth* " 

 # Code review (detailed)
/code-review feature/auth/ --gate-mode

/code-review - 8-category code review
/checklist:feature-complete - Feature complete checklist
/dev:run - Full development cycle (can be auto-invoked at Step 8.7)

feature-qa

/feature-qa — 기능 품질 건강검진#

한마디로#

누가·언제 쓰나요#

무엇을 해주나요#

어떻게 쓰나요#

안에서 무슨 일이 벌어지나요#

Triggers#

Usage#

Parameters#

5-Axis Evaluation System#

Functional Completeness — Weight 30%#

UI/UX (Visual) — Weight 20%#

Accessibility — Weight 20%#

Performance — Weight 15%#

Internationalization (i18n) — Weight 15%#

Health Score Calculation#

Score Computation#

Grade Criteria#

Baseline Storage and Regression Comparison#

Baseline Storage#

Regression Comparison#

Output Format#

Parallel Evaluation (--parallel, Agent Teams)#

Prerequisites#

Parallel Execution Flow#

Fallback (Sequential Evaluation)#

Automation#

Related Commands#

Parallel Evaluation (`--parallel`, Agent Teams)#