fix: harden project template

.github/dependabot.yml

@@ -0,0 +1,14 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      development-dependencies:
+        dependency-type: development
+
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly

.github/workflows/ci.yml

@@ -5,27 +5,35 @@ on:
     branches: [main]
   pull_request:
 
+permissions:
+  contents: read
+
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
 jobs:
   check:
-    runs-on: ubuntu-latest
+    name: Python ${{ matrix.python-version }}
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.13"]
     steps:
       - uses: actions/checkout@v6
 
       - uses: actions/setup-python@v6
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
           cache: "pip"
-          cache-dependency-path: pyproject.toml
+          cache-dependency-path: requirements-dev.lock
 
-      - name: Create venv and install dev dependencies
-        run: |
-          python -m venv .venv
-          .venv/bin/pip install --upgrade pip
-          .venv/bin/pip install -e ".[dev]"
+      - name: Install locked development environment
+        run: make install-dev
 
       - name: Run all checks (lint + format check + mypy + pytest + coverage)
         run: make ci-check
+
+      - name: Verify template initialization workflow
+        run: make test-integration

.pre-commit-config.yaml

@@ -74,14 +74,14 @@ repos:
         name: "Ruff 포매터"
 
   # ==========================================
-  # 4. 자동 수정 결과를 같은 커밋에 stage
+  # 4. 자동 수정 검토 안내
+  #    index를 변경하지 않아 부분 staging을 보존한다.
   #    (반드시 ruff/ruff-format 다음에 위치)
-  #    stdlib만 사용하므로 어떤 python3든 OK.
   # ==========================================
   - repo: local
     hooks:
-      - id: stage-fixes
-        name: "자동 수정 파일 stage"
+      - id: review-fixes
+        name: "자동 수정 검토 안내"
         entry: python3 scripts/stage_fixes.py
         language: system
         stages: [pre-commit]
@@ -116,7 +116,7 @@ repos:
 
       - id: mypy-push
         name: "mypy (push 전)"
-        entry: .venv/bin/python -m mypy src
+        entry: .venv/bin/python -m mypy src scripts
         language: system
         types: [python]
         stages: [pre-push]

CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Python 3.12 프로젝트 템플릿. Ruff(린터+포매터), pre-commit 훅, Commitizen(Conventional Commits)을 통한 자동화된 코드 품질 검사 시스템.
+Python 3.12–3.13 프로젝트 템플릿. Ruff(린터+포매터), pre-commit 훅, Commitizen(Conventional Commits)을 통한 자동화된 코드 품질 검사 시스템.
 
 ## Commands
 
@@ -27,6 +27,9 @@ make validate
 # CI용 검사 (수정 없이 검증만)
 make ci-check
 
+# 임시 프로젝트에서 init → install-dev → ci-check 검증
+make test-integration
+
 # 테스트 (pytest + coverage)
 make test
 
@@ -45,14 +48,16 @@ make clean
 
 Ruff 직접 실행:
 ```bash
-.venv/bin/ruff check src tests --fix
-.venv/bin/ruff format src tests
+.venv/bin/ruff check src tests scripts --fix
+.venv/bin/ruff format src tests scripts
 ```
 
 ## Architecture
 
 - `src/your_project/` — 소스 코드 패키지 (TODO: 프로젝트명으로 변경)
-- `tests/` — 테스트 디렉토리
+- `tests/` — 단위 테스트와 템플릿 초기화 통합 테스트
+- `scripts/` — 프로젝트 초기화와 fail-only 자동 수정 검토 안내
+- `requirements-dev.lock` — Python 3.12–3.13 공통 개발 constraints
 - `pyproject.toml` — 프로젝트 메타데이터, Ruff 설정, Commitizen 설정 통합
 - `.pre-commit-config.yaml` — Git 훅 (파일 검사, Ruff, Commitizen)
 - `Makefile` — 개발 자동화 명령어

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Junghee Im
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -1,6 +1,6 @@
 # ============================================================================
 # Makefile - Python 프로젝트 개발 자동화
-# Python 3.12+ 프로젝트용
+# Python 3.12–3.13 프로젝트용
 # ============================================================================
 # 사용법:
 #   make help       - 사용 가능한 명령어 목록
@@ -20,7 +20,7 @@ COLOR_BLUE    := \033[34m
 COLOR_CYAN    := \033[36m
 
 # 프로젝트 설정
-PYTHON := python3.12
+PYTHON ?= python3
 VENV := .venv
 VENV_BIN := $(VENV)/bin
 PIP := $(VENV_BIN)/pip
@@ -29,7 +29,11 @@ PYTHON_VENV := $(VENV_BIN)/python
 # 소스 디렉토리
 SRC_DIR := src
 TEST_DIR := tests
-ALL_DIRS := $(SRC_DIR) $(TEST_DIR)
+SCRIPT_DIR := scripts
+ALL_DIRS := $(SRC_DIR) $(TEST_DIR) $(SCRIPT_DIR)
+MYPY_DIRS := $(SRC_DIR) $(SCRIPT_DIR)
+COVERAGE_ARGS := --cov=$(SRC_DIR) --cov=$(SCRIPT_DIR)
+DEV_CONSTRAINTS := requirements-dev.lock
 
 # 도구 실행 경로
 RUFF := $(VENV_BIN)/ruff
@@ -43,7 +47,8 @@ COMMITIZEN := $(VENV_BIN)/cz
 
 .PHONY: help install install-dev install-hooks clean lint format \
         check ci-check validate test typecheck commit bump-version \
-        pre-commit run-all update-hooks quick-check full-check list-checks init
+        pre-commit run-all update-hooks quick-check full-check list-checks init \
+        test-integration lock-dev
 
 # ============================================================================
 # help - 사용 가능한 명령어 목록
@@ -61,6 +66,7 @@ help:
 	@echo "  make lint            - 코드 품질 검사 (자동 수정)"
 	@echo "  make format          - 코드 포매팅 (자동 정리)"
 	@echo "  make test            - 테스트 실행 (pytest + coverage)"
+	@echo "  make test-integration - 임시 프로젝트 초기화부터 CI 검사까지 검증"
 	@echo "  make typecheck       - 타입 검사 (mypy)"
 	@echo ""
 	@echo "$(COLOR_GREEN)통합 명령어:$(COLOR_RESET)"
@@ -82,6 +88,7 @@ help:
 	@echo ""
 	@echo "$(COLOR_GREEN)유지보수:$(COLOR_RESET)"
 	@echo "  make update-hooks    - pre-commit 훅 업데이트"
+	@echo "  make lock-dev        - 개발 의존성 constraints 파일 재생성 (uv 필요)"
 	@echo ""
 
 # ============================================================================
@@ -101,7 +108,7 @@ install-dev:
 	@echo "$(COLOR_BOLD)$(COLOR_BLUE)개발 환경 설치 중...$(COLOR_RESET)"
 	@test -d $(VENV) || $(PYTHON) -m venv $(VENV)
 	@$(PIP) install --upgrade pip setuptools wheel
-	@$(PIP) install -e ".[dev]"
+	@$(PIP) install -c $(DEV_CONSTRAINTS) -e ".[dev]"
 	@$(MAKE) install-hooks
 	@echo "$(COLOR_GREEN)✓ 개발 환경 설치 완료$(COLOR_RESET)"
 	@echo "$(COLOR_YELLOW)다음 명령어로 환경 활성화:$(COLOR_RESET)"
@@ -175,24 +182,32 @@ ci-check:
 	@echo "$(COLOR_BOLD)$(COLOR_BLUE)CI 검사 중...$(COLOR_RESET)"
 	@$(RUFF) check $(ALL_DIRS) --no-fix
 	@$(RUFF) format $(ALL_DIRS) --check
-	@$(VENV_BIN)/mypy $(SRC_DIR)
-	@$(VENV_BIN)/pytest --cov=$(SRC_DIR) --cov-report=term-missing --no-header -q
+	@$(VENV_BIN)/mypy $(MYPY_DIRS)
+	@$(VENV_BIN)/pytest $(COVERAGE_ARGS) --cov-report=term-missing --no-header -q
 	@echo "$(COLOR_GREEN)✓ CI 검사 통과$(COLOR_RESET)"
 
 # ============================================================================
 # test - 테스트 실행 (coverage 포함, 80% 게이트)
 # ============================================================================
 test:
 	@echo "$(COLOR_BOLD)$(COLOR_BLUE)테스트 실행 중...$(COLOR_RESET)"
-	@$(VENV_BIN)/pytest --cov=$(SRC_DIR) --cov-report=term-missing
+	@$(VENV_BIN)/pytest $(COVERAGE_ARGS) --cov-report=term-missing
 	@echo "$(COLOR_GREEN)✓ 테스트 완료$(COLOR_RESET)"
 
+# ============================================================================
+# test-integration - 임시 복사본에서 init → install-dev → ci-check 검증
+# ============================================================================
+test-integration:
+	@echo "$(COLOR_BOLD)$(COLOR_BLUE)템플릿 초기화 통합 테스트 실행 중...$(COLOR_RESET)"
+	@$(VENV_BIN)/pytest -m integration --no-cov -q
+	@echo "$(COLOR_GREEN)✓ 초기화 통합 테스트 통과$(COLOR_RESET)"
+
 # ============================================================================
 # typecheck - 타입 검사
 # ============================================================================
 typecheck:
 	@echo "$(COLOR_BOLD)$(COLOR_BLUE)타입 검사 중...$(COLOR_RESET)"
-	@$(VENV_BIN)/mypy $(SRC_DIR)
+	@$(VENV_BIN)/mypy $(MYPY_DIRS)
 	@echo "$(COLOR_GREEN)✓ 타입 검사 완료$(COLOR_RESET)"
 
 # ============================================================================
@@ -243,6 +258,16 @@ update-hooks:
 	@$(PRE_COMMIT) autoupdate
 	@echo "$(COLOR_GREEN)✓ 훅 업데이트 완료$(COLOR_RESET)"
 
+# ============================================================================
+# lock-dev - Python 3.12–3.13/전체 플랫폼용 개발 constraints 재생성
+# ============================================================================
+lock-dev:
+	@command -v uv >/dev/null || { echo "uv가 필요합니다: https://docs.astral.sh/uv/"; exit 1; }
+	@uv pip compile pyproject.toml --extra dev --universal \
+		--no-emit-package your-project \
+		--custom-compile-command "make lock-dev" \
+		--output-file $(DEV_CONSTRAINTS)
+
 # ============================================================================
 # quick-check - commit 시뮬레이션 (pre-commit 단계 훅 전체)
 # ============================================================================