애플리케이션 현대화 계획

# 목표

현재 워크플로를 깨뜨리거나 광범위한 리팩터링에 위험을 숨기지 않으면서 애플리케이션을 더 깔끔하고 빠르며 유지보수하기 쉬운 제품으로 이동합니다. 작업은 변경된 각 표면에 대한 증거와 함께 작고 리뷰 가능한 단위로 반영해야 합니다.

# 원칙

• 경계가 명확하게 변경 부담, 성능 비용, 또는 사용자에게 보이는 버그를 유발하지 않는 한 현재 아키텍처를 유지합니다.
• 각 문제에 대해 가장 작은 올바른 패치를 우선 적용한 뒤 반복합니다.
• 필수 수정과 선택적 다듬기를 분리하여 유지관리자가 주관적 결정에 기다리지 않고 가치가 높은 작업을 반영할 수 있게 합니다.
• Plugin 대상 동작은 문서화하고 이전 버전과 호환되게 유지합니다.
• 회귀가 수정되었다고 주장하기 전에 출시된 동작, 의존성 계약, 테스트를 검증합니다.
• 주요 사용자 경로를 먼저 개선합니다: 온보딩, 인증, 채팅, 제공자 설정, Plugin 관리, 진단.

# 1단계: 기준 감사

변경하기 전에 현재 애플리케이션을 인벤토리화합니다.

• 주요 사용자 워크플로와 이를 소유하는 코드 표면을 식별합니다.
• 사용되지 않는 어포던스, 중복 설정, 불명확한 오류 상태, 비용이 큰 렌더링 경로를 나열합니다.
• 각 표면의 현재 검증 명령을 기록합니다.
• 문제를 필수, 권장, 선택으로 표시합니다.
• 특히 API, 보안, 릴리스, Plugin 계약 변경처럼 소유자 리뷰가 필요한 알려진 차단 요소를 문서화합니다.

완료 기준:

• 저장소 루트 기준 파일 참조가 포함된 문제 목록 하나.
• 각 문제에는 심각도, 소유자 표면, 예상 사용자 영향, 제안된 검증 경로가 있습니다.
• 추측성 정리 항목은 필수 수정에 섞지 않습니다.

# 2단계: 제품 및 UX 정리

눈에 보이는 워크플로를 우선하고 혼란을 제거합니다.

• 모델 인증, Gateway 상태, Plugin 설정 주변의 온보딩 문구와 빈 상태를 다듬습니다.
• 가능한 동작이 없는 곳에서는 사용되지 않는 어포던스를 제거하거나 비활성화합니다.
• 중요한 동작을 취약한 레이아웃 가정 뒤에 숨기지 말고 반응형 너비 전반에서 보이게 유지합니다.
• 반복되는 상태 문구를 통합하여 오류의 단일 진실 공급원을 둡니다.
• 핵심 설정은 빠르게 유지하면서 고급 설정에는 점진적 공개를 추가합니다.

권장 검증:

• 최초 실행 설정과 기존 사용자 시작의 수동 성공 경로.
• 라우팅, 구성 지속성, 상태 파생 로직에 대한 집중 테스트.
• 변경된 반응형 표면의 브라우저 스크린샷.

# 3단계: 프런트엔드 아키텍처 강화

광범위한 재작성 없이 유지보수성을 개선합니다.

• 반복되는 UI 상태 변환을 좁은 타입 지정 헬퍼로 이동합니다.
• 데이터 가져오기, 지속성, 표현 책임을 분리해 유지합니다.
• 새 추상화보다 기존 훅, 스토어, 컴포넌트 패턴을 우선합니다.
• 결합도를 줄이거나 테스트를 명확하게 할 때만 지나치게 큰 컴포넌트를 분리합니다.
• 로컬 패널 상호작용을 위해 광범위한 전역 상태를 도입하지 않습니다.

필수 가드레일:

• 파일 분리의 부수 효과로 공개 동작을 변경하지 않습니다.
• 메뉴, 대화상자, 탭, 키보드 탐색의 접근성 동작을 그대로 유지합니다.
• 로딩, 빈 상태, 오류, 낙관적 상태가 계속 렌더링되는지 검증합니다.

# 4단계: 성능 및 신뢰성

광범위한 이론적 최적화보다 측정된 문제를 대상으로 합니다.

• 시작, 라우트 전환, 큰 목록, 채팅 기록 비용을 측정합니다.
• 프로파일링으로 가치가 입증되는 곳에서는 반복되는 비용 큰 파생 데이터를 메모화된 선택자나 캐시된 헬퍼로 대체합니다.
• 주요 경로에서 피할 수 있는 네트워크 또는 파일시스템 스캔을 줄입니다.
• 모델 페이로드 구성 전에 프롬프트, 레지스트리, 파일, Plugin, 네트워크 입력에 대해 결정적 순서를 유지합니다.
• 주요 헬퍼와 계약 경계에 가벼운 회귀 테스트를 추가합니다.

완료 기준:

• 각 성능 변경은 기준값, 예상 영향, 실제 영향, 남은 격차를 기록합니다.
• 저렴한 측정이 가능한 경우 어떤 성능 패치도 직감만으로 반영하지 않습니다.

# 5단계: 타입, 계약, 테스트 강화

사용자와 Plugin 작성자가 의존하는 경계 지점의 정확성을 높입니다.

• 느슨한 런타임 문자열을 판별 유니언이나 닫힌 코드 목록으로 대체합니다.
• 외부 입력은 기존 스키마 헬퍼나 zod로 검증합니다.
• Plugin 매니페스트, 제공자 카탈로그, Gateway 프로토콜 메시지, 구성 마이그레이션 동작 주변에 계약 테스트를 추가합니다.
• 호환성 경로는 시작 시 숨겨진 마이그레이션 대신 doctor 또는 repair 흐름에 유지합니다.
• Plugin 내부에 대한 테스트 전용 결합을 피하고, SDK 파사드와 문서화된 배럴을 사용합니다.

권장 검증:

• pnpm check:changed
• 변경된 모든 경계에 대한 대상 테스트.
• 지연 경계, 패키징, 또는 게시된 표면이 변경될 때 pnpm build.

# 6단계: 문서 및 릴리스 준비

사용자 대상 문서를 동작과 일치하게 유지합니다.

• 동작, API, 구성, 온보딩, 또는 Plugin 변경과 함께 문서를 업데이트합니다.
• 변경 로그 항목은 사용자에게 보이는 변경에만 추가합니다.
• 사용자 대상에는 Plugin 용어를 유지하고, 내부 패키지 이름은 기여자에게 필요한 곳에서만 사용합니다.
• 릴리스 및 설치 지침이 현재 명령 표면과 여전히 일치하는지 확인합니다.

완료 기준:

• 관련 문서는 동작 변경과 같은 브랜치에서 업데이트됩니다.
• 생성된 문서 또는 API 드리프트 검사가 변경된 경우 통과합니다.
• 인계 내용에는 건너뛴 검증과 그 이유를 명시합니다.

# 권장 첫 단위

범위가 제한된 Control UI 및 온보딩 점검부터 시작합니다.

• 최초 실행 설정, 제공자 인증 준비 상태, Gateway 상태, Plugin 설정 표면을 감사합니다.
• 사용되지 않는 동작을 제거하고 실패 상태를 명확히 합니다.
• 상태 파생과 구성 지속성에 대한 집중 테스트를 추가하거나 업데이트합니다.
• pnpm check:changed를 실행합니다.

이는 제한된 아키텍처 위험으로 높은 사용자 가치를 제공합니다.

# 프런트엔드 Skills 업데이트

이 섹션을 사용하여 현대화 작업과 함께 제공된 프런트엔드 중심 SKILL.md를 업데이트합니다. 이 지침을 저장소 로컬 OpenClaw Skills로 채택하는 경우 먼저 .agents/skills/openclaw-frontend/SKILL.md를 만들고, 해당 대상 Skills에 속하는 프런트매터를 유지한 다음, 본문 지침을 다음 내용으로 추가하거나 교체합니다.

# 프런트엔드 전달 표준

사용자 대상 React, Next.js, 데스크톱 webview, 또는 앱 UI 작업을 구현하거나 리뷰할 때
이 Skills를 사용합니다.

## 운영 규칙

- 기존 제품 워크플로와 코드 규칙에서 시작합니다.
- 현재 사용자 경로를 개선하는 가장 작은 올바른 패치를 우선합니다.
- 인계에서 필수 수정과 선택적 다듬기를 분리합니다.
- 요청이 애플리케이션 표면에 대한 것일 때는 마케팅 페이지를 만들지 않습니다.
- 지원되는 뷰포트 크기 전반에서 동작이 보이고 사용 가능하게 유지합니다.
- 동작할 수 없는 컨트롤을 남겨두지 말고 사용되지 않는 어포던스를 제거합니다.
- 로딩, 빈 상태, 오류, 성공, 권한 상태를 보존합니다.
- 새 프리미티브를 추가하기 전에 기존 디자인 시스템 컴포넌트, 훅, 스토어, 아이콘을 사용합니다.

## 구현 체크리스트

1. 기본 사용자 작업과 이를 소유하는 컴포넌트 또는 라우트를 식별합니다.
2. 편집하기 전에 로컬 컴포넌트 패턴을 읽습니다.
3. 문제를 해결하는 가장 좁은 표면을 패치합니다.
4. 고정 형식 컨트롤, 도구 모음, 그리드, 카운터에 반응형 제약을 추가하여
   텍스트와 호버 상태가 예기치 않게 레이아웃 크기를 바꾸지 않게 합니다.
5. 데이터 로딩, 상태 파생, 렌더링 책임을 명확히 유지합니다.
6. 로직, 지속성, 라우팅, 권한, 또는 공유 헬퍼가 변경될 때 테스트를 추가합니다.
7. 주요 성공 경로와 가장 관련 있는 경계 사례를 검증합니다.

## 시각 품질 게이트

- 텍스트는 모바일과 데스크톱에서 컨테이너 안에 맞아야 합니다.
- 도구 모음은 줄바꿈될 수 있지만, 컨트롤은 계속 접근 가능해야 합니다.
- 버튼은 아이콘이 텍스트보다 더 명확할 때 익숙한 아이콘을 사용해야 합니다.
- 카드는 반복 항목, 모달, 프레임이 있는 도구에 사용해야 하며,
  모든 페이지 섹션에 사용하지 않습니다.
- 운영 콘텐츠와 경쟁하는 단조로운 색상 팔레트와 장식적 배경을 피합니다.
- 밀도 높은 제품 표면은 훑어보기, 비교, 반복 사용에 최적화해야 합니다.

## 인계 형식

보고 항목:

- 변경된 내용.
- 변경된 사용자 동작.
- 통과한 필수 검증.
- 건너뛴 검증과 구체적인 이유.
- 선택적 후속 작업은 필수 수정과 명확히 분리합니다.