backend-claude-code 1.0.0

package/commands/git-commit.md

@@ -0,0 +1,112 @@
+---
+description: "Quick commit with natural language file targeting — describe what to commit in plain English"
+argument-hint: "[target description] (blank = all changes)"
+---
+
+# Smart Commit
+
+> Adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series.
+
+**Input**: $ARGUMENTS
+
+---
+
+## Phase 1 — ASSESS
+
+```bash
+git status --short
+```
+
+If output is empty → stop: "Nothing to commit."
+
+Show the user a summary of what's changed (added, modified, deleted, untracked).
+
+---
+
+## Phase 2 — INTERPRET & STAGE
+
+Interpret `$ARGUMENTS` to determine what to stage:
+
+| Input | Interpretation | Git Command |
+|---|---|---|
+| *(blank / empty)* | Stage everything | `git add -A` |
+| `staged` | Use whatever is already staged | *(no git add)* |
+| `*.ts` or `*.py` etc. | Stage matching glob | `git add '*.ts'` |
+| `except tests` | Stage all, then unstage tests | `git add -A && git reset -- '**/*.test.*' '**/*.spec.*' '**/test_*' 2>/dev/null \|\| true` |
+| `only new files` | Stage untracked files only | `git ls-files --others --exclude-standard \| grep . && git ls-files --others --exclude-standard \| xargs git add` |
+| `the auth changes` | Interpret from status/diff — find auth-related files | `git add <matched files>` |
+| Specific filenames | Stage those files | `git add <files>` |
+
+For natural language inputs (like "the auth changes"), cross-reference the `git status` output and `git diff` to identify relevant files. Show the user which files you're staging and why.
+
+```bash
+git add <determined files>
+```
+
+After staging, verify:
+```bash
+git diff --cached --stat
+```
+
+If nothing staged, stop: "No files matched your description."
+
+---
+
+## Phase 3 — COMMIT
+
+Craft a single-line commit message in imperative mood:
+
+```
+{type}: {description}
+```
+
+Types:
+- `feat` — New feature or capability
+- `fix` — Bug fix
+- `refactor` — Code restructuring without behavior change
+- `docs` — Documentation changes
+- `test` — Adding or updating tests
+- `chore` — Build, config, dependencies
+- `perf` — Performance improvement
+- `ci` — CI/CD changes
+
+Rules:
+- Imperative mood ("add feature" not "added feature")
+- Lowercase after the type prefix
+- No period at the end
+- Under 72 characters
+- Describe WHAT changed, not HOW
+
+```bash
+git commit -m "{type}: {description}"
+```
+
+---
+
+## Phase 4 — OUTPUT
+
+Report to user:
+
+```
+Committed: {hash_short}
+Message:   {type}: {description}
+Files:     {count} file(s) changed
+
+Next steps:
+  - git push           → push to remote
+  - /git pr            → create a pull request
+  - /code-review       → review before pushing
+```
+
+---
+
+## Examples
+
+| You say | What happens |
+|---|---|
+| `/git commit` | Stages all, auto-generates message |
+| `/git commit staged` | Commits only what's already staged |
+| `/git commit *.ts` | Stages all TypeScript files, commits |
+| `/git commit except tests` | Stages everything except test files |
+| `/git commit the database migration` | Finds DB migration files from status, stages them |
+| `/git commit only new files` | Stages untracked files only |

package/commands/git-issue.md

@@ -0,0 +1,74 @@
+---
+description: GitHub 이슈 생성 — bug_report 또는 feature_request 템플릿으로 이슈를 만든다
+argument-hint: [bug | feat] <제목>
+---
+
+# Create Issue
+
+GitHub 이슈를 생성합니다.
+
+**입력**: $ARGUMENTS
+- `bug <제목>` — 버그 리포트 이슈
+- `feat <제목>` — 기능 요청 이슈
+- 타입 생략 시 대화로 결정
+
+---
+
+## Step 1 — 타입과 제목 파악
+
+`$ARGUMENTS`에서 첫 단어로 타입(`bug` / `feat`)을 판별하고, 나머지를 제목으로 사용한다.
+둘 다 없으면 사용자에게 타입과 제목을 묻는다.
+
+## Step 2 — 내용 작성
+
+현재 컨텍스트(변경된 파일, 오류 메시지, 대화 내용)를 바탕으로 이슈 본문을 작성한다.
+
+**bug** 인 경우:
+```
+## 버그 설명
+<현상 요약>
+
+## 재현 절차
+1. 
+2. 
+
+## 기대 동작
+<기대값>
+
+## 실제 동작
+<실제값>
+
+## 로그 / 스택 트레이스
+<관련 로그>
+
+## 환경
+- Spring Boot 버전:
+- Java 버전:
+```
+
+**feat** 인 경우:
+```
+## 목적
+<왜 필요한지>
+
+## 도메인 / 레이어
+- [ ] Controller / Service / Repository / Domain / 인프라
+
+## 제안하는 해결책
+<구현 방향>
+
+## 인수 조건
+- [ ] 
+- [ ] 
+```
+
+## Step 3 — 이슈 생성
+
+```bash
+gh issue create \
+  --title "<제목>" \
+  --body "<본문>" \
+  --label "<bug|enhancement>"
+```
+
+생성된 이슈 URL을 출력한다.

package/commands/git-pr.md

@@ -0,0 +1,184 @@
+---
+description: "Create a GitHub PR from current branch with unpushed commits — discovers templates, analyzes changes, pushes"
+argument-hint: "[base-branch] (default: main)"
+---
+
+# Create Pull Request
+
+> Adapted from PRPs-agentic-eng by Wirasm. Part of the PRP workflow series.
+
+**Input**: `$ARGUMENTS` — optional, may contain a base branch name and/or flags (e.g., `--draft`).
+
+**Parse `$ARGUMENTS`**:
+- Extract any recognized flags (`--draft`)
+- Treat remaining non-flag text as the base branch name
+- Default base branch to `main` if none specified
+
+---
+
+## Phase 1 — VALIDATE
+
+Check preconditions:
+
+```bash
+git branch --show-current
+git status --short
+git log origin/<base>..HEAD --oneline
+```
+
+| Check | Condition | Action if Failed |
+|---|---|---|
+| Not on base branch | Current branch ≠ base | Stop: "Switch to a feature branch first." |
+| Clean working directory | No uncommitted changes | Warn: "You have uncommitted changes. Commit or stash first. Use `/git commit` to commit." |
+| Has commits ahead | `git log origin/<base>..HEAD` not empty | Stop: "No commits ahead of `<base>`. Nothing to PR." |
+| No existing PR | `gh pr list --head <branch> --json number` is empty | Stop: "PR already exists: #<number>. Use `gh pr view <number> --web` to open it." |
+
+If all checks pass, proceed.
+
+---
+
+## Phase 2 — DISCOVER
+
+### PR Template
+
+Search for PR template in order:
+
+1. `.github/PULL_REQUEST_TEMPLATE/` directory — if exists, list files and let user choose (or use `default.md`)
+2. `.github/PULL_REQUEST_TEMPLATE.md`
+3. `.github/pull_request_template.md`
+4. `docs/pull_request_template.md`
+
+If found, read it and use its structure for the PR body.
+
+### Commit Analysis
+
+```bash
+git log origin/<base>..HEAD --format="%h %s" --reverse
+```
+
+Analyze commits to determine:
+- **PR title**: Use conventional commit format with type prefix — `feat: ...`, `fix: ...`, etc.
+  - If multiple types, use the dominant one
+  - If single commit, use its message as-is
+- **Change summary**: Group commits by type/area
+
+### File Analysis
+
+```bash
+git diff origin/<base>..HEAD --stat
+git diff origin/<base>..HEAD --name-only
+```
+
+Categorize changed files: source, tests, docs, config, migrations.
+
+### PRP Artifacts
+
+Check for related PRP artifacts:
+- `.claude/PRPs/reports/` — Implementation reports
+- `.claude/PRPs/plans/` — Plans that were executed
+- `.claude/PRPs/prds/` — Related PRDs
+
+Reference these in the PR body if they exist.
+
+---
+
+## Phase 3 — PUSH
+
+```bash
+git push -u origin HEAD
+```
+
+If push fails due to divergence:
+```bash
+git fetch origin
+git rebase origin/<base>
+git push -u origin HEAD
+```
+
+If rebase conflicts occur, stop and inform the user.
+
+---
+
+## Phase 4 — CREATE
+
+### With Template
+
+If a PR template was found in Phase 2, fill in each section using the commit and file analysis. Preserve all template sections — leave sections as "N/A" if not applicable rather than removing them.
+
+### Without Template
+
+Use this default format:
+
+```markdown
+## Summary
+
+<1-2 sentence description of what this PR does and why>
+
+## Changes
+
+<bulleted list of changes grouped by area>
+
+## Files Changed
+
+<table or list of changed files with change type: Added/Modified/Deleted>
+
+## Testing
+
+<description of how changes were tested, or "Needs testing">
+
+## Related Issues
+
+<linked issues with Closes/Fixes/Relates to #N, or "None">
+```
+
+### Create the PR
+
+```bash
+gh pr create \
+  --title "<PR title>" \
+  --base <base-branch> \
+  --body "<PR body>"
+  # Add --draft if the --draft flag was parsed from $ARGUMENTS
+```
+
+---
+
+## Phase 5 — VERIFY
+
+```bash
+gh pr view --json number,url,title,state,baseRefName,headRefName,additions,deletions,changedFiles
+gh pr checks --json name,status,conclusion 2>/dev/null || true
+```
+
+---
+
+## Phase 6 — OUTPUT
+
+Report to user:
+
+```
+PR #<number>: <title>
+URL: <url>
+Branch: <head> → <base>
+Changes: +<additions> -<deletions> across <changedFiles> files
+
+CI Checks: <status summary or "pending" or "none configured">
+
+Artifacts referenced:
+  - <any PRP reports/plans linked in PR body>
+
+Next steps:
+  - gh pr view <number> --web   → open in browser
+  - /code-review <number>       → review the PR
+  - gh pr merge <number>        → merge when ready
+```
+
+---
+
+## Edge Cases
+
+- **No `gh` CLI**: Stop with: "GitHub CLI (`gh`) is required. Install: <https://cli.github.com/>"
+- **Not authenticated**: Stop with: "Run `gh auth login` first."
+- **Force push needed**: If remote has diverged and rebase was done, use `git push --force-with-lease` (never `--force`).
+- **Multiple PR templates**: If `.github/PULL_REQUEST_TEMPLATE/` has multiple files, list them and ask user to choose.
+- **Large PR (>20 files)**: Warn about PR size. Suggest splitting if changes are logically separable.

package/commands/git-push.md

@@ -0,0 +1,28 @@
+# Git Commit & Push
+
+변경사항을 커밋하고 원격 저장소에 푸시합니다.
+
+## 실행 순서
+
+1. `git status`로 변경 파일 확인
+2. `git diff --staged` + `git diff`로 변경 내용 파악
+3. `git log --oneline -5`로 최근 커밋 스타일 확인
+4. 변경사항에 맞는 커밋 메시지 작성 (Semantic Commit)
+5. 관련 파일 스테이징 후 커밋
+6. 현재 브랜치로 push
+
+## 규칙
+
+- 커밋 메시지는 Semantic Commit 형식 (`feat:`, `fix:`, `refactor:`, `chore:` 등)
+- 서명 스킵 (`--no-verify`) 금지 — 훅 실패 시 원인 수정
+- `.env`, 시크릿 파일 커밋 금지
+- `git add .` 대신 파일명 지정으로 스테이징
+- force push 금지
+- Co-Authored-By 태그 포함:
+  ```
+  Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+  ```
+
+## 완료 기준
+
+`git log --oneline -1`로 커밋 확인 + push 성공 메시지 확인.

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "backend-claude-code",
+  "version": "1.0.0",
+  "description": "Java/Spring Boot 프로젝트를 위한 Claude Code 설정 패키지",
+  "bin": {
+    "backend-claude-code": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "agents/",
+    "rules/",
+    "commands/",
+    "skills/",
+    ".claude/",
+    ".mcp.json",
+    ".github/",
+    "CLAUDE.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["claude-code", "spring-boot", "java", "backend"],
+  "license": "MIT"
+}

package/rules/architecture.md

@@ -0,0 +1,33 @@
+---
+paths:
+  - "**/*.java"
+---
+# Architecture
+
+Spring Boot 3.x (Jakarta namespace) 표준 레이어드 아키텍처.
+
+```
+src/main/java/com/{company}/{app}/
+├── web/           # REST controllers (@RestController)
+├── service/       # 비즈니스 로직 (@Service, @Transactional)
+├── repository/    # JPA + QueryDSL 데이터 접근
+├── domain/
+│   ├── entity/    # JPA 엔티티
+│   ├── enums/     # 공유 열거형
+│   └── value/     # Value objects
+├── dto/           # 요청/응답 DTO (*Dtos.java 내 static inner record)
+└── global/
+    ├── config/    # Spring 설정
+    ├── security/  # 인증/인가
+    ├── error/     # 예외 및 핸들러
+    └── util/      # 공통 유틸리티
+```
+
+## 레이어 책임
+
+| 레이어 | 책임 | 금지 사항 |
+|--------|------|----------|
+| Controller | HTTP 매핑, 입력 검증, 응답 포맷 | 비즈니스 로직 |
+| Service | 비즈니스 로직, 트랜잭션 | 직접 HTTP 처리 |
+| Repository | 데이터 접근, 쿼리 | 비즈니스 로직 |
+| Entity | 도메인 상태 | 외부 DTO 의존 |

package/rules/coding-style.md

@@ -0,0 +1,113 @@
+---
+paths:
+  - "**/*.java"
+---
+# Java Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with Java-specific content.
+
+## 포매팅
+
+- **google-java-format** 또는 **Checkstyle** (Google 또는 Sun 스타일) 강제 적용
+- 파일당 하나의 공개 최상위 타입
+- 일관된 들여쓰기: 2 또는 4 스페이스 (프로젝트 표준에 맞춤)
+- 멤버 순서: 상수, 필드, 생성자, 공개 메서드, protected, private
+
+## 불변성
+
+- 값 타입에는 `record` 선호 (Java 16+)
+- 기본적으로 필드를 `final`로 표시 — 필요한 경우에만 가변 상태 사용
+- 공개 API에서 방어적 복사 반환: `List.copyOf()`, `Map.copyOf()`, `Set.copyOf()`
+
+```java
+// GOOD — 불변 값 타입
+public record OrderSummary(Long id, String customerName, BigDecimal total) {}
+
+// GOOD — final 필드, setter 없음
+public class Order {
+    private final Long id;
+    private final List<LineItem> items;
+
+    public List<LineItem> getItems() {
+        return List.copyOf(items);
+    }
+}
+```
+
+## 명명 규칙
+
+표준 Java 관례 준수:
+- `PascalCase` — 클래스, 인터페이스, 레코드, 열거형
+- `camelCase` — 메서드, 필드, 매개변수, 지역 변수
+- `SCREAMING_SNAKE_CASE` — `static final` 상수
+- 패키지: 모두 소문자, 역방향 도메인 (`com.example.app.service`)
+
+## 모던 Java 기능
+
+명확성을 향상시키는 경우 모던 언어 기능 사용:
+- **Records** — DTO 및 값 타입 (Java 16+)
+- **Sealed classes** — 닫힌 타입 계층 (Java 17+)
+- **Pattern matching** `instanceof` — 명시적 캐스트 불필요 (Java 16+)
+- **Text blocks** — 여러 줄 문자열 (SQL, JSON 템플릿) (Java 15+)
+- **Switch expressions** — 화살표 구문 (Java 14+)
+- **Pattern matching in switch** — sealed 타입 완전 처리 (Java 21+)
+
+```java
+// 패턴 매칭 instanceof
+if (shape instanceof Circle c) {
+    return Math.PI * c.radius() * c.radius();
+}
+
+// Sealed 타입 계층
+public sealed interface PaymentMethod permits CreditCard, BankTransfer, Wallet {}
+
+// Switch 표현식
+String label = switch (status) {
+    case ACTIVE -> "Active";
+    case SUSPENDED -> "Suspended";
+    case CLOSED -> "Closed";
+};
+```
+
+## Optional 사용법
+
+- 결과가 없을 수 있는 finder 메서드에서 `Optional<T>` 반환
+- `map()`, `flatMap()`, `orElseThrow()` 사용 — `isPresent()` 없이 `get()` 절대 금지
+- `Optional`을 필드 타입이나 메서드 매개변수로 사용 금지
+
+```java
+// GOOD
+return repository.findById(id)
+    .map(ResponseDto::from)
+    .orElseThrow(() -> new OrderNotFoundException(id));
+
+// BAD — 매개변수로 Optional
+public void process(Optional<String> name) {}
+```
+
+## 오류 처리
+
+- 도메인 오류에는 unchecked 예외 선호
+- `RuntimeException`을 확장하는 도메인별 예외 생성
+- 최상위 핸들러 외에는 `catch (Exception e)` 지양
+- 예외 메시지에 컨텍스트 포함
+
+```java
+public class OrderNotFoundException extends RuntimeException {
+    public OrderNotFoundException(Long id) {
+        super("Order not found: id=" + id);
+    }
+}
+```
+
+## Streams
+
+- 변환에 스트림 사용; 파이프라인을 짧게 유지 (최대 3-4 연산)
+- 가독성이 있을 때 메서드 참조 선호: `.map(Order::getTotal)`
+- 스트림 연산에서 부작용 방지
+- 복잡한 로직은 복잡한 스트림 파이프라인보다 루프 선호
+
+## 참고
+
+skill: `java-coding-standards` — 예시가 포함된 전체 코딩 표준
+skill: `jpa-patterns` — JPA/Hibernate 엔티티 설계 패턴

package/rules/controller-patterns.md

@@ -0,0 +1,63 @@
+---
+paths:
+  - "**/controller/**/*.java"
+  - "**/web/**/*.java"
+---
+# Controller 패턴
+
+## 클래스 구조
+
+```java
+@RestController
+@RequestMapping("/api/v1/{domain}")
+@RequiredArgsConstructor
+@Validated
+public class FooController {
+    private final FooService fooService;
+}
+```
+
+## 응답 포맷
+
+공통 래퍼 없이 DTO 직접 반환.
+
+```java
+// 조회
+public FooDtos.FooResponse getFoo(...) { ... }
+
+// 생성
+@ResponseStatus(HttpStatus.CREATED)
+public FooDtos.FooResponse createFoo(...) { ... }
+
+// 삭제 / 본문 없는 수정
+@ResponseStatus(HttpStatus.NO_CONTENT)
+public void deleteFoo(...) { ... }
+```
+
+## Validation
+
+- `@Validated` 클래스 레벨 선언
+- Request record 필드: `@NotBlank`, `@NotNull`, `@Positive`, `@PositiveOrZero`
+- nullable 필드 조건부 검증: `@AssertTrue` 메서드로 처리
+
+```java
+public record FooUpdateRequest(String title) {
+    @AssertTrue(message = "title must not be blank")
+    public boolean hasNonBlankTitleWhenPresent() {
+        return title == null || !title.isBlank();
+    }
+}
+```
+
+## 페이지네이션 파라미터
+
+```java
+@RequestParam(defaultValue = "1") @Positive int page,
+@RequestParam(defaultValue = "20") @Positive int size
+```
+
+## 금지 사항
+
+- 컨트롤러에 비즈니스 로직 작성 금지
+- `@Autowired` 필드 주입 금지
+- 엔티티 직접 반환 금지

package/rules/dto-patterns.md

@@ -0,0 +1,76 @@
+---
+paths:
+  - "**/dto/**/*.java"
+---
+# DTO 패턴
+
+## 파일 구조
+
+한 도메인의 모든 DTO는 `dto/FooDtos.java` 한 파일 안에 static inner record로 정의한다.
+
+```java
+public class FooDtos {
+
+    public record CreateRequest(
+        @NotBlank String title,
+        Integer duration
+    ) {
+        public Foo toEntity(String id, String ownerId) {
+            return new Foo(id, ownerId, title, duration);
+        }
+    }
+
+    public record UpdateRequest(String title) {
+        @AssertTrue(message = "title must not be blank")
+        public boolean hasNonBlankTitleWhenPresent() {
+            return title == null || !title.isBlank();
+        }
+    }
+
+    public record FooResponse(
+        String id,
+        String title,
+        FooStatus status
+    ) {
+        public static FooResponse from(Foo foo) {
+            return new FooResponse(foo.getId(), foo.getTitle(), foo.getStatus());
+        }
+    }
+
+    public record FooListResponse(
+        List<FooResponse> items,
+        long total,
+        int page,
+        int size,
+        boolean hasMore
+    ) {
+        public static FooListResponse of(List<FooResponse> items, long total, int page, int size) {
+            return new FooListResponse(items, total, page, size, (long) page * size < total);
+        }
+    }
+}
+```
+
+## 변환 메서드 규칙
+
+| 메서드 | 용도 |
+|--------|------|
+| `from(Entity)` | 단일 엔티티 → DTO |
+| `fromDetail(Entity, ...)` | 연관 데이터 포함한 상세 조회 |
+| `toEntity(...)` | Request DTO → 엔티티 |
+
+## 네이밍 컨벤션
+
+| 용도 | 이름 |
+|------|------|
+| 생성 요청 | `CreateRequest` |
+| 수정 요청 | `UpdateRequest` |
+| 단건 응답 | `FooResponse` |
+| 목록 응답 | `FooListResponse` |
+| 상세 응답 | `FooDetailResponse` |
+
+## 금지 사항
+
+- DTO에서 엔티티 import 금지 (toEntity 제외)
+- record 대신 class 사용 금지
+- 응답 DTO에 비즈니스 로직 작성 금지