권장 Git 구조
Plextype를 받아서 새 사이트를 만들 때는 프로젝트 저장소를 완전히 새로 만들되, 원본 Plextype 저장소는 upstream remote로 남겨두는 방식을 권장합니다.
origin = 사용자 개인/회사 사이트 저장소
upstream = Gjworks/plextype 원본 저장소처음 프로젝트 만들기
git clone git@github.com:Gjworks/plextype.git my-site
cd my-site
git remote rename origin upstream
git remote add origin git@github.com:USER/my-site.git
git push -u origin main패치 받아오기
git fetch upstream
git merge upstream/main
npm run extensions:sync
npm run extensions:check
npm run extensions:test
npm run prisma:sync
npm run prisma:generate
npm run build이력을 더 깔끔하게 유지하고 싶은 팀은 merge 대신 rebase를 사용할 수 있습니다.
git fetch upstream
git rebase upstream/main코어 파일 수정 최소화
src/modules, src/core와 기본 모듈 라우트는 코어 업데이트 대상입니다. 레이아웃이나 스킨 변경은 확장으로 처리합니다. src/app/(modules)에도 확장 소유 연결 파일이 있으므로 routes.json에서 소유권을 확인하고, 생성 파일 충돌은 원본과 연결 목록을 먼저 정리한 뒤 재생성합니다.
커스텀 위치
src/extensions/index.tsx
src/extensions/layouts/*
src/extensions/pages/*
src/extensions/posts/[feature]/*
src/extensions/user/[skin]/*
src/extensions/[feature]/routes/*
src/extensions/[feature]/api/*
src/extensions/[feature]/routes.json
src/extensions/[feature]/registry.tsx
src/extensions/[feature]/prisma/schema/*.prisma
src/extensions/[feature]/triggers/*
src/extensions/proxy.ts
src/extensions/prisma/seed.js업데이트 충돌이 난다면 “코어 파일을 내 사이트용으로 더 고친다”보다 “내 사이트 로직을 extension으로 옮긴다”가 장기적으로 훨씬 안정적입니다.
Next.js 라우트는 src/app에 필요하지만 구현 원본은 기능 폴더에 유지합니다. 연결 파일의 Git 추적 여부는 배포 정책에 맞춰 정하고, 추적하지 않는 환경은 빌드 전에 extensions:sync가 실행되도록 운영 절차에 명시합니다. 현재 npm dev/build 명령에 자동 연결되어 있지는 않습니다.
확장 삭제·이름 변경 시 남은 연결 파일은 자동 삭제되지 않습니다. 기존 URL, registry, Trigger, 다른 기능의 import와 DB 보존 정책을 확인한 뒤 정리합니다.
AGENTS.md 권장 규칙
# Project Custom Rules
- Plextype 코어 파일(src/core, src/modules, src/app/(modules))은 가능한 한 수정하지 않는다.
- 사이트별 기능의 원본은 src/extensions의 기능별 폴더에 모은다.
- 코어 posts/user와 확장 posts/user는 합치지 않는다.
- 페이지·API 구현은 기능 폴더에 두고 routes.json 및 extensions:sync로 src/app 연결 파일을 관리한다.
- DB 모델은 해당 기능의 prisma/schema.prisma 또는 prisma/schema/*.prisma에 작성한다.
- 모듈은 자기 폴더의 registry.tsx에서 defineModule()로 관리자 메뉴, breadcrumb, 관련 스킨을 함께 등록한다.
- 스킨과 레이아웃은 각 폴더의 registry.tsx에서 definePostSkin(), definePostLayout(), defineAdminLayout(), defineUserSkin()으로 등록한다.
- src/extensions/registry.tsx는 각 모듈/스킨 registry를 import해서 조립만 한다.
- 다른 프로젝트로 배포할 모듈이나 스킨은 registry.tsx를 포함한 폴더 단위로 유지한다.
- 원본 패치 반영 후 extensions:sync, extensions:check, extensions:test와 타입 검사·빌드를 실행한다.
- 스키마 변경 시 prisma:sync와 prisma:generate를 확인하되 DB 적용과 혼동하지 않는다.
- DB migration, push, seed는 명시 승인 없이 실행하지 않고 적용된 마이그레이션 이력을 보존한다.
- 코어 수정이 필요하면 먼저 extension hook, registry, action wrapper로 해결 가능한지 검토한다.배포 전 확인
npm run extensions:check
npm run extensions:test
npx tsc --noEmit --incremental false
npm run build연결 검사가 실패하면 원본 및 routes.json을 수정하고 동기화합니다. 빌드 통과만으로 DB 테이블 존재나 실제 구매·다운로드 권한까지 검증되지는 않습니다. 별도 테스트 환경에서 로그인, 권한, 주요 화면과 API를 확인하세요.
스키마 변경은 검토한 마이그레이션을 저장소에 포함하고 승인된 배포 절차에서 적용합니다. 원격 모듈 설치, 자동 의존성 해결, 구매 인증은 현재 라우트 동기화 명령의 범위가 아닙니다. 전체 에이전트 규칙 예시는 [시작하기](/docs/getting-started)를 참고하세요.