Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

애플리케이션 현대화 계획

​

목표

​

원칙

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

​

1단계: 기준선 감사

• 주요 사용자 워크플로와 이를 소유하는 코드 표면을 식별합니다.
• 죽은 affordance, 중복 설정, 불명확한 오류 상태, 비용이 큰 렌더 경로를 나열합니다.
• 각 표면의 현재 검증 명령을 수집합니다.
• 문제를 필수, 권장, 선택 사항으로 표시합니다.
• 특히 API, 보안, 릴리스, Plugin 계약 변경 중 소유자 검토가 필요한 알려진 blocker를 문서화합니다.

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

​

2단계: 제품 및 UX 정리

• 모델 인증, Gateway 상태, Plugin 설정 주변의 온보딩 문구와 빈 상태를 정리합니다.
• 수행 가능한 작업이 없는 죽은 affordance는 제거하거나 비활성화합니다.
• 깨지기 쉬운 레이아웃 가정 뒤에 숨기지 말고 중요한 액션이 반응형 너비 전반에서 계속 보이도록 유지합니다.
• 반복되는 상태 문구를 통합하여 오류에 하나의 단일 truth source를 갖게 합니다.
• 고급 설정에는 점진적 공개를 추가하되 핵심 설정은 빠르게 유지합니다.

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

​

3단계: 프런트엔드 아키텍처 정리

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

• 파일 분할의 부작용으로 공개 동작을 바꾸지 않습니다.
• 메뉴, 대화상자, 탭, 키보드 내비게이션의 접근성 동작을 유지합니다.
• 로딩, 빈 상태, 오류, optimistic 상태가 여전히 렌더링되는지 검증합니다.

​

4단계: 성능 및 안정성

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

• 각 성능 변경은 기준선, 예상 영향, 실제 영향, 남은 격차를 기록합니다.
• 저렴한 측정이 가능할 때 성능 패치는 직관만으로 반영되지 않습니다.

​

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

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

• pnpm check:changed
• 변경된 모든 경계에 대한 대상 테스트.
• lazy 경계, 패키징, 공개 표면이 변경될 때 pnpm build.

​

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

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

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

​

권장 첫 번째 단위 작업

• 첫 실행 설정, 제공자 인증 준비 상태, Gateway 상태, Plugin 설정 표면을 감사합니다.
• 죽은 액션을 제거하고 실패 상태를 더 명확히 합니다.
• 상태 도출 및 config 지속성에 대한 집중 테스트를 추가하거나 업데이트합니다.
• pnpm check:changed를 실행합니다.

​

프런트엔드 Skill 업데이트

# 프런트엔드 전달 표준

사용자 대상 React, Next.js,
데스크톱 webview, 또는 앱 UI 작업을 구현하거나 검토할 때 이 skill을 사용하세요.

## 운영 규칙

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

## 구현 체크리스트

1. 기본 사용자 작업과 이를 소유하는 컴포넌트 또는 라우트를 식별합니다.
2. 수정 전에 로컬 컴포넌트 패턴을 읽습니다.
3. 문제를 해결하는 가장 좁은 표면을 패치합니다.
4. 고정 형식 컨트롤, 툴바, 그리드, 카운터에 반응형 제약을 추가하여 텍스트와 hover 상태 때문에 레이아웃 크기가 예기치 않게 바뀌지 않도록 합니다.
5. 데이터 로딩, 상태 도출, 렌더링 책임을 명확하게 유지합니다.
6. 로직, 지속성, 라우팅, 권한, 공유 helper가 바뀌면 테스트를 추가합니다.
7. 주요 happy path와 가장 관련 있는 edge case를 검증합니다.

## 시각 품질 게이트

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

## 인계 형식

다음을 보고하세요:

- 무엇이 변경되었는지.
- 어떤 사용자 동작이 변경되었는지.
- 통과한 필수 검증.
- 건너뛴 검증이 있다면 구체적인 이유.
- 선택적 후속 작업은 필수 수정과 명확히 분리.