어느 프로젝트에서 어느 세션이 일해도
같은 파일 · 같은 이름 · 같은 계층.

왜 만들었나

앱이 의존성으로 받는 라이브러리(jar · npm 패키지)가 아닙니다. 사람과 LLM이 같은 방식으로 일하게 하는 규칙과 도구입니다.

4층 구조

Claude Code 플러그인으로 줄 수 있는 것은 스킬 · hook · 에이전트 · MCP뿐입니다. 그래서 경로 규칙은 판을 고정한 사본으로 프로젝트에 넣습니다.

새 프로젝트 시작하기

빈 폴더에서 Spring Boot + React 멀티모듈(backend/ · frontend/) 프로젝트를 만듭니다.

1. 준비물

   git · gh(gh auth login 뒤 gh auth setup-git), JDK 17 이상, Docker, Claude Code v2.1.277 이상, python3. Node는 Gradle이 받습니다.

2. devkit 받기 (한 번만)

   git clone https://github.com/seokan80/kiwiz-devkit.git ~/Developer/kiwiz-devkit
   DEVKIT=~/Developer/kiwiz-devkit

3. 프로젝트 만들기

   mkdir -p ~/Developer/work/my-app && cd ~/Developer/work/my-app
   git init -b main
   $DEVKIT/plugins/kiwiz/scripts/init-project.sh . --name my-app --java 25 --router react-router \
     --with-gradle-config --with-web-config --with-web-starter

   옵션	값	뜻
   --java	17 · 21 · 25(기본)	고객사 JDK에 맞춰 고릅니다. Spring Boot 4와 의존성은 그대로이고 툴체인 · .sdkmanrc · java.md가 그 판으로 들어갑니다
   --router	react-router(기본) · tanstack	react-router + vite-plugin-pages 또는 TanStack Router(파일 기반). 웹 틀 · 시작 코드 · routing.md가 그 라우터 것으로 들어갑니다
   --with-gradle-config		Gradle 골격 — 버전 카탈로그 · 서버 · 웹 빌드(웹 빌드 결과를 서버 jar에 넣음)
   --with-web-config		웹 설정 — package.json(정확한 판) · ESLint · Prettier · tsconfig · Vite
   --with-web-starter		웹 시작 코드 — 라우터 · 로그인 가드 · 페이지 · ApiError · 시험

   이미 있는 파일은 건드리지 않으므로 다시 돌려도 됩니다.

4. Gradle 래퍼 · 웹 확인

   gradle wrapper --gradle-version 9.8.1 --distribution-type bin \
     --gradle-distribution-sha256-sum dce76f55f8e251a3a1f130eb120f30b3d271de2b76c9b0729d316b5a1b6dc01f
   cd frontend && npm install && npm run check   # 타입 · 린트 · 서식 · 시험
   cd .. && ./gradlew build                        # 서버 시험 + 웹 검사 + 웹 빌드 + jar

   서버 시작 코드(Application · package-info · 모듈 시험)는 아직 손으로 만듭니다. 자세한 것은 문서 01을 봅니다.

5. Claude Code 열기

   claude   # 이 폴더에서 열고 "이 폴더를 신뢰" → 마켓플레이스 kiwiz 등록 · 플러그인 kiwiz 켜짐

   세션에서 /plugin을 열어 kiwiz@kiwiz가 켜졌는지 봅니다. /kiwiz:api · /kiwiz:screen · /kiwiz:setup이 보이면 됩니다.

6. 채우고 첫 커밋

   • AGENTS.md의 TODO를 채웁니다(설계 문서 위치 · 검증 명령 · 병합 절차).
   • 검증 스크립트에 ./gradlew build와 scripts/kiwiz/check-rules.sh를 넣습니다.
   • 첫 화면 · 첫 API가 병합되면 .claude/rules/project/의 정답 파일 표에 등록합니다.
   • CLAUDE.md는 개인 메모라 커밋하지 않습니다. 공유 규칙은 AGENTS.md에 둡니다.

기존 프로젝트에 붙이기

이미 있는 파일은 덮어쓰지 않습니다. 규칙 사본(.claude/rules/kiwiz/)과 검사 스크립트만 devkit 것을 넣습니다. 작업 브랜치에서 합니다.

• Java 판은 gradle/libs.versions.toml의 java에서, 라우터는 웹 package.json의 의존성에서 알아냅니다. 다르게 적어야 할 때만 --java · --router를 줍니다.
• .claude/settings.json에는 마켓플레이스 kiwiz와 kiwiz@kiwiz 켜기만 더해지고, 다른 키는 그대로 둡니다.
• 프로젝트에 있던 경로 규칙 · 스킬 · 서식 hook은 회사 공통과 겹치는 부분을 지우고, 프로젝트 고유만 .claude/rules/project/와 프로젝트 스킬에 남깁니다.

스킬 · hook

Claude는 스킬 설명을 늘 보고 있다가 일이 맞으면 스스로 엽니다. 직접 부를 때는 /kiwiz:screen처럼 씁니다.

규칙 갱신 · 판 관리

스킬 · hook은 플러그인 판이 오르면 팀원 PC에 퍼집니다. 규칙 사본은 각 프로젝트가 sync-rules.sh를 돌려 PR로 받을 때만 바뀝니다.

# 새 판 받기 — Java 판 · 라우터 · 폴더는 kiwiz.lock의 값을 씁니다
$DEVKIT/plugins/kiwiz/scripts/sync-rules.sh .
git diff .claude/rules/kiwiz

# 검사 — 프로젝트 검증 스크립트에 넣습니다
scripts/kiwiz/check-rules.sh

팀원 PC의 플러그인은 Claude Code 세션에서 /plugin marketplace update kiwiz로 새 판을 받습니다. 자동 갱신을 켜 두면 세션을 시작할 때 저절로 받습니다.

옛 이름 kiwiz-core에서 옮기기 (0.5.0)

0.4.0까지는 저장소와 플러그인 이름이 kiwiz-core였습니다. sync-rules.sh를 한 번 돌리면 lock 이름(kiwiz.lock), settings의 플러그인 키(kiwiz@kiwiz), 저장소 주소가 새 이름으로 바뀝니다. 문서의 스킬 이름(kiwiz-core:api → kiwiz:api)은 손으로 고칩니다.

git remote set-url origin https://github.com/seokan80/kiwiz-devkit.git   # 받아 둔 devkit 사본
claude plugin uninstall kiwiz-core@kiwiz                                   # 팀원 PC — 옛 플러그인 지우기

문제 풀기

문서

저장소가 비공개라 문서를 열려면 GitHub 읽기 권한이 필요합니다. 권한은 저장소 주인에게 받습니다.