backend-claude-code 1.0.0

package/.claude/settings.json

@@ -0,0 +1,42 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(./mvnw:*)",
+      "Bash(./gradlew:*)",
+      "Bash(mvn:*)",
+      "Bash(gradle:*)",
+      "Bash(java -version:*)",
+      "Bash(git diff:*)",
+      "Bash(git log:*)",
+      "Bash(git status:*)",
+      "Bash(git diff --name-only:*)",
+      "Bash(grep -rn:*)",
+      "Bash(find . -name:*)",
+      "Bash(ls:*)"
+    ]
+  },
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if echo \"$FILE_PATH\" | grep -q '\\.java$'; then echo '[Hook] Java 파일 변경 감지 — 컴파일 중...'; (./mvnw compile -q --no-transfer-progress 2>&1 | tail -5 || ./gradlew compileJava -q 2>&1 | tail -5) && echo '[Hook] 컴파일 OK' || echo '[Hook] 컴파일 실패 — /java-build 실행을 권장합니다'; fi"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "if [ -f pom.xml ] || [ -f build.gradle ] || [ -f build.gradle.kts ]; then echo '[Hook] 최종 빌드 검증 중...'; (./mvnw verify -q --no-transfer-progress 2>&1 | tail -10 || ./gradlew check -q 2>&1 | tail -10) && echo '[Hook] 모든 검사 통과' || echo '[Hook] 검증 실패 — 빌드 로그를 확인하세요'; fi"
+          }
+        ]
+      }
+    ]
+  }
+}

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,35 @@
+---
+name: 버그 리포트
+about: 버그를 발견했을 때 사용하세요
+title: '[BUG] '
+labels: bug
+assignees: ''
+---
+
+## 버그 설명
+<!-- 어떤 문제가 발생했는지 간략히 설명 -->
+
+## 재현 절차
+1. 
+2. 
+3. 
+
+## 기대 동작
+<!-- 어떻게 동작해야 하는지 -->
+
+## 실제 동작
+<!-- 실제로 어떻게 동작하는지 -->
+
+## 로그 / 스택 트레이스
+```
+# 관련 로그나 스택 트레이스를 붙여넣으세요
+```
+
+## 환경
+- Spring Boot 버전:
+- Java 버전:
+- OS:
+- 빌드 도구 (Maven / Gradle):
+
+## 추가 정보
+<!-- 기타 관련 정보 (스크린샷, 설정 파일 등) -->

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,33 @@
+---
+name: 기능 요청
+about: 새로운 기능을 제안할 때 사용하세요
+title: '[FEAT] '
+labels: enhancement
+assignees: ''
+---
+
+## 목적
+<!-- 이 기능이 왜 필요한지, 어떤 문제를 해결하는지 -->
+
+## 도메인 / 레이어
+<!-- 어느 영역에 해당하는지 체크 -->
+- [ ] Controller (API 엔드포인트)
+- [ ] Service (비즈니스 로직)
+- [ ] Repository (데이터 접근)
+- [ ] Domain (엔티티 / VO)
+- [ ] 인프라 (설정, 보안, 배포)
+
+## 제안하는 해결책
+<!-- 어떻게 구현하면 좋을지 -->
+
+## 인수 조건
+<!-- 이 기능이 완료됐다고 판단하는 기준 -->
+- [ ] 
+- [ ] 
+- [ ] 
+
+## 대안
+<!-- 고려한 다른 접근법이 있다면 -->
+
+## 추가 정보
+<!-- 참고 자료, 관련 이슈 등 -->

package/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,32 @@
+## 변경 내용
+<!-- 무엇을 바꿨는지 간략히 -->
+
+## 변경 이유
+<!-- 왜 이 변경이 필요한지 -->
+
+## 관련 이슈
+<!-- Closes #123 -->
+
+## 테스트
+- [ ] 단위 테스트 추가/수정 (`@ExtendWith(MockitoExtension.class)`)
+- [ ] 웹 레이어 테스트 (`@WebMvcTest`)
+- [ ] 통합 테스트 (`@SpringBootTest`)
+- [ ] JaCoCo 커버리지 80%+ 확인 (`./mvnw verify`)
+
+## 변경 유형
+- [ ] feat: 새 기능
+- [ ] fix: 버그 수정
+- [ ] refactor: 기능 변경 없는 코드 개선
+- [ ] docs: 문서 변경
+- [ ] test: 테스트 추가/수정
+- [ ] chore: 빌드/설정 변경
+- [ ] perf: 성능 개선
+
+## Spring Boot 체크리스트
+- [ ] 생성자 주입 사용 (`@Autowired` 필드 주입 없음)
+- [ ] `@Transactional` 서비스 레이어에만 적용
+- [ ] 엔티티 직접 반환 없음 (DTO 변환)
+- [ ] `@Valid` 검증 적용
+- [ ] 하드코딩된 시크릿 없음
+- [ ] N+1 쿼리 없음 (EAGER fetch 없음)
+- [ ] 예외 처리 누락 없음 (swallowed exception 없음)

package/.mcp.json

@@ -0,0 +1,19 @@
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github@2025.4.8"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
+      }
+    },
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@2.1.4"]
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking@2025.12.18"]
+    }
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,126 @@
+# CLAUDE.md
+
+Java/Spring Boot 백엔드 API 프로젝트를 위한 Claude Code 가이드.
+
+> **이 파일을 프로젝트에 맞게 커스터마이징하세요.** 특히 "프로젝트 개요"와 "아키텍처" 섹션.
+
+## 프로젝트 개요
+
+<!-- TODO: 프로젝트 목적과 주요 도메인을 여기에 작성하세요 -->
+Spring Boot 기반 REST API 백엔드 서비스.
+
+## 빌드 명령어
+
+```bash
+# Gradle
+./gradlew compileJava             # 컴파일
+./gradlew test                    # 단위 테스트
+./gradlew check                   # 전체 테스트 + 린트
+./gradlew bootRun                 # 로컬 실행
+./gradlew jacocoTestReport        # 커버리지 리포트
+```
+
+## 아키텍처
+
+3계층 표준 아키텍처:
+
+```
+Controller  →  Service  →  Repository  →  Database
+   (HTTP)    (Business)    (Data Access)
+```
+
+```
+src/main/java/com/example/
+├── controller/      # REST 엔드포인트, 입력 검증
+├── service/         # 비즈니스 로직, 트랜잭션
+├── repository/      # Spring Data JPA 인터페이스
+├── domain/          # 엔티티, VO, 도메인 모델
+├── dto/             # 요청/응답 DTO (record 선호)
+├── exception/       # 도메인 예외, 글로벌 핸들러
+└── config/          # Spring 설정 클래스
+
+src/test/java/com/example/
+├── controller/      # @WebMvcTest
+├── service/         # @ExtendWith(MockitoExtension.class)
+├── repository/      # @DataJpaTest
+└── integration/     # @SpringBootTest
+```
+
+## 개발 워크플로우
+
+```
+1. 기능 계획   → /dev plan  (코드베이스 분석 후 계획서 작성)
+2. 구현 & 검증 → /dev run   (계획서 기반 구현 + 빌드 확인)
+3. 테스트      → /dev test  (TDD 워크플로우, 테스트 먼저 작성)
+4. 리뷰        → /dev review (로컬 변경 또는 PR 종합 리뷰)
+5. 커밋        → /git commit
+6. PR 생성     → /git pr
+```
+
+전체 파이프라인 한 번에: `/dev`
+
+## 슬래시 커맨드
+
+### dev — 개발 워크플로우
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/dev` | 계획 → 구현 → 테스트 전체 워크플로우 |
+| `/dev plan` | 코드베이스 분석 후 구현 계획서 작성 |
+| `/dev run` | 계획서 기반 코드 구현 및 검증 |
+| `/dev test` | TDD 워크플로우 (테스트 먼저 작성) |
+| `/dev review` | 로컬 변경(Java 특화) 또는 PR 종합 리뷰 |
+| `/dev build` | 빌드 오류 진단 및 수정 |
+| `/dev fix` | 빌드 에러 자동 수정 |
+| `/dev verify` | 빌드·정적분석·테스트·커버리지·보안 전체 검증 |
+| `/dev coverage` | 커버리지 분석 및 미달 영역 테스트 생성 |
+
+### git — GitHub 워크플로우
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/git commit` | 변경사항 커밋 |
+| `/git pr` | PR 자동 생성 (push → PR → CI 확인) |
+| `/git issue` | 이슈 생성 (`bug` / `feat`) |
+
+### 기타
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/db-migrate` | DB 마이그레이션 실행·상태 확인·롤백 |
+
+## 에이전트
+
+| 에이전트 | 용도 | 언제 사용 |
+|---------|------|----------|
+| `code-reviewer` | Java/Spring Boot 코드 리뷰 | 코드 수정 후 항상 |
+| `java-build-resolver` | 빌드/컴파일 에러 수정 | 빌드 실패 시 |
+| `security-reviewer` | 보안 취약점 분석 | 인증/인가/입력처리 변경 시 |
+| `tdd-guide` | TDD 워크플로우 안내 | 새 기능/버그수정 시 |
+| `planner` | 기능 구현 계획 수립 | 복잡한 기능 시작 전 |
+| `database-reviewer` | DB 쿼리·스키마 최적화 | JPA/SQL 변경 시 |
+| `java-performance-reviewer` | JVM·N+1·커넥션 풀·캐시 성능 분석 | 성능 이슈 발생 시 |
+
+## 핵심 규칙
+
+1. **코드 수정 후**: 반드시 `code-reviewer` 에이전트 실행
+2. **새 기능**: TDD 워크플로우 준수 (테스트 RED → 구현 GREEN → 리팩토링)
+3. **빌드 실패**: `java-build-resolver` 에이전트 사용, 증상 억제 금지
+4. **보안 코드**: `security-reviewer` 실행 필수 (인증/DB쿼리/파일처리)
+5. **커밋 전**: `./mvnw verify` 또는 `./gradlew check` 통과 확인
+6. **의존성 주입**: 필드 주입(`@Autowired`) 금지 — 생성자 주입 필수
+
+## 스킬 참조
+
+| 작업 | 스킬 |
+|------|------|
+| REST API 구조 설계 | `springboot-patterns` |
+| JPA 엔티티/쿼리 최적화 | `jpa-patterns` |
+| 보안 설정 | `springboot-security` |
+| TDD 패턴 | `springboot-tdd` |
+| 코딩 표준 | `java-coding-standards` |
+| DB 마이그레이션 | `database-migrations` |
+| PostgreSQL 쿼리/인덱스 | `postgres-patterns` |
+| 헥사고날 아키텍처 | `hexagonal-architecture` |
+| REST API 설계 원칙 | `api-design` |
+| ADR 작성 | `architecture-decision-records` |

package/README.md

@@ -0,0 +1,142 @@
+# backend-claude-code
+
+Java/Spring Boot 백엔드 프로젝트에 Claude Code 설정을 빠르게 적용하는 harness.
+
+---
+
+## 설치
+
+```bash
+# 현재 디렉토리에 설치
+./install.sh
+
+# 특정 프로젝트 경로에 설치
+./install.sh /path/to/your/project
+```
+
+설치 시 이미 존재하는 파일은 덮어쓰지 않고 스킵합니다.
+복사된 파일 목록은 `.claude/.installed-files`에 기록됩니다.
+
+## 제거
+
+```bash
+# 현재 디렉토리에서 제거
+./uninstall.sh
+
+# 특정 프로젝트 경로에서 제거
+./uninstall.sh /path/to/your/project
+```
+
+`.installed-files`에 기록된 파일만 삭제합니다. 프로젝트에서 직접 만든 파일은 건드리지 않습니다.
+
+---
+
+## 설치 후 해야 할 일
+
+1. `CLAUDE.md` — 프로젝트 이름, 아키텍처, 패키지 구조를 맞게 수정
+2. `.mcp.json` — `GITHUB_TOKEN` 환경변수 설정
+3. `.claude/settings.json` — 기존 파일이 있다면 수동 병합
+
+---
+
+## 포함 항목
+
+### 에이전트 (8개)
+
+| 에이전트 | 역할 |
+|---------|------|
+| `java-reviewer` | Java/Spring Boot 코드 리뷰 |
+| `java-build-resolver` | 빌드·컴파일 에러 수정 |
+| `security-reviewer` | 보안 취약점 분석 (OWASP) |
+| `tdd-guide` | TDD 워크플로우 안내 |
+| `planner` | 기능 구현 계획 수립 |
+| `database-reviewer` | DB 쿼리·스키마 최적화 |
+| `performance-optimizer` | 성능 병목 분석 |
+| `code-reviewer` | 코드 품질 종합 리뷰 |
+
+### 슬래시 커맨드 (13개)
+
+#### dev — 개발 워크플로우
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/dev` | 계획 → 구현 → 테스트 전체 워크플로우 실행 |
+| `/dev plan` | 코드베이스 분석 후 구현 계획서 작성 |
+| `/dev run` | 계획서 기반 코드 구현 및 검증 |
+| `/dev test` | TDD 워크플로우 (테스트 먼저 작성) |
+| `/dev review` | 로컬 변경사항(Java 특화) 또는 PR 종합 리뷰 |
+| `/dev build` | 빌드 오류 진단 및 수정 |
+| `/dev fix` | 빌드 에러 자동 수정 |
+| `/dev verify` | 빌드·정적분석·테스트·커버리지·보안 전체 검증 |
+| `/dev coverage` | 커버리지 분석 및 미달 영역 테스트 생성 |
+
+#### git — GitHub 워크플로우
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/git commit` | 변경사항 커밋 |
+| `/git pr` | PR 자동 생성 (push → PR → CI 확인) |
+| `/git issue` | 이슈 생성 (`bug` / `feat`) |
+
+#### 기타
+
+| 커맨드 | 설명 |
+|--------|------|
+| `/db-migrate` | DB 마이그레이션 실행·상태 확인·롤백 (Flyway/Liquibase 자동 감지) |
+
+### 스킬 (10개)
+
+> 사용법: 프롬프트에서 `skill: <이름>` 으로 참조
+
+#### Spring Boot
+
+| 스킬 | 설명 |
+|------|------|
+| `springboot-patterns` | Controller·Service·Repository 구조, 공통 패턴 |
+| `springboot-security` | Spring Security 설정 및 리뷰 기준 |
+| `springboot-tdd` | JUnit5·Mockito·Testcontainers TDD 워크플로우 |
+
+#### Java
+
+| 스킬 | 설명 |
+|------|------|
+| `java-coding-standards` | Java 코딩 규칙·관용구·금지 패턴 |
+| `jpa-patterns` | 엔티티 설계, N+1 해결, 쿼리 최적화 |
+
+#### 데이터베이스
+
+| 스킬 | 설명 |
+|------|------|
+| `database-migrations` | Flyway·Liquibase 마이그레이션 패턴 |
+| `postgres-patterns` | PostgreSQL 쿼리·인덱스·성능 패턴 |
+
+#### 아키텍처
+
+| 스킬 | 설명 |
+|------|------|
+| `hexagonal-architecture` | 헥사고날 아키텍처 (Ports & Adapters) 구현 |
+| `api-design` | REST API 설계 원칙·버저닝·에러 포맷 |
+| `architecture-decision-records` | ADR 작성 가이드 |
+
+
+### 규칙
+
+| 파일 | 적용 범위 |
+|------|----------|
+| `coding-style` | 전체 Java 파일 |
+| `testing` | 테스트 파일 |
+| `security` | 인증·인가·입력처리 |
+| `hooks` | PostToolUse·Stop 자동화 |
+| `architecture` | 레이어 구조 및 책임 |
+| `controller-patterns` | `*Controller.java` |
+| `dto-patterns` | `*Dtos.java` |
+| `entity-patterns` | `*Entity.java`, `domain/**` |
+| `repository-patterns` | `*Repository*.java` |
+| `service-patterns` | `*Service.java` |
+| `error-handling` | 예외 처리 전반 |
+
+### GitHub 템플릿
+
+- `.github/PULL_REQUEST_TEMPLATE.md` — Spring Boot 체크리스트 포함 PR 템플릿
+- `.github/ISSUE_TEMPLATE/bug_report.md` — 버그 리포트
+- `.github/ISSUE_TEMPLATE/feature_request.md` — 기능 요청

package/agents/code-reviewer.md

@@ -0,0 +1,84 @@
+---
+name: code-reviewer
+description: Expert Java and Spring Boot code reviewer specializing in layered architecture, JPA patterns, security, and concurrency. Use for all Java code changes. MUST BE USED for Spring Boot projects.
+tools: ["Read", "Grep", "Glob", "Bash"]
+model: sonnet
+---
+You are a senior Java engineer ensuring high standards of idiomatic Java and Spring Boot best practices.
+When invoked:
+1. Run `git diff -- '*.java'` to see recent Java file changes
+2. Run `./mvnw verify -q` or `./gradlew check` if available
+3. Focus on modified `.java` files
+4. Begin review immediately
+
+You DO NOT refactor or rewrite code — you report findings only.
+
+## Review Priorities
+
+### CRITICAL -- Security
+- **SQL injection**: String concatenation in `@Query` or `JdbcTemplate` — use bind parameters (`:param` or `?`)
+- **Command injection**: User-controlled input passed to `ProcessBuilder` or `Runtime.exec()` — validate and sanitise before invocation
+- **Path traversal**: User-controlled input passed to `new File(userInput)`, `Paths.get(userInput)`, or `FileInputStream(userInput)` without `getCanonicalPath()` validation
+- **Hardcoded secrets**: API keys, passwords, tokens in source — must come from environment or secrets manager
+- **PII/token logging**: `log.info(...)` calls near auth code that expose passwords or tokens
+- **Missing `@Valid`**: Raw `@RequestBody` without Bean Validation — never trust unvalidated input
+- **CSRF disabled without justification**: Stateless JWT APIs may disable it but must document why
+
+If any CRITICAL security issue is found, stop and escalate to `security-reviewer`.
+
+### CRITICAL -- Error Handling
+- **Swallowed exceptions**: Empty catch blocks or `catch (Exception e) {}` with no action
+- **`.get()` on Optional**: Calling `repository.findById(id).get()` without `.isPresent()` — use `.orElseThrow()`
+- **Missing `@RestControllerAdvice`**: Exception handling scattered across controllers instead of centralised
+- **Wrong HTTP status**: Returning `200 OK` with null body instead of `404`, or missing `201` on creation
+
+### HIGH -- Spring Boot Architecture
+- **Field injection**: `@Autowired` on fields is a code smell — constructor injection is required
+- **Business logic in controllers**: Controllers must delegate to the service layer immediately
+- **`@Transactional` on wrong layer**: Must be on service layer, not controller or repository
+- **Missing `@Transactional(readOnly = true)`**: Read-only service methods must declare this
+- **Entity exposed in response**: JPA entity returned directly from controller — use DTO or record projection
+
+### HIGH -- JPA / Database
+- **N+1 query problem**: `FetchType.EAGER` on collections — use `JOIN FETCH` or `@EntityGraph`
+- **Unbounded list endpoints**: Returning `List<T>` from endpoints without `Pageable` and `Page<T>`
+- **Missing `@Modifying`**: Any `@Query` that mutates data requires `@Modifying` + `@Transactional`
+- **Dangerous cascade**: `CascadeType.ALL` with `orphanRemoval = true` — confirm intent is deliberate
+
+### MEDIUM -- Concurrency and State
+- **Mutable singleton fields**: Non-final instance fields in `@Service` / `@Component` are a race condition
+- **Unbounded `@Async`**: `CompletableFuture` or `@Async` without a custom `Executor` — default creates unbounded threads
+- **Blocking `@Scheduled`**: Long-running scheduled methods that block the scheduler thread
+
+### MEDIUM -- Java Idioms and Performance
+- **String concatenation in loops**: Use `StringBuilder` or `String.join`
+- **Raw type usage**: Unparameterised generics (`List` instead of `List<T>`)
+- **Missed pattern matching**: `instanceof` check followed by explicit cast — use pattern matching (Java 16+)
+- **Null returns from service layer**: Prefer `Optional<T>` over returning null
+
+### MEDIUM -- Testing
+- **`@SpringBootTest` for unit tests**: Use `@WebMvcTest` for controllers, `@DataJpaTest` for repositories
+- **Missing Mockito extension**: Service tests must use `@ExtendWith(MockitoExtension.class)`
+- **`Thread.sleep()` in tests**: Use `Awaitility` for async assertions
+- **Weak test names**: `testFindUser` gives no information — use `should_return_404_when_user_not_found`
+
+## Diagnostic Commands
+```bash
+git diff -- '*.java'
+./mvnw verify -q
+./gradlew check
+./mvnw checkstyle:check
+./mvnw spotbugs:check
+./mvnw test
+grep -rn "@Autowired" src/main/java --include="*.java"
+grep -rn "FetchType.EAGER" src/main/java --include="*.java"
+grep -rn "\.get()" src/main/java --include="*.java" | grep -v "//.*\.get()"
+```
+Read `pom.xml`, `build.gradle`, or `build.gradle.kts` to determine the build tool and Spring Boot version before reviewing.
+
+## Approval Criteria
+- **Approve**: No CRITICAL or HIGH issues
+- **Warning**: MEDIUM issues only
+- **Block**: CRITICAL or HIGH issues found
+
+For detailed Spring Boot patterns and examples, see `skill: springboot-patterns`.

package/agents/database-reviewer.md

@@ -0,0 +1,91 @@
+---
+name: database-reviewer
+description: PostgreSQL database specialist for query optimization, schema design, security, and performance. Use PROACTIVELY when writing SQL, creating migrations, designing schemas, or troubleshooting database performance. Incorporates Supabase best practices.
+tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
+model: sonnet
+---
+
+# Database Reviewer
+
+You are an expert PostgreSQL database specialist focused on query optimization, schema design, security, and performance. Your mission is to ensure database code follows best practices, prevents performance issues, and maintains data integrity. Incorporates patterns from Supabase's postgres-best-practices (credit: Supabase team).
+
+## Core Responsibilities
+
+1. **Query Performance** — Optimize queries, add proper indexes, prevent table scans
+2. **Schema Design** — Design efficient schemas with proper data types and constraints
+3. **Security & RLS** — Implement Row Level Security, least privilege access
+4. **Connection Management** — Configure pooling, timeouts, limits
+5. **Concurrency** — Prevent deadlocks, optimize locking strategies
+6. **Monitoring** — Set up query analysis and performance tracking
+
+## Diagnostic Commands
+
+```bash
+psql $DATABASE_URL
+psql -c "SELECT query, mean_exec_time, calls FROM pg_stat_statements ORDER BY mean_exec_time DESC LIMIT 10;"
+psql -c "SELECT relname, pg_size_pretty(pg_total_relation_size(relid)) FROM pg_stat_user_tables ORDER BY pg_total_relation_size(relid) DESC;"
+psql -c "SELECT indexrelname, idx_scan, idx_tup_read FROM pg_stat_user_indexes ORDER BY idx_scan DESC;"
+```
+
+## Review Workflow
+
+### 1. Query Performance (CRITICAL)
+- Are WHERE/JOIN columns indexed?
+- Run `EXPLAIN ANALYZE` on complex queries — check for Seq Scans on large tables
+- Watch for N+1 query patterns
+- Verify composite index column order (equality first, then range)
+
+### 2. Schema Design (HIGH)
+- Use proper types: `bigint` for IDs, `text` for strings, `timestamptz` for timestamps, `numeric` for money, `boolean` for flags
+- Define constraints: PK, FK with `ON DELETE`, `NOT NULL`, `CHECK`
+- Use `lowercase_snake_case` identifiers (no quoted mixed-case)
+
+### 3. Security (CRITICAL)
+- RLS enabled on multi-tenant tables with `(SELECT auth.uid())` pattern
+- RLS policy columns indexed
+- Least privilege access — no `GRANT ALL` to application users
+- Public schema permissions revoked
+
+## Key Principles
+
+- **Index foreign keys** — Always, no exceptions
+- **Use partial indexes** — `WHERE deleted_at IS NULL` for soft deletes
+- **Covering indexes** — `INCLUDE (col)` to avoid table lookups
+- **SKIP LOCKED for queues** — 10x throughput for worker patterns
+- **Cursor pagination** — `WHERE id > $last` instead of `OFFSET`
+- **Batch inserts** — Multi-row `INSERT` or `COPY`, never individual inserts in loops
+- **Short transactions** — Never hold locks during external API calls
+- **Consistent lock ordering** — `ORDER BY id FOR UPDATE` to prevent deadlocks
+
+## Anti-Patterns to Flag
+
+- `SELECT *` in production code
+- `int` for IDs (use `bigint`), `varchar(255)` without reason (use `text`)
+- `timestamp` without timezone (use `timestamptz`)
+- Random UUIDs as PKs (use UUIDv7 or IDENTITY)
+- OFFSET pagination on large tables
+- Unparameterized queries (SQL injection risk)
+- `GRANT ALL` to application users
+- RLS policies calling functions per-row (not wrapped in `SELECT`)
+
+## Review Checklist
+
+- [ ] All WHERE/JOIN columns indexed
+- [ ] Composite indexes in correct column order
+- [ ] Proper data types (bigint, text, timestamptz, numeric)
+- [ ] RLS enabled on multi-tenant tables
+- [ ] RLS policies use `(SELECT auth.uid())` pattern
+- [ ] Foreign keys have indexes
+- [ ] No N+1 query patterns
+- [ ] EXPLAIN ANALYZE run on complex queries
+- [ ] Transactions kept short
+
+## Reference
+
+For detailed index patterns, schema design examples, connection management, concurrency strategies, JSONB patterns, and full-text search, see skills: `postgres-patterns` and `database-migrations`.
+
+---
+
+**Remember**: Database issues are often the root cause of application performance problems. Optimize queries and schema design early. Use EXPLAIN ANALYZE to verify assumptions. Always index foreign keys and RLS policy columns.
+
+*Patterns adapted from Supabase Agent Skills (credit: Supabase team) under MIT license.*