@kood/claude-code 0.2.4 → 0.3.0

package/templates/hono/CLAUDE.md

@@ -1,61 +1,105 @@
-# CLAUDE.md - Hono Server Framework
+# CLAUDE.md - Hono
 
-> Web Standards 기반 초경량 서버 프레임워크
-
-## Instructions
+> Web Standards 기반 초경량 프레임워크
 
+<instructions>
 @../../commands/git.md
+@docs/guides/getting-started.md
 @docs/library/hono/index.md
 @docs/library/prisma/index.md
+@docs/library/t3-env/index.md
 @docs/library/zod/index.md
-@docs/deployment/index.md
+</instructions>
 
 ---
 
-## STOP - 금지 사항
+<forbidden>
+
+| 분류 | 금지 |
+|------|------|
+| **Git** | `Generated with Claude Code`, `🤖`, `Co-Authored-By:`, 여러 줄, 이모지 |
+| **Prisma** | `db push/migrate/generate` 자동 실행, schema 임의 변경 |
+| **API** | handler 내 수동 검증/인증, 일반 Error throw |
+| **검색** | grep, rg, find |
 
-| 분류 | 금지 항목 |
-|------|----------|
-| **Git** | `Generated with Claude Code`, `🤖`, `Co-Authored-By:`, 여러 줄 커밋, 이모지 |
-| **Prisma** | `db push`, `migrate`, `generate` 자동 실행, schema 임의 변경 |
-| **API** | handler 내부 수동 검증 (→ zValidator), 수동 인증 (→ middleware), 일반 Error throw (→ HTTPException) |
-| **검색** | grep, rg, find (→ ast-grep 사용) |
+</forbidden>
 
 ---
 
-## ALWAYS - 필수 사항
+<required>
 
 | 작업 | 필수 |
 |------|------|
-| 작업 전 | 관련 docs 읽기 |
-| 코드 검색 | ast-grep 사용 |
-| 복잡한 분석 | Sequential Thinking MCP |
-| 3+ 파일 수정 | gemini-review 실행 |
-| 코드 작성 | UTF-8, 코드 묶음별 한글 주석 |
-| Prisma | Multi-File 구조, 모든 요소 한글 주석 |
+| 작업 전 | 관련 docs 읽기 (API→hono, DB→prisma) |
+| 코드 검색 | ast-grep |
+| 복잡한 작업 | Sequential Thinking MCP |
+| 3+ 파일 수정 | gemini-review |
+| Validation | zValidator, HTTPException 에러 처리 |
+| 코드 작성 | UTF-8, 코드 묶음별 한글 주석, Prisma Multi-File 모든 요소 주석 |
+
+</required>
 
 ---
 
-## Tech Stack
+<tech_stack>
 
-| 기술 | 버전 | 주의사항 |
-|------|------|----------|
-| Hono | 최신 | Web Standards 기반 |
-| TypeScript | 5.x | strict mode |
+| 기술 | 버전 | 주의 |
+|------|------|------|
+| Hono | 최신 | - |
+| TypeScript | 5.x | strict |
 | Prisma | **7.x** | `prisma-client`, output 필수 |
-| Zod | **4.x** | `z.email()`, `z.url()` (v4 문법) |
+| Zod | **4.x** | `z.email()`, `z.url()` |
+
+</tech_stack>
 
 ---
 
-## Quick Patterns
+<structure>
+```
+src/
+├── routes/
+│   ├── index.ts       # Root routes
+│   ├── users.ts       # /users/*
+│   └── posts.ts       # /posts/*
+├── middleware/        # Auth, CORS, Logger
+├── services/          # Business logic
+├── lib/
+│   ├── prisma.ts
+│   └── env.ts
+└── types/
+```
+
+공통 로직 → `src/services/`, 라우트별 로직 → 각 route 파일
+</structure>
+
+---
+
+<conventions>
+
+파일명: kebab-case
+TypeScript: const 선언, 명시적 return type, interface(객체)/type(유니온), any→unknown
+Import 순서: 외부 → 내부 → 상대경로 → type
+
+Prisma Multi-File:
+```
+prisma/schema/
+├── +base.prisma   # datasource, generator
+├── +enum.prisma   # enum
+└── [model].prisma # 모델별 (한글 주석!)
+```
+
+</conventions>
+
+---
 
-### App + 에러 핸들러
+<quick_patterns>
 
 ```typescript
+// App + 에러 핸들러
 import { Hono } from 'hono'
 import { HTTPException } from 'hono/http-exception'
 
-type Bindings = { DATABASE_URL: string; JWT_SECRET: string }
+type Bindings = { DATABASE_URL: string }
 
 const app = new Hono<{ Bindings: Bindings }>()
 
@@ -67,21 +111,18 @@ app.onError((err, c) => {
   return c.json({ error: 'Internal Server Error' }, 500)
 })
 
-app.notFound((c) => c.json({ error: 'Not Found' }, 404))
-
 export default app
 ```
 
-### Zod 검증 (v4 문법)
-
 ```typescript
+// Zod v4 + Validation
 import { zValidator } from '@hono/zod-validator'
 import { z } from 'zod'
 
 const schema = z.object({
-  email: z.email(),           // ✅ v4
+  email: z.email(),
   name: z.string().min(1).trim(),
-  website: z.url().optional() // ✅ v4
+  website: z.url().optional()
 })
 
 app.post('/users', zValidator('json', schema), (c) => {
@@ -90,36 +131,40 @@ app.post('/users', zValidator('json', schema), (c) => {
 })
 ```
 
-### Prisma Multi-File 구조
+```typescript
+// Middleware
+import { createMiddleware } from 'hono/factory'
+import { HTTPException } from 'hono/http-exception'
 
-```
-prisma/schema/
-├── +base.prisma    # datasource, generator
-├── +enum.prisma    # enum 정의
-├── user.prisma     # User 모델 (한글 주석 필수)
-└── post.prisma     # Post 모델
+export const authMiddleware = createMiddleware(async (c, next) => {
+  const token = c.req.header('Authorization')?.replace('Bearer ', '')
+  if (!token) throw new HTTPException(401, { message: 'Unauthorized' })
+
+  c.set('userId', decoded.sub)
+  await next()
+})
+
+// 사용
+app.use('/api/*', authMiddleware)
 ```
 
 ```prisma
-// +base.prisma
+// +base.prisma (Prisma 7.x)
 generator client {
-  provider = "prisma-client"      // ✅ v7
-  output   = "./generated/client" // ✅ 필수
+  provider = "prisma-client"
+  output   = "./generated/client"
 }
 ```
 
----
+</quick_patterns>
 
-## 문서 구조
+---
 
+<docs_structure>
 ```
 docs/
-├── library/
-│   ├── hono/       # 라우팅, 미들웨어, 검증, RPC
-│   ├── prisma/     # CRUD, 관계, D1 연동
-│   ├── zod/        # v4 문법, 검증 패턴
-│   ├── ai-sdk/     # LLM 통합 (streaming, tools)
-│   └── pino/       # 로깅
-├── deployment/     # Docker, Railway, Vercel, Cloudflare
-└── architecture/   # 아키텍처 패턴
+├── guides/       # getting-started, conventions, env-setup
+├── library/      # hono, prisma, t3-env, zod
+└── deployment/   # cloudflare, docker, railway, vercel
 ```
+</docs_structure>

package/templates/hono/docs/guides/conventions.md

@@ -0,0 +1,352 @@
+# 코드 컨벤션
+
+> Hono 프로젝트 코드 작성 규칙
+
+---
+
+<naming>
+
+## 파일 네이밍
+
+| 타입 | 규칙 | 예시 |
+|------|------|------|
+| **일반 파일** | kebab-case | `user-service.ts`, `auth-middleware.ts` |
+| **Route 파일** | kebab-case | `users.ts`, `posts.ts` |
+| **타입 파일** | kebab-case | `user-types.ts`, `api-types.ts` |
+
+</naming>
+
+---
+
+<typescript>
+
+## TypeScript 규칙
+
+| 규칙 | 설명 | 예시 |
+|------|------|------|
+| **함수 선언** | const 함수, 명시적 return type | `const fn = (): ReturnType => {}` |
+| **타입 정의** | interface (객체), type (유니온) | `interface User {}`, `type Status = 'a' \| 'b'` |
+| **any 금지** | unknown 사용 | `const data: unknown = JSON.parse(str)` |
+| **Import 타입** | type import 분리 | `import type { User } from '@/types'` |
+
+## 패턴
+
+```typescript
+// ✅ const 함수, 명시적 타입
+const getUserById = async (id: string): Promise<User | null> => {
+  return prisma.user.findUnique({ where: { id } })
+}
+
+// ✅ 간단한 함수도 명시적 타입
+const formatDate = (date: Date): string => {
+  return date.toISOString()
+}
+
+// ✅ any 금지 → unknown 사용
+const parseJSON = (data: string): unknown => {
+  return JSON.parse(data)
+}
+
+// ❌ any 사용 금지
+const badParse = (data: string): any => {  // ❌
+  return JSON.parse(data)
+}
+
+// ❌ function 키워드 금지
+function badFunction() {  // ❌
+  return 'use const arrow function'
+}
+```
+
+</typescript>
+
+---
+
+<imports>
+
+## Import 순서
+
+```typescript
+// 1. External libraries
+import { Hono } from 'hono'
+import { zValidator } from '@hono/zod-validator'
+import { z } from 'zod'
+
+// 2. Internal modules
+import { authMiddleware } from './middleware/auth'
+import { prisma } from './lib/prisma'
+import { env } from './lib/env'
+
+// 3. Type imports
+import type { User } from './types'
+import type { Context } from 'hono'
+```
+
+</imports>
+
+---
+
+<comments>
+
+## 한글 주석 (묶음 단위)
+
+```typescript
+// ✅ 코드 묶음 단위 주석
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 사용자 조회
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+users.get('/', async (c) => {
+  const users = await prisma.user.findMany()
+  return c.json({ users })
+})
+
+users.get('/:id', async (c) => {
+  const id = c.req.param('id')
+  const user = await prisma.user.findUnique({ where: { id } })
+  if (!user) throw new HTTPException(404, { message: 'User not found' })
+  return c.json({ user })
+})
+
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+// 사용자 생성/수정
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+users.post('/', zValidator('json', createUserSchema), async (c) => {
+  const data = c.req.valid('json')
+  const user = await prisma.user.create({ data })
+  return c.json({ user }, 201)
+})
+```
+
+```typescript
+// ❌ 세세한 주석 (금지)
+users.get('/', async (c) => {  // 사용자 목록 조회
+  const users = await prisma.user.findMany()  // DB에서 조회
+  return c.json({ users })  // JSON 반환
+})
+```
+
+</comments>
+
+---
+
+<error_handling>
+
+## 에러 처리 패턴
+
+### HTTPException 사용
+
+```typescript
+import { HTTPException } from 'hono/http-exception'
+
+// ✅ HTTPException 사용
+users.get('/:id', async (c) => {
+  const id = c.req.param('id')
+  const user = await prisma.user.findUnique({ where: { id } })
+
+  if (!user) {
+    throw new HTTPException(404, { message: 'User not found' })
+  }
+
+  return c.json({ user })
+})
+
+// ❌ 일반 Error 사용 금지
+users.get('/:id', async (c) => {
+  const id = c.req.param('id')
+  const user = await prisma.user.findUnique({ where: { id } })
+
+  if (!user) {
+    throw new Error('User not found')  // ❌
+  }
+
+  return c.json({ user })
+})
+```
+
+### 전역 에러 핸들러
+
+```typescript
+// src/index.ts
+import { Hono } from 'hono'
+import { HTTPException } from 'hono/http-exception'
+
+const app = new Hono()
+
+app.onError((err, c) => {
+  if (err instanceof HTTPException) {
+    return c.json(
+      {
+        error: err.message,
+        status: err.status,
+      },
+      err.status
+    )
+  }
+
+  console.error('Unexpected error:', err)
+  return c.json(
+    {
+      error: 'Internal Server Error',
+      status: 500,
+    },
+    500
+  )
+})
+
+app.notFound((c) => {
+  return c.json(
+    {
+      error: 'Not Found',
+      status: 404,
+    },
+    404
+  )
+})
+```
+
+### 커스텀 에러 클래스
+
+```typescript
+// lib/errors.ts
+import { HTTPException } from 'hono/http-exception'
+
+export class NotFoundError extends HTTPException {
+  constructor(resource: string) {
+    super(404, { message: `${resource} not found` })
+  }
+}
+
+export class ValidationError extends HTTPException {
+  constructor(message: string) {
+    super(400, { message })
+  }
+}
+
+export class UnauthorizedError extends HTTPException {
+  constructor() {
+    super(401, { message: 'Unauthorized' })
+  }
+}
+
+// 사용
+import { NotFoundError } from '@/lib/errors'
+
+users.get('/:id', async (c) => {
+  const user = await prisma.user.findUnique({ where: { id } })
+  if (!user) throw new NotFoundError('User')
+  return c.json({ user })
+})
+```
+
+</error_handling>
+
+---
+
+<validation>
+
+## Validation 패턴
+
+### zValidator 사용
+
+```typescript
+import { zValidator } from '@hono/zod-validator'
+import { z } from 'zod'
+
+// ✅ zValidator 사용
+const createUserSchema = z.object({
+  name: z.string().min(1).trim(),
+  email: z.email(),
+  age: z.number().int().min(18).optional(),
+})
+
+users.post('/', zValidator('json', createUserSchema), async (c) => {
+  const data = c.req.valid('json')  // 타입 안전
+  const user = await prisma.user.create({ data })
+  return c.json({ user }, 201)
+})
+
+// ❌ 수동 검증 금지
+users.post('/', async (c) => {
+  const body = await c.req.json()
+
+  if (!body.name || !body.email) {  // ❌
+    return c.json({ error: 'Invalid input' }, 400)
+  }
+
+  const user = await prisma.user.create({ data: body })
+  return c.json({ user }, 201)
+})
+```
+
+### 여러 Validator
+
+```typescript
+// Query Params
+users.get('/', zValidator('query', z.object({ page: z.string() })), (c) => {
+  const { page } = c.req.valid('query')
+  return c.json({ page })
+})
+
+// Path Params
+users.get('/:id', zValidator('param', z.object({ id: z.string() })), (c) => {
+  const { id } = c.req.valid('param')
+  return c.json({ id })
+})
+
+// JSON Body
+users.post('/', zValidator('json', createUserSchema), (c) => {
+  const data = c.req.valid('json')
+  return c.json({ data }, 201)
+})
+```
+
+</validation>
+
+---
+
+<examples>
+
+## 파일명 예시
+
+| 타입 | ❌ 잘못된 예시 | ✅ 올바른 예시 |
+|------|---------------|---------------|
+| Route | `Users.ts` | `users.ts` |
+| Service | `userService.ts` | `user-service.ts` |
+| Middleware | `authMiddleware.ts` | `auth-middleware.ts` |
+| Utility | `formatUtils.ts` | `format-utils.ts` |
+| Type | `UserTypes.ts` | `user-types.ts` |
+
+## 디렉토리 구조
+
+```
+src/
+├── routes/
+│   ├── users.ts           # /users/*
+│   ├── posts.ts           # /posts/*
+│   └── auth.ts            # /auth/*
+├── middleware/
+│   ├── auth.ts            # 인증 미들웨어
+│   ├── logger.ts          # 로깅 미들웨어
+│   └── cors.ts            # CORS 미들웨어
+├── services/
+│   ├── user-service.ts    # 사용자 비즈니스 로직
+│   └── post-service.ts    # 게시글 비즈니스 로직
+├── lib/
+│   ├── prisma.ts          # Prisma 클라이언트
+│   ├── env.ts             # 환경 변수
+│   └── errors.ts          # 커스텀 에러
+└── types/
+    ├── user-types.ts      # 사용자 타입
+    └── api-types.ts       # API 타입
+```
+
+</examples>
+
+---
+
+<sources>
+
+- [Hono Best Practices](https://hono.dev/guides/best-practices)
+- [TypeScript Style Guide](https://google.github.io/styleguide/tsguide.html)
+
+</sources>