analyze-nextjs-architecture - SKILL.md Agent Skill

name: analyze_nextjs_architecture description: Next.js 프로젝트의 아키텍처 건전성, 컴포넌트 패턴(서버/클라이언트), 그리고 보안 취약점을 분석합니다.

이 스킬은 Next.js 애플리케이션이 Clean Architecture 원칙을 잘 따르고 있는지, Server/Client Component가 적절히 사용되고 있는지, 그리고 보안상 위험한 요소가 없는지 체계적으로 점검하기 위해 사용합니다.

새로운 기능을 구현한 후나 레거시 코드를 리팩토링하기 전에 이 스킬을 실행하여 코드베이스의 건강 상태를 진단하세요. 다음 단계들을 순차적으로 수행하며 발견된 문제점을 리포트합니다.

가장 먼저 불필요한 클라이언트 컴포넌트 사용을 식별합니다.

"use client" 검색: grep_search를 사용하여 클라이언트 컴포넌트 사용 현황을 파악합니다.
```
grep -r "use client" src/
```
Leaf Node 원칙 검증:
- 검색된 파일 중 상위 레이아웃이나 페이지 전체에 "use client"가 선언된 경우가 있는지 확인합니다.
- view_file로 해당 코드를 열어보고, 실제 useState, useEffect나 이벤트 핸들러가 없는 경우 서버 컴포넌트로 전환을 제안합니다.

내부 계층이 외부 계층을 의존하는 위반 사례를 찾습니다.

Domain 계층 오염 확인: src/core/domain 디렉토리 내의 파일들이 src/infrastructure나 src/app, src/components를 import 하고 있는지 확인합니다.
```
grep -r "from '@/infrastructure" src/core/domain
grep -r "from '@/app" src/core/domain
grep -r "from '@/components" src/core/domain
```
- 결과: 위 명령에서 결과가 나온다면 심각한 아키텍처 위반입니다.
Application 계층 구현체 의존 확인: src/core/application 내에서 구체적인 구현체(Repository Class 등)를 직접 import 하는지 확인합니다. 오직 interface만 의존해야 합니다.

Next.js 및 웹 애플리케이션의 일반적인 보안 위험을 점검합니다.

민감 정보 노출 (Sensitive Data Props):
- 클라이언트 컴포넌트로 전달되는 props 중 민감한 이름이 있는지 확인합니다.
- 패턴: token, password, secret, key 등.
- 주의: 서버 컴포넌트에서 클라이언트 컴포넌트로 이 데이터를 넘기는 순간 브라우저 번들에 포함되어 노출됩니다.
XSS 위험 (dangerouslySetInnerHTML):
- dangerouslySetInnerHTML 사용처를 검색합니다.
- 사용된 경우, 해당 데이터가 dompurify 등으로 살균(sanitize) 처리되었는지 view_file로 확인합니다.
Server Actions 보안:
- "use server"가 선언된 파일(src/app/actions.ts 등)을 검사합니다.
- 입력 검증: Zod 등을 사용하여 입력값(FormData 등)을 검증하고 있는지 확인합니다.
- 권한 검사: 액션 함수 시작 부분에 인증/인가 체크(예: getUser(), assertAuthenticated())가 있는지 확인합니다. 이것이 없다면 누구나 API를 호출해 데이터를 조작할 수 있습니다.

무거운 패키지 import: 클라이언트 컴포넌트에서 거대한 라이브러리(예: 전체 lodash, 무거운 차트 라이브러리 등)를 import 하는지 확인합니다. 가능하면 dynamic import를 제안합니다.

분석을 마치면 다음과 같은 요약 리포트를 작성하세요:

각 문제에 대해 수정 제안을 함께 제공하세요.