| name | design-improve |
| description | Gyeol 프로젝트 UI/UX 지속 개선. Material Design 3 + flutter_flow_chart 기반. TDD 위젯 테스트 동반. |
절대 규칙
- Main은 Task 호출만 반복, 결과 수신 후 즉시 다시 Task 호출
- 멈추지 않는다 — 커밋 후, 에러 후, 개선항목 없어도 계속
- 정지: 사용자가 "stop"/"중지"/"잠깐" 명시 입력만
- 1사이클 = 1개선, 같은 파일 연속 수정 금지
- 포맷 외 출력 금지 — "요약", "총정리" 절대 출력 안 함
- 서브태스크 30분 초과 시 중지 후 새 Task로 재시작 (N 유지)
- 모든 UI 수정은 위젯 테스트 동반 (TDD)
- 수정 대상이 lib/features/ 또는 lib/shared/ 이면 flutter-engineer 사용
- 수정 후 반드시 quality-guard로 빌드 검증
디자인 시스템 아키텍처
테마 계층
MaterialApp.theme (lib/core/theme/app_theme.dart)
├── ColorScheme (Seed color 기반 자동 생성)
│ ├── primary / onPrimary / primaryContainer
│ ├── secondary / onSecondary / secondaryContainer
│ ├── tertiary / onTertiary / tertiaryContainer
│ ├── error / onError / errorContainer
│ ├── surface / onSurface / surfaceVariant
│ ├── outline / outlineVariant
│ └── inverseSurface / inversePrimary
├── TextTheme (google_fonts 기반)
│ ├── headlineLarge/Medium/Small
│ ├── titleLarge/Medium/Small
│ ├── bodyLarge/Medium/Small
│ └── labelLarge/Medium/Small
└── Component themes (CardTheme, AppBarTheme, etc.)
컴포넌트 계층
공통 위젯 (lib/shared/widgets/)
├── AppShell — 앱 셸 (BottomNavigationBar + 라우팅)
├── StatusBadge — 상태 뱃지 (Pending=warning, Running=info, Done=success, Failed=error)
├── EmptyState — 빈 상태 (icon + title + description + action)
├── PageHeader — 페이지 공통 헤더 (icon + title + description + action)
└── StatCard — 통계 카드 (label + value + icon + trend)
그래프 위젯 (lib/features/layers/graph/)
├── FlowCanvas — flutter_flow_chart 메인 캔버스
├── LayerNodeWidget — 커스텀 노드 (상태 표시, 워커 수, 타입 뱃지)
├── NodeDetailPanel — 노드 상세 패널 (편집, 워커 목록)
└── graph_utils — Layer[] → 노드/엣지 변환 유틸리티
Main 루프
반복해서 Task 호출:
Task(
subagent_type: "general",
prompt: "Cycle N 실행. 아래 절차와 포맷 준수.
Phase 1 — 분석:
아래 탐지 명령어로 디자인 편차 탐지:
탐지 명령어 (순서대로 실행):
1. rg 'Colors\.' lib/ --line-number -n | rg -v ' Colors\.transparent| Colors\.white| Colors\.black|app_theme'
→ 하드코딩 Material Colors (Theme.of(context).colorScheme 사용 필요)
2. rg 'TextStyle\(' lib/ --line-number -n | rg -v 'context'
→ Theme 없는 직접 TextStyle 생성 (Theme.of(context).textTheme 사용 필요)
3. rg 'EdgeInsets\.(all|symmetric|only)\(' lib/ --line-number -c | sort -t: -k3 -n
→ 반복 패딩 패턴 (상수 또는 공통 위젯 추출 후보)
4. rg 'SizedBox\(' lib/ --line-number -c | sort -t: -k3 -n
→ 반복 간격 패턴
5. flutter analyze 2>&1
6. flutter test 2>&1
우선순위:
P0: 하드코딩 색상 (Colors.xxx 직접 사용)
P1: 테스트 없는 위젯 (위젯 테스트 작성 필요 — TDD)
P2: 반복 패턴 (동일 위젯 조합 3회 이상 → 공통 위젯 추출)
P3: 접근성 (Semantics, tooltip, label 누락)
P4: 마이크로 인터랙션 (애니메이션, 트랜지션)
Phase 2 — 선택:
분석 결과에서 최우선 1개 선택.
Phase 3 — 수정 (TDD):
수정 대상이 lib/ 이면 Task(flutter-engineer) 호출.
수정 원칙:
- 색상: 항상 Theme.of(context).colorScheme.* 사용 — Colors.xxx 직접 사용 금지
- 타이포그래피: 항상 Theme.of(context).textTheme.* 사용 — TextStyle() 직접 생성 금지
- 간격: 반복 패턴은 상수 또는 공통 위젯으로 추출
- 상태색: StatusBadge 위젯 사용 (success/warning/error/info)
- 새 위젯: lib/shared/widgets/에만 생성, Material Design 3 스타일 준수
- 그래프: LayerNodeWidget도 테마 토큰 사용
반드시 Red-Green-Refactor 순서:
1. Red: 위젯 테스트 먼저 작성 → flutter test → 실패 확인
2. Green: 최소 위젯 코드 작성 → flutter test → 통과 확인
3. Refactor: 정리 → flutter test → 회귀 없음 확인
수정 완료 후 Task(quality-guard) 호출하여 빌드 검증.
회귀 발생 시 즉시 원복.
금지: pubspec.yaml 의존성 추가, .g.dart 수동 수정, Drift 스키마 변경.
Phase 4 — 커밋:
3사이클마다 git add + commit/push.
Phase 5 — 완료:
완료 시간 출력. `date '+%Y-%m-%d %H:%M:%S'` 실행 후 아래 포맷으로 출력.
출력 포맷 (이 형식 외 출력 금지):
[Phase 1] {분석요약} | {편차수}개 | 위젯테스트커버리지: {N}/{M}
[PROCEED TO Phase 2]
[Phase 2] {파일} | {이슈} | P{등급}
[PROCEED TO Phase 3]
[Phase 3] {에이전트} | {TDD단계} | {변경내용} | analyze:{결과} test:{통과/총수}
[PROCEED TO Phase 4]
[Phase 4] C{N}: {WHAT} — {WHY}
[PROCEED TO Phase 5]
[DONE C{N}] {YYYY-MM-DD HH:MM:SS}
"
)
Sub 결과 수신 → 즉시 같은 Task 다시 호출.
색상 매핑 참조
docs/domain/conventions.md의 색상 매핑 테이블 참조.
검증 체크리스트 (quality-guard)
수정 후 반드시 순서대로 실행:
flutter analyze — 정적 분석dart format --set-exit-if-changed lib/ test/ — 포맷팅flutter test — 전체 테스트- 하나라도 실패 시 즉시
git checkout -- {파일} 원복
타임아웃 처리
서브태스크가 30분(1,800,000ms) 이상 실행되면:
- Task 호출 시
timeout: 1800000 설정
- 타임아웃/에러 발생 시 동일 N으로 새 Task 즉시 재시작
- 이전 사이클에서 수정 중이던 내용은 무시하고 깨끗한 상태에서 시작
- 재시작 프롬프트에 "이전 C{N} 타임아웃으로 재시작" 명시
