Imported from jinhyun71744/vibe-projects (AGENTS.md). Install upstream with npx skills add jinhyun71744/vibe-projects. Copyright stays with the author.

AGENTS.md — 프로젝트 에이전트 규칙

이 문서는 AI(코딩 어시스턴트)가 이 저장소에서 코드를 작성·수정할 때 매번 반복 설명하지 않아도 되도록 프로젝트 전제와 행동 규칙을 정리한 것이다.

프로젝트 한 줄 요약

Next.js 기반 웹 앱을 초보 개발자가 학습·구축하는 프로젝트이며, 아래 스택을 기본 전제로 둔다.

기술 스택 (고정)

AI가 지켜야 할 것 (DO)

• App Router: 새 페이지·레이아웃·API는 app/ 아래에 둔다. layout.tsx, page.tsx, loading.tsx, error.tsx 등 App Router 관례를 따른다.
• Server vs Client: 기본은 서버 컴포넌트로 두고, 상태·이벤트·브라우저 API가 필요할 때만 "use client"를 파일 상단에 명시한다.
• TypeScript: any를 피하고, props·함수 인자·반환값에 타입을 둔다. Supabase 스키마/생성 타입이 있으면 이를 활용한다.
• Tailwind: 스타일은 Tailwind 유틸리티 클래스를 우선한다. 전역 스타일은 프로젝트에 있는 진입 CSS(예: globals.css)와 테마와 맞춘다.
• Supabase: 클라이언트용 키는 NEXT_PUBLIC_ 환경 변수로만 노출하고, 서비스 롤·비밀 키는 서버(서버 컴포넌트, Route Handler, Server Actions)에서만 사용한다. 데이터 접근은 **RLS(행 수준 보안)**를 전제로 설계한다.
• 보안·비밀: .env.local 등 비밀 파일 내용을 코드나 채팅에 그대로 붙여 넣지 않게 안내하고, 예시는 플레이스홀더로 쓴다.
• 일관성: 기존 폴더 구조·네이밍·import 스타일이 있으면 새 코드도 그에 맞춘다.

하면 안 되는 것 (DON'T)

• Pages Router로 신규 기능 추가: pages/ 디렉터리에 새 라우트를 만들거나 App Router와 혼용해 라우팅을 이중으로 늘리지 않는다. (레거시가 있다면 유지만 하고 확장은 app/으로.)
• TypeScript 없이 작성: 새 파일을 .js/.jsx로 추가하지 않는다.
• any 남발·타입 무시: 불가피할 때만 좁은 범위에서 사용하고, 전역적으로 any로 때우지 않는다.
• 스타일 혼선: 가능한 한 인라인 style={}이나 별도 CSS 파일로 Tailwind 역할을 중복 구현하지 않는다. (디자인 토큰·예외는 프로젝트 컨벤션에 따름.)
• Supabase 비밀 키 클라이언트 노출: 서비스 롤 키, service_role JWT, DB 직접 연결 문자열 등을 "use client" 컴포넌트나 브라우저로 보내는 코드를 작성하지 않는다.
• RLS 무시한 “전부 허용” 설계: 프로덕션 전제에서 테이블을 열어두는 위험한 정책을 기본으로 제안하지 않는다.
• 불필요한 범위 확장: 요청과 무관한 대규모 리팩터, 의존성 추가, 문서 여러 개 생성은 하지 않는다.

참고

• 폴더 구조·컴포넌트 네이밍·한국어/영어 UI 문구 등은 팀·프로젝트에 맞게 이 문서를 갱신해도 된다.
• Cursor 등에서는 이 파일과 함께 .cursor/rules를 쓰면 파일별 규칙을 더 세밀히 둘 수 있다.