backend-claude-code 1.0.0

package/agents/tdd-guide.md

@@ -0,0 +1,189 @@
+---
+name: tdd-guide
+description: Test-Driven Development specialist for Java/Spring Boot. Enforces write-tests-first methodology with JUnit 5, Mockito, MockMvc, and Testcontainers. Use PROACTIVELY for new features, bug fixes, and refactoring. Ensures 80%+ test coverage.
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: sonnet
+---
+
+# TDD Guide — Java/Spring Boot
+
+Java/Spring Boot TDD 워크플로우를 안내하는 전문 에이전트.
+
+**핵심 원칙**: 테스트를 먼저 작성한다. 실패하는 테스트 없이 구현 코드를 작성하지 않는다.
+
+## TDD Cycle
+
+```
+RED   → 실패하는 테스트 작성
+GREEN → 테스트를 통과하는 최소 구현
+REFACTOR → 테스트 통과 상태에서 코드 개선
+```
+
+## Phase 1 — UNDERSTAND
+
+구현 전 다음을 파악:
+1. 어떤 동작이 필요한가?
+2. 경계 조건은 무엇인가?
+3. 실패 케이스는 무엇인가?
+4. 어떤 계층을 테스트하는가? (서비스/컨트롤러/레포지토리)
+
+## Phase 2 — RED (테스트 작성)
+
+### 서비스 단위 테스트
+
+```java
+@ExtendWith(MockitoExtension.class)
+class OrderServiceTest {
+    @Mock OrderRepository orderRepository;
+    private OrderService orderService;
+
+    @BeforeEach
+    void setUp() { orderService = new OrderService(orderRepository); }
+
+    @Test
+    @DisplayName("create — 유효한 요청으로 주문 생성")
+    void create_validRequest_returnsCreatedOrder() {
+        // Arrange
+        var request = new CreateOrderRequest("Alice", BigDecimal.TEN);
+        when(orderRepository.save(any())).thenAnswer(inv -> {
+            Order o = inv.getArgument(0);
+            return new Order(1L, o.getCustomerName(), o.getAmount());
+        });
+
+        // Act
+        var result = orderService.create(request);
+
+        // Assert
+        assertThat(result.id()).isNotNull();
+        assertThat(result.customerName()).isEqualTo("Alice");
+        verify(orderRepository).save(any());
+    }
+
+    @Test
+    @DisplayName("create — 고객명 공백 시 예외 발생")
+    void create_blankCustomerName_throwsException() {
+        var request = new CreateOrderRequest("", BigDecimal.TEN);
+        assertThatThrownBy(() -> orderService.create(request))
+            .isInstanceOf(IllegalArgumentException.class)
+            .hasMessageContaining("customer");
+    }
+}
+```
+
+### 컨트롤러 테스트
+
+```java
+@WebMvcTest(OrderController.class)
+class OrderControllerTest {
+    @Autowired MockMvc mockMvc;
+    @MockBean OrderService orderService;
+
+    @Test
+    @DisplayName("POST /orders — 201 반환")
+    void createOrder_returns201() throws Exception {
+        when(orderService.create(any())).thenReturn(sampleResponse());
+
+        mockMvc.perform(post("/api/orders")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("""{"customerName":"Alice","amount":100}"""))
+            .andExpect(status().isCreated())
+            .andExpect(jsonPath("$.data.customerName").value("Alice"));
+    }
+
+    @Test
+    @DisplayName("POST /orders — 검증 실패 시 400 반환")
+    void createOrder_invalidInput_returns400() throws Exception {
+        mockMvc.perform(post("/api/orders")
+                .contentType(MediaType.APPLICATION_JSON)
+                .content("""{"customerName":"","amount":-1}"""))
+            .andExpect(status().isBadRequest());
+    }
+}
+```
+
+### 레포지토리 테스트
+
+```java
+@DataJpaTest
+@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
+@Import(TestContainersConfig.class)
+class OrderRepositoryTest {
+    @Autowired OrderRepository repository;
+
+    @Test
+    void findByCustomerName_existingName_returnsOrders() {
+        repository.save(new OrderEntity("Alice", BigDecimal.TEN));
+        var results = repository.findByCustomerName("Alice");
+        assertThat(results).hasSize(1);
+    }
+}
+```
+
+## Phase 3 — GREEN (최소 구현)
+
+테스트를 통과하는 최소한의 코드만 작성. 과도한 구현 금지.
+
+```bash
+# 테스트 실행
+./mvnw test -Dtest=OrderServiceTest -q
+./gradlew test --tests "com.example.service.OrderServiceTest"
+```
+
+모든 테스트 통과 확인 후 다음 단계.
+
+## Phase 4 — REFACTOR
+
+테스트가 통과한 상태에서:
+- 중복 제거
+- 명명 개선
+- 메서드 추출
+- 매 변경 후 테스트 재실행
+
+## Phase 5 — COVERAGE
+
+```bash
+./mvnw test jacoco:report -q
+./gradlew test jacocoTestReport
+# 리포트: target/site/jacoco/index.html
+```
+
+80% 미만이면 누락된 경로에 대한 테스트 추가.
+
+## 파라미터화 테스트
+
+```java
+@ParameterizedTest
+@CsvSource({
+    "100.00, 10, 90.00",
+    "50.00, 0,  50.00",
+    "200.00, 25, 150.00"
+})
+@DisplayName("할인 계산 정확성")
+void applyDiscount(BigDecimal price, int pct, BigDecimal expected) {
+    assertThat(PricingUtils.discount(price, pct))
+        .isEqualByComparingTo(expected);
+}
+```
+
+## 테스트 데이터 빌더
+
+```java
+class OrderBuilder {
+    private String customerName = "Test Customer";
+    private BigDecimal amount = BigDecimal.TEN;
+
+    OrderBuilder withCustomerName(String name) {
+        this.customerName = name;
+        return this;
+    }
+    OrderBuilder withAmount(BigDecimal amount) {
+        this.amount = amount;
+        return this;
+    }
+    Order build() {
+        return new Order(null, customerName, amount);
+    }
+}
+```
+
+For detailed TDD patterns, see `skill: springboot-tdd`.

package/bin/cli.js

@@ -0,0 +1,144 @@
+#!/usr/bin/env node
+// npx backend-claude-code [target-dir] 진입점
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const PKG_DIR = path.join(__dirname, '..');
+const TARGET = process.argv[2] ? path.resolve(process.argv[2]) : process.cwd();
+
+if (!fs.existsSync(TARGET)) {
+  console.error(`Error: 대상 디렉토리가 존재하지 않습니다: ${TARGET}`);
+  process.exit(1);
+}
+
+console.log(`backend-claude-code → ${TARGET}`);
+
+const CLAUDE_DIR   = path.join(TARGET, '.claude');
+const TRACKING     = path.join(CLAUDE_DIR, '.installed-files');
+const IGNORE_FILE  = path.join(CLAUDE_DIR, '.claude-ignore');
+
+// 디렉토리 초기화
+for (const d of ['rules', 'agents', 'commands', 'skills']) {
+  fs.mkdirSync(path.join(CLAUDE_DIR, d), { recursive: true });
+}
+if (!fs.existsSync(TRACKING)) fs.writeFileSync(TRACKING, '');
+
+// .claude-ignore 파싱
+const ignored = new Set(
+  fs.existsSync(IGNORE_FILE)
+    ? fs.readFileSync(IGNORE_FILE, 'utf8')
+        .split('\n')
+        .map(l => l.trim())
+        .filter(l => l && !l.startsWith('#'))
+    : []
+);
+const isIgnored = rel => ignored.has(rel);
+
+// 트래킹 파일 읽기/쓰기
+const readTracked  = () => new Set(fs.readFileSync(TRACKING, 'utf8').split('\n').filter(Boolean));
+const writeTracked = set => fs.writeFileSync(TRACKING, [...set].join('\n') + (set.size ? '\n' : ''));
+
+const track   = dest => { const s = readTracked(); s.add(dest);    writeTracked(s); };
+const untrack = dest => { const s = readTracked(); s.delete(dest); writeTracked(s); };
+
+// 파일 동기화
+const syncFile = (src, dest, rel) => {
+  if (isIgnored(rel)) { console.log(`  skip (ignored): ${rel}`); return; }
+  fs.copyFileSync(src, dest);
+  track(dest);
+  console.log(`  sync: ${rel}`);
+};
+
+// dest → { rel, src } 매핑
+const resolve = dest => {
+  const settingsDest = path.join(CLAUDE_DIR, 'settings.json');
+  if (dest === settingsDest)
+    return { rel: 'settings.json', src: path.join(PKG_DIR, '.claude', 'settings.json') };
+  if (dest.startsWith(CLAUDE_DIR + path.sep)) {
+    const rel = dest.slice(CLAUDE_DIR.length + 1);
+    return { rel, src: path.join(PKG_DIR, rel) };
+  }
+  if (dest === path.join(TARGET, 'CLAUDE.md'))
+    return { rel: 'CLAUDE.md', src: path.join(PKG_DIR, 'CLAUDE.md') };
+  if (dest === path.join(TARGET, '.mcp.json'))
+    return { rel: '.mcp.json', src: path.join(PKG_DIR, '.mcp.json') };
+  return null;
+};
+
+// --- 소스에서 삭제된 파일 정리 ---
+console.log('\n정리 중...');
+for (const dest of readTracked()) {
+  const r = resolve(dest);
+  if (!r) continue;
+  if (fs.existsSync(r.src)) continue;
+
+  if (isIgnored(r.rel)) {
+    console.log(`  keep (ignored, source removed): ${r.rel}`);
+  } else {
+    fs.rmSync(dest, { force: true });
+    untrack(dest);
+    console.log(`  remove: ${r.rel}`);
+  }
+}
+
+// --- 동기화 ---
+console.log('\n동기화 중...');
+
+for (const dir of ['rules', 'agents', 'commands']) {
+  const srcDir = path.join(PKG_DIR, dir);
+  if (!fs.existsSync(srcDir)) continue;
+  for (const fname of fs.readdirSync(srcDir).filter(f => f.endsWith('.md'))) {
+    syncFile(path.join(srcDir, fname), path.join(CLAUDE_DIR, dir, fname), `${dir}/${fname}`);
+  }
+}
+
+const skillsDir = path.join(PKG_DIR, 'skills');
+if (fs.existsSync(skillsDir)) {
+  for (const name of fs.readdirSync(skillsDir)) {
+    const src = path.join(skillsDir, name, 'SKILL.md');
+    if (!fs.existsSync(src)) continue;
+    const destDir = path.join(CLAUDE_DIR, 'skills', name);
+    fs.mkdirSync(destDir, { recursive: true });
+    syncFile(src, path.join(destDir, 'SKILL.md'), `skills/${name}/SKILL.md`);
+  }
+}
+
+const settingsSrc = path.join(PKG_DIR, '.claude', 'settings.json');
+if (fs.existsSync(settingsSrc)) {
+  syncFile(settingsSrc, path.join(CLAUDE_DIR, 'settings.json'), 'settings.json');
+}
+
+const mcpSrc = path.join(PKG_DIR, '.mcp.json');
+if (fs.existsSync(mcpSrc)) {
+  syncFile(mcpSrc, path.join(TARGET, '.mcp.json'), '.mcp.json');
+}
+
+const claudeMdSrc = path.join(PKG_DIR, 'CLAUDE.md');
+if (fs.existsSync(claudeMdSrc)) {
+  syncFile(claudeMdSrc, path.join(TARGET, 'CLAUDE.md'), 'CLAUDE.md');
+}
+
+// GitHub 템플릿 (항상 덮어쓰기)
+const githubSrc = path.join(PKG_DIR, '.github');
+if (fs.existsSync(githubSrc)) {
+  const prSrc = path.join(githubSrc, 'PULL_REQUEST_TEMPLATE.md');
+  if (fs.existsSync(prSrc)) {
+    fs.mkdirSync(path.join(TARGET, '.github'), { recursive: true });
+    fs.copyFileSync(prSrc, path.join(TARGET, '.github', 'PULL_REQUEST_TEMPLATE.md'));
+  }
+  const issueSrc = path.join(githubSrc, 'ISSUE_TEMPLATE');
+  if (fs.existsSync(issueSrc)) {
+    const issueDest = path.join(TARGET, '.github', 'ISSUE_TEMPLATE');
+    fs.mkdirSync(issueDest, { recursive: true });
+    for (const fname of fs.readdirSync(issueSrc).filter(f => f.endsWith('.md'))) {
+      fs.copyFileSync(path.join(issueSrc, fname), path.join(issueDest, fname));
+    }
+  }
+}
+
+console.log('\n완료!');
+console.log('\n특정 파일을 업데이트에서 제외하려면:');
+console.log(`  ${IGNORE_FILE}`);
+console.log('  예시: rules/repository-patterns.md');

package/commands/db-migrate.md

@@ -0,0 +1,134 @@
+---
+description: DB 마이그레이션 실행·상태 확인·롤백 — Flyway 또는 Liquibase 자동 감지
+argument-hint: [info | migrate | rollback | repair | blank for status]
+---
+
+# DB Migrate
+
+**Action**: $ARGUMENTS (기본값: `info`)
+
+---
+
+## Phase 1 — DETECT
+
+빌드 도구와 마이그레이션 도구 감지:
+
+```bash
+# 빌드 도구
+[ -f "pom.xml" ] && echo "Maven" || echo "Gradle"
+
+# 마이그레이션 도구
+grep -q "flyway" pom.xml build.gradle build.gradle.kts 2>/dev/null && echo "Flyway"
+grep -q "liquibase" pom.xml build.gradle build.gradle.kts 2>/dev/null && echo "Liquibase"
+```
+
+마이그레이션 도구를 찾을 수 없으면 종료: "pom.xml 또는 build.gradle에서 Flyway/Liquibase 의존성을 찾을 수 없습니다."
+
+마이그레이션 파일 위치 확인:
+```bash
+find src/main/resources -name "*.sql" -path "*/migration*" | head -10
+find src/main/resources -name "*.sql" -path "*/db*" | head -10
+```
+
+## Phase 2 — INFO (현재 상태 확인)
+
+`$ARGUMENTS`가 비어 있거나 `info`인 경우:
+
+**Flyway (Maven)**:
+```bash
+./mvnw flyway:info -q 2>&1
+```
+
+**Flyway (Gradle)**:
+```bash
+./gradlew flywayInfo 2>&1
+```
+
+**Liquibase (Maven)**:
+```bash
+./mvnw liquibase:status -q 2>&1
+```
+
+**Liquibase (Gradle)**:
+```bash
+./gradlew liquibaseStatus 2>&1
+```
+
+현재 버전, 적용된 마이그레이션, 대기 중인 마이그레이션을 보고.
+
+## Phase 3 — MIGRATE
+
+`$ARGUMENTS`가 `migrate`인 경우:
+
+### 사전 확인
+```bash
+# 대기 중인 마이그레이션 목록 확인
+./mvnw flyway:info -q 2>&1 | grep "Pending"
+```
+
+대기 중인 마이그레이션이 있으면 목록을 보여주고 확인 요청.
+
+### 실행
+**Flyway (Maven)**:
+```bash
+./mvnw flyway:migrate 2>&1
+```
+
+**Flyway (Gradle)**:
+```bash
+./gradlew flywayMigrate 2>&1
+```
+
+**Liquibase (Maven)**:
+```bash
+./mvnw liquibase:update 2>&1
+```
+
+### 실행 후 검증
+```bash
+./mvnw flyway:info -q 2>&1 | tail -10
+```
+
+## Phase 4 — ROLLBACK
+
+`$ARGUMENTS`가 `rollback`인 경우:
+
+> **주의**: Flyway 무료 버전은 undo를 지원하지 않음. Liquibase는 rollbackCount 사용.
+
+**Flyway Pro (Maven)**:
+```bash
+./mvnw flyway:undo 2>&1
+```
+
+**Liquibase (Maven)**:
+```bash
+./mvnw liquibase:rollback -Dliquibase.rollbackCount=1 2>&1
+```
+
+롤백 후 현재 상태 재확인.
+
+## Phase 5 — REPAIR
+
+`$ARGUMENTS`가 `repair`인 경우 (체크섬 불일치 또는 실패한 마이그레이션 수정):
+
+**Flyway (Maven)**:
+```bash
+./mvnw flyway:repair 2>&1
+```
+
+## Output
+
+```
+DB Migration — <날짜>
+Tool: Flyway | Liquibase
+Build: Maven | Gradle
+Action: info | migrate | rollback | repair
+
+Current version: <version>
+Applied: N
+Pending: N
+
+Status: SUCCESS | FAILED | NO_CHANGES
+```
+
+> 마이그레이션 파일 작성 시 `skill: database-migrations` 참조.

package/commands/dev-build.md

@@ -0,0 +1,72 @@
+---
+description: Java 빌드 오류 진단 및 수정 — Maven/Gradle 컴파일/테스트 실패 자동 해결
+argument-hint: [error message | blank to auto-detect]
+---
+
+# Java Build Fix
+
+**Input**: $ARGUMENTS
+
+---
+
+## Phase 1 — DETECT BUILD TOOL
+
+```bash
+[ -f "pom.xml" ] && echo "Maven" || \
+[ -f "build.gradle.kts" ] && echo "Gradle Kotlin DSL" || \
+[ -f "build.gradle" ] && echo "Gradle" || \
+echo "Unknown — 빌드 파일을 찾을 수 없습니다"
+```
+
+## Phase 2 — RUN BUILD
+
+Maven:
+```bash
+./mvnw compile -q --no-transfer-progress 2>&1
+```
+
+Gradle:
+```bash
+./gradlew compileJava -q 2>&1
+```
+
+오류 없으면: "빌드 성공. 오류가 없습니다."
+
+## Phase 3 — PARSE ERROR
+
+오류 메시지 분석:
+1. 오류 타입 식별 (컴파일, 의존성, 어노테이션 프로세서)
+2. 영향 받는 파일과 라인 특정
+3. 근본 원인 파악
+
+## Phase 4 — DELEGATE TO java-build-resolver
+
+`java-build-resolver` 에이전트에 위임:
+- 오류 메시지 전달
+- 영향 받는 파일 목록 포함
+- 빌드 도구 (Maven/Gradle) 명시
+
+## Phase 5 — VERIFY
+
+수정 후 빌드 재실행:
+```bash
+./mvnw compile -q --no-transfer-progress 2>&1 || \
+./gradlew compileJava -q 2>&1
+```
+
+성공 시:
+```bash
+./mvnw test -q --no-transfer-progress 2>&1 | tail -10 || \
+./gradlew test -q 2>&1 | tail -10
+```
+
+## Output
+
+```
+Build Fix — <날짜>
+Build Tool: Maven | Gradle
+Initial Status: FAILED
+Errors Fixed: N
+Files Modified: <파일 목록>
+Final Status: SUCCESS | FAILED
+```

package/commands/dev-coverage.md

@@ -0,0 +1,73 @@
+---
+description: Analyze coverage, identify gaps, and generate missing tests toward the target threshold.
+---
+
+# Test Coverage
+
+Analyze test coverage, identify gaps, and generate missing tests to reach 80%+ coverage.
+
+## Step 1: Detect Test Framework
+
+| Indicator | Coverage Command |
+|-----------|-----------------|
+| `jest.config.*` or `package.json` jest | `npx jest --coverage --coverageReporters=json-summary` |
+| `vitest.config.*` | `npx vitest run --coverage` |
+| `pytest.ini` / `pyproject.toml` pytest | `pytest --cov=src --cov-report=json` |
+| `Cargo.toml` | `cargo llvm-cov --json` |
+| `pom.xml` with JaCoCo | `mvn test jacoco:report` |
+| `go.mod` | `go test -coverprofile=coverage.out ./...` |
+
+## Step 2: Analyze Coverage Report
+
+1. Run the coverage command
+2. Parse the output (JSON summary or terminal output)
+3. List files **below 80% coverage**, sorted worst-first
+4. For each under-covered file, identify:
+   - Untested functions or methods
+   - Missing branch coverage (if/else, switch, error paths)
+   - Dead code that inflates the denominator
+
+## Step 3: Generate Missing Tests
+
+For each under-covered file, generate tests following this priority:
+
+1. **Happy path** — Core functionality with valid inputs
+2. **Error handling** — Invalid inputs, missing data, network failures
+3. **Edge cases** — Empty arrays, null/undefined, boundary values (0, -1, MAX_INT)
+4. **Branch coverage** — Each if/else, switch case, ternary
+
+### Test Generation Rules
+
+- Place tests adjacent to source: `foo.ts` → `foo.test.ts` (or project convention)
+- Use existing test patterns from the project (import style, assertion library, mocking approach)
+- Mock external dependencies (database, APIs, file system)
+- Each test should be independent — no shared mutable state between tests
+- Name tests descriptively: `test_create_user_with_duplicate_email_returns_409`
+
+## Step 4: Verify
+
+1. Run the full test suite — all tests must pass
+2. Re-run coverage — verify improvement
+3. If still below 80%, repeat Step 3 for remaining gaps
+
+## Step 5: Report
+
+Show before/after comparison:
+
+```
+Coverage Report
+──────────────────────────────
+File                   Before  After
+src/services/auth.ts   45%     88%
+src/utils/validation.ts 32%    82%
+──────────────────────────────
+Overall:               67%     84%  PASS:
+```
+
+## Focus Areas
+
+- Functions with complex branching (high cyclomatic complexity)
+- Error handlers and catch blocks
+- Utility functions used across the codebase
+- API endpoint handlers (request → response flow)
+- Edge cases: null, undefined, empty string, empty array, zero, negative numbers

package/commands/dev-fix.md

@@ -0,0 +1,75 @@
+---
+description: 빌드 에러 자동 수정 — 빌드 도구를 감지하고 컴파일/테스트 오류를 수정합니다
+argument-hint: [blank to auto-detect build errors]
+---
+
+# Build Fix
+
+**Input**: $ARGUMENTS
+
+---
+
+## Step 1 — DETECT
+
+```bash
+[ -f "pom.xml" ] && echo "Maven" || \
+[ -f "build.gradle.kts" ] && echo "Gradle KTS" || \
+[ -f "build.gradle" ] && echo "Gradle" || \
+echo "No build file found"
+```
+
+Java 버전 확인:
+```bash
+java -version 2>&1 | head -1
+./mvnw --version 2>&1 | head -1 || ./gradlew --version 2>&1 | head -3
+```
+
+## Step 2 — BUILD
+
+Maven:
+```bash
+./mvnw clean compile -q --no-transfer-progress 2>&1
+```
+
+Gradle:
+```bash
+./gradlew clean compileJava -q 2>&1
+```
+
+## Step 3 — ANALYZE ERRORS
+
+오류 없으면: "빌드 성공. 수정할 오류가 없습니다."
+
+오류 있으면 분류:
+- **컴파일 오류** → `java-build-resolver` 에이전트
+- **의존성 오류** → `java-build-resolver` 에이전트
+- **테스트 실패** → 별도 분석 후 `java-build-resolver`
+
+## Step 4 — FIX
+
+`java-build-resolver` 에이전트에 위임:
+- 오류 메시지 전달
+- 빌드 도구 명시
+- 영향 파일 목록 포함
+
+**원칙**: 증상을 억제하지 않고 근본 원인을 수정. `@SuppressWarnings` 금지.
+
+## Step 5 — VERIFY
+
+수정 후:
+```bash
+# 컴파일 확인
+./mvnw compile -q --no-transfer-progress 2>&1 | tail -3 || \
+./gradlew compileJava -q 2>&1 | tail -3
+
+# 테스트 확인
+./mvnw test -q --no-transfer-progress 2>&1 | tail -5 || \
+./gradlew test -q 2>&1 | tail -5
+```
+
+## Stop Condition
+
+3회 시도 후에도 실패 시:
+- 오류 상세 내용 보고
+- 수동 개입 요청
+- 아키텍처 변경이 필요한 경우 `planner` 에이전트 권장