BcKmini · BcKmini · Aug 10, 2026 · Aug 10, 2026 · Aug 10, 2026 · Aug 10, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -12,7 +12,10 @@ on:
       - 'rust/**'
       - 'agents/**'
       - 'tools/**'
+      - 'tests/**'
       - 'scripts/**'
+      - 'tox.ini'
+      - 'pyproject.toml'
   pull_request:
     branches:
       - main
@@ -21,7 +24,10 @@ on:
       - 'rust/**'
       - 'agents/**'
       - 'tools/**'
+      - 'tests/**'
       - 'scripts/**'
+      - 'tox.ini'
+      - 'pyproject.toml'
   workflow_dispatch:
 
 concurrency:
@@ -50,6 +56,50 @@ jobs:
       - name: Check agent MD files
         run: bash scripts/validate-agents.sh
 
+  # ── Job: Python tests (tox, version matrix) ──────────────────────────────────
+  python-tests:
+    name: Python tests (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: .
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install tox
+        run: pip install tox
+
+      - name: Run tests
+        run: tox -e py
+
+  # ── Job: Python lint/format (ruff via tox) ───────────────────────────────────
+  python-lint:
+    name: Python lint (ruff)
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: .
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+
+      - name: Install tox
+        run: pip install tox
+
+      - name: Lint + format check
+        run: tox -e lint,fmt-check
+
   # ── Job: rustfmt ─────────────────────────────────────────────────────────────
   fmt:
     name: cargo fmt
@@ -102,6 +152,26 @@ jobs:
       - name: Run workspace tests
         run: cargo test --workspace
 
+  # ── Job: MSRV verification ────────────────────────────────────────────────────
+  msrv:
+    name: MSRV verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: rust -> target
+
+      - name: Install cargo-msrv
+        run: cargo install cargo-msrv --locked
+
+      - name: Discover the real MSRV
+        working-directory: rust/claude-tools
+        run: cargo msrv find
+
   # ── Job: Windows smoke build ─────────────────────────────────────────────────
   windows-smoke:
     name: Windows build smoke

diff --git a/Makefile b/Makefile
@@ -73,8 +73,11 @@ install-rust: build ## Build Rust binary and install to ~/.local/bin/
 	@echo "Installed claude-tools → $(BIN_TARGET)/claude-tools"
 
 # ─── test ──────────────────────────────────────────────────────────────────
-.PHONY: test test-rust test-python test-agents
-test: test-rust test-python ## Run all tests
+.PHONY: test test-rust test-python test-agents tox
+test: test-rust test-python ## Run all tests (fast, zero-dependency smoke checks)
+
+tox: ## Full Python test matrix + lint (requires: pip install tox ruff)
+	tox
 
 test-rust: ## Cargo check + clippy
 	cd $(RUST_DIR) && $(CARGO) check
@@ -113,6 +116,9 @@ test-agents: ## Verify agent files exist and are non-empty
 lint: ## Clippy lint (Rust)
 	cd $(RUST_DIR) && $(CARGO) clippy -- -D warnings
 
+msrv: ## Verify the crate builds on its declared MSRV (requires: cargo install cargo-msrv)
+	cd $(RUST_DIR)/claude-tools && cargo msrv verify
+
 fmt: ## Format all code (Rust + Python)
 	bash scripts/fmt.sh
 

diff --git a/README.ko.md b/README.ko.md
@@ -8,7 +8,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
 [![Python 3.8+](https://img.shields.io/badge/Python-3.8%2B-blue?style=flat-square&logo=python&logoColor=white)](https://www.python.org)
-[![Rust](https://img.shields.io/badge/Rust-1.75%2B-orange?style=flat-square&logo=rust)](https://www.rust-lang.org)
+[![Rust](https://img.shields.io/badge/Rust-1.78%2B-orange?style=flat-square&logo=rust)](https://www.rust-lang.org)
 [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey?style=flat-square)](https://github.com/BcKmini/Claudecode-Agent)
 [![Claude Code](https://img.shields.io/badge/Claude_Code-Compatible-blueviolet?style=flat-square&logo=anthropic)](https://claude.ai/code)
 [![Agents](https://img.shields.io/badge/Agents-11-green?style=flat-square)](#에이전트-구성)
@@ -431,9 +431,11 @@ make help           # 전체 타겟 목록
 make install        # 에이전트 + 슬래시 커맨드 + Python 도구
 make install-rust   # Rust 바이너리 빌드 및 설치
 make build          # cargo build --release
-make test           # 전체 테스트
-make lint           # clippy + ruff
-make fmt            # rustfmt + ruff format
+make test           # 빠른 스모크 테스트 (추가 의존성 없음)
+make tox            # 전체 Python 테스트 매트릭스(py38-py313) + lint + fmt-check
+make msrv           # Rust 크레이트가 명시된 MSRV에서 빌드되는지 검증
+make lint           # clippy (Rust)
+make fmt            # rustfmt + ruff format (범위 한정 — CONTRIBUTING.ko.md 참고)
 make status         # git log + 도구 설치 상태 확인
 make env            # Claude 환경 헬스체크
 make clean          # 빌드 아티팩트 제거
@@ -446,6 +448,8 @@ make clean          # 빌드 아티팩트 제거
 ```
 claude-code-use/
 ├── Makefile                          ← 빌드 / 설치 / 테스트 / 정리
+├── tox.ini                           ← Python 테스트 매트릭스 + lint + fmt-check
+├── pyproject.toml                    ← ruff 설정 (이 저장소 스타일에 맞게 범위 한정)
 ├── install.sh                        ← 원라인 설치 스크립트
 ├── setup-agents.ps1                  ← Windows 빠른 설치
 ├── setup-agents.sh                   ← macOS / Linux 빠른 설치
@@ -473,6 +477,10 @@ claude-code-use/
 │   ├── claude-lessons.py             ← 신규 실패/교훈 기록
 │   ├── install-tools.ps1  ·  install-tools.sh
 │
+├── tests/                            ← tools/*.py용 pytest 스위트
+│   ├── conftest.py                   ← run_tool / home / git_repo 픽스처
+│   └── test_*.py                     ← 도구당 파일 하나
+│
 ├── rust/claude-tools/src/
 │   ├── main.rs  ·  snippet.rs  ·  handoff.rs  ·  cost.rs
 │   ├── watch.rs  ·  env.rs  ·  colors.rs

diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
 [![Python 3.8+](https://img.shields.io/badge/Python-3.8%2B-blue?style=flat-square&logo=python&logoColor=white)](https://www.python.org)
-[![Rust](https://img.shields.io/badge/Rust-1.75%2B-orange?style=flat-square&logo=rust)](https://www.rust-lang.org)
+[![Rust](https://img.shields.io/badge/Rust-1.78%2B-orange?style=flat-square&logo=rust)](https://www.rust-lang.org)
 [![Platform](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey?style=flat-square)](https://github.com/BcKmini/Claudecode-Agent)
 [![Claude Code](https://img.shields.io/badge/Claude_Code-Compatible-blueviolet?style=flat-square&logo=anthropic)](https://claude.ai/code)
 [![Agents](https://img.shields.io/badge/Agents-11-green?style=flat-square)](#agent-roster)
@@ -433,9 +433,11 @@ make help           # list all targets
 make install        # agents + slash commands + Python tools
 make install-rust   # build and install Rust binary
 make build          # cargo build --release
-make test           # all tests
-make lint           # clippy + ruff
-make fmt            # rustfmt + ruff format
+make test           # fast smoke tests (no extra deps)
+make tox            # full Python test matrix (py38-py313) + lint + fmt-check
+make msrv           # verify the Rust crate builds on its declared MSRV
+make lint           # clippy (Rust)
+make fmt            # rustfmt + ruff format (scoped — see CONTRIBUTING.md)
 make status         # git log + tool install check
 make env            # Claude environment health check
 make clean          # remove build artifacts
@@ -448,6 +450,8 @@ make clean          # remove build artifacts
 ```
 Claudecode-Agent/
 ├── Makefile                          ← build / install / test / clean
+├── tox.ini                           ← Python test matrix + lint + fmt-check
+├── pyproject.toml                    ← ruff config (scoped to this repo's style)
 ├── setup-agents.ps1                  ← Windows quick installer
 ├── setup-agents.sh                   ← macOS / Linux quick installer
 │
@@ -489,6 +493,10 @@ Claudecode-Agent/
 │   ├── install-tools.ps1             ← Windows tool installer
 │   └── install-tools.sh              ← macOS/Linux tool installer
 │
+├── tests/                            ← pytest suite for tools/*.py
+│   ├── conftest.py                   ← run_tool / home / git_repo fixtures
+│   └── test_*.py                     ← one file per tool
+│
 ├── rust/claude-tools/src/
 │   ├── main.rs
 │   ├── snippet.rs

diff --git a/docs/CONTRIBUTING.ko.md b/docs/CONTRIBUTING.ko.md
@@ -29,14 +29,26 @@ python --version   # 3.8+ 필요
 make status        # 설치 상태 확인
 ```
 
-`snippet.py`, `claude-handoff.py`, `claude-cost.py`, `claude-review-diff.py`, `claude-remind.py` 모두 Python 표준 라이브러리만 사용합니다 — `pip install` 불필요.
+`snippet.py`, `claude-handoff.py`, `claude-cost.py`, `claude-review-diff.py`, `claude-remind.py`, `claude-harness.py`, `claude-pipeline.py`, `claude-lessons.py` 모두 Python 표준 라이브러리만 사용합니다 — *실행*에는 `pip install` 불필요. 테스트에는 dev 의존성이 필요합니다:
+
+```bash
+pip install tox
+tox              # 전체 매트릭스: py38-py313(설치 안 된 버전은 건너뜀) + lint + fmt-check
+tox -e py        # 현재 인터프리터로 tests/만 실행
+tox -e lint      # ruff check tools/ tests/
+```
+
+ruff 설정은 `pyproject.toml`에 있습니다 — 전체 기본 룰셋이 아니라 `E`/`F`/`I`/`UP`(실질적 버그, 미사용 import, import 순서, 문법 현대화)로 범위를 좁혔고, `E402`는 무시합니다 — 모든 도구가 docstring 바로 뒤, import보다 먼저 `VERSION` 상수를 두는 게 의도된 스타일이기 때문입니다. `fmt-check`는 `tools/claude-lessons.py`와 `tests/`만 검사합니다 — 기존 도구들은 `ruff format`이 없애버릴 의도적인 정렬 스타일을 쓰고 있어서, 저장소 전체에는 강제하지 않습니다.
 
 Rust 바이너리:
 
 ```bash
 cd rust
 cargo check   # 빌드 확인
 cargo build --release
+
+cargo install cargo-msrv --locked
+cd claude-tools && cargo msrv verify   # 명시된 rust-version에서 여전히 빌드되는지 확인
 ```
 
 ---
@@ -82,9 +94,10 @@ python tools/snippet.py run my-snippet --dry-run
    - `NO_COLOR` 환경변수 준수
 2. `.claude/commands/<name>.md` 슬래시 커맨드 문서 추가
 3. `Makefile` → `install-tools` 타겟과 `status` 타겟에 추가
-4. Rust 구현 추가 시: `rust/claude-tools/src/<name>.rs` 작성 후 `main.rs`에 연결
-5. `README.md`와 `README.ko.md`의 도구 섹션, 슬래시 커맨드 테이블, 저장소 구조 업데이트
-6. `docs/AGENT-CHEATSHEET.md`와 `docs/AGENT-CHEATSHEET.ko.md` 업데이트
+4. `tests/test_<name>.py` 추가 (`tests/conftest.py`의 `run_tool`/`home`/`git_repo` 픽스처 사용, subprocess 기반) 후 `tox -e py,lint` 통과 확인
+5. Rust 구현 추가 시: `rust/claude-tools/src/<name>.rs` 작성 후 `main.rs`에 연결
+6. `README.md`와 `README.ko.md`의 도구 섹션, 슬래시 커맨드 테이블, 저장소 구조 업데이트
+7. `docs/AGENT-CHEATSHEET.md`와 `docs/AGENT-CHEATSHEET.ko.md` 업데이트
 
 ---
 
@@ -116,11 +129,13 @@ python tools/snippet.py run my-snippet --dry-run
 - [ ] `snippet import snippets/defaults.json` 정상 작동
 - [ ] `cargo check` 통과 (Rust 변경 시)
 - [ ] `make test` 통과
+- [ ] `tox` 통과 — 최소 `tox -e py,lint` (Python 변경 시)
+- [ ] `cargo msrv verify` 통과 (Rust 변경 시 — 명시된 `rust-version`에서 여전히 빌드되는지 확인)
 - [ ] 새 스니펫·에이전트·도구 추가 시 README 테이블 업데이트됨
 - [ ] **EN/KO 문서 쌍 모두 업데이트됨** (README, CHEATSHEET, SETUP, INTEGRATION 해당 항목)
 - [ ] 새 도구 추가 시 슬래시 커맨드 `.md` 파일 추가됨
 - [ ] 새 도구 추가 시 `Makefile` 업데이트됨
-- [ ] 외부 의존성 새로 추가하지 않음
+- [ ] `tools/`에는 외부 의존성 새로 추가하지 않음 (`examples/` 스크립트는 예외 — Code Style 참고)
 
 ---
 

diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md
@@ -29,14 +29,26 @@ python --version   # 3.8+ required
 make status        # check what's installed
 ```
 
-`snippet.py`, `claude-handoff.py`, `claude-cost.py`, `claude-review-diff.py`, `claude-remind.py` all use only the Python standard library — no `pip install` needed.
+`snippet.py`, `claude-handoff.py`, `claude-cost.py`, `claude-review-diff.py`, `claude-remind.py`, `claude-harness.py`, `claude-pipeline.py`, `claude-lessons.py` all use only the Python standard library — no `pip install` needed to *run* them. Testing them does need dev dependencies:
+
+```bash
+pip install tox
+tox              # full matrix: py38-py313 (skips interpreters you don't have) + lint + fmt-check
+tox -e py        # just run tests/ on your current interpreter
+tox -e lint      # ruff check tools/ tests/
+```
+
+Ruff's config lives in `pyproject.toml` — it's scoped to `E`/`F`/`I`/`UP` (real bugs, unused imports, import order, modernization), not the full default ruleset, and `E402` is ignored because every tool deliberately puts its `VERSION` constant right after the docstring, before imports. `fmt-check` only covers `tools/claude-lessons.py` and `tests/` — the older tools use a deliberate hand-aligned style that `ruff format` would flatten, so it isn't enforced repo-wide.
 
 For the Rust binary:
 
 ```bash
 cd rust
 cargo check   # verify build
 cargo build --release
+
+cargo install cargo-msrv --locked
+cd claude-tools && cargo msrv verify   # confirm it still builds on the declared rust-version
 ```
 
 ---
@@ -82,9 +94,10 @@ python tools/snippet.py run my-snippet --dry-run
    - Respect `NO_COLOR` environment variable
 2. Add `.claude/commands/<name>.md` slash command doc
 3. Add the tool to `Makefile` → `install-tools` target and `status` target
-4. If adding a Rust implementation, add `rust/claude-tools/src/<name>.rs` and wire it into `main.rs`
-5. Update `README.md` and `README.ko.md` tool sections, slash command table, and repo layout
-6. Update `docs/AGENT-CHEATSHEET.md` and `docs/AGENT-CHEATSHEET.ko.md`
+4. Add `tests/test_<name>.py` (subprocess-based, using the `run_tool`/`home`/`git_repo` fixtures in `tests/conftest.py`) and confirm `tox -e py,lint` passes
+5. If adding a Rust implementation, add `rust/claude-tools/src/<name>.rs` and wire it into `main.rs`
+6. Update `README.md` and `README.ko.md` tool sections, slash command table, and repo layout
+7. Update `docs/AGENT-CHEATSHEET.md` and `docs/AGENT-CHEATSHEET.ko.md`
 
 ---
 
@@ -116,11 +129,13 @@ examples (e.g. an MCP server) that legitimately need a third-party package. Keep
 - [ ] `snippet import snippets/defaults.json` still works
 - [ ] `cargo check` passes (Rust changes)
 - [ ] `make test` passes
+- [ ] `tox` passes — at minimum `tox -e py,lint` (Python changes)
+- [ ] `cargo msrv verify` passes (Rust changes — confirms the declared `rust-version` still builds)
 - [ ] README tables updated if new snippets / agents / tools added
 - [ ] **Both EN and KO docs updated** (README, CHEATSHEET, SETUP, INTEGRATION as applicable)
 - [ ] Slash command `.md` added if new tool introduced
 - [ ] `Makefile` updated if new tool added
-- [ ] No new external dependencies introduced
+- [ ] No new external dependencies introduced in `tools/` (an `examples/` script may declare one — see Code Style)
 
 ---
 

diff --git a/pyproject.toml b/pyproject.toml
@@ -0,0 +1,9 @@
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+
+[tool.ruff.lint]
+# E402 ignored: every tool in tools/ deliberately puts a VERSION constant
+# right after the module docstring, before imports, for easy `grep`.
+select = ["E", "F", "I", "UP"]
+ignore = ["E501", "E402"]
diff --git a/rust/claude-tools/Cargo.toml b/rust/claude-tools/Cargo.toml
@@ -2,6 +2,7 @@
 name = "claude-tools"
 version = "1.0.0"
 edition = "2021"
+rust-version = "1.78"
 description = "Claude Code productivity CLI: snippet manager, session handoff, cost estimator"
 authors = ["BcKmini"]
 license = "MIT"

diff --git a/scripts/fmt.sh b/scripts/fmt.sh
@@ -36,16 +36,20 @@ else
 fi
 
 # ── Python ─────────────────────────────────────────────────────────────────
+# Scoped to claude-lessons.py + tests/, not all of tools/: most existing
+# tools/*.py use a deliberate hand-aligned style (aligned `=`, aligned dict
+# values) that `ruff format` would flatten. See tox.ini's fmt-check comment.
+PY_FMT_TARGETS=("$REPO_ROOT/tools/claude-lessons.py" "$REPO_ROOT/tests/")
 if command -v ruff &>/dev/null; then
   if [ "$CHECK" -eq 1 ]; then
-    if ruff format --check "$REPO_ROOT/tools/" 2>/dev/null; then
+    if ruff format --check "${PY_FMT_TARGETS[@]}" 2>/dev/null; then
       ok "Python: ruff format check passed"
     else
       fail "Python: ruff format check failed — run: bash scripts/fmt.sh"
       FAILURES=$((FAILURES+1))
     fi
   else
-    ruff format "$REPO_ROOT/tools/" 2>/dev/null && ok "Python: ruff format applied"
+    ruff format "${PY_FMT_TARGETS[@]}" 2>/dev/null && ok "Python: ruff format applied"
   fi
 else
   printf '  skipping Python (ruff not found)\n'