Claude Code Python Template

A repo built on this template, heading to Mars.

A reusable .claude/ configuration template for Claude Code Python projects. It enables fast, accurate prototyping and establishes a self-improvement loop grounded in documentation and evidence.

This workflow originated from citypaul/.dotfiles and adapted for my own use.

Core Features

🛡️ Python quality pipeline — A pre-commit pipeline enforces Python conventions on every commit: ruff for linting and formatting, bandit for security scanning, and pip-audit for dependency vulnerability checks. The check skill runs all gates in read-only mode for inspection; auto-fix applies safe automated fixes.

📋 Programmer-written requirements gate — Vibe-coding produces code fast, but the programmer must still own and understand every line. Before any code is generated, the planning skill opens a grill-me-style interrogation: the AI fires relentless follow-up questions until requirements are fully concrete. The programmer then writes user stories in their own words and authors the BDD Given/When/Then failing tests by hand. Throughout this phase the AI may only advise — it cannot edit documents or code directly. Once tests exist, a guard hook prevents the AI from manipulating test logic to force a pass rather than fixing the implementation. Exception: typing 삐약삐약 저는 코딩 병아리입니다. (lit. "Cheep cheep, I'm a coding chick.") verbatim in chat unlocks full AI authorship for beginners who need a working scaffold to learn from.

📝 Documentation-driven self-improvement loop — Every stage of development — planning, implementation, review, and retrospective — produces structured documents (ADRs, lessons-learned, trade-off analyses). These documents serve as the shared memory that lets both the human and the AI agent improve their own workflow over time: revisiting past decisions, correcting recurring mistakes, and refining the process itself based on evidence rather than intuition.

🔄 Bidirectional template sync — Keep downstream projects and this template in sync. When a downstream project discovers a useful pattern, it can propose changes upstream; the template consolidates and broadcasts updates back to all projects.

💡 Creative and analytical thinking skills — Beyond code generation, the template ships skills that reframe hard problems through structured thinking frameworks: rethink-unblock breaks circular reasoning with targeted reframing, davinci-define applies the seven Da Vincian principles to clarify goals and life choices, and sparks-create uses the 13 tools from Sparks of Genius to generate cross-disciplinary creative angles. Use these when conventional analysis stalls.

For details, refer to these documents.

Document	Description
Workflow: Plan-Implement-Document-Guard	End-to-end development workflow
Template Management Skill	Bidirectional template sync between projects
Hooks Reference	How hooks intercept tool calls to enforce rules
Rules Reference	How rules shape Claude's behavior every session

External Services

This template includes optional integrations with third-party services. Some have commercial pricing:

Service	Purpose	Free tier	Pricing
jcodemunch	Code navigation & symbol search via MCP	—	Paid for commercial use

If you don't need jcodemunch, remove mcp__jcodemunch entries from .mcp.json and .claude/rules/code-navigation-guidelines.md.

Getting Started

1. Clone this repository.

   git clone https://github.com/tae0y/python-project-template.git my-project
   cd my-project

2. Run the initialization script.

   bash scripts/init-project.sh my-project

   This removes template-only directories (localdocs/, proposals/, resources/, docs/, *.nouse/, claude-code-ref/), deletes .gitkeep files, removes cache and build artifacts (.venv, __pycache__, .pytest_cache, .ruff_cache, .mypy_cache, dist, build, *.egg-info), resets settings.json from settings.sample.json, removes settings.local.json, resets README.md to an H1 title, updates pyproject.toml with the project name, and bootstraps a fresh localdocs/ directory.

3. Set up the Python environment.

   uv sync

4. Install the pre-commit hook.

   pre-commit install --hook-type commit-msg

5. Customize CLAUDE.md for your project. See CLAUDE.sample.md for reference.

   Note: If you use a shared TIL repository, move .claude/skills.nouse/localdocs-til-link into .claude/skills/ and run /localdocs-til-link to symlink localdocs/ there.

6. The full directory structure looks like this:

   .claude/
   ├── WORKFLOW.md              # Workflow trigger map
   ├── settings.json            # Global settings
   ├── rules/                   # Behavioral rules applied to every response
   ├── commands/                # Reusable prompt templates
   ├── hooks/                   # Lifecycle shell scripts (pre-commit gate, convention checks)
   ├── skills/                  # Domain-specific capability definitions
   │   ├── tdd/                 # TDD workflow
   │   ├── planning/            # Task breakdown into known-good increments
   │   ├── check/               # Code quality inspection (ruff, pyright, bandit)
   │   ├── auto-fix/            # Lint & format auto-fix
   │   ├── rethink-unblock/     # Reframe stuck problems
   │   ├── davinci-define/      # Da Vincian principles for goal clarity
   │   ├── sparks-create/       # Cross-disciplinary creative thinking
   │   ├── template-broadcast/  # Batch rollout to all downstream projects
   │   └── ...
   ├── skills.nouse/            # Disabled skills (preserved for re-activation)
   └── agents/                  # Specialized sub-agent definitions
   

Roadmap

Near-term improvements planned for this template:

Item	Status	Description
Template versioning with Copier	Planned	Replace manual sync with Copier's 3-way merge so downstream projects track template versions and apply updates without file-by-file comparison
Unsupervised harness mode	Planned	Let the harness run without a human in the loop: scoped tool access, sandboxed execution, self-correcting test loop, and structured run reports
Planning phase artifacts	Planned	Clarify what each planning phase produces and where it lands, so SPIKE, architecture, and implementation outputs don't overlap